CLAUDE.md 한계와 서브레딧 의견 공유

요약

CLAUDE.md에 규칙을 계속 추가할수록 오히려 준수율이 떨어지는 문제를 겪은 필자가, 규칙을 인프라로 옮기는 5단계 프레임워크를 정리한 글입니다. 668K 라인 코드베이스에서 198개 에이전트, 27개 실패 사례를 기반으로 Citadel이라는 오픈소스 시스템을 공개했습니다.

인사이트

• CLAUDE.md가 100줄을 넘으면 뒷부분 지시가 "제안" 수준으로 취급됩니다. 190줄로 늘렸을 때 오히려 준수율이 떨어졌습니다
• 감사 결과 40%가 중복·모순·시점 지남이었습니다. 123줄로 줄이자 즉시 개선됐습니다
• "규칙을 지켜라"는 지시는 확률적으로 무시될 수 있지만, 환경이 강제하는 훅은 무시할 수 없습니다

해결

1. CLAUDE.md는 라우터로만 사용

• 프로젝트 컨벤션, 기술 스택, 가장 중요한 5가지만 유지합니다
• 나머지는 필요할 때 로드되는 별도 파일로 분리합니다

2. 반복 지시 → 스킬 파일로 전환

• 도메인별 패턴·제약·예시를 마크다운 파일로 캡슐화합니다
• 현재 태스크에 해당하는 스킬만 로드하여 토큰을 절약합니다

3. 품질 검증 → 라이프사이클 훅으로 자동화

• 파일 저장마다 타입체크, 세션 종료 시 안티패턴 스캔을 자동 실행합니다
• 같은 이슈 3회 반복 실패 시 에이전트를 중단하는 서킷 브레이커를 적용합니다

4. 세션 간 컨텍스트 → 캠페인 파일로 유지

• 무엇을 만들었는지, 어떤 결정을 했는지, 남은 작업을 구조화된 문서로 기록합니다
• 세션을 닫고 다음 날 돌아와도 정확히 이어서 작업합니다

참고

• 댓글: Anthropic 공식 claude-md-management 플러그인이 마켓플레이스에 있다는 제보 (41 upvotes)
• 댓글: "규칙은 모델이 참이라고 생각하는 것을 알려주고, 도구는 실제로 참인 것을 보여준다" (2 upvotes)
• 댓글: git diff를 감시하여 문서를 자동 업데이트하는 aspens npm 패키지 공유 (35 upvotes)
• 레딧 r/ClaudeAI, score 517