Claude Code를 팀에 도입하고 나서 가장 먼저 마주치는 착각이 있다. CLAUDE.md에 규칙을 잘 써두면 에이전트가 그걸 지킨다는 믿음이다. 틀린 말은 아니다. 잘 작성된 CLAUDE.md는 에이전트의 행동 방향을 잡아주는 데 확실히 효과가 있다. 문제는 그게 '보통은'이라는 단서가 붙는다는 점이다. 세션이 길어질수록, 컨텍스트가 오염될수록, 에이전트는 슬그머니 지침을 잊는다.
세 개의 소스를 조합해보면 같은 진단이 반복된다. dev.to의 Adrian Jiga는 6개월간 Claude Code를 운용한 경험에서 이렇게 말한다. "CLAUDE.md의 규칙은 요청이다. Claude는 보통 따르지만, '보통'은 보장이 아니다. 특히 긴 세션 후반부에선 더욱 그렇다." dev.to의 또 다른 분석 글은 더 명쾌하게 층위를 나눈다. 에이전트가 지침을 무시하는 것처럼 보일 때, 실제 원인은 세 가지 중 하나다. 파일이 애초에 세션에 로드되지 않았거나, 로드됐지만 현재 태스크에서 준수되지 않았거나, 아니면 애초에 모델 바깥에서 강제해야 할 결과를 지침으로 처리하려 했거나.
이 세 번째 경우가 핵심이다. '모델 바깥에서 강제해야 할 것'을 지침에 집어넣으면, 그건 에이전트에게 "제발 이렇게 해줘"라고 부탁하는 것과 같다. 팀 운용에서 '제발'이 통하는 통제 구조는 없다. 사람도 마찬가지이고, 에이전트는 더욱 그렇다.
Hooks: 에이전트가 기억하는지와 무관하게 작동하는 레이어
Claude Code의 Hooks는 바로 이 간극을 메우기 위해 설계됐다. Hooks는 에이전트의 라이프사이클 이벤트(PreToolUse, PostToolUse, Stop 등)에 셸 커맨드를 붙여두는 메커니즘이다. 에이전트가 도구를 호출하기 직전이나 직후에 지정한 스크립트가 실행되고, exit code 2를 반환하면 그 액션 자체가 차단된다. 에이전트가 규칙을 기억하는지 여부와 완전히 무관하게.
Adrian Jiga의 실전 셋업을 보면 이게 얼마나 실용적인지 바로 감이 온다. 그가 가장 먼저 만든 Hook은 위험한 Bash 커맨드 차단이었다. rm -rf /, DROP TABLE, chmod -R 777 / 같은 패턴이 감지되면 실행 전에 막는다. 그 다음은 파일 쓰기 전 시크릿 스캔이다. AWS 키, API 토큰, 프라이빗 키 블록이 코드에 포함되려는 순간 차단한다. 세 번째는 프로젝트 디렉토리 외부 접근 제한이다. ../../ 경로 트래버설이나 절대 경로를 통한 프로젝트 루트 탈출을 원천 봉쇄한다.
이 세 가지는 사실 새로운 규칙이 아니다. 시니어 개발자라면 PR 리뷰 때 머릿속에서 자동으로 체크하는 항목들이다. Hooks가 하는 일은 그 암묵적 판단을 코드로 외재화하는 것이다. 팀 전체가 같은 기준으로, 매번, 빠짐없이 적용받도록. 팀 컨벤션 강제도 마찬가지다. lint 에러가 있으면 commit을 막고, main 브랜치에 직접 push하거나 force-push를 시도하면 차단한다. 이 규칙들이 PR 템플릿이나 위키 문서에 적혀있을 때와, Hook으로 실행될 때의 차이는 '권고'와 '강제' 사이의 차이다.
CLAUDE.md의 진짜 문제: Context Rot
Hooks가 '강제 실행 레이어'라면, CLAUDE.md는 '방향 지시 레이어'다. 그런데 이 방향 지시 레이어가 제대로 관리되지 않으면 에이전트에게 오염된 지도를 쥐어주는 것과 같다. Anthropic의 공식 플러그인인 claude-md-management가 주목받는 이유가 여기 있다.
Context Rot은 CLAUDE.md가 시간이 지나면서 자연스럽게 부패하는 현상이다. 초기엔 명확했던 규칙들이 기능 추가와 버그 수정을 거치며 300줄, 500줄로 불어난다. 규칙 간 충돌이 발생하고, 오래된 컨텍스트가 새 컨텍스트와 뒤섞인다. 모든 프롬프트마다 이 오염된 규칙 덩어리가 통째로 주입되면서 토큰 비용은 폭증하고, AI의 추론 성능은 저하된다. 더 비싼 모델로 바꿔도 해결이 안 된다. 문제는 모델 지능이 아니라 컨텍스트 오염이기 때문이다.
claude-md-management는 이 문제를 6가지 품질 지표(Commands, Architecture, Patterns, Conciseness, Currency, Actionability)로 진단하고 C부터 A까지 등급을 매긴다. 누락된 빌드·린트·테스트 명령어를 경고하고, /revise-claude-md 커맨드 한 번으로 세션에서 학습한 새 컨벤션을 규칙 파일에 병합한다. 이미 27만 건 이상 설치됐다는 숫자는 이게 개인의 강박이 아니라 보편적인 운용 문제라는 증거다.
지침과 통제를 구분하는 실전 기준
세 소스가 공통으로 수렴하는 실용 원칙은 하나다. 지침은 방향 설정에, 툴링은 강제 집행에. dev.to의 분석 글이 제시하는 진단 프레임이 이를 가장 명쾌하게 정리한다.
- 접근 경계: CLAUDE.md로 설명하되, 실제 제어는 샌드박스와 권한 설정으로
- 커맨드 검증: PreToolUse Hooks로
- 스타일 일관성: 포매터와 린터로
- 동작 검증: 테스트로
- 릴리스 게이트: CI로
- 돌이킬 수 없는 외부 액션: 사람 승인으로
이 구분 없이 CLAUDE.md에 모든 것을 몰아넣으면, 에이전트에게 도덕적 설득으로 위험을 막으려는 셈이다. 그건 설계가 아니라 기도다.
지침 문구를 개선하는 것보다 먼저 확인해야 할 것이 있다. 그 지침이 현재 세션에 실제로 로드됐는가(/context로 확인), 규칙이 테스트 가능한 형태로 쓰여 있는가("API 표준을 따르라"가 아니라 "src/api/**를 수정할 때 npm run test:api를 실행하고 실패 테스트를 보고하라"), 그리고 절대 실패하면 안 되는 규칙이 지침이 아닌 다른 메커니즘으로 강제되고 있는가.
팀 단위로 Claude Code를 운용한다면 이 설계 순서가 중요하다. 에이전트에게 무엇을 맡길지 정하기 전에, 팀이 에이전트를 어떻게 통제할지를 먼저 설계해야 한다. Hook으로 강제할 경계를 코드로 정의하고, CLAUDE.md의 위생 상태를 주기적으로 관리하고, 지침과 강제 실행 레이어를 명확히 분리하는 것. 이 세 가지가 갖춰지지 않은 상태에서 auto-accept 모드를 켜는 건, 안전벨트 없이 자율주행을 믿는 것과 다르지 않다.