How I check an agent's work

When an agent finishes a task, it provides a summary of what it changed and which tests it ran. I use that report to get oriented, but not as confirmation. Confirmation comes from the diff and from running the checks again.

This matters because an agent's mistake rarely arrives labeled as a mistake. The code can look right, pass the obvious cases, and still leave an important detail behind.

The error that looks correct#

Some problems are small enough to survive a quick review: a test covers the main path but misses an edge case, a literal color appears where a token belongs, or a UI string exists only in Portuguese.

The agent may have run the right suite without writing the test that exposes the problem. I need to look at both the reported result and what the implementation never exercised.

Check without inheriting the reasoning#

I start from the diff, read every line, and run the gates in a clean session: pnpm typecheck, pnpm lint, pnpm test, and pnpm build. When a report mentions a score or an audit, I try to reproduce it.

This was already the job of the second terminal. I later turned the same idea into three verifiers, each responsible for one class of mistake. They all start from the diff, and none of them edits the code under review.

What each verifier does#

The three verifiers live in .claude/agents/ and are read-only:

• code-reviewer runs typecheck, lint, tests, and the Turbopack build. It also reads the full diff, checks scope, and looks for violations of the Next 16 and design-system conventions.
• i18n-consistency-checker compares the keys in messages/pt.json and messages/en.json, checks that posts exist in both languages, and looks for internal links that ignore the locale.
• a11y-checker reviews alt, label-in-name, and WCAG 2.1 AA contrast. Instead of looking only at the Lighthouse score, it opens each relevant audit.

Why separate them#

A general review has to split its attention across correctness, scope, i18n, accessibility, and style. Giving each verifier a smaller responsibility makes the criteria clearer and the report easier to check.

The code-reviewer doesn't need to calculate contrast. The a11y-checker doesn't need to decide whether a file belongs to the ticket. They may still find the same problem, but they reach it through different checks.

Because the instructions live in files, I don't have to remember every item each time I open a review.

The cost of the workflow#

Three agents reading the same diff use more tokens and take more time than a direct commit. I accept that cost on changes where a small mistake can survive the common checks.

In a recent review, two defects passed both the build and Lighthouse. A comment in a code block had a 3.74:1 contrast ratio, below the 4.5:1 required by AA. Another issue broke label-in-name because the visible text was not part of the accessible name.

The aggregate score stayed green. The problems appeared when the a11y-checker opened the individual results. That is the kind of detail these three reviews are meant to catch before I call a change done.