CLAUDE.md는 왜 가끔 무시되는가
전달 방식의 차이로 결정되는 강제력과 훅의 역할
"커밋 전 반드시 lint를 돌린다"를 굵게 적어두고도 주 1~2회 그냥 커밋되는 일이 생깁니다. CLAUDE.md 내용은 시스템 프롬프트가 아니라 시스템 프롬프트 뒤의 사용자 메시지로 전달되기 때문에 엄격한 준수가 보장되지 않습니다. 문구를 CRITICAL로 강화해도 전달 방식은 그대로이고, 오히려 과한 표현은 도구·스킬을 과도하게 트리거해 불안정해집니다. 규칙을 강하게 만들고 싶다면 문장을 고칠 것이 아니라 규칙이 놓인 자리를 바꿔야 합니다.
| 배치 위치 | 강제력 | 이럴 때 고른다 |
|---|---|---|
| CLAUDE.md·rules | 기대 수준(확률적) | 배경·관례·선호를 알릴 때 |
| --append-system-prompt | 시스템 프롬프트 수준 지침 | 우선순위는 올리되 실행은 자율일 때 |
| PreToolUse 훅 | 실행 전 차단 가능 | 어기면 되돌릴 수 없는 동작일 때 |
| InstructionsLoaded 훅 | 차단 불가, 관찰 전용 | 무엇이 왜 로드됐는지 감사할 때 |
| REVIEW.md | 리뷰 에이전트에 verbatim 주입 | 리뷰 심각도를 바꿔야 할 때 |
- 가역성 분류CLAUDE.md의 각 규칙을 되돌릴 수 있는 것과 없는 것으로 나눕니다.
- 훅으로 승격되돌릴 수 없는 규칙은 PreToolUse 훅으로 옮겨 차단 조건을 코드로 적습니다.
- 문서 정리문서에는 이유와 예외만 남기고 여러 파일에 복사된 문장을 지웁니다.
- 로딩 감사InstructionsLoaded 훅으로 어떤 지침이 왜 로드됐는지 기록만 남깁니다.