Reviewing AI-written code against user outcomes
Get Claude Code to Catch Bugs Outside the Diff
Claude Code can review a clean diff and still miss a broken user flow. I give the reviewer a failure brief so it checks what the patch leaves out.

To get Claude Code to catch bugs outside the diff, I give it the user promise before I give it the patch. A reviewer needs to know what must still work, what failure would look like, and where to find evidence. Otherwise, it can carefully inspect every changed line and approve a feature that breaks the moment someone uses it. When I ship a SaaS product solo, that gap matters more than how polished the review sounds.
I use AI to build and ship real products, including Tadam, an AI ad creative studio built for Hebrew-native ads. That work keeps bringing me back to the same problem: the code an agent writes contains its interpretation of the task. If I ask another agent to review only that code, I give it the interpretation without the original promise. It can find implementation mistakes while completely missing a requirement the implementation never attempted to satisfy.
The missing requirement has no changed line
Consider a hypothetical change in Tadam: letting someone retry a failed creative generation. The patch might add a button, connect a request, and display the result. A reviewer can check the handler, error handling, and component state. But the important product question sits outside those lines: what happens to the person's previous usable result while the retry runs? A technically correct retry can still create a bad experience if it makes existing work disappear.
That example is a review exercise, not a claim about a production incident. It shows why I want the review to start with behavior. If the brief only says 'add retry,' both the author and reviewer can reasonably overlook preservation of the previous result. Asking for a more thorough review does not supply that missing decision. I have to define the expected behavior, or have the reviewer surface the ambiguity before the change ships.
Give the reviewer a failure brief
My review brief is short enough to read before opening the diff. It describes the user action, the outcome I am promising, and the conditions that would make me reject the release. I anchor it in the task and existing product behavior, rather than copying the implementation agent's summary. For the retry example, I would give the reviewer the following brief. These are proposed acceptance conditions for that scenario, not assumptions about how every generation product should work.
- User promise: someone can retry a failed generation and understand whether the new attempt is running, complete, or failed.
- Preservation rule: an existing usable result remains accessible while the retry runs and if the retry fails.
- Repeated action: clicking again during an active attempt must follow the product's defined behavior, with no accidental duplicate work.
- Recovery condition: after leaving and reopening the page, the displayed state must agree with the state the server actually retained.
- Review evidence: trace the relevant request, saved state, and rendered result; identify which conditions were executed and which were only inspected.
Start a fresh review with the original task
I want a fresh review context because the implementation conversation accumulates explanations for why the patch looks the way it does. Those explanations are useful, but they can also become assumptions the reviewer inherits. I give the reviewer the task, the failure brief, the relevant repository instructions, and access to the code. Then I ask it to map each acceptance condition to the implementation and available evidence. Missing coverage becomes something it must report explicitly.
A fresh context does not make an AI reviewer independent in the same sense as a person with different experience. It can still share the author's blind spots. The value comes from changing the assignment and making its claims checkable. Instead of asking whether the patch looks correct, I ask where the product promise is enforced and how we know. If the answer points only to a button handler, but the promise depends on persisted state, the review has exposed unfinished work.
Approve evidence, not a reassuring verdict
I separate a finding from an unanswered question. A finding identifies a concrete mismatch, the path that triggers it, and its consequence. An unanswered question identifies a condition the reviewer could not establish. Both are useful, but they require different next steps. A reproducible mismatch needs a fix. An unverified recovery path needs a focused check. Neither becomes resolved because the reviewer ends its response with 'overall, this looks good.'
This also keeps verification proportional. I do not need an elaborate test suite for every copy change. I do need a check that can catch the failure I care about when a change affects saved work, access, or an asynchronous operation. For the retry exercise, a successful response alone proves very little about recovery after navigation. I would verify the relevant failure and recovery paths in a safe test environment, then keep the result attached to the change.
The review should challenge my brief too
The brief is my responsibility, and it can be incomplete. I therefore ask the reviewer to identify missing product decisions as well as broken code. Should a retry preserve the previous result? What should a second click do? Those questions deserve explicit answers before they become accidental behavior. Better coding agents let me produce changes faster. To turn that speed into reliable releases, I need reviews that can reject the assumptions behind a patch, with evidence clear enough for me to act on.
A little more detail
Questions & answers
What should I give Claude Code before asking it to review a patch?
Give it the original task, the expected user outcome, a short list of failure conditions, and the relevant repository instructions. Ask it to connect each condition to code and evidence, including anything it could not verify.
Should I use a separate Claude Code session for code review?
I use a fresh context to reduce dependence on the implementation conversation. That helps the reviewer examine the original requirements, but it does not guarantee different reasoning or complete coverage.
How is a failure brief different from a test plan?
A failure brief defines the outcomes that would make the release unacceptable. A test plan describes how to check them. I establish the product conditions first, then choose the smallest meaningful checks.
Can an AI code review replace running the feature?
Reading code can expose defects, but it cannot establish that every relevant user flow works. When the change depends on runtime behavior, I require focused execution evidence alongside the review.
Keep exploring.
Browse all articles

