Hi all,
I kept running into the same problem with AGENTS.md and .cursor/rules across my projects - instructions slowly drifting from the actual repo state. Commands referenced in the file no longer existed in package.json, paths pointed to deleted files, nested instruction files quietly contradicted root-level ones.
Built a small CLI to catch this deterministically (no LLM calls, just static analysis):
-
lint- checks for oversized files, missing required sections, dead path references, missing commands, risky instructions -
verify- same as lint plus coverage sanity checks, designed for CI -
explain <path>- shows which AGENTS.md / .cursor/rules / .claude files apply to a specific path, with conflict markers for things like package manager disagreement or test command mismatches
Supports AGENTS.md, .cursor/rules//*.mdc, and .claude//*.md (opt-in via config).
Quick try:
npx agents-doctor@latest lint .
npx agents-doctor@latest explain src/
GitHub: https://github.com/ItsHege/agents-md-doctor
Sharing in case anyone else is dealing with the same drift problem. Open to feedback on what other rules would be useful, especially around Cursor-specific patterns I might be missing.