---
name: review-agents-md
description: Reviews an AGENTS.md or CLAUDE.md file against best practices and reports concrete fixes. Use when the user asks to review, audit, lint, or improve an AGENTS.md / CLAUDE.md / context file, or says "review my agents file".
---

The meta-principle: a context file earns its tokens. Every line must tell the agent something it can't infer from the code, the formatter, or the linter. If a line could be deleted without the agent getting worse, delete it.

## Workflow

1. Read the target file (default: `AGENTS.md`, then `CLAUDE.md` at repo root). If both exist, review both.
2. Evaluate against each rubric below. For every issue, quote the offending lines and propose a concrete rewrite — not just a critique.
3. Report findings grouped by severity: **Cut** (delete), **Rewrite** (fix in place), **Add** (missing required content).
4. End with a one-line verdict: total lines now vs. proposed, and whether the tech stack is mentioned.

Do not auto-edit the file unless the user asks. Surface the diff first.

## Rubric

### Length & signal density
*Good*: Short and load-bearing. Every line is non-obvious and would change agent behavior if removed.
*Bad*: Long preambles, restated obvious facts ("we use TypeScript"), or generic engineering advice. Flag any file over ~200 lines as suspect and identify the lowest-signal sections to cut.

### Non-obvious content only
*Good*: Conventions, architecture choices, tooling quirks ("we use bun, not node"; "migrations run via `make db-migrate`, not the ORM CLI").
*Bad*: Anything derivable from `package.json`, `Cargo.toml`, file extensions, or a five-second skim of the repo. Cut it.

### Tech stack is mentioned
*Good*: The language/runtime/framework choices the agent would otherwise guess wrong are mentioned somewhere in the file (e.g., "Bun 1.x runtime, not Node"; "Postgres 16 + Drizzle, not Prisma"). A dedicated `## Tech Stack` section is fine but not required — a one-liner near the top works too.
*Bad*: No mention at all of the non-obvious stack choices, so the agent has to infer them from manifests. If missing, propose a short addition drafted from the repo's manifests.

### Auto-generated content
*Good*: Hand-written, curated.
*Bad*: Looks `/init`-generated — boilerplate headings, file-tree dumps, restatement of `package.json` scripts. Auto-generated context files measurably reduce success rates. Recommend deletion and replacement with a hand-written file.

### Outdated docs
*Good*: Current. References match the code.
*Bad*: Mentions removed files, renamed commands, deprecated workflows. The agent reads these anyway and gets misled. Flag specific stale references and recommend deletion from the repo, not just from the context file.

### Don't redocument the formatter / linter
*Good*: Silent on style — `prettier`, `eslint`, `rustfmt`, `ruff` enforce it.
*Bad*: "Use 2-space indent", "prefer single quotes", "no unused imports". Cut. If a rule isn't enforced by tooling, recommend adding the rule to the tooling instead of to the context file.

### Procedural workflows live elsewhere
*Good*: Recurring multi-step tasks (release, migration, deploy) live in slash commands or skills. `AGENTS.md` points to them by name.
*Bad*: Numbered step-by-step procedures embedded in `AGENTS.md` itself. Recommend extracting each procedure into `.claude/commands/<name>.md` or a skill, and replacing the section with a one-line pointer.

### Decision tables for genuine choices
*Good*: When 2–3 valid approaches exist, a small table with columns like *Situation* / *Use* / *Why*.
*Bad*: Prose that lists options without telling the agent which to pick when. Convert to a table.

### Pair every "don't" with a "do"
*Good*: "Don't add new endpoints to `legacy/api.ts` — add them to `routes/v2/` and register in `routes/index.ts`."
*Bad*: "Don't touch the legacy module." A bare prohibition makes the agent over-explore looking for the allowed path. Flag every unpaired "don't" / "never" / "avoid" and propose the missing "do".

### Progressive disclosure
*Good*: The always-loaded root file is small. Path- or task-specific guidance lives in nested `AGENTS.md` files (e.g., `services/billing/AGENTS.md`), slash commands, or skills, surfaced only when relevant.
*Bad*: One mega-file with sections that only apply to one subdirectory or one rare task. Identify those sections and recommend moving them to a nested file or a skill.

## Output format

Structure the review as:

```
## Cut (N lines)
- L12–18: <quote>. Reason: <which rubric>. Replacement: <none / shorter line>.

## Rewrite
- L34: <quote>. Issue: bare "don't". Proposed: <do-form>.

## Add
- Tech stack not mentioned. Proposed addition (one-liner or section):
  <draft>

## Verdict
Before: 187 lines. After proposed edits: ~60 lines. Tech stack mentioned: no → added.
```

Be specific. Quote line numbers. Propose replacement text, not just labels.