agent-doctor

Instruction quality auditor for AI agent rule files.

AI agents are only as good as the rules they follow. But as your CLAUDE.md, .cursorrules, and system prompts grow, nobody asks the hard questions:

• Do these rules contradict each other?
• Are they specific enough to actually change behavior?
• Are the file paths and commands they reference still valid?
• Is the same instruction written four different ways?

agent-doctor is a CLI that scans your rule files and gives you a health score — with specific, actionable findings.

Demo

  ╭────────────────────────────────────────────────────────────────────╮
  │  AGENT DOCTOR                                              v0.1.0  │
  ╰────────────────────────────────────────────────────────────────────╯

  CLAUDE.md
  1 file(s)  ·  47 rules parsed  ·  5 issue(s) found

  ┌────────────────────────��───────────────────────────────────────────┐
  │                                                                    │
  │  HEALTH SCORE                                                  C   │
  │                                                                    │
  │  ████████████████████░░░░░░░░░░░░░░░   62 / 100                    │
  │                                                                    │
  └────────────────────────────────────────────────────────────────────┘

  ── HIGH ────────────────────────────────────────────────────────────

  │ ⚡  CONFLICT                         CLAUDE.md:14 ↔ CLAUDE.md:87
  │ ──────────────────────────────────────────────────────────────────
  │  "act autonomously on reasonable assumptions" conflicts with
  │  "always ask before making significant changes"

  │ ◌  VAGUE RULE                                         CLAUDE.md:22
  │ ──────────────────────────────────────────────────────────────────
  │  "write clean, maintainable code"
  │
  │  Vague phrases:  write clean
  │  → Rewrite as: "when X → do Y"

  ── MEDIUM ──────────────────────────────────────────────────────────

  │ ⊘  DEAD REF                                           CLAUDE.md:103
  │ ──────────────────────────────────────────────────────────────────
  │  ./scripts/deploy.sh  →  not found (path)

  ── SUGGESTIONS ─────────────────────────────────────────────────────

  1  Add a precedence section: e.g. "safety > repo-policy > style guidance"
  2  Rewrite 1 vague rule(s) as concrete trigger → action pairs
  3  Update or remove dead path/command references

Installation

# Run once without installing
npx agent-doctor check .

# Or install globally
npm install -g agent-doctor

Usage

# Scan current directory
ard check .

# Scan a specific file
ard check CLAUDE.md

# Scan a directory recursively
ard check ./my-project

# Heuristic checks only (no API key required)
ard check . --no-llm

# Filter by severity
ard check . --severity high

# Output as JSON
ard check . --output json

# Output as Markdown
ard check . --output markdown > RULES_HEALTH.md

What it detects

| Check | Severity | Method | |---|---|---| | Conflicting rules — "always ask" vs "act immediately" | HIGH | LLM | | Missing precedence — conflicts exist but no priority order defined | HIGH | Heuristic | | Vague rules — "be thoughtful", "write clean code" | HIGH | Heuristic + LLM | | Redundancy — same instruction written multiple times | MEDIUM | Jaccard similarity | | Dead references — file paths or commands that no longer exist | MEDIUM | fs + which | | Weak triggers — "when needed", "if appropriate" | MEDIUM | Heuristic |

Supported rule files

Automatically discovered in the target directory:

• CLAUDE.md / .claude/CLAUDE.md
• .cursorrules
• .windsurfrules
• AGENTS.md
• .copilot-instructions.md
• *system-prompt*.md
• *instructions*.md

LLM-powered checks

Conflict detection uses the Claude API for semantic analysis. Set your API key to enable it:

export ANTHROPIC_API_KEY=sk-ant-...
ard check .

Without the key, all heuristic checks still run. The --no-llm flag explicitly disables LLM checks.

Exit codes

| Code | Meaning | |------|---------| | 0 | No HIGH severity issues | | 1 | One or more HIGH severity issues found | | 2 | Error (file not found, etc.) |

Useful for CI:

- name: Audit agent rules
  run: npx agent-doctor check . --no-llm

Scoring

Base score: 100

Deductions per issue:
  CONFLICT           -12
  MISSING_PRECEDENCE -10
  VAGUE              -7
  REDUNDANCY         -5
  DEAD_REF           -4
  WEAK_TRIGGER       -3

Grade: A (90–100)  B (75–89)  C (60–74)  D (40–59)  F (<40)

License

MIT © Efe Görkem Bildi