15.6 Rules the reviewer reads
- Approved by
- Panaversity ·
In everyday life. The editors at a newspaper correct every article, and they work from a style guide. It does not say "write well". It says what counts as an error at this paper: a misspelled name, an unchecked number, a quote without a source. It also says what to leave alone. A new editor follows it on day one, and the paper's writers cannot change it to meet a deadline.
What you will learn. How to write the rules an AI reviewer follows, and how to make sure it reads the copy on main.
Why it matters. A reviewer knows nothing about your project until it reads your files, so what it finds depends on what you wrote.
What does a reviewer read before it reviews?
A short file of rules, written for reviewers only. This is Brightline's:
# Review rules
## What failure means here
- A total that differs from what AP expects.
- A due date computed outside the due-date code.
- A key printed or committed.
- An existing test changed to make code pass.
## Skip
- `package-lock.json`, `py/uv.lock` and `exercises/`.
## How to report
- Start with the number of findings. If there are none, say "No issues found." and stop.
- Every finding names a file and a line, and says what input would make it go wrong.
- Report at most three nits. Never report formatting.This is a review rules file. It is the editors' style guide. Ana's file has one more part at the end, the risk tiers of 15.9, left out here.
In this chapter you keep the review rules in one file, REVIEW.md. The project rules file, AGENTS.md, stays short, because every agent reads it in full at the start of every session.
What does a good review rules file say?
Five things, and each one is in the file above.
- What failure means here. Not "find bugs". The style guide does not say "write well". Brightline's file names four failures in its own words, such as a total that differs from what AP expects.
- How many nits. A nit is a small point that should not block a change. A reviewer that reports twenty nits hides the one finding that matters.
- Which paths to skip. Lock files and other generated output: files that a tool writes, not a person. Also practice files. Never the risky parts, such as the tests or the payment code.
- What each finding must show. A file, a line, and the input that would make it go wrong. Then you can check the finding yourself, at the exact place.
- A count first, and a plain answer when there is nothing. A reviewer told to find problems will otherwise invent some.
At work. Ana's first REVIEW.md said "review carefully for bugs". The first review reported eleven findings, nine about naming. She rewrote it as the file above. The next review reported two findings, both real.
Why must the reviewer read the rules from main?
So that a change cannot weaken the rules it is judged by. The paper's writers cannot change the style guide to meet a deadline. But an agent on a branch can edit REVIEW.md: it could add "Skip src/due-date.ts" in the same change that breaks that file. A reviewer that read the branch's copy would obey.
A reviewer you start yourself reads whatever copy is in its folder, and on a branch that can be the changed copy. So never just say "read REVIEW.md". Say which copy:
Review the diff between main and this branch. First read REVIEW.md as it is on main, not this branch's copy, and follow it. Change nothing.
A change to REVIEW.md itself is a high-risk change, and a person approves it (15.9).
What if a finding keeps coming back?
Fix it at the source: move the rule to where a machine checks it every time, such as a test, or add a line to the rules file.
A rules file only guides a reviewer. It does not stop a merge: only the repository's own checks and approvals do (15.8 and 15.9).
Try it
In your practice folder from 15.1, the project has no REVIEW.md yet. You will write three lines of review rules, and then see why a reviewer reads them from main.
-
Here are three lines of rules. You may change the third, which says what every finding must name. Send all of it in one message:
Write these three lines to a new file REVIEW.md on main, and commit it: A total that differs from what AP expects is a failure. Report at most three nits. Never report formatting. Every finding names a file, a line and an input that fails. -
Write your prediction first. A branch adds one line to
REVIEW.md. After that, which copy holds the new line: the branch's copy, the copy onmain, or both? -
Send: "Make a new branch practice-rules. Add this line to REVIEW.md: Skip src/due-date.ts. Commit it."
-
Send: "Show me REVIEW.md as it is on this branch, and as it is on main. Then switch back to main."
What you should see. The branch's copy holds your three lines and the new line that skips src/due-date.ts. The copy on main holds only your three. A reviewer that read the branch's copy would skip the file that computes every due date. You will see a reviewer use your file in the Try it of 15.7.
The operating rule: write the review rules as what failure means in this repository, give the reviewer the copy on main, and move any finding that repeats into a check.

Figure 15.11. The reviewer reads the rules from main. A change cannot rewrite the rules it is judged by.
Other words you will meet
| Word | What it means |
|---|---|
git show main:REVIEW.md | The command that prints the file as it is on main, whatever branch you are on |
| Base branch | The branch a pull request will merge into. Here it is main |
| Linter | A tool that checks code style, so a reviewer does not need to |
| Managed reviewer | A reviewer that a company runs for you, on its own computers |
In your tool: the details
Each product has its own place for review rules.
Claude Code reads CLAUDE.md. From version 2.1.277 it reads AGENTS.md instead when there is no CLAUDE.md or CLAUDE.local.md in the folder or above it. Where it cannot, a CLAUDE.md that imports @AGENTS.md loads the same rules, which is why Brightline keeps both.1 Code Review, the managed service, reads REVIEW.md from the base or default branch, never from the pull request's changes, plus CLAUDE.md files. Its rules for skipping paths, capping nits and lowering severity are honored only when the default branch is protected.2 /code-review reads CLAUDE.md, not REVIEW.md.3
Codex reads ## Code Review Rules sections in AGENTS.md files. It applies the root file, and any more specific file that covers each changed file. OpenAI's page says these rules guide Codex and do not replace tests, branch protections or required approvals.4 For a review you start yourself, paste the output of git show main:REVIEW.md into your prompt.
There are no built-in review rules, because there is no built-in reviewer. You write a command file that reads them: have its prompt read the rules with git show main:REVIEW.md, because a reviewer you run yourself reads whatever copy is in its folder.5
Next. 15.7 reads what an AI reviewer finds, and answers each finding.
Check yourself
Question 1 / 8
0 answered
Which line belongs in a review rules file?
Sources
- Owner
- Panaversity