How to write a code review prompt: six rules and a template

Why most code review prompts produce noise

Most code review prompts are a list of topics: “Review this code; look for bugs, security holes, performance and readability.” The model takes the list at its word and writes something under every heading. You get a long, polite comment that is mostly useless. The author of the pull request either reads it all and throws most of it away, or skips it entirely.

What actually changes the output is a demand for evidence: the model reports what it can show and leaves out what it cannot. In diffox, which splits a pull request across 17 specialist agents, every agent’s instructions open with that same requirement (a separate post explains how it works). The six rules below come from that experience and from the tools’ own documentation.

The six rules

1. Ask for evidence. A finding should come with a concrete input or state that produces the wrong result: “When the list is empty, the average divides by zero.” If the model cannot come up with such a scenario, it should stay quiet. This one sentence gets rid of most “you might also want to look at this” comments.
2. Ask for a verbatim quote, not a line number. Models are bad at counting lines, but a quote is something you can search the file for. Anthropic’s documentation recommends the same technique: if the model cannot find a quote that supports a claim, it should retract the claim (source).
3. Limit the scope to this change. A review is about problems caused by the lines the pull request adds or changes. Blame today’s author for every flaw in the old code and nobody will read the comment.
4. Leave out matters of taste and what your tools already check. Formatting, naming preferences and a missing comment are not review findings; do not have the model repeat what the linter and the type checker already report. Codex’s documentation says the same: leave formatting and lint checks to CI.
5. Define severity. Write down what “blocking” and “minor” mean: a wrong result, data loss or a security hole is blocking; something that shows up only on a rare path, or is no more than a misleading name, is minor. Without a definition, every finding comes out “important”.
6. Set the output format. Every finding should come with the same fields: file, quote, scenario, wrong result, severity, a one-line fix. If there are no findings, the model should say so in one line and stop, rather than pad out an empty review.

What the six rules have in common is that each describes a check the model can actually make. “Be careful” cannot be checked; “is the quote in the file?” can.

Copy this template and adapt it to your repository

The prompt below puts the six rules together. Its last line sets the language of the comments; change it if your team reviews in another language. Beyond that, there are two places to adapt: the severity definitions and the “do not report” list.

You are reviewing a pull request. Report only defects that this
change introduces or exposes.

A finding is valid only if you can state all three:
1. the code, quoted word for word from the changed lines;
2. a concrete input or state that reaches that code;
3. the wrong result that follows, and what the right one would be.
If you cannot state all three, do not report it.

Do not report: style, formatting, naming taste, missing comments,
anything a linter or a type checker already reports, or code this
change did not touch.

Severity:
- blocking: wrong result, data loss, security hole, or a crash on
  an ordinary path
- minor: wrong only on a rare path, or a name, comment or test that
  says something the code does not do

For each finding give: file, the quoted code, the scenario, the
wrong result, severity, and a one-line fix.
If you find nothing, write "No findings" and stop.
Write the findings in English.

We kept the template short on purpose. Claude Code’s documentation warns that length has a cost: a long instruction file dilutes the rules that matter most. When you add rules of your own, check whether each new line actually changes a finding.

Which file does each tool read?

Where you write the prompt depends on the tool. We built the table below from each tool’s own documentation on 15 October 2026.

Source: each tool’s own documentation, 15 October 2026.

Two details are easy to miss. In Claude Code, only the managed Code Review on GitHub reads REVIEW.md; /code-review in the terminal does not. Copilot reads instructions from the pull request’s head branch, the one with your changes, so a pull request that changes an instruction file also changes the rules for its own review.

To turn your own prompt into a command in Claude Code, write a skill: put the template in .claude/skills/review-pr/SKILL.md and add the line !`git diff main...HEAD` at the top. That line runs the command and puts its output into the prompt, so when you type /review-pr, the model finds the diff already there (skills documentation).

Writing rules for your own repository

The template covers the basics; the real value is in your repository’s own rules. These are the things you find yourself saying in every review: which data may not cross which layer, which side effect is dangerous, which contract must not break.

A good rule has three parts, and Codex’s documentation lists all three: the behaviour to flag, why it matters, and the safe path or exception. The third is the one people forget most often: if you do not tell the model the right path, it flags the expected behaviour as a bug too.

• Weak: “Be careful with database queries.”
• Strong: “Every query must be scoped to the caller’s tenant. Safe path: the scoped() helper. Exception: admin reports.”

You can set the evidence requirement at the repository level too. Claude Code’s documentation gives an example: a claim about behaviour must point to a file and line in the source rather than be inferred from a name. This one rule cuts the false alarms that would otherwise cost the author a round trip.

When one prompt is not enough

Ask one prompt about security, concurrency, tests and rule compliance all at once, and the model splits its attention and finds a little of each. On large changes, split the work instead: each prompt looks for one thing, under the same evidence requirement.

The second step is to check what the model says. A model can sound convincing and still be wrong: it quotes a line that is not in the file, or objects to code the change did not touch. Because you asked for a quote, a program can check this: is the quote really in that file, and does it belong to the changed lines? Claude Code’s documentation describes the same pattern for its managed Code Review: each agent looks for a different class of issue, then a verification step filters out false alarms.

diffox does both steps for you: each of the 17 specialist agents on the team looks for one thing and shows what it found with a verbatim quote from the code; code, not a model, checks the quote. Any sentence in your repository’s root rules file (AGENTS.md or CLAUDE.md) that states an obligation also goes to the agents as a review rule.

Test the rule on a real pull request

You cannot tell whether a prompt is good by reading it. The most practical advice is in Codex’s documentation: open a representative pull request, ask for a review, refine the rules based on the findings, and narrow or remove the instructions that produce noise.

• Try it on a change that contains a violation the rule should catch: does it catch it?
• Try it on a change that uses the safe path: does it stay quiet?
• Try it on an unrelated change: does it still stay quiet?

Review the same pull request twice and you can get two different results, so a single run is not a result. Compare the same few pull requests before and after you add a rule.