Claude Code는 매 세션마다 가장 먼저 CLAUDE.md 파일을 읽습니다. 그런데 이 파일이 조용히 600줄짜리 스타일 성경처럼 불어나 있다면, 그중 상당수는 무시되고 있을 가능성이 큽니다. 해결책은 더 좋은 문장이 아니라, 짧게 유지하는 원칙과 각 지시가 계층의 어느 수준에 속해야 하는지 아는 데 있습니다.
CLAUDE.md는 이렇게 관리해야 합니다: 상속 흐름, 간결함, 선택적 포함
CLAUDE.md는 Claude Code가 매 세션 시작 시 다시 불러오는 지속 메모리 파일입니다. Anthropic은 이 파일을 생성하는 일을 품질을 가장 크게 끌어올릴 수 있는 단일 개선책으로 설명합니다 . 처음부터 손으로 쓰지 마세요. 먼저 /init을 실행해 Claude가 빌드 시스템, 테스트 프레임워크, 코드 패턴을 분석해 초안을 만들게 하세요 . 그다음 덜어내면 됩니다. 빌드 명령, 코딩 표준, 아키텍처 결정, 워크플로 규칙, 주의할 함정처럼 오래 유지될 사실만 남기세요.
지시는 네 단계의 흐름을 따라 해석되며, 각 단계마다 대상이 다릅니다.
~/.claude/CLAUDE.md— 모든 프로젝트에 따라다니는 사용자 전체 선호 사항입니다../CLAUDE.md또는./.claude/CLAUDE.md— git에 커밋되어 팀이 공유하는 규칙입니다../CLAUDE.local.md— 한 기기에서만 쓰는 개인 메모이며 gitignore 처리됩니다.@path/to/docs.md— 참고 파일을 본문에 붙여 넣는 대신, 관련 있을 때만 불러오는 온디맨드 import입니다 .
대부분의 팀이 걸려 넘어지는 지점은 엄격한 상한입니다. 자동 메모리는 대략 처음 200줄 또는 25KB 정도를 읽습니다. 그 이후부터 Claude는 경고를 내기보다 지시를 조용히 무시하기 시작합니다 . 따라서 비대한 파일은 짧은 파일보다 더 나쁩니다. 중요한 규칙의 힘을 희석하기 때문입니다. 여러 단계로 된 절차는 CLAUDE.md 밖으로 빼서 .claude/skills/에 넣으세요. 이 파일들은 호출될 때만 로드됩니다 . 모노레포라면 루트 파일을 부풀리지 말고, 하위 디렉터리별로 부모와 자식 CLAUDE.md 파일을 연결해 각 패키지가 자기 문맥을 갖게 하세요 .
수정하기 전에 먼저 살피세요: 읽기 전용 조사와 승인된 개요
낯선 저장소에서 단 한 줄의 수정을 요청하기 전, Claude에게 관련 파일을 찾고 아키텍처, 데이터 모델, 인증, 실행 흐름을 그려보게 하세요. 실제 코드 경로에 기반한 수정은 추측에 기대어 만든 수정보다 회귀가 훨씬 적습니다. 권장 워크플로는 명확합니다. Explore → Plan → Implement → Commit입니다. 이때 탐색 단계가 있는 이유는 Claude가 엉뚱한 문제가 아니라 올바른 문제를 풀게 하기 위해서입니다 .
Plan mode는 이 원칙을 공식화한 형태입니다. 읽기 전용으로 동작합니다. Claude는 아무것도 실행하지 않고 파일 전반에 걸쳐 변경 범위를 매핑하며, 사용자는 Ctrl+G를 눌러 편집기에서 초안 개요를 열고 실제 계획을 검토한 뒤 변경을 승인합니다 . 여러 파일에 걸친 작업, 낯선 코드, 위험도가 높은 작업에 사용하세요. Meta의 한 스태프 엔지니어는 이렇게 말합니다. "저는 Claude가 전체를 읽고 계획을 제안하게 한 뒤에야 뭔가를 건드리게 합니다. 회귀는 바로 그 단계에서 잡힙니다" (video: John Kim).
승인만으로 검증이 끝나는 것은 아닙니다. Claude가 스스로 평가할 수 있는 종료 조건을 주세요. 실행할 테스트, lint 통과, 빌드 종료 코드, fixture diff 같은 것입니다. 지시는 "작동하게 해줘"가 아니라 "이게 통과할 때까지 반복해"라고 표현하세요 . 이를 매 턴 다시 확인되는 /goal 완료 조건으로 높이거나, 스크립트가 통과하기 전에는 턴이 끝나지 않도록 막는 Stop hook으로 확장할 수도 있습니다 .
디버깅에서는 같은 루프가 반대로 적용됩니다. 정확한 실패 명령, 스택 트레이스, 기대 출력을 제공한 다음, Claude에게 먼저 실패하는 테스트를 작성하고 코드를 고친 뒤 대상 테스트만 실행하라고 요청하세요 . 전체 테스트 스위트가 아니라 범위가 제한된 테스트를 실행하면 변경이 좁게 유지되고, 자율 수정이 엇나가게 만드는 범위 확장을 막을 수 있습니다. 엣지 케이스 테스트는 수정 뼈대가 잡히고 초록색이 된 뒤에 요청하세요.
슬래시 정의, 위임, 결정적 콜백
수정 범위가 정해지면, 다음으로 큰 효과는 반복 작업을 프롬프트로 다시 입력하는 대신 호출 가능한 단위로 묶는 데서 나온다. 스킬은 .claude/skills/<name>/SKILL.md에 저장되고 /name으로 호출되는 절차다. 스킬에는 호출될 때만 로드되는 보조 스크립트를 함께 넣을 수 있어, 필요해지기 전까지 세션 컨텍스트를 차지하지 않는다 . 배포, 리뷰, 마이그레이션, 이슈 수정 같은 흐름은 스킬에 두는 것이 맞다. 바로 CLAUDE.md 밖으로 빼고 싶은 다단계 절차들이다.
부작용이 있는 작업이라면 disable-model-invocation: true를 지정해 사람만 실행할 수 있게 하고, Bash(git add *) 같은 좁은 범위의 도구만 allowed-tools로 사전 승인하라 . Claude가 자율적으로 실행할 수 없는 배포 스킬은 가장 저렴하게 만들 수 있는 안전장치다:
---
name: deploy
disable-model-invocation: true
allowed-tools: Bash(git add *)
---
Run the staging deploy, then report the build exit code.위임은 안전뿐 아니라 컨텍스트에도 같은 방식으로 작동한다. .claude/agents/에 전용 모델과 좁은 도구 허용 목록을 가진 서브 에이전트를 정의하라. 적대적 보안 리뷰에는 Opus, 읽기 전용 코드베이스 검색에는 Haiku처럼 나누면, 비용이 크거나 컨텍스트를 많이 쓰는 작업이 메인 세션을 오염시키지 않는다 . 내장 Explore 서브 에이전트는 이미 Haiku에서 실행되며 Write와 Edit를 거부한다 .
매번 반드시 실행되어야 하는 동작은 지시문이 아니라 훅을 사용하라. .claude/settings.json에서 편집하거나 /hooks로 설정하는 훅은 에디터 이벤트에 맞춰 결정적 스크립트를 실행한다. 예를 들어 매 수정 후 eslint를 돌리거나, 테스트 스위트로 턴 완료를 막을 수 있다 .
마지막으로 Jira, Sentry, GitHub, 데이터베이스 같은 외부 컨텍스트는 claude mcp add <server>로 연결한다. changelog 2.1.186 기준으로 2026년 6월 22일부터 claude mcp login/logout이 명령줄 MCP 인증을 처리한다 . 다만 대부분의 작업에서는 gh, aws, gcloud 같은 CLI 도구가 MCP API 래퍼보다 컨텍스트 효율이 높으므로 기본 통합 방식으로 삼는 편이 좋다 .
예상 가능한 함정과 시도해볼 만한 실험
컨텍스트 오버플로는 가장 크게 발목을 잡는 실패 모드다. 조용히 발생하기 때문이다. 길고 끊기지 않은 세션에서는 창이 차오를수록 출력 품질이 낮아지지만, 이를 알려주는 오류는 없다 . 의도적으로 관리하라. /compact <instructions>는 진행 중인 세션을 요약하고, /clear는 서로 무관한 작업 사이에서 컨텍스트를 초기화하며, Esc+Esc 또는 /rewind는 체크포인트를 복원한다. 단, 체크포인트는 Claude가 만든 변경만 스냅샷으로 남기며 임의의 외부 수정은 포함하지 않는다. 따라서 git의 대체물이 아니다 .
Auto 모드는 완전한 권한 부여가 아니라 리서치 프리뷰 단계의 안전 인프라로 다뤄야 한다. 2026년 arXiv 스트레스 테스트(AmPermBench: 프롬프트 128개, 상태 변경 작업 253개)는 의도적으로 모호한 DevOps 프롬프트에서 엔드투엔드 false negative가 81.0%에 달한다고 보고했다. 많은 상태 변경 파일 수정이 분류기의 범위 밖에 있었기 때문이다 . 논문이 말하듯, 프롬프트 수가 줄어드는 것이 곧 안전을 뜻하지는 않는다. 영향 범위가 큰 작업에서는 분류기만 믿기보다 /sandbox의 OS 수준 격리와 명시적 허용 목록을 우선하라 .
규모를 키울 때의 지렛대는 헤드리스 모드다. 다음 명령은 CI나 pre-commit 훅에 연결할 수 있다:
claude -p "fix lint errors in changed files" --output-format json --allowedTools "Bash(eslint *),Edit"대규모 마이그레이션은 파일 목록을 만들고 범위가 제한된 호출을 루프 실행하는 방식으로 분산하라. 병렬 에이전트가 같은 파일에서 충돌하지 않도록 동시 세션은 별도의 git worktree에서 실행한다 .
다음으로 실험해볼 만한 것들은 2026년 6월 22일 changelog 2.1.186에 추가된 명령줄 MCP 인증용 claude mcp login , 프로그래밍 방식 오케스트레이션을 위한 Agent SDK query() 인터페이스, GitHub Action 예약 작업, 그리고 git 브랜치처럼 이름 있는 세션을 분기하고 재개하는 claude --continue 또는 --resume이다 . 결론은 앞의 내용과 일관된다. 가장 큰 효과를 내는 제어점은 프롬프트 표현이 아니라 컨텍스트, 권한, 반복 가능한 인프라다. CLAUDE.md는 짧게 유지하고, 변경 전 검증하며, 결정적 콜백으로 작업을 통제하라.
자주 묻는 질문
CLAUDE.md는 실제로 어느 정도 길이가 적당할까요?
대략 200줄 또는 25KB 이하로 유지하세요. 이 범위가 매 세션 자동 메모리에 로드되는 창입니다 . 그보다 길어지면 Claude가 지침을 조용히 무시하기 시작하므로, Anthropic도 비대해진 파일은 품질을 떨어뜨린다고 경고합니다 . 오래 유지될 사실만 넣으세요. 빌드 명령, 코딩 표준, 아키텍처 결정, 워크플로 규칙, 알려진 주의점 정도면 충분합니다. 여러 단계 절차는 호출될 때만 로드되는 .claude/skills/ 파일로 옮기고, 긴 문서를 붙여 넣는 대신 @path import로 참조하세요.
Claude가 바로 수정하게 두지 말고 plan mode를 써야 할 때는 언제인가요?
여러 파일에 걸친 리팩터링, 익숙하지 않은 코드베이스, 인증·스키마·공개 API 표면을 건드리는 변경에는 plan mode를 쓰세요. plan mode는 읽기 전용이므로 Claude가 아무것도 바꾸지 않은 채 변경 범위를 파악하고 구체적인 개요를 만듭니다. 승인하기 전에 이를 검토하면 됩니다(계획을 에디터에서 열려면 Ctrl+G를 누르세요) . 핵심은 쉽게 되돌리기 어려운 여러 파일에서 Claude가 엉뚱한 문제를 자신 있게 해결하지 못하게 막는 것입니다. 위험이 낮은 단일 파일 수정이라면 생략하고 Claude가 바로 작업하게 해도 됩니다.
skill과 sub-agent의 실질적인 차이는 무엇인가요?
skill은 재사용 가능한 slash 호출 워크플로 스크립트입니다(.claude/skills/<name>/SKILL.md에 정의). 프롬프트와 지원 파일을 함께 묶고 필요할 때 로드되므로, 배포·리뷰·마이그레이션처럼 반복 가능한 작업에 적합합니다 . sub-agent는 자체 모델과 도구 허용 목록을 가진 격리된 컨텍스트에서 실행됩니다 . 작업이 메인 컨텍스트를 넘치게 만들 정도로 크거나 다른 모델이 필요할 때 sub-agent를 쓰세요. 예를 들어 Opus 기반 보안 리뷰어, 또는 Haiku에서 동작하는 내장 읽기 전용 Explore agent가 그런 경우입니다.
Claude Code의 auto permission mode는 프로덕션에 안전한가요?
auto mode는 보안 경계가 아니라 프롬프트를 줄여 주는 편의 계층으로 보세요. 2026년 arXiv 스트레스 테스트(AmPermBench, 128개 프롬프트)에서는 의도적으로 모호하게 만든 DevOps 프롬프트에서 end-to-end false negative가 81.0%로 나타났습니다. 주된 이유는 상태를 바꾸는 많은 파일 수정이 classifier의 범위 밖에 있었기 때문입니다 . 프롬프트가 줄어든다고 완전한 권한 부여 안전성이 생기는 것은 아닙니다. 실제 영향 범위가 있는 작업이라면 classifier에 기대기보다 /sandbox OS 수준 격리와 좁은 allowlist를 우선하세요.
CI에서 Claude Code를 비대화식으로 실행하려면 어떻게 하나요?
headless mode를 사용하세요. claude -p "prompt" --output-format json(스트리밍은 --output-format stream-json)을 CI, pre-commit hook, pipeline에 연결할 수 있습니다 . 큰 마이그레이션에서는 대상 파일 목록을 만들고 범위를 좁힌 claude -p 호출을 반복하세요. 각 실행이 건드릴 수 있는 범위는 --allowedTools로 제한합니다 . 동시에 실행할 때 수정 충돌이 나지 않도록 git worktree를 추가해 각 invocation이 별도 브랜치에서 작업하게 하세요.
