CLAUDE.md는 예산입니다

내가 읽는 모든 CLAUDE.md는 점점 커진다. 아무도 그것을 줄이지 않는다. 그것이 증상이다. 진짜 질병은 그것을 시스템 프롬프트 (System Prompt)가 아닌 문서 (Documentation)처럼 취급하는 것이다.

이 파일은 매 턴마다 컨텍스트 (Context)에 로드된다. 당신이 추가하는 모든 줄은 Claude가 중요한 규칙을 찾기 위해 읽어야 하는 한 줄이 된다. 줄을 충분히 추가하면, 중요한 규칙은 당신이 만든 건초더미 속의 바늘이 되어버린다. 더 나쁜 것은, 의미가 조용히 변한다는 것이다. 오늘 중요한 규칙은 당신이 6주 전에 기록했을 때 중요했던 규칙이 아니다.

이 프레임워크의 전환은 작지만 하중을 견디는 핵심적인 부분이다. CLAUDE.md는 시스템 프롬프트 (System Prompt)이다. 이는 토큰 (Tokens)이 예산임을 의미한다. 신호 (Signal)가 유의미하게 저하되기 전까지 당신에게는 약 500줄 정도의 지시 사항 라인이 있다. 당신은 그것을 어떻게 사용할 것인가?

세 가지 범주

파일을 한 줄씩 훑어보라. 각 줄은 세 가지 범주 중 하나에 속한다.

결정론적 적용 가능 (Deterministic eligible). "마이그레이션 (Migrations)을 절대 수정하지 마세요." "커밋 전에는 항상 린트 (Lint)를 실행하세요." "Python 변수에는 snake_case를 사용하세요." 이것들은 훅 (Hook)이나 설정 항목이 기계적으로 강제할 수 있는 규칙들이다. 이것들은 Claude의 판단을 필요로 하지 않기 때문에 산문 (Prose) 형태로 존재할 필요가 없다. 이것들에게 필요한 것은 가드 (Guard)이다.

확률론적 전용 (Probabilistic only). "기존 코드 스타일을 맞추세요." "사용자의 경험을 고려하세요." "리팩터링 (Refactoring) 전에 마이그레이션 비용을 따져보세요." 이것들은 판단을 필요로 한다. 훅 (Hook)은 이것들을 강제할 수 없다. 이것들은 산문 (Prose)에 속한다.

모호함 (Vague). "도움이 되세요." "좋은 코드를 작성하세요." "주의하세요." 이것들은 열망에 불과하다. 이것들은 행동을 변화시키지 않는다. 아무것도 생산하지 못한 채 예산만 채운다. 삭제하라.

내가 살펴본 대부분의 CLAUDE.md 파일은 결정론적 적용 가능 항목이 약 60%, 확률론적 항목이 25%, 모호한 항목이 15%였다. 결정론적인 항목이 가장 크게 움직일 수 있는 범주이다. 또한 Claude가 이를 놓쳤을 때 가장 많은 운영 사고 (Production incidents)를 일으키는 부분이기도 하다. 마이그레이션을 절대 수정하지 말라는 산문 (Prose) 규칙은 Claude가 실제로 수정하는 날을 막아주는 보호책이 되지 못한다.

결정론적 규칙에 있어 왜 훅 (Hooks)이 산문 (Prose)보다 나은가

산문 (Prose) 규칙은 권고 사항입니다. Claude는 이를 읽고 준수하려고 노력합니다. 파일이 짧고 규칙이 최근에 작성되었다면 대부분 잘 작동합니다. 하지만 파일이 2000줄에 달하고 규칙이 1400번째 줄에 묻혀 있다면, Claude는 때때로 이를 놓칩니다. 이는 운영 환경(production)에 도달하기 전까지는 알아차릴 수 없습니다.

훅 (Hooks)은 탈출구입니다. 훅은 실행되거나, 실행되지 않거나 둘 중 하나입니다. 만약 훅이 실행되었으나 실패한다면, 해당 동작은 일어나지 않습니다. 여기에는 확률적 경사 (probability gradient)가 존재하지 않습니다. "X를 절대 수정하지 마세요"라는 문구는 Bash 거부 규칙 (deny rule)이 되며, 여기서 "절대"는 "거의 항상"이 아니라 실제로 정말로 "절대"를 의미하게 됩니다.

경험 법칙 (rule of thumb): 만약 사후에 변경 사항을 읽음으로써 위반 여부를 감지할 수 있다면, 훅을 통해 동작이 일어나기 전에 감지할 수 있을 가능성이 높습니다. 그리고 훅을 통해 동작 전에 감지할 수 있다면, 산문 (prose)은 그 규칙을 담기에 적절한 장소가 아닙니다.

구체적인 마이그레이션 (Migrating)

Claude Code에서의 훅은 도구 이벤트 (tool event) 발생 시 실행되는 작은 프로그램입니다. PreToolUse는 Claude의 도구 호출 (tool call) 전에 실행되며 차단할 수 있습니다. PostToolUse는 호출 후에 실행됩니다. UserPromptSubmit은 사용자가 메시지를 제출할 때 실행되며 이를 재작성 (rewrite)할 수 있습니다. Stop은 Claude가 한 턴을 마칠 때 실행됩니다.

예시: "이 저장소에서 rm -rf를 절대 실행하지 마세요." 산문 형태는 하나의 바람(wish)일 뿐입니다. 훅 형태는 결정론적인 차단 (deterministic block)입니다:

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

Bash, Greps를 사용합니다. 매칭될 경우 0이 아닌 종료 코드 (exit non zero)를 반환합니다. Claude는 차단을 확인하고 적응합니다. 이제 규칙이 기계적으로 강제되므로, 당신은 기존의 산문 규칙을 삭제하면 됩니다.

CLAUDE.md의 절반은 이런 방식으로 옮길 수 있습니다. 옮길 수 없는 나머지 절반이 바로 중요한 부분입니다.

감사 (The audit)

작은 기술 (skill) 하나가 다음 카테고리에 따라 당신의 CLAUDE.md를 분류해 줍니다: github.com/blacksun-dev/claudemd-audit. 이를 .claude/skills/에 넣고 Claude에게 당신의 파일을 가리키게 하면 보고서를 받을 수 있습니다. 휴리스틱 (heuristics)이 완벽하지는 않습니다. 흔한 신호 패턴은 잡아내지만, 더 미묘한 패턴은 놓칠 수 있습니다. 이는 최종 결론이 아닌 시작점입니다.

출력 결과는 다음과 같습니다:

total file lines: 487
instruction lines: 312

...

모호한 28개의 라인은 쉽게 해결할 수 있는 부분입니다. 그냥 삭제하세요. 아무것도 망가지지 않습니다.

중복된 15개의 라인 역시 쉽게 해결할 수 있습니다. 이를 통합하세요.

결정론적인(deterministic) 191개의 적격 라인이 실제 프로젝트입니다. 그것이 마이그레이션(migration)입니다. 이 모든 것을 한 번의 주말 만에 끝낼 수는 없습니다. 상위 10개를 한 시간 만에 옮기고 그 차이를 느껴볼 수 있습니다.

남는 것

마이그레이션 이후 CLAUDE.md에 남는 것은 짧습니다. 50줄에서 150줄, 어쩌면 200줄 정도입니다. 이는 프로젝트 컨텍스트(context), 판단(judgment calls), 그리고 LLM이 진정으로 무게를 달아보아야 할 사항들로 구성된 집중된 브리프(brief)처럼 읽힙니다.

그것이 승리입니다. "더 작은 파일"이 아니라, "신호 밀도(signal density)가 더 높은 더 작은 파일"이 되는 것입니다. 결정론적인 규칙들이 사라졌기 때문에, 남아 있는 모든 규칙은 Claude가 실제로 주의 깊게 읽어야 하는 규칙이 됩니다. 이 규칙들은 더 이상 준수 여부를 확인하기 위해 주의력 예산(attention budget)을 소모하지 않습니다. 오직 위반되었을 때만 주의력 예산을 소모합니다.

습관

결정론적인 규칙들을 옮기고 나면 두 가지 일이 일어납니다.

첫째, "Claude가 틀렸다"라는 상황에 대한 기본 대응으로 CLAUDE.md에 새로운 규칙을 추가하는 것을 멈추게 됩니다. 대신 다음과 같이 질문하게 됩니다. "이것이 잘못된 판단(judgment call)이었는가, 아니면 작성되기를 기다리는 결정론적인 규칙이었는가?" 만약 결정론적이라면, 훅(hook)을 작성하세요. 판단의 문제라면, 산문(prose) 형태의 한 줄을 추가하세요. 둘둘 다 아니라면, 아무것도 추가하지 마세요.

둘째, 산문 형태의 문장들을 비용이 많이 드는 것으로 취급하기 시작합니다. 각 문장은 매 턴(turn)마다 읽힙니다. 각 문장은 주의력을 얻기 위해 다른 문장들과 경쟁합니다. 당신은 문장을 더 조밀하게, 글자당 더 많은 신호를 담아 작성하게 됩니다. 그리고 그 문장이 제 역할을 다하지 못하게 되면 삭제합니다.

감사(audit)는 일회성 작업이 아닙니다. 그것은 습관입니다. 분기에 한 번씩 현재의 CLAUDE.md에 대해 감사를 실행하여, 무엇이 모호하게 변했는지, 무엇이 중복되어 쌓였는지, 결정론적인 규칙의 비중이 어떻게 변했는지 확인하세요.

기술은 오픈 소스입니다

github.com/blacksun-dev/claudemd-audit. 가져가서 포크(fork)하고, 휴리스틱(heuristics)을 개선하세요. 오분류를 발견하면 이슈(issue)를 등록하세요. 목표는 2,000줄짜리 CLAUDE.md 파일을 줄이는 것입니다. 그게 전부입니다.