# 15.6 Rules the reviewer reads (/building-ai-workers/code-review/rules-the-reviewer-reads) --- type: Document title: "15.6 Rules the reviewer reads" description: "A short project rules file, and a review rules file that says what failure means in this repository, read from main so a change cannot rewrite the rules it is judged by." status: stable order: 315.06 ksor: owner: team:panaversity audience: [ public ] approval: by: process:panaversity at: 2026-11-02T18:33:52Z chapter: "15" part: III expert_status: builder-only concepts: [ "15.6" ] last_verified: 2026-10-31 sources: - id: anthropic-team-review title: "How the Claude Code team does code review (Anthropic, October 15, 2026, accessed 2026-10-31)" resource: https://claude.dev/blog/solving-code-review-at-anthropic/ generated: at: 2026-11-02T18:33:52Z by: esl-rewrite/1.2.0+ksor.1 trust_tier: unverified build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85 dirty: true ksor_version: 0.0.60 --- **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](both-ai-vendors.md) 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](approval-scaled-by-risk.md)). Some managed reviewers, the ones a company runs for you, enforce this themselves ([15.11](both-ai-vendors.md)). 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: ```bash 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](checks-that-block.md) and [15.9](approval-scaled-by-risk.md)). **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](approval-scaled-by-risk.md). The next review reported two findings, both real. ```markdown ## 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.[^anthropic-team-review] **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. ![REVIEW.md, from a recorded commit on main, goes to the reviewer as the authority, and the reviewer loads it first. The pull request branch holds code and proposed edits to the rules, which go to the reviewer only as content to inspect. A note says rule changes need explicit approval, and a proposed edit does not control its own review.](img/rules-from-main.png) *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](both-ai-vendors.md#practice-rules-the-reviewer-reads), in your own tool, ten minutes. [^anthropic-team-review]: How the Claude Code team does code review, Anthropic.