Lesson 15.615.6 Rules the reviewer reads

In everyday life. A newspaper's copy editors, who correct every article, 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 says what to leave alone, too. A new copy 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 why it reads them from 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.

Which files shape a reviewer?

Two files. One is the rules file you met in Chapter 12. The other is a file only reviewers read.

The project rules file, AGENTS.md in Brightline, tells every agent what the project is, how to test it, and what must never happen. Agents find it in different ways, and 15.11 says how each does. Brightline also keeps a one-line CLAUDE.md that imports it, so every agent reads the same rules. Keep it short. It is read in full at the start of every session, so every line costs attention.

What does a good review rules file do?

The review rules file, REVIEW.md in Brightline, is for reviewers only. A good one does five things:

1. Says what failure means here. Not "find bugs". For Brightline: 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. For a docs repository, failure is "it lies". For a repository of settings, it is "it sends things to the wrong place".
2. Limits nits. "Report at most three nits. Never report formatting." The linter already checks style. A reviewer that reports twenty nits hides the one finding that matters.
3. Names paths to skip. Lock files, generated output, practice files.
4. Asks for evidence. Every finding names a file and a line, and the input that would make it go wrong.
5. Asks for a count first, and a plain answer when there is nothing. "Start with the number of findings. If there are none, say 'No issues found.' and stop." A reviewer told to find problems will otherwise invent some.

Why read the rules from main?

A review rules file is only useful if a change cannot weaken it. If the reviewer read the rules from the pull request's own branch, an agent could add "skip src/due-date.ts" in the same change that breaks it. So the reviewer reads the rules from main, and a change to REVIEW.md is itself a high-risk change that needs a person (15.9).

Some managed reviewers, the ones a company runs for you, enforce this themselves (15.11). A reviewer you run yourself does not. If it reads REVIEW.md at all, it reads the copy in its folder, and on a branch that can be the changed copy. So give it the rules from main yourself:

git show main:REVIEW.md

That prints the file as it is on main, whatever the current branch says. Paste it into the reviewer's prompt, or tell the reviewer to run that command itself. Never just say "read REVIEW.md".

What if a finding keeps coming back?

Fix it at the source. When a reviewer reports the same kind of finding twice, move the rule to where a machine checks it every time: a test, a lint rule or a required check. Otherwise, add a line to the rules file. A review that keeps catching the same mistake is a check that should have been automated.

Does a rules file stop a merge?

No. A rules file guides a reviewer. Only the repository's required checks and approvals stop a merge (15.8 and 15.9).

At work. Ana's first REVIEW.md said "review carefully for bugs". The first review reported eleven findings, nine about naming. She rewrote it: what failure means in AP, three nits at most, skip package-lock.json, py/uv.lock and exercises/, a file and line for each finding, and the risk tiers from 15.9. The next review reported two findings, both real.

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

In the case study. The team keeps its CLAUDE.md short and lets code owners write REVIEW.md. Its good review files say what failure looks like in that repository, limit the nits, list the paths to skip, and ask for a file and line as evidence.¹

The operating rule: write the review rules as what failure means in this repository, read them from 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.

Practice it. Practice: rules the reviewer reads, in your own tool, ten minutes.