CLAUDE.md에 규칙 추가하는 걸 멈추고 인프라를 구축하면 어떻게 되는가
What happens when you stop adding rules to CLAUDE.md and start building infrastructure instead
TL;DR Highlight
CLAUDE.md가 100줄을 넘으면 규칙 준수율이 오히려 떨어지는 문제를 해결하기 위해, 규칙 파일 대신 hooks·skill 파일·campaign 파일 등 환경 기반 인프라로 전환한 실전 경험담이다.
Who Should Read
Claude Code(구 claude.ai Projects)나 Claude 에이전트를 활용해 코딩 워크플로우를 자동화하려는 개발자. 특히 CLAUDE.md가 점점 길어지는데 Claude가 지시를 자꾸 무시한다고 느끼는 분들에게 직접적으로 유용하다.
Core Mechanics
- CLAUDE.md는 100줄을 넘어가면 규칙 준수율이 급격히 떨어진다. 작성자가 직접 190줄짜리 파일을 감사해보니 40%가 중복이었고, 서로 모순되거나 이미 유효하지 않은 규칙도 섞여 있었다. 123줄로 줄이자 즉시 준수율이 개선됐다.
- 진짜 해결책은 파일 트리밍이 아니라 '강제성의 위치'를 바꾸는 것이다. 'typecheck를 항상 실행해라'는 규칙 대신, 파일 저장 시 자동으로 typecheck를 실행하는 lifecycle hook으로 교체하면 Claude가 선택할 여지 자체가 없어진다.
- 반복적으로 설명하던 도메인 지식은 skill 파일(마크다운)로 분리한다. 에이전트가 현재 태스크에 맞는 skill 파일만 로드하기 때문에 불필요한 context 토큰이 0이 된다. 코드 리뷰 프로세스처럼 매 세션마다 재설명하던 것들이 여기에 해당한다.
- 세션이 끊기면 컨텍스트가 사라지는 문제는 campaign 파일로 해결한다. 무엇을 만들었는지, 어떤 결정을 내렸는지, 무엇이 남았는지를 구조화된 문서로 추적해서 다음 날 세션을 재개할 때 처음부터 설명할 필요가 없다.
- 인프라 수준을 5단계로 정의한다: 1) Raw prompting → 2) CLAUDE.md → 3) Skills(모듈식 전문성) → 4) Hooks(환경 기반 품질 강제) → 5) Orchestration(병렬 에이전트, 캠페인). 대부분의 프로젝트는 Level 2~3으로 충분하다.
- 작성자는 이 시스템을 668K 줄 코드베이스에서 198개 에이전트를 돌리며 27번의 실패를 통해 다듬었고, Citadel이라는 이름으로 오픈소스화했다. /do 명령어 하나로 태스크를 적절한 orchestration 레벨로 자동 라우팅해준다.
Evidence
- 작성자는 CLAUDE.md를 190줄 → 123줄로 줄인 직후 Claude의 규칙 준수율이 즉각 향상됐다고 보고했다. 40% 중복 제거와 모순 규칙 정리가 핵심이었다.
- '파일 저장 시 typecheck 자동 실행' hook을 도입한 뒤 리뷰 시간이 크게 줄었다고 한다. PR 리뷰 시점에는 타입 에러와 broken import가 이미 제거된 상태라, 의도와 설계만 검토하면 됐다.
- 668K 줄 규모의 실제 코드베이스에서 198개 에이전트를 운영하며 27번의 문서화된 실패를 거쳐 시스템을 구축했다고 명시되어 있다. 각 규칙은 실제로 무언가가 깨진 경험에서 도출됐다.
- session context 압축(compaction) 직전에 자동으로 상태를 저장하는 hook, 동일 이슈에서 3번 연속 실패 시 에이전트를 종료하는 circuit breaker 등 구체적인 hook 예시들이 실제 운영 중임을 시사한다.
How to Apply
- 지금 당장 CLAUDE.md를 열어서 감사해보자. 비슷한 말을 반복하는 규칙, 서로 모순되는 규칙, 더 이상 유효하지 않은 규칙을 찾아 제거한다. 100줄 이하를 목표로 프로젝트 컨벤션·기술 스택·가장 중요한 5가지만 남긴다.
- 자주 어기는 규칙이 있다면 그걸 규칙으로 유지하지 말고 환경으로 이전한다. 예를 들어 'lint 실행해라'는 규칙은 pre-save hook 스크립트로 교체하고, 코드 리뷰 프로세스는 별도 skill 마크다운 파일로 분리한다.
- Citadel 레포(https://github.com/SethGammon/Citadel)를 클론해서 skill 시스템, hooks, campaign 파일 구조를 참고한다. 전체 시스템을 도입하지 않더라도 campaign 파일 패턴만 가져와도 세션 간 컨텍스트 유실 문제를 즉시 줄일 수 있다.
Terminology
CLAUDE.mdClaude Code에서 프로젝트 루트에 두는 설정 파일. 세션 시작 시 Claude가 읽어서 프로젝트 컨벤션·지시사항을 파악한다. GitHub의 CONTRIBUTING.md와 비슷한 역할이지만 AI 에이전트를 위한 것.
lifecycle hook특정 이벤트(파일 저장, 세션 종료 등)가 발생할 때 자동으로 실행되는 스크립트. Git의 pre-commit hook처럼 개발자나 에이전트가 잊어버려도 강제로 실행된다.
context compactionClaude가 대화가 길어지면 이전 내용을 자동으로 압축·요약하는 동작. 이 과정에서 중요한 작업 상태나 결정 사항이 유실될 수 있다.
circuit breaker같은 문제에서 반복적으로 실패할 때 자동으로 에이전트 실행을 중단시키는 패턴. 무한 루프나 반복 실패로 인한 자원 낭비를 막기 위해 사용한다.