CLAUDE.md 파일이 너무 길어서 Claude Code가 이를 무시하는 이유

모두가 Claude Code를 사용하며 똑같은 벽에 부딪힙니다. CLAUDE.md에 규칙을 하나 추가합니다. 잘 작동합니다. 열 개를 더 추가합니다. 대부분 잘 작동합니다. 마흔 개를 더 추가합니다 — 그러면 이제 Claude는 당신이 가장 중요하게 생각하는 규칙, 즉 첫날부터 그 자리에 있었던 규칙을 아주 밝게 웃으며 무시하기 시작합니다. 그래서 당신은 대문자로 쓰고, 느낌표 세 개를 붙여서 더 강하게(LOUDER) 만듭니다. 그래도 여전히 건너뜁니다.

본능적으로는 더 많이 쓰려고 하게 됩니다. 하지만 해결책은 거의 항상 더 적게 쓰는 것입니다. 그 이유와 대신 무엇을 해야 하는지 알려드리겠습니다.

지시 이행(Instruction-following)에는 예산이 있으며, 당신은 초과 지출 중입니다

이 부분은 대부분의 CLAUDE.md 가이드에서 생략하는 내용입니다. 최첨단 모델(Frontier models)은 한 번에 150~200개의 지시 사항 정도를 안정적으로 따릅니다. 그리고 규칙을 쌓아 올릴수록 단일 규칙에 대한 준수율은 떨어집니다. 이것은 절벽처럼 갑자기 떨어지는 것이 아니라, 서서히 부과되는 세금과 같습니다. 당신이 추가하는 모든 줄은 다른 모든 줄이 준수될 가능성을 조금씩 낮춥니다.

이제 당신이 통제할 수 없는 부분을 빼보십시오. Claude Code 자체의 시스템 프롬프트(System prompt)가 당신의 파일이 읽히기도 전에 이미 그 예산의 상당 부분을 사용합니다. 따라서 당신의 프로젝트 규칙을 위한 가용 예산은 헤드라인에 나오는 숫자보다 작습니다. 300줄에 달하는 방대한 CLAUDE.md는 300개의 규칙이 준수되는 것이 아니라, 아마 처음 150개 정도만 잘 준수되고 나머지는 배경 소음(Ambience)처럼 취급될 뿐입니다.

이후의 모든 문제를 해결하는 사고 모델(Mental model): CLAUDE.md는 위시리스트(Wishlist)가 아니라 예산(Budget)입니다. 당신은 문서를 작성하고 있는 것이 아닙니다. 당신은 희소한 주의력 허용치(Attention allowance)를 소비하고 있으며, 모든 줄은 서로 경쟁하고 있습니다.

모든 줄에 대한 테스트: 이 규칙이 지켜질 것이라고 5달러를 걸 수 있습니까?

파일을 한 줄씩 훑으며 각 규칙에 대해 한 가지 질문을 던지십시오: 이 규칙이 관련될 때마다 실행될 것이라고 돈을 걸 수 있는가?

세 가지 결과가 나옵니다:

• 네, 그리고 이는 핵심적인 역할을 합니다 (Load-bearing) — 유지하십시오. 이것이 바로 예산을 사용하는 목적입니다.
• 있으면 좋지만, 돈을 걸 정도는 아닙니다 — 삭제하거나, (아래에서 설명할) 참조 파일로 옮기십시오. 이는 당신이 돈을 걸 만한 규칙들을 희석시킵니다.
• 매번 반드시 일어나야만 합니다 — 그렇다면 그것은 CLAUDE.md에 있을 것이 아니라 훅(Hook)으로 만들어야 합니다.

세 번째 카테고리는 사람들이 흔히 오해하는 부분입니다. 그러니 구체적으로 살펴보겠습니다.

권고(Advisory) vs 결정론적(Deterministic): 무엇이 필요한지 파악하세요

CLAUDE.md 규칙은 하나의 _요청(request)_입니다. 성능이 좋은 모델은 이를 대부분의 경우 — 약 80% 정도 — 준수합니다. 스타일 선호도, 명명 규칙(naming conventions), "리팩터링(refactor)하기 전에 설명할 것"과 같은 사항에 대해서는 80%의 준수율로도 충분합니다. 이를 어겼을 때의 비용이 낮기 때문입니다.

하지만 어떤 규칙들은 5번 중 1번의 실패도 허용할 수 없습니다. 예를 들어, 비밀번호(secrets)를 절대 커밋하지 말 것, production.env를 절대 건드리지 말 것, 완료를 선언하기 전에 항상 테스트 스위트(test suite)를 실행할 것 등입니다. 이러한 경우에는 아무리 강한 어조로 표현하더라도 산문(prose)은 적절한 도구가 아닙니다. 여러분에게 필요한 것은 **훅(hook)**입니다. 즉, Claude Code가 자신의 라이프사이클(lifecycle) 내 특정 시점에 자동으로 실행하는 셸 명령(shell command)입니다. 훅은 모델에게 협조를 요청하는 것이 아니라, 모델이 "그렇게 느끼든 말든" 매번 결정론적(deterministically)으로 실행됩니다.

실제 적용 단계는 다음과 같습니다. CLAUDE.md 버전 — 권고형, 약 80%:

# in CLAUDE.md
- Never edit .env files or anything under .git/. Never commit secrets.

훅 버전 — 결정론적, 100%. 쓰기 작업이 일어나기 전에 이를 _차단(blocks)_하는 PreToolUse 훅:

{
  "hooks": {
    "PreToolUse": [{
...

종료 코드(Exit code) 2는 Claude Code에 해당 작업이 거부되었음을 알리고 그 이유를 모델에 다시 전달합니다. 따라서 모델은 조용히 실패하는 대신 상황에 맞춰 적응합니다. 이 훅이 대체한 규칙은 이제 CLAUDE.md에서 완전히 제거할 수 있습니다. 여러분은 컨텍스트 예산(budget) 한 줄을 확보했을 뿐만 아니라, 반드시 실행되어야 하는 규칙을 80%에서 100%로 업그레이드한 것입니다. 이것이 바로 모든 중요한 규칙에서 여러분이 추구해야 할 트레이드오프(trade-off)입니다.

모든 규칙에는 이유가 필요합니다 — 그렇지 않으면 일반화할 수 없습니다

"Use tabs, not spaces"는 말 그대로 단 한 번만 적용되는 규칙입니다. 반면 "Use tabs, not spaces — our linter rejects spaces and the build fails"는 모델이 _추론(reasoning)_할 수 있는 규칙입니다. 이제 모델은 근저에 깔린 제약 사항을 알게 되었으므로, 당신이 명시적으로 설명하지 않은 상황에서도 올바른 결정을 내릴 것입니다. 이유가 있는 규칙은 일반화(generalize)됩니다. 단순한 명령은 당신이 작성한 정확한 경우에만 따르게 되며, 맥락이 아주 조금만 바뀌어도 조용히 무시됩니다. 이유는 군더더기가 아닙니다. 규칙이 컨텍스트 예산(budget) 내에서 자리를 차지할 가치가 있게 만드는 핵심입니다.

점진적 공개 (Progressive disclosure): 핫 패스(hot path)를 짧게 유지하세요

"짧은 파일"과 "철저한 가이드" 사이에서 반드시 하나를 선택해야 하는 것은 아닙니다. CLAUDE.md에는 _대부분_의 작업에 적용되는 규칙만 남겨두고, 나머지는 경로를 통해 참조할 수 있는 별도의 집중된 파일들로 분리하세요.

# CLAUDE.md (항상 로드되는 핫 패스 — 가볍게 유지하세요)
- 어떤 작업이 완료되었다고 선언하기 전에 `npm test`를 실행할 것.
- API 컨벤션은 docs/api-guidelines.md에 있습니다 — routes/를 수정하기 전에 이를 읽으세요.
...

Claude는 실제로 마이그레이션(migration) 작업을 수행할 때만 docs/migrations.md를 컨텍스트로 가져옵니다. 상세한 가이드는 여전히 온전하게 존재하지만, 해당 가이드가 불필요한 90%의 작업에서는 당신의 예산을 소모하지 않습니다. 당신의 CLAUDE.md는 응집도 높고 준수율이 높은 핵심(core)으로 유지되며, 깊이 있는 내용은 필요할 때만 로드되는 한 단계 떨어진 곳에 존재하게 됩니다.

20분 감사 (The 20-minute audit)

지금 바로 CLAUDE.md를 열고 다음 과정을 수행해 보세요:

• 줄 수를 세어보세요. 약 150줄을 넘어서고 있나요? 그것만으로도 "왜 내 말을 무시하지?"라는 현상의 많은 부분이 설명됩니다.
• 5달러를 걸 수 없는 규칙은 모두 삭제하세요. 냉정해져야 합니다. 내용이 희석된 파일은 그 어떤 것도 제대로 따르지 못합니다.
• 반드시 실행되어야 하는 규칙을 찾아 훅(hook)으로 만드세요. 비밀 정보, 파괴적인 명령, 완료 전 테스트 수행 등이 해당됩니다. 이를 산문 형태의 설명에서 분리하세요.
• 살아남은 모든 규칙에 이유를 추가하세요. 왜 그래야 하는지 설명할 수 없다면, 그 규칙은 필요 없는 것입니다.
• 작업별 상세 내용은 참조 파일로 이동시키세요. 핫 패스를 가볍게 유지하세요.

이 작업을 수행하는 거의 모든 사람은 정직하게도 Claude가 더 신뢰성 있게 따르는 더 짧은 파일을 갖게 됩니다. 이것은 역설이 아닙니다. 예산(budget)이 의도한 대로 작동하고 있는 것입니다.

한 단락 요약 버전

지시 사항 준수(Instruction-following)는 희소한 예산이지, 위시리스트가 아닙니다. 모델은 약 150~200개의 규칙을 안정적으로 따르며, 규칙을 더 많이 쌓을수록 준수율은 떨어집니다. 따라서 CLAUDE.md의 모든 줄은 당신이 돈을 걸 수 있을 만큼 확실한 것이어야 합니다. 돈을 걸 수 없는 내용은 삭제하고, 살아남은 각 규칙에는 일반화될 수 있는 이유를 부여하며, 작업별 상세 내용은 참조 파일로 밀어 넣고, 반드시 실행되어야 하는 규칙은 권고형 산문에서 결정론적 훅(deterministic hooks)으로 격상시키세요. 파일이 짧아질수록 준수율은 높아집니다.

이러한 원칙을 이미 따르고 있는 CLAUDE.md 템플릿과 함께, 바로 붙여넣을 수 있는 5가지 훅(위에서 언급한 보안 가드 포함), 서브 에이전트(subagents), 슬래시 명령(slash-command) 기술을 원하신다면, 제가 **Claude Code Power-User Pack**을 준비했습니다. 이제 막 시작하는 단계라면, 이메일 등록 없이도 7가지 신뢰성 규칙과 3가지 붙여넣기 가능한 가드레일(guardrails)을 다루는 **무료 필드 가이드(free field guide)**를 확인해 보세요.

당신의 CLAUDE.md가 계속 무시하는 단 하나의 규칙은 무엇인가요? 답글로 알려주세요. 생각보다 패턴이 반복될 것입니다.