Git pre-commit hook prevents AI coding agents from committing with stale documentation

Problem: AI coding agents commit code with outdated documentation

When working with AI coding assistants like Claude Code over multiple sessions, developers encounter a specific issue: the AI makes code changes (adding routes, refactoring components, renaming things) but doesn't update documentation files like ARCHITECTURE.md and README. This causes subsequent sessions to start with the AI reading documentation that describes code from weeks ago.

The consequences include:

• Claude hallucinating function names that no longer exist
• Referencing API endpoints that were renamed
• Suggesting patterns that contradict the current architecture

Advisory warnings don't work because when Claude is committing, nobody sees stderr output.

Solution: A blocking pre-commit hook

The developer created a Git pre-commit hook with this workflow:

• The hook knows which file changes should trigger documentation updates (configurable patterns per project)
• When Claude Code commits, the hook detects it via environment variables
• The hook skips trying to auto-fix documentation (which would cause a deadlock from spawning Claude from inside Claude)
• Instead, it exits with code 1 and displays a clear message: "docs are stale, update these files, then retry"
• Claude reads the error, updates the documentation, retries the commit, and the commit goes through

For human commits, the hook calls the Anthropic API directly and patches the relevant sections (taking approximately 20 seconds).

Every commit generates a session-context.md file with a summary of recent activity so the next session has continuity.

Implementation details

The tool is available as an npm package: @mossrussell/agent-guard

Key characteristics:

• Works with Claude Code, Cursor, Windsurf, and Copilot
• Zero dependencies
• Available at: https://www.npmjs.com/package/@mossrussell/agent-guard