AI 코딩 에이전트가 문서를 동기화하도록 강제하는 도구를 만들었습니다

Source: Dev.to

Keeping Docs in Sync with Git Hooks

두 번째 커밋은 문서가 이제 코드와 함께 스테이징되기 때문에 통과합니다. 훅은 AI를 호출할 필요가 없으며, 단지 올바른 파일이 포함되었는지 확인합니다.

자체 호출 방지는 매우 중요합니다: 훅이 Claude Code를 서브프로세스로 실행하려고 시도하면서 Claude Code가 이미 실행 중이라면 교착 상태가 발생합니다. CLAUDECODE 환경 변수를 감지하고 모든 엔진을 건너뛰어 훅이 이를 완전히 방지합니다.

API 자동‑수정 (Human Commits용)

터미널에서 커밋할 때 (CLAUDECODE 환경 변수가 없을 경우) 훅은 Anthropic API를 직접 호출해 문서를 업데이트합니다:

{
  "autoFix": {
    "hook": { "mode": "blocking" },
    "narrative": {
      "engine": "api",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

훅은 다음과 같이 동작합니다:

1. 스테이징된 소스 파일을 읽습니다.
2. 현재 ARCHITECTURE.md를 읽습니다.
3. 두 파일을 API에 전송합니다.
4. 업데이트된 섹션을 다시 기록합니다.

작업 시간은 약 20 초 정도이며, 커밋당 약 $0.10 정도의 비용이 발생합니다. 업데이트된 문서는 자동으로 스테이징되고, 추가적인 상호작용 없이 커밋이 진행됩니다.

API가 다운되었거나 키가 없을 경우, 훅은 advisory 모드로 전환됩니다 — 경고를 출력하지만 커밋을 차단하지 않으므로 인프라 장애에 의해 작업이 중단되지 않습니다.

세션 컨텍스트: 세션 간 연속성

각 커밋은 .agent-guard/session-context.md 파일을 생성하며, 이는 AI 에이전트에게 세션 간 기억을 제공하는 순환 요약입니다:

# Session Context — agent-guard
> Auto-generated by agent-guard. Do not edit manually.
> Last updated: 2026-03-29T16:46:40.973Z

최근 커밋

Documentation Health

• Hook mode: 차단
• Engine: claude-code
• Stale marker: 없음
• Categories: env (.env), source (src/)

Standing instructions tell Claude Code to read this file before making any changes, so each new session knows what happened last time — which files changed, whether docs were updated, and whether anything is stale.

스스로 업데이트되는 상시 지시문

agent-guard는 AI 설정 파일(.cursorrules, CLAUDE.md, 및 모든 additionalAgentConfigs)에 문서 유지 관리 섹션을 삽입합니다. 생성된 표는 다음과 같습니다:

후크가 자동 수정(auto‑fix)을 실행하면 현재 설정 카테고리에서 이 표를 다시 생성합니다. 새로운 카테고리(예: src/services/)를 추가하면 다음 커밋 시 상시 지시문이 자동으로 업데이트되며, 수동 편집이 필요하지 않습니다.

동작 매트릭스

이것이 하지 않는 것

• 이 도구는 아키텍처를 대신 작성하지 않습니다. ARCHITECTURE.md가 비어 있으면 그대로 비어 있습니다.
• 솔로 개발자와 소규모 팀을 대상으로 하며, 대규모 엔터프라이즈 협업을 위한 것이 아닙니다.
• Git 내부에서만 작동하고, Git 훅과 API 호출 외에 외부 의존성이 전혀 없습니다.
• Node 20+ 환경에서 내장 모듈만 사용하여 실행됩니다.

시도해 보기

npm install --save-dev @mossrussell/agent-guard
npx agent-guard init

• npm:
• GitHub:

MIT 라이선스. 의존성 없음. Node 20+.