CLAUDE.md, 늘릴수록 무시당한다
2026-05-14#ai#claude-code#harness
AI 규칙 파일을 운영하며 겪은 실패 기록 — 규칙 매몰, 강제의 역효과, 자기 증식, 그리고 틀렸던 믿음.
하네스에서 가장 만만해 보이는 도구는 지시문서다. AI가 뭔가 어긋나면 CLAUDE.md에 규칙 한 줄을 추가하면 될 것 같다. 실제로 그렇게 몇 주를 운영했고, 이 글은 그 과정에서 겪은 실패들의 기록이다.
실패 1 — 규칙은 늘릴수록 매몰된다#
"서브에이전트를 적극 활용하라"고 적어뒀는데 전혀 쓰지 않았다. 원인을 뜯어보니 규칙 자체가 문제였다.
- 모호한 표현 — "적극 활용"은 권장이지 강제가 아니다
- 트리거 부재 — "언제" 써야 하는지가 없다
- 규칙 매몰 — 138줄 문서의 중간에 위치. 긴 문서에서 중간 규칙은 무시될 확률이 높다
- 예외 부재 — "직접 해도 되는 경우"가 없어 모델이 자의적으로 판단한다
그래서 CLAUDE.md를 60줄 이내로 줄이는 것부터 시작했다. 규칙을 지키게 하고 싶다면 규칙을 늘리는 게 아니라 줄여야 한다는 게 첫 번째 교훈이었다.
실패 2 — 강제하면 반대로 망가진다#
이번엔 반대 방향으로 갔다. "적극 활용"을 MANDATORY(반드시 ~하라) 트리거 5개로 바꿨다 — Kotlin 파일을 수정하면 backend 에이전트, 이런 식의 강제 규칙. 기술 명세의 MUST/SHOULD처럼, 규칙 파일에서 대문자 키워드는 "권장이 아니라 의무"라는 표시다. 사용률은 올라갔는데 새 문제가 생겼다. 당시 피드백을 그대로 옮기면 — "하나의 기술에 대해서만 작업을 하는데 자꾸 서브에이전트에게 주려고 하더라고. 병렬 작업이 아닌데."
트리거가 컨텍스트와 무관하게 발화한 것이다. 위임에는 새 컨텍스트 초기화와 파일 재읽기라는 비용이 있어서, 병렬 이득이 없는 위임은 순손실이다. 그래서 위임 조건을 AND로 좁혔다 — "2개 이상 병렬 가능하고, 파일이 격리되고…". 그러자 이번엔 조건이 너무 엄격해서 단순한 백엔드 작업까지 메인이 직접 처리했다. 결국 AND를 OR로 다시 완화했다.
모호(방치) → 강제(과잉) → 과엄격(위축) → 완화. 규칙 하나가 자리 잡는 데 네 번의 진자 운동이 필요했다. 규칙은 한 번에 맞출 수 없고, 실제 행동을 보고 조정하는 수밖에 없다.
실패 3 — md 파일은 자기 증식한다#
어느 날 토큰 사용량이 이상해서 뒤져보니 레포 곳곳에 CLAUDE.md가 136개 있었다. 메모리 플러그인이 방문한 디렉토리마다 컨텍스트 블록을 담은 CLAUDE.md를 자동 생성하고 있었고, 도구는 현재 위치에서 상위로 올라가며 CLAUDE.md 체인을 전부 로드하니 매 세션 수천 토큰이 주입되고 있었다.
124개를 지워 12개로 만들었다. 그리고 2주 뒤 다시 세어보니 63개였다. 삭제만 하고 생성원을 안 막으면 재발한다. 파일을 내용별로 분류해서(자동 생성 블록뿐인 55개는 삭제, 실제 내용이 있는 6개는 블록만 제거) 정리하고, 플러그인 훅에서 자동 생성 명령 한 줄을 제거하고 나서야 끝났다.
실패 4 — 로딩된다고 믿었던 게 로딩되지 않았다#
가장 뼈아픈 발견. 도메인별 규칙을 rules/ 디렉토리에 나눠 담고
"조건부로 자동 로딩된다"고 믿으며 운영했는데, 설정 파일을 열어
실제 메커니즘을 확인해보니 자동 주입 장치가 없었다. 실측한
강제력의 서열은 이랬다.
- CLAUDE.md의 한 줄 — 매 턴 상시 주입, 가장 강한 레버
- rules/ 파일 — 자동 주입 없음. CLAUDE.md가 가리키는 참조 문서
- 스킬 — 설명(description)을 보고 모델이 판단해서 발동
즉 md 파일 체계는 결정론적 강제가 아니라 모델의 확률적 자기규율이었다. 그럼 훅으로 강제해야 하나? 비교해보니 훅은 발동률 100%지만 상황 판단이 0%다 — 단순 작업에까지 무거운 검증 의례를 기계적으로 강요하게 된다. 그래서 판단이 필요한 규칙은 넛지(md)로 남기고, 절대 어기면 안 되는 것만 훅으로 옮겼다.
정리#
md 규칙 파일은 "쓰면 지켜진다"는 도구가 아니었다. 얼마나 로딩되는지, 언제 발동하는지, 실제로 행동이 바뀌는지를 측정해야 하는 시스템이다. 몇 주의 실패로 남은 기준은 셋이다 — 규칙은 60줄 안에서 우선순위 경쟁을 시키고, 강제가 필요한 것은 산문이 아니라 훅과 CI로 옮기고, 자동 생성되는 md는 생성원부터 막는다.