Code review best practices

Code review best practices that hold up in research and in agent-to-agent review: keep changes small, write the project's rules down, answer every finding, judge disputes against the code, turn repeated rejections into rules, and keep people on policy rather than on every diff. The evidence is published studies and CodePanel's own pull requests.

On CodePanel's own repository, Claude Code wrote 147 of the 150 pull requests merged from PR 61 to PR 213 as of 17 October 2026, and it reads the reviews. These practices are what that loop settled on, checked against what the studies say.

Small changes get read, large ones get skimmed

The studies agree on the direction, less so on the number:

Weigh the last row carefully. It is an industry case study with no stated statistical methods and no peer review. Its often-quoted 60-minute limit is derived by arithmetic from two other figures, and it reports that its measure, defects found per thousand lines, falls as the change grows. That fall is weak evidence on its own: a fixed number of defects spread over more lines would produce it too. It fits the pattern of the other rows and proves little on its own.

Agents do not follow the pattern. As of 17 October 2026, the median merged pull request on CodePanel's repository changed 434.5 lines across 12 files (150 pull requests, additions plus deletions, so documents and data files count). That is far above the medians in the table, though the studies count lines differently.

A model reviewer copes better than a person, up to a limit. CodePanel's reviewers get the diff (up to 120,000 characters a round and 20,000 per patch) and the code around each change: the whole file up to 24,000 characters, otherwise 40 lines around each change, for the first 25 changed files and 80,000 characters in all. Past either limit a reviewer has only the diff, and a pull request of 40 files is past the first.

So tell the coding agent to split work as you would tell a person: one behavior per pull request, with its tests, and moves and bulk edits apart from logic changes.

Review is mostly understanding, so ask for the reasoning

Bacchelli and Bird (ICSE 2013) classified 570 review comments at Microsoft. Defects were 78 of them (14%), and "code improvements" the largest group at 165 (29%): reviews are "less about defects than expected".

A reviewer agent cannot ask the author what a change is for, so the description has to say: what changed, why, what was left alone, and how it was tested. A reviewer that knows the intent judges the code against it; one that does not judges it against its own guess.

Write the project's rules down where the reviewer reads them

A reviewer applies the rules it has been given. Put the invariants in a file both the reviewer and the coding agent read, one checkable rule per line, on the base branch so a change cannot loosen its own rules. Writing review rules that agents follow covers how; Repo context and custom rules covers where CodePanel reads them.

Turn repeated rejections into rules, and keep them reversible

A false positive rejected once is noise. The same one rejected again and again is a missing fact about the codebase, and an agent that rebuts it every round wastes rounds.

CodePanel's orchestrator drafts the rule itself, under conditions the code sets:

• At least three false-positive verdicts from at least two pull requests must share a cause.
• The evidence is a person's false-positive rating with a note, or an agent's dispute the orchestrator conceded after reading the code. An agent's word alone is not evidence.
• The scope is the path prefix every cited file shares. The learning is active at once, applies to pull requests opened after it, reaches the orchestrator only (at most 10 per review), and never lowers a security or critical finding.
• Any down rating turns it off at once, and a finding a draft used is never drafted from again, so turning one off sticks. One left unconfirmed for 180 days stops applying.

A real one: on 17 October 2026 the orchestrator drafted learning L4, scoped to src/content/, from four findings rejected as false positives across PR 202, PR 187 and PR 178. L4 records that a test already validates every internal link and anchor in the content pages, so reviewers should not call them unverifiable. Later reviews of those files name L4 and say /feedback L4 down <reason> turns it off. Nobody wrote the rule, and anyone can see why it exists and undo it.

A rule can also be read too widely. On PR 178, two warnings cited a design rule on a public page: reuse the shared PageHeader, Section and Row components. Claude Code disputed both: those are dashboard components, and the guides index hand-builds the same layout. The orchestrator checked the code and withdrew both. The rule names dashboard components but applies to every TSX and CSS file under src/. Scope a rule to where it holds, and narrow it when it is cited elsewhere.

Answer every finding, and keep the score honest

An unanswered finding teaches nothing. A fix, or a rating with a reason, closes it, and later reviews of the same files remember the reason. Rate every finding once, under one agent name.

Count the right thing. CodePanel's quality report (get_quality) counts decided disputes as verified evidence and the agents' own ratings toward no precision figure, because an author agent that fixes everything has a perfect fixed rate and its ratings measure compliance as much as accuracy. Judge disputes against the code: a confident rebuttal is an argument to check, not a reason to concede (Agentic code review shows how).

Respond before the author moves on

Google's engineering practices cap a review response at one business day, and say a team's speed depends on it. Between agents the budget is smaller: a session that has ended cannot act on a review, so the coding agent here blocks on wait_for_review in the same turn.

Push the fixes together: CodePanel holds each push for 60 seconds and reviews only the newest head (Triggering reviews).

Block on what matters

Perfect is not the bar: the same Google guidance says to approve once a change improves the code's health. The merge gate makes that the default: at the warning level, critical and warning findings must be answered and suggestions do not block. At all, every nit blocks.

A finding that blocks is a blocking finding, and the merge gate is the status that holds the pull request. Which field an agent should act on is in PR review; the levels are in Merge gate.

Review every change, not only the risky ones

McIntosh et al. (MSR 2014) studied three open-source projects, Qt, VTK and ITK. Components with low review coverage (the share of changes reviewed) had up to two more post-release defects, and low participation up to five more. The study is observational and per component, so it shows an association, and says nothing about change size or a panel of models.

The practice that follows: nothing merges unreviewed. All 150 pull requests merged from PR 61 to PR 213 were reviewed by CodePanel. It skips pull requests opened by bots by default, so the three bot-opened ones were reviewed after someone commented /review.

Keep people on policy, not on every diff

None of those 150 has a GitHub approving review: merging main takes CI and the CodePanel status, and the repository's maintainer docs say no approval is required (What is a pull request). People keep the settings an agent should not hold:

• Keys. Provider keys are entered in the browser, so they never pass through an agent's context.
• Scopes. A person chooses each token's scopes. A coding agent needs read and reviews:write, and nothing that lets it change the repository's settings or raise a budget.
• Rules. .codepanel/rules.md changes by pull request and is read from the base branch, so a change cannot loosen its own rules. A learning an agent adds stays a candidate until a person, or another identity on another pull request, confirms it.
• Budgets. Only a token with budget:write can raise a limit, and no other scope includes it.

Audit what the reviewer has learned

Learned rules drift. With the CodePanel MCP server connected, give your agent this:

Use the CodePanel list_learnings tool for owner/name. For each learning:
1. Say what it rests on. If its source is drafted, read drafted.evidence
   (label, file, note); otherwise give its source (comment, api or dashboard).
2. If its state.status is candidate, say what state.needs asks for.
3. Read the code under its scope and check that the fact is still true.
4. If the code contradicts it, call rate_learning with rating down, a reason,
   and a note that names the file and line that contradict it. If you cannot
   name one, leave it and report it instead. If it holds, leave it.
Pass the pull request you are on as pr. Report one line per learning: ref,
keep or turn off, and why.

rate_learning needs the reviews:write scope. An agent's down turns the learning off at once, for every later review, and only an up from the same identity undoes it, since each identity's latest rating is its word (Learnings). Have a person read the report before relying on it. An agent's up without pr never counts toward activation, so leave confirming to a person.

To set up the loop with your agent, start from the Quickstart. For how a round runs end to end, see AI code review.