agents-md-lint

agents-md-lint

Audit AI agent instruction files by spawning a blind sub-agent that tries to rediscover each documented fact from code search alone. Test descriptive facts for practical discovery cost. Preserve normative instructions even when examples of compliance are visible in code.

This works on any file whose purpose is to give an AI agent context about a codebase: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, or similar. The workflow refers to these collectively as "instruction files."

Modes

Default (rewrite): Produces a report and rewrites the instruction files with only the surviving facts.

Dry-run: Produces the report but does not modify any files. Use this when the user wants to see what would change before committing, or says things like "just show me," "report only," or "what's redundant." Ask which mode the user wants if it's ambiguous, in the same question as Step 1's extra/excluded files check.

Workflow

1. Discover and normalize instruction files

Scan the repo for instruction files. Common names: AGENTS.md, CLAUDE.md, CONVENTIONS.md, .cursorrules, .github/copilot-instructions.md. Ask the user if there are others, or if any should be excluded — together with the mode question when mode is ambiguous, so the user answers once.

Rename or symlink instruction files only when separately requested; trimming does not change their discovery paths.

2. Extract facts

Separate mandatory conventions, prohibitions and acceptance contracts from descriptive facts. Keep the former unless explicitly superseded; code examples cannot prove that a rule is unnecessary. List every descriptive fact as a numbered item, grouped by file. A "fact" is any single claim, convention, instruction, or piece of context — e.g., "tests use vitest," "branch names follow feature/JIRA-123 format," "never mock the database in integration tests."

3. Chunk facts for testing

Sub-agents get unreliable when asked too many questions at once. If a file contains more than 25 facts, split them into batches of 20–25 and spawn a separate sub-agent for each batch. Each batch should be self-contained — include enough context in the prompt so the sub-agent understands the domain without needing to see the other batches. Start every batch across all instruction files in one parallel dispatch rather than file by file.

4. Spawn blind reviewer(s)

For each batch of descriptive facts, spawn an isolated sub-agent without inherited conversation/instruction context with this task template. The key insight here is that the sub-agent must not have access to the instruction files — it should rely only on what it can find by searching the code. Rather than renaming or moving files (which risks data loss if something goes wrong), tell the sub-agent explicitly which files to ignore:

You are reviewing the codebase at <REPO_PATH> to test what facts are easily
discoverable from code alone — without any documentation.

IMPORTANT: Do NOT read or search inside these files, as they are the
documentation being audited:
<list of instruction file paths to exclude>

For EACH question below, try to answer using code searches (grep, glob,
reading config/source files). Use up to 3-4 searches per question — check
multiple locations if the first search doesn't find it (e.g., config files,
source code, test files, CI configs). Answer briefly and rate your confidence:

- HIGH: Found clear, unambiguous evidence
- MEDIUM: Found partial or indirect evidence (e.g., an example exists but
  the convention isn't stated, or the fact is buried in a non-obvious place)
- LOW: Could not find evidence, or only found it after extensive digging

For MEDIUM answers, note WHERE you found the evidence and how many searches
it took. This helps distinguish "technically findable but practically buried"
from "right there in the config."

QUESTIONS:
<numbered list of questions, one per extracted fact>

Use the selected runtime model or an explicit reviewer configuration. Record searches and elapsed lookup cost; disclose if instruction auto-loading prevented a blind review.

5. Score results

Compare each sub-agent's answers against the original facts. The scoring accounts for both correctness and practical discoverability — a fact that's technically in the code but requires insider knowledge to find is still worth documenting.

Agent confidence	Agent correct?	Verdict
HIGH	Yes	Candidate to remove — only if future lookup cost is lower than retaining a short pointer
HIGH	Partially	Keep the missing detail only
MEDIUM	Yes	Keep — findable but buried; an agent without docs would likely miss it or waste time searching
MEDIUM	Partially	Keep — not reliably found
LOW	—	Keep — not discoverable

6. Present results

Show a summary table:

| # | Fact | Confidence | Correct? | Verdict |
|---|------|-----------|----------|---------|
| 1 | Uses vitest for testing | HIGH | Yes | Remove |
| 2 | Branch naming: feature/JIRA-### | LOW | No | Keep |
| 3 | Auth middleware in src/middleware/auth.ts | MEDIUM | Yes | Keep (buried) |

Report the evidence, preserved conventions, proposed removals, line reduction and lookup cost. Context savings alone do not establish total efficiency.

If dry-run mode: Stop here. Do not modify any files.

7. Rewrite the files (default mode only)

Rewrite each instruction file with only the surviving facts. Principles:

• Every line must earn its tokens
• No headers or sections with a single bullet (inline it)
• Don't repeat what's in CONTRIBUTING.md, README.md, or config files
• Group related facts naturally
• Preserve the original file's voice and structure where possible — this is a trim, not a rewrite from scratch

Tips

• For monorepos with multiple instruction files, test each file separately — a fact might be discoverable in one subproject's context but not another's
• Facts about conventions (naming rules, branch patterns) are usually NOT discoverable even if examples exist in git history — keep them
• Facts about auth mechanisms are often buried in middleware — usually worth keeping
• Facts about known gotchas (e.g., "use --forceExit," "don't mock the DB") are almost never discoverable — keep them
• Facts about file locations ("tests live in tests/") are often easily discoverable from directory structure — good candidates for removal
• When in doubt, keep the fact. The cost of a missing instruction (agent does the wrong thing) is higher than the cost of a few extra context tokens