Claude Code의 버그 수정 회피 방지를 위한 'Fix Everything' 훅 공개

실용적 조언

Claude Code 사용 시 CLAUDE.MD 파일에만 의존하지 말고, PreToolUse 훅을 활용하여 모델의 도구 사용 의도를 검증하라.
GitHub 리포지토리(idiolectai/cc-fix-everything)에서 제공하는 fix-everything.md와 scan-dismiss.sh를 프로젝트에 적용하여 버그 수정 누락을 방지하라.

섹션별 상세

Claude Code가 세션 중 발견한 버그를 'pre-existing' 또는 'out of scope'로 분류하며 수정을 회피하는 문제가 보고됐다. 특히 Opus 4.6 모델에서 이러한 경향이 두드러지며, 단순한 규칙 설정이나 프롬프트 지시만으로는 해결되지 않는 깊게 각인된 행동 특성임이 확인됐다.

해결책으로 제시된 시스템은 PreToolUse 훅을 통해 도구 실행 전 대화 기록을 실시간으로 스캔한다. 텍스트에서 회피성 언어가 감지되면 즉시 도구 호출을 차단하고 모델에게 해당 문제를 조사하도록 강제 지시하는 방식으로 작동한다. 마지막 실행 이후의 기록만 검사하여 중복 활성화를 방지하며, 실행 시 약 10ms의 지연 시간만 추가되어 성능 영향이 미미하다.

오탐지(False Positive)를 방지하기 위한 여러 안전장치와 우회 메커니즘이 포함됐다. 사용자가 특정 세션이나 단일 도구 호출에 대해 훅을 수동으로 비활성화할 수 있는 기능을 제공하여 메타 토론 중 발생할 수 있는 간섭을 최소화했다. 모델이 스스로 해결하기 어려운 시스템적 이슈인 경우 AskUser를 통해 사용자에게 가이드를 요청하도록 설계됐다.

용어 해설

훅(Hook): — 소프트웨어 구성 요소 간에 발생하는 이벤트를 가로채서 특정 로직을 실행하거나 동작을 변경하는 메커니즘이다. 이 아티클에서는 Claude Code가 도구를 사용하기 전후에 사용자 정의 스크립트를 실행하여 모델의 행동을 제어하는 용도로 사용된다.
도구 사용 전 훅(PreToolUse Hook): — AI 에이전트가 외부 도구(터미널 명령, 파일 수정 등)를 실제로 실행하기 직전에 트리거되는 인터셉터이다. 모델의 의도를 미리 검사하여 부적절한 실행을 차단하거나 지시 사항을 수정함으로써 에이전트의 안전성과 정확도를 높이는 역할을 한다.
오탐지(False Positive): — 시스템이 정상적인 상황을 오류나 특정 패턴으로 잘못 판단하여 경고를 발생시키는 현상이다. 본문에서는 훅이 모델의 일반적인 대화를 회피성 발언으로 오인하여 도구 실행을 불필요하게 차단하는 경우를 의미한다.

언급된 도구

Claude Code추천

Anthropic의 CLI 기반 AI 코딩 에이전트

cc-fix-everything추천링크

Claude Code의 회피 동작을 차단하는 훅 및 규칙 세트

언급된 리소스

GitHubcc-fix-everything GitHub Repository