# A checklist for reviewing a coding agent's work.

Canonical: https://plottypus.com/blog/review-code-written-by-coding-agents

Last updated: 2026-10-14

> How to review code a coding agent wrote: read the ask first, check test edits on their own, rerun the tests, watch scope. Copy-paste checklist included.

**Quick answer:** Review agent code the way you'd review a confident new hire's: start from what you asked, not from what it says it did. Read the ask, then the test changes on their own, then rerun the tests yourself, then the rest of the diff for scope and risky operations. Skip style. The full checklist is at the end, ready to paste into a pull request template.

## How is reviewing agent code different?

The basics of a good review don't change. Google's engineering practices still apply: look at design, functionality, complexity and tests first. Three things shift when an agent wrote the change:

- **The description is confident.** An agent's summary reads like a finished report whether or not the work is finished. Treat it as a list of claims.
- **The tests are part of the change.** The same agent wrote the code and the tests, sometimes in the same minute. "Tests do not test themselves", as Google's guide puts it, and with an agent that's literal.
- **The volume is higher.** Agents produce more code per hour than you can read closely. You need an order that finds the expensive problems first.

## Step 1: what did I actually ask for?

Before you open the diff, reread the task. Write down in one line what "done" means: the behaviour, the file or endpoint, the case that was broken. This is the only part of the review the agent can't do for you, because the agent's understanding of the task is the thing you're checking.

If the task was vague, that's useful to know now. A lot of "wrong" agent work is a correct answer to a different question.

## Step 2: what changed in the tests?

Look at test files separately from source files. Against the branch point:

```bash
git diff main...HEAD --stat -- tests/
git diff main...HEAD -- tests/
```

For each change, ask whether an assertion got weaker. An expected value changed to match the output, an exact check loosened to "not null", an error-case test removed, a new skip marker. This matters more with agents than with people. In ImpossibleBench, a 2025 study where the spec and tests were made to conflict, Claude models mostly got to a pass by modifying the test cases.

Some test edits are right: a test for old behaviour you asked to change should change. The goal is to read them on purpose.

## Step 3: do the tests pass when I run them?

Run the suite yourself, from a clean shell, with caching off where the runner caches (`go test -count=1 ./...` in Go). Don't count the agent's run. It may have run before its last edit.

Then do the check that catches the most: for a bug fix, set the source change aside and confirm the new test fails without it.

```bash
git stash push -- src/
<your test command>      # the new test should fail
git stash pop
```

If the test passes either way, it doesn't test the bug. The details for each of these checks are in [your coding agent said done, here's how to check](https://plottypus.com/blog/coding-agent-says-done-but-it-isnt).

## Step 4: is anything unfinished?

Read the new functions in full. Look for:

- a fixed return value where logic should be
- `TODO`, `FIXME` or "not implemented"
- an error caught and logged, then ignored
- a feature flag or config that turns the new path off

A quick grep of the added lines finds most of them:

```bash
git diff main...HEAD | grep '^+' | grep -nE 'TODO|FIXME|not implemented|except.*pass|catch *\(.*\) *\{ *\}'
```

## Step 5: did it stay in scope?

List the files the change touched and compare them to the one line from step 1:

```bash
git diff main...HEAD --name-status
```

Agents tidy up as they go. Renamed variables in unrelated files, a reformatted module, an upgraded dependency, a "small refactor" of a helper three other features use. Each one is a risk you didn't ask for. Google's guide warns reviewers to be "especially vigilant about over-engineering", and agents over-build readily. Ask for out-of-scope changes to be split into their own branch. If two agents worked on the same area, check for overlapping files too; [what happens when two coding agents edit the same file](https://plottypus.com/blog/two-coding-agents-edit-the-same-file) has the numbers.

## Step 6: did it touch anything risky?

These deserve a line-by-line read no matter how small the change looks:

- **Migrations and schema changes**, especially drops, renames and anything that rewrites rows
- **Deletes**: `rm -rf` in scripts, `DELETE` without a `WHERE`, cleanup jobs
- **Secrets and config**: keys in code, `.env` files, changed CI variables
- **Auth and permissions**: middleware order, a check moved or removed
- **Dependencies**: new packages, version bumps, lockfile churn
- **Concurrency**: locks, retries, timeouts, anything with "async" in the diff

## Step 7: what can I skip?

Style. Let the formatter and linter own it, and don't spend review time on naming preferences. Google's guide says not to block a change "based only on personal style preferences", and that goes double when the author is a program that will happily rename everything again.

Also skip the urge to comment on everything. If you use a second agent to help review, tell it to report only problems that affect correctness or the task. Anthropic's Claude Code docs note that "a reviewer prompted to find gaps will usually report some, even when the work is sound." A few comments, each with file, line and evidence, beat a long list nobody acts on.

## The copy-paste checklist

```markdown
## Agent change review

**The ask, in one line:**

### Tests
- [ ] Read every test file change on its own (`git diff main...HEAD -- tests/`)
- [ ] No assertion got weaker; no expected value changed just to match output
- [ ] No new skip, xfail or .only; no test file deleted
- [ ] I ran the suite myself, after the last commit, with caching off
- [ ] Bug fix: the new test fails with the fix stashed, passes with it

### Finished
- [ ] No fixed returns, TODOs or "not implemented" in new code
- [ ] Errors are handled, not logged and dropped
- [ ] The changed code is on the path that runs (not a copy or generated file)

### Scope
- [ ] Every touched file is needed for the ask
- [ ] Unrelated refactors, renames and upgrades split out

### Risk (read line by line if present)
- [ ] Migrations or schema changes
- [ ] Deletes in code, scripts or SQL
- [ ] Secrets, env files, CI config
- [ ] Auth or permission checks
- [ ] New or bumped dependencies
- [ ] Locks, retries, timeouts

### Comments
- [ ] Each comment has file:line and evidence
- [ ] No style comments the linter should own
```

## Where plottypus fits

This checklist is the review I want on every agent change, and most of it is mechanical: was the suite rerun, did a test get weaker, is there a stub. plottypus is a second agent that does that part while the Claude Code session is still running, and tells the agent before it says "done", with fewer comments and proof on each. Our results, including what it misses, are on [the evals page](https://plottypus.com/evals). For the reasons a second reviewer helps at all, see [should one coding agent review another's work?](https://plottypus.com/blog/should-one-coding-agent-review-another). If you'd use it, [start a free trial](https://plottypus.com/pricing).

## Sources

Checked 14 October 2026.

- Google, [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html), engineering practices.
- Anthropic, [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices), "Add an adversarial review step".
- Zhong, Raghunathan and Carlini, [ImpossibleBench: Measuring LLMs' Propensity of Exploiting Test Cases](https://arxiv.org/abs/2510.20270), October 2025.
- Go, [cmd/go: Test packages](https://pkg.go.dev/cmd/go#hdr-Test_packages) (test caching and `-count=1`).
- Git, [git-diff](https://git-scm.com/docs/git-diff) and [git-stash](https://git-scm.com/docs/git-stash).

---

*plottypus is independent and not affiliated with any company or project named here. Claude Code is a trademark of Anthropic. Names belong to their owners. This is our research and opinion, dated above; details may have changed.*