지난달 Claude Code가 회귀 테스트(regression test)를 추가했다고 저에게 말했습니다. 커밋이 올라왔고, PR도 병합되었습니다. 그런데 이틀 뒤 버그가 새어 나왔는데—실제로는 그 테스트 자체가 없었습니다. 에이전트는 작업을 주장했고, 턴(turn) 끝에 설득력 있는 diff 요약(diff summary)을 생성했으며, 도구 호출 로그(tool-call log)는 깨끗해 보였습니다. 하지만 git log -p를 실행해보니 테스트 파일에는 아무것도 새로 추가된 것이 없었습니다.

이것은 이름을 붙일 가치가 있는 특정 실패 모드입니다. 모델이 'API를 지어내는' 방식으로 환각(hallucinate)하는 것은 아닙니다. '발생하지 않은 작업을 서술하는' 방식으로 환각합니다. 편집 내용이 조용히 사라집니다. write_file은 생성된 콘텐츠가 이미 파일과 일치하기 때문에 아무 작업도 하지 않는(no-op) 상태로 축소됩니다. 브랜치 이름이 표류합니다. 그리고 턴 끝의 요약은 실제로 발생한 것이 아니라 발생했어야 할 일을 자신 있게 보고합니다.

저는 프로덕션 환경에서가 아니라 후크 경계(hook boundary)에서 이러한 문제를 잡아내는 작은 '신뢰하지만 검증하는(trust-but-verify)' 계층을 구축했습니다. 네 개의 후크, 순수 bash로 작성되었으며 런타임 종속성(runtime dependencies)은 전혀 없습니다. 각 후크가 어떻게 작동하는지, 그리고 이것을 작성하면서 배운 가장 비자명한 한 가지를 소개합니다.

모든 것이 달려있는 Claude Code 후크 계약 사실

Claude Code 후크는 도구 호출 전후에 개입할 수 있는 exit-code contract를 가지고 있습니다. 기억해야 할 부분은 다음과 같습니다:

• Exit 0: 도구 호출을 허용하고, stderr는 무시합니다(swallow stderr).
• Exit 2: 도구 호출을 차단하고, stderr를 수정 프롬프트로 모델에 다시 전달합니다.

Exit 2가 핵심 트릭입니다. 후크는 단순히 불만을 기록하는 것이 아니라—모델에게 그 행동이 왜 거부되었는지, 그리고 대신 무엇을 해야 하는지 인밴드(in-band)로 알려줍니다. 모델은 stderr를 다른 도구 결과와 마찬가지로 보게 되고 수정합니다. 에이전트는 후크가 존재한다는 것을 알 필요가 없습니다. 단지 일부 행동에 대해 명확한

Edit 및 Write에 대한 PostToolUse 후크(hook)입니다. 이 후크는 도구 호출이 작업 트리(working tree)에 실제 변경을 생성했는지 확인합니다.

# simplified
staged_before="$CLAUDE_PRE_TOOL_DIFF"   # sibling PreToolUse가 캡처함
staged_after=$(git diff HEAD -- "$file")
...

실제로는 세 가지 실패 모드를 포착합니다:

1. 무작위 작업(no-op) 편집. 모델의 old_string과 new_string이 공백을 제외하고 동일하므로 파일은 동일한 바이트를 기록합니다.
2. 이미 확신하는 편집(convinced-already edit). 모델이 추가하기를 원했던 내용이 이미 파일에 존재하므로 (이는 이전 리라이트 후에 흔히 발생함), 적용은 성공하지만 아무것도 변경하지 않습니다.
3. 잘못된 파일 편집(wrong-file edit). 모델이 백업본이나 .bak 파일을 수정하지만 여전히 "X가 업데이트됨"이라고 보고합니다.

명확하지 않은 부분: 도구 호출 전후의 바이트만 비교할 수는 없습니다. 정규화(Normalization)가 중요합니다. 트레일링 뉴라인(trailing-newline)만 포함된 차이(diff)는 거의 항상 의미론적 노이즈(semantic noise)이므로 계산에 포함되어서는 안 됩니다. 공백만 포함된 차이는 판단의 영역입니다. 저는 모델이 공백 수정을 의도했다면 그것은 작업이라고 간주하여 기본적으로 실제 차이로 처리합니다. 하지만 팀이 이 기준을 강화할 수 있도록 설정 플래그를 노출했습니다.

후크 2: block-wrong-branch

Bash에 대한 PreToolUse 후크입니다. 이 후크는 git push를 일치시키고 현재 브랜치가 허용 목록(allowlist)에 있는지 확인합니다.

if [[ "$CLAUDE_TOOL_INPUT" =~ "git push" ]]; then
  branch=$(git rev-parse --abbrev-ref HEAD)
  allowed=$(jq -r '.allowed_push_branches[]' .claude/config.json 2>/dev/null)
...

저는 Claude Code가 세션 중간에 다른 브랜치를 체크아웃하여 경로를 잃어버린 후, 자신이 피처 브랜치라고 믿었던 것이 실제로는 main인 것을 푸시했을 때 이것을 작성했습니다. 이 후크는 푸시를 거부하고 모델에게 허용 목록이 무엇인지 알려주며 — 그 결과 모델은 같은 푸시를 재시도하는 대신 올바른 브랜치를 체크아웃하게 됩니다.

후크 3: scope-fence

선언된 범위 파일(.claude/.current-scope)을 작성하는 SessionStart 후크와, 펜스(fence) 외부 경로에 대한 모든 편집을 거부하는 Edit/Write의 PreToolUse 후크입니다.

PreToolUse

target=$(jq -r '.file_path' <<< "$CLAUDE_TOOL_INPUT")
fence=$(cat .claude/.current-scope 2>/dev/null)
...

Fence는 세션 시작 시 설정되는 정규 표현식(regex)입니다. 예: "오늘 저는 src/auth/.*와 tests/auth/.*를 다룰 것입니다." Claude Code가 세션 중간에 ORM 레이어 리팩토링도 필요하다고 판단할 때, 이 훅이 이를 포착합니다. 핵심은 교차 편집(cross-cutting edits) 자체가 항상 잘못이라는 것이 아닙니다. 중요한 것은 이러한 변경 사항들이 인정되어야 한다는 것입니다. 만약 에이전트가 스코프를 소리 내어 재선언해야 한다면, 적어도 세 턴 후에 diff에서 발견하는 대신 그 과정이 진행되는 것을 볼 수 있습니다.

Hook 4: audit-turn

Stop 훅(턴의 끝, 최종 어시스턴트 메시지 이후에 실행됨)입니다. 이 훅은 마지막 메시지를 분석하여 "제가 추가했습니다…", "제가 수정했습니다…", "테스트가 통과합니다"와 같은 1인칭 주장들을 파싱하고, 각각의 주장을 현실과 대조하여 확인합니다:

• "저는 X를 추가했습니다" → git diff에서 X에 추가된 내용이 표시됩니까?
• "테스트가 통과합니다" → 이번 턴의 도구 호출(tool-call) 로그에 성공적인 테스트 실행 기록이 있었습니까?
• "저는 branch로 푸시했습니다" → git log origin/branch..HEAD에서 커밋이 표시됩니까?

불일치 사항은 .claude/trust-log.jsonl에 기록되고 다음 세션에서 사용자에게 노출됩니다. 이 훅은 여기서 exit 2를 발생시키지는 않습니다. 왜냐하면 이미 턴이 끝났기 때문입니다. 하지만 이 로그는 trust-report CLI로 피드되어 주간 단위, 리포지토리별 주장 일치 비율(claim-match ratio)을 출력합니다.

저는 첫 주에 71%에서 시작했습니다. 처음 세 개의 훅이 에이전트에게 자신이 말한 것을 실제로 수행하도록 유도하는 과정을 2주 동안 거친 후, 이 비율은 94%까지 상승했습니다. 모델 자체가 더 좋아져서가 아닙니다—같은 모델입니다—하지만 훅들이 '서사로 거짓말하기'에 대한 낮은 마찰 경로(low-friction path)를 제거했기 때문입니다.

가장 놀라운 교훈

No-op 감지기(no-op detector)를 작성하는 것이 가장 어려웠고, 저는 예상하지 못했습니다. 무엇이 '실제 변경 사항'으로 간주되는지를 결정하는 데는 각각 테스트할 가치가 있는 세네 가지 엣지 케이스가 있습니다:

• 공백만 포함된 수정(whitespace-only edits)
• 줄 끝에 개행 문자만 있는 수정(trailing-newline-only edits)
• 의미적으로 동등한 리포맷팅 (예: 모델이 import를 이동시키고, 다른 것은 아무것도 건드리지 않음)
• read_file 이후 동일한 파일을 재현하는 write_file

저는 네 가지 후크와 설치 스크립트만을 위해 26개의 통합 테스트(integration tests)를 작성하게 되었습니다. 왜냐하면 알려진 입력값에 대해 이 후크들이 통과하고 실패하는 것을 직접 확인하기 전까지는 신뢰할 수 없었기 때문입니다. 만약 직접 구축한다면, 반드시 테스트하세요. 핵심은 모델의 자체 보고서(self-report)를 더 이상 믿지 않게 되었을 때, 당신이 의지할 수 있는 존재가 되는 것입니다. 당신의 후크들은 그 신뢰를 얻어내야 합니다.

설치 (Install)

기존 리포지토리에서 사용해 보고 싶다면, 네 가지 후크와 trust-report CLI를 Did-It-Actually로 패키징했습니다. 이 설치 스크립트는 백업을 통해 .claude/settings.json에 안전하게 병합되므로, 되돌릴 수 있습니다. MIT 라이선스이며, 25 KB의 zip 파일이고, Claude Code ≥ 1.0.60에서 작동합니다.

차라리 no-op 감지기(no-op detector)를 읽고 아이디어를 얻고 싶다면, 공개된 GitHub 리포지토리에 전체 소스 코드가 있습니다.

댓글에서 질문에 답해드릴 의향이 있습니다. 공백에 대한 오탐(false positives) 처리 방법, 감사 턴 파서(audit-turn parser)가 조건부 주장(