I Built a Tool That Forces AI Coding Agents to Keep Documentation in Sync

Russell Moss — Sun, 29 Mar 2026 17:28:32 +0000

Second commit passes because docs are now staged alongside code. The hook doesn't need to call any AI — it just checks whether the right files are included.

The self-invocation guard is critical: if the hook tried to spawn Claude Code as a subprocess while Claude Code is already running, you'd get a deadlock. By detecting the CLAUDECODE env var and skipping all engines, the hook avoids this entirely.

API Auto-Fix for Human Commits

When you commit from the terminal (no CLAUDECODE env var), the hook calls the Anthropic API directly to update your docs:

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

It reads your staged source files, reads the current ARCHITECTURE.md, sends both to the API, and writes back the updated sections. About 20 seconds and ~$0.10 per commit. The hook stages the updated docs and the commit proceeds without you doing anything.

If the API is down or your key is missing, the hook degrades to advisory mode — it prints a warning but lets the commit through. You don't get punished for infrastructure failures.

Session Context: Continuity Between Sessions

Every commit generates .agent-guard/session-context.md — a rolling summary that gives AI agents memory between sessions:

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

## Recent Commits

| Hash | Date | Message | Categories | Docs Updated |
|------|------|---------|------------|--------------|
| f622d60 | 2026-03-29 | fix: session context on all paths | source | ARCHITECTURE.md |
| 29f8f9f | 2026-03-29 | fix: session-context staging | source | ARCHITECTURE.md |
| 174323f | 2026-03-29 | feat: auto-generate session context | source | — |

## Documentation Health

- **Hook mode:** blocking
- **Engine:** claude-code
- **Stale marker:** none
- **Categories:** env (.env), source (src/)

The standing instructions tell Claude Code to read this file before making any changes. Now when you start a new session, the agent knows what happened last time — which files changed, whether docs were updated, and whether anything is stale.

Standing Instructions That Update Themselves

agent-guard injects a documentation maintenance section into your AI config files. It writes to .cursorrules, CLAUDE.md, and any additionalAgentConfigs simultaneously. Here's what the generated table looks like:

| If You Changed… | Update This | And Run… |
|---|---|---|
| `.env` | Environment Variables section in `docs/ARCHITECTURE.md` | Run `npm run gen:env` |
| `src/*` | Architecture section in `docs/ARCHITECTURE.md` | — |

When the hook runs auto-fix, it regenerates this table from the current config categories. Add a new category for src/services/ and the standing instructions automatically include it on the next commit. No manual editing.

The Behavior Matrix

Scenario	What Happens
Human commits, docs current	Silent pass
Human commits, docs stale	API auto-fix (~20s), commit proceeds
Human commits, API down	Degrade to advisory + warning
Claude Code commits, docs current	Silent pass
Claude Code commits, docs stale	Block + remediation instructions
Rebase/merge in progress	Auto-downgrade to advisory

What It Doesn't Do

agent-guard keeps documentation in sync — it doesn't write your architecture for you. If your ARCHITECTURE.md is empty, it stays empty. The tool maintains what you've written, not what you should write.

It's designed for solo devs and small teams, not enterprise collaboration. It doesn't work outside git. It has zero dependencies — the whole thing is git hooks and API calls, not a platform. Node 20+ built-ins only.

Try It

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

npm: npmjs.com/package/@mossrussell/agent-guard
GitHub: github.com/russellmoss/agent-guard

MIT licensed. Zero dependencies. Node 20+.

Your AI Agent is Coding Against Fiction — How I Fixed Doc Drift with a Pre-Commit Hook

Russell Moss — Sat, 21 Feb 2026 21:35:29 +0000

If you're vibe coding with Claude Code, Cursor, or Copilot, you've probably experienced this:

Start a project. Write a nice ARCHITECTURE.md.
Feed it to your AI agent as context.
Ship 20 commits.
Realize half the API routes in your docs don't exist anymore.

Your agent is now making decisions based on documentation that's completely wrong. I call this doc drift, and it's the silent killer of AI-assisted development.
The Problem
AI coding agents are only as good as the context you give them. When your .cursorrules or CLAUDE.md reference an architecture doc that hasn't been updated in two weeks, every suggestion your agent makes is built on a foundation of lies.
Manual doc maintenance doesn't scale — especially for solo devs who are moving fast.
What I Built
agent-guard is a zero-dependency CLI that creates a self-healing documentation layer for your project. It works in four layers:
Standing Instructions — Writes rules into your AI agent config (.cursorrules, CLAUDE.md, etc.) telling the agent to update docs alongside code changes.
Generated Inventories — Deterministic scripts extract truth directly from your source code. API routes, Prisma models, env vars — all auto-generated into markdown files that can't lie.
Pre-commit Hook — Catches drift before it reaches your repo. If Claude Code is installed, it auto-updates your narrative docs. If not, it prints a ready-made prompt you can paste into your editor.
CI/CD Audits — GitHub Actions that run on every push and PR, plus weekly scheduled health checks.
Setup
bashnpm install --save-dev @mossrussell/agent-guard
npx agent-guard init
npx agent-guard sync
The init wizard auto-detects your framework and sets everything up. The hook never blocks commits — it always exits cleanly.
What It Looks Like in Practice
When you commit with Claude Code available:
✓ Doc-relevant changes detected — docs also updated. Nice!
When Claude Code isn't available:
⚠️ Documentation may need updating

Changed:
📡 API Routes (1 file):
- src/app/api/users/route.ts

┌─────────────────────────────────────┐
│ Claude Code Prompt (copy-paste): │
└─────────────────────────────────────┘
Why Zero Dependencies Matters
For solo devs doing vibe coding, every dependency is a liability. agent-guard uses only Node.js built-ins. No runtime overhead, no supply chain risk, no version conflicts.
Try It

npm: https://www.npmjs.com/package/@mossrussell/agent-guard
GitHub: https://github.com/russellmoss/agent-guard

I'd love feedback — especially from other solo devs fighting doc drift. What's your current approach?

Forem: Russell Moss