Git pre-commit 훅은 AI 코딩 에이전트가 오래된 문서로 커밋하는 것을 방지합니다.

문제: AI 코딩 에이전트가 오래된 문서와 함께 코드를 커밋함

Claude Code와 같은 AI 코딩 도우미로 여러 세션 동안 작업할 때, 개발자들은 특정 문제에 직면합니다: AI는 코드 변경(라우트 추가, 컴포넌트 리팩토링, 이름 변경)을 수행하지만 ARCHITECTURE.md나 README와 같은 문서 파일을 업데이트하지 않습니다. 이로 인해 후속 세션은 몇 주 전의 코드를 설명하는 문서를 읽는 AI로 시작하게 됩니다.

그 결과는 다음과 같습니다:

• 존재하지 않는 함수 이름을 Claude가 환각적으로 생성함
• 이름이 변경된 API 엔드포인트를 참조함
• 현재 아키텍처와 모순되는 패턴을 제안함

경고 메시지는 작동하지 않습니다. Claude가 커밋할 때는 아무도 stderr 출력을 보지 못하기 때문입니다.

해결책: 차단하는 pre-commit 훅

개발자는 다음과 같은 워크플로우를 가진 Git pre-commit 훅을 만들었습니다:

• 훅은 어떤 파일 변경이 문서 업데이트를 트리거해야 하는지 알고 있습니다(프로젝트별로 구성 가능한 패턴)
• Claude Code가 커밋할 때, 훅은 환경 변수를 통해 이를 감지합니다
• 훅은 문서 자동 수정을 시도하지 않습니다(Claude 내부에서 Claude를 생성하는 데드락을 유발할 수 있음)

대신, 코드 1로 종료하고 명확한 메시지를 표시합니다: "문서가 오래됨, 이 파일들을 업데이트한 후 다시 시도하세요"

• Claude는 에러를 읽고, 문서를 업데이트하며, 커밋을 다시 시도하고, 커밋이 진행됩니다

사람이 커밋할 때는, 훅이 Anthropic API를 직접 호출하고 관련 섹션을 패치합니다(약 20초 소요).

모든 커밋은 최근 활동 요약이 담긴 session-context.md 파일을 생성하여 다음 세션이 연속성을 가질 수 있도록 합니다.

구현 세부사항

이 도구는 npm 패키지로 이용 가능합니다: @mossrussell/agent-guard

주요 특징:

• Claude Code, Cursor, Windsurf, Copilot과 함께 작동
• 제로 의존성
• 이곳에서 이용 가능: https://www.npmjs.com/package/@mossrussell/agent-guard