On this page#
What changes when an agent does this#
Claude Code code review moves the bottleneck from finding possible defects to deciding which findings deserve trust. The agent can inspect broad change context and propose repairs quickly, but it cannot own repository invariants. The engineer’s job becomes evidence review: verify each claim, reject speculative cleanup, and approve only changes tied to an explicit requirement.
A large language model generates likely outputs from learned patterns; it does not independently know which behavior your repository must preserve. That distinction matters more in review than in code generation. Plausible criticism can look authoritative even when it conflicts with an undocumented invariant.
Use the agent for:
- Mapping a pull request to affected components.
- Finding missing validation, error handling, and test coverage.
- Tracing data or control flow across files.
- Producing small, reviewable repair suggestions.
- Challenging assumptions already stated by the author.
Do not delegate:
- The definition of correct behavior.
- Acceptance of security or migration risk.
- Decisions about intentional compatibility constraints.
- Final approval of generated patches.
That division preserves the purpose of code review: evaluating a proposed change, not merely generating more code around it. A claude code pr review is useful when it compresses investigation. It quietly hurts when its fluency replaces the engineer’s judgment.
The Claude Code overview explains the agent’s coding workflow. The missing operational rule is simple: broad read access can be useful, but write authority should remain narrow until the reviewer has validated the diagnosis.
Photo by Christina Morillo on Pexels.
The prompt chain#
A reliable review uses separate prompts for context, risk, evidence, and repair. One giant instruction encourages the agent to mix observations with assumptions and silently jump from “this may be wrong” to “I changed it.” Staging the work creates checkpoints where an engineer can correct the model before a weak premise becomes a patch.
Stage 1: Establish the contract#
Start by making the agent restate the change and the constraints it must preserve.
Review this change without editing files.
First identify:
- the intended behavior,
- the repository invariants that appear relevant,
- the public interfaces or stored data affected,
- assumptions you cannot verify from the available code.
Separate explicit requirements from inferred requirements.
Do not report defects yet.This prompt forces uncertainty into the open. If the agent cannot state the contract correctly, continuing the review is wasted motion. Correct its model of the repository before asking for criticism.
For unfamiliar workflows, the Claude Code documentation is the appropriate reference for tool behavior. It is not a substitute for repository-specific rules, which should be supplied through checked-in guidance, tests, schemas, or the review prompt.
Stage 2: Build a risk map#
Ask for prioritized inspection targets, not a generic review.
Using the confirmed contract, rank the changed areas by risk.
For each area, provide:
- the invariant at risk,
- the failure that could violate it,
- the files or symbols that require inspection,
- the evidence needed to confirm or dismiss the concern.
Do not propose fixes.This structure prevents a common failure: flooding the review with style comments while overlooking a state transition, authorization boundary, or compatibility promise.
Stage 3: Demand evidence#
Now require every finding to survive an adversarial check.
Inspect the highest-risk areas.
For each finding, return:
1. the exact code path involved,
2. a concrete triggering condition,
3. the observable incorrect result,
4. existing code or tests supporting the claim,
5. what evidence would disprove the finding.
Label unsupported concerns as hypotheses, not defects.The fifth item is crucial. A claim that cannot describe its own disconfirming evidence is usually too vague to block a pull request.
If your team uses “claude code ultra review” to mean an exhaustive pass, this is where rigor should increase: deeper traceability, not more comments. Exhaustiveness without evidence merely increases review noise.
Stage 4: Request the smallest repair#
Only confirmed findings should reach patch generation.
For each confirmed defect, propose the smallest repair that restores
the stated invariant.
Do not refactor adjacent code.
Do not rename unrelated symbols.
Do not alter public behavior beyond the confirmed requirement.
List the tests that should fail before the repair and pass afterward.
Return a patch plan before making any edit.The separation between plan and edit keeps scope visible. Engineers who want a reusable version of this chain can use PairFoundry’s Review and Repair pack; the packs overview shows the broader workflow options.
The gate#
The mandatory human gate sits between the patch plan and any file modification. At that point, stop and verify three things: the finding is real, the proposed behavior matches the repository contract, and the repair is the smallest safe change. If any one fails, the agent must not edit.
Use this approval checklist:
- Can you reproduce the failure logically from the cited code path?
- Is the violated invariant documented in code, tests, schema, or the task?
- Does the suggested repair preserve callers and stored data?
- Is every changed file necessary to fix the confirmed defect?
- Would the proposed test detect a regression rather than mirror the implementation?
- Can the patch be reverted without mixing it with unrelated cleanup?
The wrong gate is “the diff looks reasonable.” Generated code is optimized for plausibility, so visual smoothness is weak evidence. The right gate connects requirement → failure path → repair → regression test.
After approval, instruct the agent to implement only the accepted plan and return a concise change inventory. Then review the resulting diff as new, untrusted code. The broader workflow library is useful when this gate needs to fit alongside planning, implementation, or debugging practices.
Photo by ThisIsEngineering on Pexels.
What it gets wrong#
Claude Code most often fails by inventing intent, expanding scope, or confusing consistency with correctness. These failures are dangerous because the output is usually coherent. Detect them by checking whether every conclusion traces to repository evidence rather than to a familiar pattern the model expects to see.
| Failure mode | What it looks like | How to catch it | |---|---|---| | Invented invariant | “This function should always…” without support | Ask for the exact test, caller, schema, or requirement establishing “always.” | | Scope drift | A defect repair includes renaming or restructuring | Compare every edit with the confirmed failure path. | | Local-only reasoning | A change fixes one function but breaks a caller | Require call-site and data-flow inspection before approval. | | False positive | Unusual code is labeled defective because it is unfamiliar | Ask for a concrete input and observable wrong result. | | Test laundering | A new test merely asserts the generated implementation | Restate the behavior independently of the patch. | | Confidence inflation | Speculation is phrased as a blocking finding | Require hypotheses and confirmed defects to remain separate. |
Another quiet failure is omission. The agent may produce several strong findings, creating the impression that the review is complete while missing the repository’s most important boundary. A polished list is not coverage evidence.
Official product documentation explains capabilities and operation; it cannot describe your internal compatibility promises. Put those promises where both humans and agents can inspect them. If that foundation is missing, start with PairFoundry’s free foundations track before adding a more elaborate review chain.
Rollback#
A clean rollback starts before the agent edits anything: isolate the repair, preserve the pre-edit state, and forbid unrelated changes. If the patch proves wrong, revert the entire agent-authored repair rather than manually removing suspicious lines. Partial rollback leaves behind tests, helpers, or behavior changes whose original rationale has already collapsed.
Use this recovery sequence:
- Stop further edits as soon as the underlying finding is disproved.
- Identify every change produced from that finding, including tests and documentation.
- Revert that unit as a whole.
- Re-run the repository’s normal validation from the restored state.
- Rewrite the contract or prompt that allowed the false premise.
- Restart from evidence gathering, not from the rejected patch.
Do not ask the same conversation to “undo whatever was wrong” without specifying the accepted baseline. The agent may reinterpret its own work and preserve pieces that appear useful. Rollback is a state-restoration operation, not another creative coding task.
The safest unit of work is one confirmed defect per repair. That boundary makes review clearer, rollback mechanical, and authorship easier to audit.
Photo by Al Nahian on Pexels.
Related reading#
- Terraform MCP server: making the output reviewable, not just correct
- Claude Code Python, with the guardrails that keep it honest
FAQ#
Should Claude Code review every pull request in a production repository?#
No. Use it where code inspection and traceability are the bottlenecks, especially across multiple files or unfamiliar control flow. Skip it for changes whose risk cannot be evaluated from repository evidence, such as decisions relying on unstated operational knowledge. The agent should supplement accountable reviewers, never satisfy an approval requirement by itself.
How is this different from following the official Claude Code workflow?#
The official documentation explains how to operate Claude Code; this workflow defines a review control system around it. The important additions are contract reconstruction, evidence requirements, a human pre-edit gate, and rollback boundaries. Those controls come from the risks of agentic review in a real repository, not from a claim that the tool can determine correctness autonomously.
What is the biggest team collaboration pitfall?#
Allowing generated findings to become blocking comments before a human validates them. That creates noise, forces authors to disprove speculative claims, and weakens trust in review. Teams should distinguish hypotheses from confirmed defects and require a concrete failure path before an agent-generated comment can block a pull request.
What should I do when an agent-generated repair passes tests but still looks wrong?#
Reject the repair and inspect the tests. Passing tests prove only that the exercised assertions succeeded; they do not prove the repository invariant was captured correctly. Recheck the intended behavior, callers, stored data, and compatibility boundaries, then request a smaller plan tied to independently stated acceptance criteria.
When should I avoid a claude code pr review entirely?#
Avoid it when the reviewer cannot provide or recover the governing contract, when sensitive context cannot be exposed to the tool, or when the change requires judgment outside the codebase. In those cases, agent output adds confidence without authority. Resolve the missing context first, then decide whether automated assistance has a legitimate role.