CLAUDE.md의 한계와 Hook의 활용

AI 코딩 에이전트(Claude Code 등)에게 프로젝트 고유의 규칙을 학습시키는 메커니즘으로 CLAUDE.md가 있다. 리포지토리 루트에 두면 에이전트가 매번 그것을 읽고 작업을 수행하는 '프로젝트의 헌법'과 같은 파일이다. /clear 명령 후에도 매번 읽는다는 사실을 이번에 처음 알았다. 잘 생각해보면 당연한 일이지만 말이다.

그런데 이 파일은, 운용하다 보면 점점 비대해진다. 나의 프로젝트에서는 처음에 작성했을 때는 200행 정도였던 것이, 어느샌가 500행을 넘어서고 있었다. 규칙을 추가할 때마다 "이것도 써두자"가 쌓인 결과다.

본 기사에서는,

• 비대해진 CLAUDE.md를 슬림화한 이야기와 그 장점·단점
• 애초에 CLAUDE.md에는 "해서는 안 될 일을 막는 힘"이 없다는 한계
• 이를 보완하는 **훅(hook)**이란 무엇인지에 대한 심층 분석과 실제 활용 방법

을 도해와 함께 해설한다. AI 에이전트를 본격적으로 운용하고 있는 사람이라면 규모와 상관없이 와닿는 이야기일 것이다.

CLAUDE.md는 "매 턴, 컨텍스트(Context)의 맨 앞에 통째로 읽힌다"는 성질을 가진다. 즉,

• 에이전트가 한 번 응답할 때마다 전체 내용이 토큰(Token)으로 소비된다
• 길어질수록 매번 발생하는 비용과 처리 시간이 증가한다
• 그리고 문장이 길어질수록 핵심적인 규칙이 묻혀서 효과가 떨어지게 된다 (이른바 "lost in the middle")

임에도 불구하고, 운용 중에는 "규칙을 추가하는" 방향의 압력만 가해진다. 버그를 발견할 때마다, 사고가 발생할 때마다 "다음부터 주의하기 위한 규칙"을 추가해 나간다. 깎아낼 동기가 없으므로 단조 증가한다.

행수
500 ┤ ╭────── ← 어느샌가 여기
│ ╭─────╯
...

문제	내용
매 턴의 토큰 낭비	전체 내용이 매번 컨텍스트에 포함됨. 500행 ≒ 30KB를 매번 읽음
규칙의 희박화	중요한 금지 사항이 세세한 절차서 속에 파묻혀 눈에 띄지 않게 됨
중복·드리프트(Drift)	별도 문서에 원본이 있음에도 본문에 그대로 복사 → 한쪽만 업데이트되어 불일치 발생
사람도 읽지 않음	너무 길어서 유지보수하는 사람 스스로도 전체상을 파악할 수 없게 됨

슬림화의 핵심(core)은 단순하다. CLAUDE.md는 "매번 지켜야 할 규율 + 상세 내용이 있는 곳의 인덱스(Index)"로 압축하고, 상세 내용은 별도 문서로 분리하는 것이다.

구체적으로는,

• worktree의 정리 절차·명령어 모음 → 운용 가이드 문서로
• 훅(hook)의 설정 절차 (최초 1회만 수행) → 설정 가이드로
• DB 설계 원칙 전문·코드 예시·예외 규정 → 아키텍처 문서로

를 분리해내고, CLAUDE.md 측에는 "이것은 ○○.md를 참조할 것"이라는 한 줄 링크만 남겼다. 결과적으로, 540행 → 201행 (약 60% 감소).

• 매 턴의 토큰이 감소 — 직접적으로 비용 절감 및 응답 속도 향상. 미미해 보이지만 매번 효과가 있음
• 중요 규칙이 눈에 띔 — 노이즈가 줄어들어 금지 사항이나 플로우(flow)가 묻히지 않게 됨. 에이전트의 준수율이 높아지는 방향
• 필요할 때만 상세 내용을 읽음 — 상세 내용은 "링크를 따라갔을 때"만 컨텍스트에 포함됨 (온디맨드(On-demand) 읽기)
• 사람이 유지보수하기 쉬움 — 전체를 한눈에 훑어볼 수 있는 사이즈로 돌아옴
• 중복 해소 — 원본을 한 곳에 집약할 수 있어, 드리프트(불일치)의 온상이 줄어듦

슬림화는 공짜가 아니다. 트레이드오프(Trade-off)가 존재한다.

• 정보가 분산됨 — 상세 내용은 별도 파일. 에이전트가 링크를 따라가지 않으면 그 상세 내용을 알 수 없음. 서브 에이전트 등 링크 대상까지 읽으러 가지 않는 케이스에서 놓칠 우려가 있음
• 요약에 의한 정보 결손 — "7가지 원칙을 한 줄씩"로 압축하면 뉘앙스나 예외 사항이 빠질 수 있음. 모호함이 증가함
• 이중 관리의 리스크 — "본문의 한 줄 요약"과 "링크 대상의 전문"이라는 두 개의 소스(source)가 되어, 방치하면 다시 드리프트가 발생함
• 재편성 자체의 리스크 — 분리 작업 중에 규칙 하나를 누락하는 사고가 발생할 수 있음

교훈: 슬림화의 판단 기준은 "그것이 매번 필요한가?"이다. 매 턴 모든 에이전트가 지켜야 할 규율은 본문에. 실제 구현 착수 시나 최초 설정 시에만 읽는 상세 내용은 외부화하여 링크로 연결한다. 이 선긋기가 핵심이다.

여기서부터가 본론이다. 슬림화(Slimming)를 통해 '가독성'과 '비용'은 개선되었다. 하지만 운영 단계에서 정말로 어려움을 겪었던 것은 다른 문제였다.

나의 운영 규칙으로는, 개발 및 수정 작업은 반드시 격리 환경(git worktree)에서 진행하고, 본진(메인 작업 디렉토리)에서는 직접 코딩하거나 커밋해서는 안 된다는 것이 있다. 여러 에이전트 세션을 병렬로 돌리면 같은 디렉토리에서 git checkout을 할 때 충돌이 발생하여 작업 중인 파일이 사라지는 사고가 일어나기 때문이다.

나는 이것을 CLAUDE.md에 여러 번 굵게 적었다. 그럼에도 불구하고, 규칙을 위반하는 에이전트가 빈번하게 발생했다.

왜일까? 답은 가슴을 열고 말하자면 간단하다.

CLAUDE.md는 '요청'이지 '강제'가 아니기 때문이다.

문서에 의한 제어는 반드시 '읽는 사람이 읽고・이해하고・따르는'이라는 3단계의 선의(善意)에 의존한다. LLM은 확률적으로 행동하기 때문에,

• 긴 컨텍스트에서 규칙이 희미해져 놓치거나
• 서브 에이전트에게 애초에 규칙이 충분히 전달되지 않거나
• '이번 한 번 정도는'이라 판단이 흐트러지면서

언젠가는 깨진다. 요청 기반의 제어는 100%가 될 수 없다.

이는 AI만의 이야기가 아니다. 인간 팀에서도 '코딩 규약에 적혀 있는데 지켜지지 않는다'는 것은 영원한 과제다. 규약(문서)과, 그것을 기계적으로 강제하는 메커니즘(CI・린터・훅)은 별개의 것이다.

그래서 등장하는 것이 **훅(hook)**이다.

훅이란 '어떤 시스템의 처리 흐름 속의 정해진 타이밍(이벤트)에 자신의 처리를 끼워 넣는 메커니즘'을 말한다.

'낚시 바늘(hook)'이 어원이 되어, 시스템이 준비한

가 반환되면, 에이전트는 해당 도구 호출(tool call)을 실행할 수 없다. 즉, commit에 이르기 직전, git checkout을 입력하려는 순간에 차단된다.

설정은 에이전트의 설정 파일에 「어떤 이벤트의 · 어떤 도구에 · 어떤 스크립트를 걸 것인가」를 등록하기만 하면 된다.

{
"hooks": {
"PreToolUse": [
...

스크립트 측은,

• 앞으로 실행될 명령어가 변경 계열의 git 操作 (checkout/switch/commit/reset/merge/rebase/cherry-pick/pull)인지 확인한다.
• worktree 하위라면 그대로 통과.
• 본진 (git-dir == git-common-dir)이라면 deny를 반환한다.

라는, 계층 A와 동일한 판정을 「착수 단계」에서 수행한다.

계층	언제 멈추는가	방어 범위	강점
계층 B (PreToolUse)	도구 실행 직전	에이전트의 모든 git 操作 (checkout 등도)	사고 직전에 멈춤
계층 A (pre-commit)	commit 확정 직전	모든 주체의 commit	빠져나가는 것을 허용하지 않는 최종 방어선

계층 B는 방어 범위가 넓지만, 에이전트 측의 설정이므로 「설정 누락」이나 「다른 도구를 통한 우회」가 발생할 수 있다. 계층 A는 타이밍은 늦지만 (commit 시), git 레벨에서 작동하므로 누가 어떻게 하든 확실하다. 빠른 그물(계층 B)과, 놓치지 않는 그물(계층 A)을 겹침으로써, 한쪽을 빠져나가더라도 다른 쪽에서 멈추게 한다. 이것이 보안에서 말하는 다층 방어 (defense in depth) 개념이다.

마지막으로, 두 가지는 대립하는 것이 아니라 역할 분담이라는 점을 강조하고 싶다.

• 문서(Document)가 잘하는 것: 의도·배경·판단 기준을 전달하는 것. 「왜 worktree를 사용하는가」, 「어떤 설계 사상인가」와 같은 이러한 "생각 방식"은 훅(hook)으로는 표현할 수 없다.
• 훅(Hook)이 잘하는 것: 「이것만은 절대로 허용하지 않는다」라는 선을 확실히 막는 것. 특히 파멸적·가역적이지 않은 조작 (운영 환경으로의 오조작, 작업 소실, 비밀 정보의 commit 등)에 대한 가드레일.

결론: 지켜주었으면 하는 사항은 CLAUDE.md에 적는다. 지키게 만들고 싶은 사항은 훅으로 만든다. 부탁과 강제를 구분하여 사용하는 것이 AI 에이전트 운용의 핵심이다.

• CLAUDE.md는 매 턴 읽히기 때문에 내용이 비대해지면 매번 비용이 발생하고 규칙도 희박해진다. 「매번 필요한 규율」과 「착수 시에만 읽는 상세 내용」을 분리하고, 후자는 별도 문서로 분리하여 링크화하는 것이 슬림화의 정석이다. 슬림화의 장점은 비용 절감·준수율 향상·유지보수성이다. 단점은 정보 분산·요약 결락·이중 관리 리스크다.
• 트레이드오프(trade-off)를 이해하고 선을 긋는다.
• CLAUDE.md는 「부탁」이며, 강제력이 없다. 지켜지지 않는 선은 문서를 아무리 굵은 글씨로 써도 지켜지지 않는다.
• **훅(Hook)**은 「처리 흐름의 정해진 타이밍에 자신의 처리를 끼워 넣는 메커니즘」이다. 시스템이 기계적으로 실행하므로, 실행 주체의 선의에 의존하지 않고 강제할 수 있다.
• git의 pre-commit (최종 방어선)과 AI 에이전트의 PreToolUse (착수 저지)를 다층으로 조합하면, 한쪽을 빠져나가더라도 다른 쪽에서 멈춘다.
• 문서와 훅은 대립하지 않고 역할 분담 관계다. 의도는 문서로, 선은 훅으로.

AI 에이전트에게 맡기는 범위가 넓어질수록, 「부탁」만으로는 사고를 방지할 수 없다. 지키게 만들고 싶은 선에는 훅을.