review-agents-md

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.

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

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.

Good: Conventions, architecture choices, tooling quirks ("we use bun, not node"; "migrations run via , not the ORM CLI"). Bad: Anything derivable from , , file extensions, or a five-second skim of the repo. Cut it.

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 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.

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

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.

Good: Silent on style — , , , 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.

Good: Recurring multi-step tasks (release, migration, deploy) live in slash commands or skills. points to them by name. Bad: Numbered step-by-step procedures embedded in itself. Recommend extracting each procedure into or a skill, and replacing the section with a one-line pointer.

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.

Good: "Don't add new endpoints to — add them to and register in ." 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".

Good: The always-loaded root file is small. Path- or task-specific guidance lives in nested files (e.g., ), 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.

Structure the review as:

undefined

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

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