Claude Code 실전 운영에서 얻은 베스트 프랙티스

[운영자 노트] 저는 컨설팅 브랜드와 텍사스 Pflugerville에 있는 피클볼 시설 Pickleland, 이렇게 두 개의 비즈니스에서 평일마다 Claude Code를 씁니다. 이 블로그의 발행 파이프라인부터 프로덕션 Worker의 코드 리뷰까지 전부요. 이 글은 Claude Code가 무엇인지 소개하는 입문 글이 아닙니다. 몇 달간 실제로 써보고 남은 습관들, 그리고 얻는 것보다 비용이 커서 버린 습관들에 대한 이야기입니다.

Table of contents

Open Table of contents

• CLAUDE.md는 문서가 아니라 규칙으로 써라
• 서브에이전트에 위임하는 것과 제 스레드에 남기는 것
• 컨텍스트 관리는 일회성 설정이 아니라 매일의 규율이다
• 혼자 하도록 두면 안 된다고 배운 것
• 배포 전에 검증하라 — Claude의 “완료”는 사실이 아니라 주장이다
• 운영자로서의 결론
• FAQ
  • CLAUDE.md 파일에는 실제로 뭐가 들어가야 하나요?
  • Claude Code의 출력을 다시 확인하지 않고 신뢰할 때는 어떻게 결정하나요?
  • Claude Code가 알아서 커밋하고 푸시하게 두나요?
  • 가장 많은 시간을 아껴준 단 하나의 습관은 무엇인가요?

CLAUDE.md는 문서가 아니라 규칙으로 써라

제가 쓴 모든 CLAUDE.md의 첫 버전은 너무 길었고, 모두 시간이 지나면서 짧아졌지 길어진 적은 한 번도 없습니다. 흔한 실수는 이걸 위키 페이지처럼 다루는 것입니다 — 배경, 철학, “우리가 왜 이렇게 하는지”. Claude는 현재 작업에 그 디테일이 필요하든 아니든 매 세션마다 파일 전체를 읽습니다. 그래서 지시문이 아닌 모든 문단은 실제 지시문과 주목을 놓고 경쟁하게 됩니다.

다듬어질수록 남는 건 더 좁습니다: 가능하면 테스트가 강제하는, 조용히 퇴행할 수 없는 하드 룰, 그리고 정말로 디테일이 필요한 경우를 위한 더 긴 문서로의 링크. “제목은 60자 미만”은 한 줄의 가치가 있습니다. 그 한도가 왜 존재하는지에 대한 이야기는 문서 링크의 가치가 있는 것이지, Claude가 매 세션 다시 읽는 파일 속 한 문단의 가치가 아닙니다.

제가 추가한 두 번째 것, 그리고 이 정도로 중요할 줄 예상 못 했던 것은: 이미 결론이 난 사실들을 짧게 목록으로 정리해 한 번만 적어두고, 다시 조사하지 말라고 명시적으로 지시하는 것입니다. 초반에 Claude Code는 몇 세션마다 같은 오탐을 다시 진단하곤 했습니다 — 불안정한 체크, 빌드 단계에 있는 알려진 특이 동작 — 이미 제가 도달한 결론을 다시 도출하느라 컨텍스트를 태웠습니다. 검증된 사실을 명시하고 조사를 다시 열지 말고 넘어가라고 지시하는 한 줄이, 이 헛도는 시간을 거의 0으로 줄였습니다. 제가 쓰는 규칙은 이렇습니다: 같은 “사실 그건 예상된 동작이야”를 두 번 설명했다면, 그건 채팅에서 세 번째로 다시 타이핑할 게 아니라 CLAUDE.md에 사실로 적혀야 합니다.

서브에이전트에 위임하는 것과 제 스레드에 남기는 것

스킬, 슬래시 명령어, 서브에이전트에 대한 의사결정 프레임워크는 이미 따로 글로 썼으니 여기서 다시 반복하진 않겠습니다. 덧붙일 가치가 있는 건, 실제로 서브에이전트를 생성하기 전에 제가 적용하는 운영자 수준의 필터입니다: “완료”가 어떤 모습인지 한 문장으로 말할 수 있는가, 그리고 중간 단계들이 제 메인 스레드에 남는다면 제가 정말로 그걸 읽을 것인가?

두 질문 모두 답이 “아니오”라면 — 작업의 경계가 명확하고 결과만 원하는 것이라면 — 서브에이전트입니다. 이 글을 12개 언어로 번역하는 게 가장 명확한 예입니다: 각 번역은 독립적으로 검증 가능하고, 이 병렬 분배가 바로 콘텐츠 파이프라인이 언어당 서브에이전트 하나를 돌리는 이유입니다 — 영어 원고가 맞는지 아직 판단하고 있는 그 스레드를, 12개 언어의 중간 왕복이 어지럽히는 건 절대 원치 않습니다.

작업이 진행 중인 추론 과정을 제가 직접 봐야 하는 경우 — 세 번째 결정이 두 번째 결정이 드러낸 내용에 달려 있는 스키마 변경 같은 것 — 이라면 메인 스레드에 남깁니다. 제가 실제로 겪은 실패 패턴은, 그런데도 그런 작업에 서브에이전트를 생성해서 깔끔한 요약을 받고, 그 요약이 정작 중요한 디테일 하나를 빠뜨려서 “잠깐, 정확히 뭘 찾았다고?”를 세 번 물어보는 것이었습니다. 같은 유형의 작업에서 이게 두 번 일어나면, 그 작업의 위임을 멈춥니다.

컨텍스트 관리는 일회성 설정이 아니라 매일의 규율이다

CLAUDE.md는 한 번 쓰고 잊어버리는 부분입니다. 컨텍스트 창은 제가 매 세션 관리하는 부분이고, 결과가 좋은지 나쁜지를 실제로 결정하는 것도 바로 이쪽입니다.

• 수정하게 두기 전에 읽게 하라. Claude Code는 현재 전체 상태를 본 적 없는 파일에 대해서도 기꺼이 수정을 제안합니다. 안에 뭐가 있는지 확신할 때조차 항상 먼저 파일을 읽게 합니다 — 그 “확신”이 틀린 적이 충분히 많아서, 더 이상 선택 사항이 아닙니다.
• 한 세션에 무관한 작업 두 가지를 시키지 마라. 배포 문제 디버깅에 한 시간을 쓰고 나서 마케팅 카피 작성으로 넘어가는 스레드는, 그 한 시간의 무관한 도구 출력을 이후 모든 응답에 끌고 다닙니다. Claude에게 “배포 얘기는 잊어줘”라고 부탁하는 대신 새 세션을 시작합니다 — 그 지시는 토큰을 없애는 게 아니라 모델에게 그걸 무시해 달라고 부탁하는 것일 뿐이고, 모델은 그걸 완벽하게 해내지 못합니다.
• 실행하게 두기 전에 계획을 세워라. 두세 단계를 넘는 모든 일에 대해, 저는 먼저 계획을 요청하고 실행을 승인하기 전에 읽습니다. 다섯 줄짜리 계획을 읽는 데는 15초가 걸립니다. 다섯 번째 단계가 이미 실행된 뒤에 세 번째 단계가 틀렸다는 걸 알게 되면 오후 전체가 날아갑니다.
• 큰 덩어리를 붙여넣는 건 편의가 아니라 비용이다. 정작 필요한 건 세 줄뿐인데 로그 파일 전체나 API 응답 전체를 대화에 던져 넣으면, 나머지 97%에 대해 컨텍스트를 낭비하는 겁니다. 저는 먼저 grep을 하고 일치하는 부분만 붙여넣습니다.

이건 일반적인 AI 에이전트를 위한 컨텍스트 엔지니어링 뒤에 있는 것과 같은 원리입니다 — Claude Code는 그저 그 비용을 더 일찍 눈에 보이게 만들 뿐입니다. Worker 로그에서 나중에 디버깅하는 대신, 컨텍스트가 실시간으로 차오르는 걸 직접 지켜보게 되니까요.

혼자 하도록 두면 안 된다고 배운 것

커밋, 푸시, 발행, 전송, 지출 같은 되돌릴 수 없는 모든 행동은 제가 직접 실행하는 명시적 승인 단계 뒤에 있습니다 — Claude Code가 작업이 끝났다고 판단해서 스스로 내딛는 행동은 절대 아닙니다. 이는 에이전트가 실제 결과에 닿는 모든 곳에서 제가 쓰는 것과 같은 휴먼인더루프 패턴이며, Claude Code가 클라우드가 아니라 제 자신의 컴퓨터에서 돌아간다고 해서 예외가 되지는 않습니다.

또 하나 그만둔 것은: 파괴적인 명령어에 광범위하고 영구적인 허가를 주는 것입니다. rm -rf, 강제 푸시, 테스트 훅 건너뛰기 — 이 중 어느 것도 포괄적인 “예”를 받지 못합니다. 매번, 그 맥락 안에서 각각 요청됩니다. 왜냐하면 “시간을 아끼려고” 광범위한 걸 미리 승인했던 그 한 번이, 작업이 제가 제대로 검토하지 않은 범위로 흘러간 바로 그 한 번이었기 때문입니다. 권한 프롬프트가 요구하는 5초는, 그 대안에 대한 값싼 보험입니다.

배포 전에 검증하라 — Claude의 “완료”는 사실이 아니라 주장이다

이게 가장 많은 시간을 되돌려준 습관이고, 가장 화려하지 않은 습관이기도 합니다: 저는 완료 보고를 신뢰하지 않습니다. 실제 점검을 직접 돌립니다.

Claude Code는 빌드가 통과했다고, 테스트 스위트가 초록불이라고, 링크가 작동한다고 말할 겁니다. 때로 그 보고는 실제 출력에서 생성된 것입니다. 때로는 절반만 실행된 명령어, 또는 안에 쓸만한 게 아무것도 없이 일찍 반환된 체크에 대한 자신만만한 요약일 뿐입니다. 채팅 기록에서는 이 둘이 똑같아 보입니다. 이 둘을 구분하는 유일한 방법은 실제 출력을 직접 보는 것입니다 — 제가 에이전트를 배포할 때 쓰는 평가 하네스 뒤에 있는 것과 같은 규율입니다: 작업은 에이전트가 그렇다고 말해서 완료로 점수 매겨지는 게 아니라, 정의된 체크가 실제로 통과할 때 완료로 점수 매겨집니다.

실무에서 이건 다음을 의미합니다: 빌드 명령어를 직접 실행하고 Claude의 요약이 아니라 실제 출력을 읽는 것. 수정했다고 말한 파일을 여는 것. 작동한다고 말한 링크를 클릭하는 것. 콘텐츠의 경우 특히, Claude가 처음부터 제대로 적용했을 거라 믿는 대신 — 길이 제한, 금지된 패턴, 깨진 내부 링크처럼 강제되고 있다고 알고 있는 규칙들에 대해 — 초안을 적대적으로 다시 읽습니다. 왜냐하면 대부분은 맞게 적용하지만 가끔은 아니고, 그 가끔의 실수가 실제 사이트에 올라가는 비용은 다시 읽는 데 드는 90초보다 훨씬 크기 때문입니다.

운영자로서의 결론

이 모든 것은 시간이 지나면서 Claude Code를 덜 신뢰하게 되는 것에 관한 얘기가 아닙니다 — 그 신뢰가 실제로 어디서 얻어져야 하는지를 정확히 하는 것에 관한 얘기입니다. 긴 문서 대신 짧고 강제 가능한 CLAUDE.md. 경계가 명확하고 검증 가능한 작업은 서브에이전트로, 추론 과정이 결과만큼 중요한 모든 것은 자신의 스레드로. 길게 끌린 세션 대신 신선한 컨텍스트. 되돌릴 수 없는 모든 것에 승인 게이트를. 그리고 위임한 무언가가 세상에 나가기 전에 직접 읽은 실제 점검을. 이게 목록 전부이고, 제가 실제로 지키는 목록입니다.

FAQ

CLAUDE.md 파일에는 실제로 뭐가 들어가야 하나요?

에이전트가 매 세션마다 따라야 할 규칙을, 지시문으로 작성한 것 — 코드베이스가 왜 지금 모습이 됐는지에 대한 배경이 아닙니다. 어떤 규칙이 테스트로 강제된다면 그렇다고 명시하고 테스트가 진실의 원천이 되게 하세요. 더 긴 배경 정보는 CLAUDE.md가 링크하는 문서에 속해야 하고, 작업이 실제로 그 영역을 건드릴 때만 읽혀야지 기본값으로 매 세션 다시 로드되어선 안 됩니다.

Claude Code의 출력을 다시 확인하지 않고 신뢰할 때는 어떻게 결정하나요?

저는 점검을 건너뛸지를 결정하는 게 아니라, 그게 얼마나 비싼지를 결정합니다. 빌드 명령어를 직접 돌리는 건 거의 공짜에 가까워서 항상 합니다. 긴 문서를 완전히 적대적으로 다시 읽는 건 시간이 더 걸리니, 실제 독자 앞에 나가는 것에만 아껴둡니다. 절대 건너뛰지 않는 유일한 것: 되돌릴 수 없는 모든 것 — 발행, 커밋, 돈을 쓰는 일.

Claude Code가 알아서 커밋하고 푸시하게 두나요?

아니요. 모든 커밋과 모든 푸시는 diff를 직접 본 뒤 제가 직접 실행합니다. Claude Code는 변경을 제안하고, 초안 상태를 벗어나는 모든 것에 대해 제가 승인 게이트입니다 — 제가 운영하는 다른 모든 에이전트에 적용하는 것과 같은 규칙입니다.

가장 많은 시간을 아껴준 단 하나의 습관은 무엇인가요?

완료 보고를 사실이 아니라 주장으로 취급하고, 실제 점검을 직접 돌리는 것입니다. 모든 걸 느리게 만들 것처럼 들립니다. 실제로는 그 반대입니다 — 가짜 “완료”를 30초 만에 잡는 게, 3일 뒤 프로덕션에서 발견하는 것보다 빠릅니다.

---

Related: Claude 스킬 vs. 슬래시 명령어 vs. 서브에이전트 · 제가 30개 이상의 프로덕션 에이전트를 운영하는 에이전트 스택 · 휴먼인더루프 AI 에이전트: 승인 게이트는 언제 만들어야 하나 · Claude 예약 작업 사용법

당신의 비즈니스에서도 Claude Code를 이렇게 운영하고 싶으신가요? 제 AI Agents for Beginners 코스는 이 플레이북이 전제하는 구축 기초를 다룹니다. 코워크 프로그램은 이런 운영 습관을 구조화된 그룹 안에서 가르치는 곳입니다. 설정 자체를 대신 해주길 원하신다면 30분 세션을 예약하세요.