review-agent-instructions

review-agent-instructions

A CLAUDE.md is a short, durable note from a human to an AI agent about this repo: what it is, why it exists, and how to work in it. It is not a README. It is not a style guide. It is the smallest set of instructions that prevents the agent from doing the wrong thing.

When to use

Invoke when the user says any of:

• •"audit / review / check my CLAUDE.md"
• •"improve / fix / clean up CLAUDE.md"
• •"bootstrap a CLAUDE.md for this repo"
• •equivalent requests for AGENTS.md, GEMINI.md, .cursorrules, etc. — same principles apply.

What to do

1. Locate the file. Default to ./CLAUDE.md. If absent and the user asked to bootstrap, propose creating one. If absent and they asked to audit, stop and ask.
2. Read it whole. Do not skim. Read related signals too: repo root listing, package.json/go.mod/pyproject.toml/Cargo.toml, top-level README, and existing scripts in Makefile / package.json scripts / justfile.
3. Critique against the principles below. Cite line numbers. Be specific.
4. Propose edits as a unified plan before touching the file. Show the user the diff intent in prose: what to add, what to cut, what to rewrite. Wait for approval.
5. Apply with `Edit` once approved. One logical change per edit. No bulk rewrites unless the user asks for a full replacement.

Principles

A good CLAUDE.md is judged on five things. These are heuristics, not scores — use judgment.

1. Grounded in this repo

Every instruction should refer to something that actually exists: a real script, a real path, a real command. Generic advice ("write clean code", "follow best practices") is noise — cut it. If a command is mentioned, verify it exists (grep the package.json scripts, check the Makefile).

2. Tells the agent what it can't infer

The agent already reads the code. Do not restate what grep would reveal. Keep only what the code doesn't say:

• •Non-obvious constraints ("never run migrations against prod; staging only")
• •Hidden conventions ("we use pnpm, not npm, despite the lockfile")
• •Past incidents codified as rules ("don't mock the DB in integration tests — see incident 2025-Q3")
• •Where to look for things that aren't in this repo (dashboards, runbooks, related repos)

3. Concrete verbs, exact commands

Replace vague verbs with executable ones.

• •Bad: "run the tests"
• •Good: "pnpm test:unit for unit tests, pnpm test:e2e for end-to-end (requires Docker running)"

4. Short

Aim for under ~60 lines. Hard ceiling around 200. Length is not a virtue — every line costs context on every turn. If you find yourself adding a sixth bullet to a list, ask whether bullets 4–6 are actually load-bearing.

5. Stable

Prefer rules that will still be true in six months. Rotate ephemeral things (current sprint, in-flight migrations) out — those belong in a PR description or a task, not CLAUDE.md.

Common violations and how to fix them

Examples

Copy-pastable before/after blocks. Each pair targets one violation.

Vague verb → exact command

Before:

## Testing
Make sure to run the tests before committing.

After:

## Testing
- `pnpm test:unit` — fast, runs on every save
- `pnpm test:e2e` — requires Docker; run before pushing

Restates the README → keep only what the agent can't infer

Before:

## About
This is a Next.js 14 app using TypeScript, Tailwind, and Prisma.
The frontend lives in `app/` and the API routes in `app/api/`.

After:

## Conventions
- Server actions only — do not add REST routes under `app/api/` (legacy).
- Prisma client is generated at build time; run `pnpm prisma:generate` after schema edits.

Aspirational rule → enforced rule, or delete

Before:

- Write clean, readable code.
- Follow SOLID principles.
- Keep functions small.

After:

- `pnpm lint` must pass; CI rejects warnings.
- Functions over 50 lines: split or document why.

Hedged voice → imperative

Before:

Tests should generally be run before opening a PR, and it's usually a good
idea to also check the type errors.

After:

Before opening a PR: `pnpm test && pnpm typecheck`.

Bootstrap template (when starting from zero)

# CLAUDE.md

## What this is
<one sentence: what the repo does, who uses it>

## How to work here
- Install: `<command>`
- Test: `<command>`
- Run locally: `<command>`

## Don't
- <hard rule grounded in a past incident or constraint>

## See also
- Runbook: <link>
- Dashboard: <link>

(Replace placeholders. Delete any section you can't fill with something specific to this repo.)

Output format

When auditing, structure the response as:

## Audit: <path>

**Strengths** (keep these)
- <line refs and what's working>

**Cut**
- L<n>: <quote> — <reason>

**Rewrite**
- L<n>: <quote>
  → <proposed replacement> — <reason>

**Add**
- <topic> — <why it's missing and what it should say>

**Verify before editing**
- <command/path the audit assumed exists — confirm before applying>

Then wait for the user to approve, modify, or narrow the scope before running Edit.

What this skill is not

• •Not a linter. Don't invent a numeric score; the principles above are sufficient.
• •Not a generator. Don't write a CLAUDE.md from a template — read the repo first.
• •Not a cross-repo aggregator. If the user wants org-wide patterns, that's a different tool (and it needs infrastructure that lives outside a skill).