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?
Top comments (0)