# Built a small CLI to detect AGENTS.md drift (missing commands, dead paths, conflicting nested files)

**URL:** <https://forum.cursor.com/t/built-a-small-cli-to-detect-agents-md-drift-missing-commands-dead-paths-conflicting-nested-files/159582>\
**Category:** Built for Cursor\
**Tags:** rules\
**Created:** [May 1, 2026, 8:44pm UTC](https://forum.cursor.com/t/built-a-small-cli-to-detect-agents-md-drift-missing-commands-dead-paths-conflicting-nested-files/159582 "2026-05-01T20:44:56Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![ItsHege](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/itshege/32/107393_2.png) [@ItsHege](https://forum.cursor.com/u/ItsHege)\
**Post date:** [May 1, 2026, 8:44pm UTC](https://forum.cursor.com/t/built-a-small-cli-to-detect-agents-md-drift-missing-commands-dead-paths-conflicting-nested-files/159582/1 "2026-05-01T20:44:56Z")

</div>

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:

```auto
npx agents-doctor@latest lint .
npx agents-doctor@latest explain src/

```

GitHub: [https://github.com/ItsHege/agents-md-doctor](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.

---

<div class="post-metadata">

**Author:** ![system](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/system/32/99069_2.png) [@system](https://forum.cursor.com/u/system)\
**Post date:** [July 30, 2026, 8:45pm UTC](https://forum.cursor.com/t/built-a-small-cli-to-detect-agents-md-drift-missing-commands-dead-paths-conflicting-nested-files/159582/3 "2026-07-30T20:45:07Z")

</div>

Closed on July 30, 2026, 8:45pm UTC

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.