당신의 CLAUDE.md는 계속해서 커지기만 합니다. 모든 장애(incident)가 규칙을 하나씩 추가하고, 모든 선호 사항이 한 단락이 되며, 6개월이 지나면 위키(wiki)처럼 읽히는 파일이 생깁니다. 그리고 에이전트(agent)는 그중 절반 정도만 따르게 되죠.

불편한 메커니즘: CLAUDE.md는 컨텍스트(context)에 자동으로 로드됩니다. 이는 해당 내용이 관련이 있든 없든, 모든 라인이 매 요청마다 토큰 비용(tax)을 발생시킨다는 것을 의미합니다. 또한 지침은 권고 사항(advisory)일 뿐입니다. 지침이 많아질수록 각 지침의 영향력은 약해집니다. 저는 긴 세션 동안 저의 규칙들이 조용히 무시되는 것을 지켜보았고, 나중에 diff를 통해서야 이를 발견했습니다.

따라서 진짜 질문은 "CLAUDE.md에 무엇을 써야 할까?"가 아닙니다. "무엇이 컨텍스트 내에 영구적인 자리를 차지할 자격이 있는가 — 그리고 그 외의 것들은 어디에 두어야 하는가?"입니다.

Claude Code는 가이드를 배치할 수 있는 네 가지 장소를 제공하며, 이들은 매우 다른 비용 모델을 가집니다:

제가 사용하는 분류 테스트를 소개합니다. 목적지당 한 문장씩 정리했습니다.

한 문장 테스트

모든 턴(turn)에서 유효하고, 기술하기 쉬우며, 위반했을 때 비용이 많이 드는 것이라면 CLAUDE.md에 유지하세요. 빌드 명령(build commands), 명명 규칙(naming conventions), "테스트는 test/에 위치하며 경로가 미러링됨", 커밋 메시지에 사용하는 어조 등이 이에 해당합니다. 만약 관련 없는 리팩터링(refactor) 도중에도 해당 규칙이 활성화되기를 원한다면, 그것은 불변량(invariant)입니다. 항상 로드되는 파일은 바로 그런 용도로 사용됩니다.

"X를 할 때"로 시작하는 내용이라면 skill로 옮기세요. 배포 체크리스트(deploy checklists), 리뷰 루브릭(review rubric), 릴리스 노트(release-notes) 형식, 마이그레이션 플레이북(migration playbook) 등이 해당합니다. skill의 이름과 설명은 에이전트가 존재를 알 수 있도록 계속 표시되지만, 본문은 실제 작업이 일치할 때만 로드됩니다. 이것이 바로 상황별 전문 지식(situational expertise)에 대해 당신이 원하는 방식입니다: 발견 가능하지만, 매 요청마다 비용이 청구되지는 않는 방식 말이죠. (형식 상세 정보: 실제로 트리거되는 SKILL.md를 작성하는 방법).

문장에 "never" 또는 "always"가 포함되어 있고 기계가 이를 검사할 수 있다면 hook으로 옮기세요. 커밋 전 포맷팅 (Formatting before commit), 보호된 경로 (protected paths), ".env 파일을 건드리지 마세요", "main 브랜치로의 push 차단" 등이 이에 해당합니다. 쉘 스크립트 (shell script)가 강제할 수 있는 내용을 언어 모델 (language model)에게 _기억_해달라고 요청하지 마세요. hook은 컨텍스트가 새로 생성되었든 50개의 파일이 쌓인 상태든 결정론적으로 실행됩니다. (Hook 설정 구조 및 매처 (Hook config structure and matchers)).

에이전트가 _준수(obey)_해야 하는 것이 아니라 읽어야(read) 하는 것이라면 docs 파일로 옮기세요. 아키텍처 개요 (Architecture overviews), API의 특이사항 (API quirks), 결제 모듈이 왜 이상하게 설계되었는지에 대한 이력 등이 해당됩니다. 이를 docs/에 넣고, CLAUDE.md에는 언제 읽어야 하는지 한 줄만 남겨두세요: "결제 관련 작업을 하나요? 먼저 docs/billing-history.md를 읽으세요." 참조 자료는 관련이 있을 때만 컨텍스트 (context)를 점유하도록 합니다.

기본 답변이 "CLAUDE.md가 아니다"인 이유

항상 로드되는 경로(always-loaded path)에는 세 가지 비용이 중첩됩니다:

1. 매 요청마다 비용을 지불합니다. 4,000 토큰 분량의 CLAUDE.md는 모든 프롬프트 (prompt), 모든 도구 호출 (tool call) 왕복 과정에서 하루 종일 4,000 토큰을 소모합니다. 최근 제 설정에서 이 감사를 수행해 본 결과, 파일의 절반은 릴리스 날에만 중요했습니다. 그 절반을 분리해냈더니 모든 요청의 오버헤드 (overhead)가 줄어들었으며 아무것도 망가지지 않았습니다.
2. 주의력(Attention)이 희석됩니다. 20개의 규칙이 있다면 모델의 준수 예산 (compliance budget)을 아주 조금씩 나누어 갖게 됩니다. 반면 5개의 규칙은 실질적인 무게감을 갖습니다. 이것은 문서화된 파라미터 (parameter)는 아니지만, 제가 실무에서 일관되게 목격하는 현상입니다. 즉, 가벼운 파일은 규칙을 잘 지키지만, 비대한 파일은 마치 제안 사항처럼 샘플링되어 무시됩니다.
3. 긴 세션은 문장을 마모시킵니다. 컨텍스트가 diff와 도구 출력값으로 채워짐에 따라 초기 지침은 희미해집니다. 그리고 압축 (compaction) 과정을 거치고 나면 살아남는 것은 요약본이지, 당신의 정확한 문구가 아닙니다. (압축 후에도 살아남는 것과 규칙을 유지하는 방법 (What survives compaction, and how to keep rules alive)).

Hooks는 세 가지 모두를 회피합니다. Skills는 처음 두 가지를 회피합니다. Docs는 세 가지 모두를 회피하지만 아무것도 강제하지 않습니다. CLAUDE.md는 그 대가를 온전히 치르는 유일한 슬롯입니다. 그러니 그럴 가치가 있는 소수의 규칙에만 사용하세요.

군더더기 없는 CLAUDE.md의 모습

# myproject — agent guide

## Commands
...

이것이 전체적인 구조입니다: 명령(commands), 불변 사항(invariants), 기계에 의해 강제되는 항목에 대한 포인터, 맵(map), 그리고 에스컬레이션 규칙(escalation rule). 단 한 화면 분량입니다. "hooks에 의해 강제됨(enforced by hooks)" 섹션은 의도적으로 중복되어 있습니다. 강제하는 것은 hook이 수행하며, 언급은 단지 에이전트가 당황하지 않게 하기 위함입니다.

비대해진 파일을 약 20분 만에 마이그레이션하기

1. 측정하기. CLAUDE.md 내용을 토큰 카운터(token counter)에 붙여넣으세요. 숫자를 기록해 두세요. 이것이 당신의 '이전' 상태입니다.
2. 모든 블록에 라벨 붙이기. 다음 네 가지 단어 중 하나로 분류하세요: always (매 턴마다 참), situational ("X를 수행할 때"), never-event (기계로 확인 가능한 금지 사항), reference (지시가 아닌 설명).
3. _always_가 아닌 모든 것을 이동하기. Situational → 트리거를 명시하는 설명과 함께 .claude/skills/<name>/SKILL.md로 이동. Never-events → hooks 또는 CI 체크로 이동. Reference → docs/로 이동하고, 한 줄의 포인터만 남겨둡니다.
4. 카나리(canary) 추가하기. 해롭지 않고 눈에 띄는 규칙 하나를 추가하세요 — 예: "src/billing을 다루는 응답은 반드시 BILLING이라는 단어로 시작할 것" — 이렇게 하면 파일이 제대로 준수되고 있는지 한눈에 알 수 있습니다. (실제로 실행된 내용을 확인하는 더 많은 방법).
5. 매달 재측정 및 재감사하기. 파일은 다시 커지려고 할 것입니다. 새로운 규칙을 추가하고 싶다면, 먼저 '한 문장 테스트'를 통과하게 하세요. 대부분의 후보는 상황에 따라 다르거나(situational) 기계로 확인 가능(machine-checkable)하므로, 하위 단계(downstream)로 분류되어야 합니다.

한 가지 솔직한 주의 사항(caveat)을 말씀드리자면, 이 중 그 어떤 것도 산문 형태의 규칙(prose rules)을 신뢰할 수 있게 만들어주지는 않습니다. 권고 사항은 어디까지나 권고 사항일 뿐입니다. 분류(sort)를 통해 얻을 수 있는 것은 모델이 실제로 유지할 수 있을 만큼 충분히 작고 항상 로드되어 있는 핵심(core)이며, 여기에 진정으로 위반될 수 없는 항목들에 대한 결정론적 강제(deterministic enforcement)가 더해지는 것입니다. 만약 이 모든 과정을 거친 후에도 규칙이 계속 깨진다면, 그것은 해당 규칙이 처음부터 훅(hook)이 되어야 했다는 신호입니다.

애초에 여러분의 규칙 파일이 어떻게 읽히는지 확실하지 않다면 — CLAUDE.md, AGENTS.md, 그리고 Cursor의 규칙은 모두 로드 방식이 다릅니다 — 각 도구가 실제로 프로젝트 규칙을 로드하는 방식부터 시작하세요.

저는 Rulestack입니다 — 저는 rulestack.gumroad.com에서 Claude Code, Cursor, 그리고 Codex를 위한 즉시 사용 가능한 규칙, 기술(skill), 훅(hook) 팩을 제작하고 유지 관리합니다. Bluesky의 @ai-shop.bsky.social에서 실용적인 AI 코딩 팁을 게시하고 있으니, 이 내용이 유익했다면 팔로우해 주세요.