September 24, 2026 · Harness Engineering · Coding Agents · Code Review · How-to · EN

How to Review Code from Multiple Coding Agents

A claim-first code review workflow for multiple coding agents: verify task contracts, inspect integration evidence, challenge risky boundaries, and review the combined outcome without reading every diff line by line.

How to Review Code from Multiple Coding Agents

The common review default is to open the largest diff and start at line one.

Read every file. Comment on naming. Ask why one helper moved. Repeat for every agent branch.

That feels thorough. It often spends the review budget on syntax while the dangerous questions remain unanswered — which contract changed, which branch depended on it, whether the evidence still holds after integration, and whether the combined result does what the task requested.

Here is the better default: review claims, contracts, and integration evidence first; use diffs to test those claims.

A multi-agent change is not one large patch. It is a stack of bounded claims produced from different checkpoints and combined under shared assumptions. The review has to reconstruct that stack before judging individual lines.

This page covers the review gate after workers have returned stable checkpoints and an integration candidate exists. It does not replace task decomposition, the coding-agent handoff protocol, dependency-aware integration, or the merge-conflict repair workflow. Those pages create the inputs. This page decides whether the claims survive review.

If the repository does not yet have standard task, evidence, and review artifacts, use repository-harness as the starting structure before adding more review agents.

The review object is the claim graph

A normal pull request often presents one author, one branch, and one narrative. Multi-agent work may contain five worker branches, three contract edges, two generated artifacts, and one final candidate.

The review object is therefore not only the final diff. It is this graph:

requested outcome
  -> accepted contracts
       -> worker claims
            -> worker evidence
                 -> integration order
                      -> combined candidate
                           -> final outcome proof

Each arrow can fail.

A worker may prove the wrong behavior. A consumer may use an earlier contract. An integrator may resolve a generated-file conflict by hand. A final test may pass against a fixture that bypasses the changed boundary.

The reviewer needs to ask whether every important claim has:

• one explicit owner;
• one stable checkpoint;
• one authoritative contract;
• one relevant proof path;
• one place in the dependency graph;
• one answer for omitted checks and residual risk.

The diff becomes useful after this map exists. Before that, it is an unordered pile of implementation detail.

Keep review separate from the neighboring jobs

The multi-agent operations cluster has several gates. Do not collapse them into one giant “review” activity.

Review should not invent missing task boundaries after the work is done. It should not become the place where an unresolved API decision is quietly chosen. It should not repair the integration branch until the tests turn green.

When an input is missing, return it to the owning gate. That keeps review from hiding process failures inside reviewer heroics.

The claim-first review workflow

The order matters. If review starts with the diff, the reviewer must infer the claim graph from implementation details. If review starts with claims and evidence, the diff has a job: confirm or falsify a specific statement.

1. Freeze the exact review candidate

Do not review a moving branch.

Record one base and one candidate:

## Review identity
- Requested outcome: avatar upload from web and CLI
- Base: `origin/main@a13f...`
- Candidate: `integration/avatar-upload@f563...`
- Working tree: clean
- Task graph: `docs/tasks/avatar-upload/graph.md`
- Integration record: `docs/tasks/avatar-upload/integration.md`
- Review owner: release maintainer

Verify those values in the repository. A branch name is not an identity because another commit can land while review is active.

If the candidate moves, decide whether the new commit invalidates earlier evidence. Do not carry approval forward by habit.

2. Reconstruct the requested outcome

Read the task packet before the agent summaries.

Write the outcome in one or two observable sentences. Then list constraints and non-goals.

Outcome:
A user can upload a JPEG or PNG avatar up to 2 MB from web and CLI.
Both clients surface the accepted validation errors.

Constraints:
The OpenAPI schema owns the public contract.
Generated clients remain reproducible.
The storage migration must preserve rollback.

Non-goals:
Image cropping and animated formats are not part of this change.

This prevents a polished worker narrative from redefining the task after implementation.

If the requested outcome cannot be stated clearly, stop. The review does not have an acceptance target.

3. Build a claim inventory

Turn every completion statement into a reviewable claim.

Avoid activity claims:

Weak:  Updated the web uploader.
Useful: Web maps every generated avatar validation error to an inline message.

Weak:  Added tests.
Useful: The browser smoke proves a 2.1 MB PNG is rejected with the accepted public error.

Weak:  Regenerated clients.
Useful: Both clients were generated from schema commit 4d31..., compile, and a second generation run is clean.

A useful claim can be disproved. That is what makes it reviewable.

4. Review contracts before implementations

Shared contracts control more risk than line count.

Review these first when they changed:

• public APIs and event schemas;
• database or persisted-state formats;
• command-line behavior;
• authentication and authorization boundaries;
• generated-source inputs;
• configuration and feature-flag semantics;
• error and retry behavior;
• ownership or instruction authority.

For every changed contract, ask:

1. Which source is authoritative?
2. Who accepted the new behavior?
3. Which workers produce it?
4. Which workers consume it?
5. Which compatibility promise applies?
6. Which check crosses the producer-consumer boundary?
7. Which downstream evidence was rerun after the final contract landed?

This is where many clean diffs fail. Separate agents can implement separate files while disagreeing about one shared behavior.

If the contract itself is still disputed, return to the owner. Do not let code review invent an undocumented compromise.

5. Challenge the evidence

Agent-reported evidence is a claim about a command, environment, checkpoint, and result. Review all four.

A useful record looks like this:

- Claim: C2, generated clients match the accepted API
- Checkpoint: `agent/avatar-client@91c2...`
- Input contract: `openapi/avatar.yaml@4d31...`
- Command: `scripts/generate-clients && scripts/check-generated-clean`
- Result: PASS; second generation produced no diff
- Environment: pinned generator from repository lockfile
- Omitted: Python package publish smoke
- Residual risk: publish metadata is covered only at release gate

Ask what the command proves. A passing unit test may prove a helper. It may not prove the public contract, the integrated binary, or recovery after failure.

Also ask what would falsify the claim:

• What input sits just outside the tested boundary?
• Which old state could break a migration?
• Which permission could bypass the intended authorization path?
• Which consumer still uses a hand-written fixture?
• Which failure happens after the first durable mutation?
• Which generator or formatter can leave an unexplained dirty tree?

Evidence review is not rerunning every command blindly. It is matching each important claim to the smallest proof that can actually support it, then broadening proof at shared boundaries.

For a repository-wide validation model, use the Repository Harness Patterns and agent-readiness audit as companion guides.

6. Inspect the diff by risk

Now read code.

Do not allocate attention by file order or changed-line count. Allocate it by consequence and evidence strength.

Inspect deeply

• public contracts and compatibility behavior;
• authorization, secrets, and trust boundaries;
• migrations, retries, and rollback paths;
• concurrency, ordering, and shared mutable state;
• destructive operations and external side effects;
• generated-source inputs and generator pins;
• integration glue between worker-owned components;
• code behind weak, indirect, or missing evidence;
• conflict resolutions and manual edits made during integration.

Inspect selectively

• mechanical renames with compiler coverage;
• deterministic generated output whose source and generator were reviewed;
• formatter-only changes;
• repetitive mappings covered by focused tests;
• documentation synchronized from an accepted contract.

This is not permission to ignore code. It is a way to use human attention where executable evidence is weakest or consequences are highest.

A one-line authorization condition can deserve more review than 8,000 generated lines.

7. Review the seams between agents

Worker-local code is often not the highest-risk surface. The seams are.

Build a boundary matrix:

Then inspect evidence from the integrated candidate, not only from worker branches.

A producer passing its tests and a consumer passing against a fixture do not prove the edge. The edge needs its own check.

This is also where Git worktree isolation stops helping. Worktrees preserve separate states. They cannot prove those states agree.

8. Review conflicts as decisions

Every non-trivial conflict resolution should be visible in the review packet.

## Conflict decision R1
- Class: generated-output conflict
- Inputs: API `4d31...`, client `91c2...`
- Authority: `openapi/avatar.yaml`
- Decision: accept API schema, discard derived client conflict, regenerate
- Proof: schema valid; generation clean twice; both clients compile
- Durable repair: client task packets now record the producer schema commit

The reviewer checks the authority and evidence. The reviewer does not reward a clean final diff if the resolution path is unreproducible.

If conflict markers were removed without a recorded contract decision, return to the contract-first merge-conflict workflow.

9. Run independent verification on the candidate

Choose a small set of checks that challenge the most important claims.

A useful review run might include:

scripts/check-api-contract
scripts/generate-clients
scripts/check-generated-clean
scripts/validate-clients avatar
scripts/validate-web avatar
scripts/validate-cli avatar
scripts/smoke-avatar-upload
scripts/smoke-avatar-errors
git status --short

The final clean-tree check matters. A generator or formatter that changes tracked files means the reviewed candidate is not reproducible as presented.

For high-risk work, use a clean session or separate verification agent. Give it the review packet and exact candidate, but not the worker chats. Ask it to:

1. reconstruct the outcome and contract graph;
2. select the highest-risk claims;
3. rerun or inspect their evidence;
4. search for one plausible counterexample per claim;
5. report contradictions, omissions, and residual risk.

A verification agent is a second evidence producer. It is not an automatic approver.

A practical multi-agent review packet

Store the packet beside the task and integration records. Keep it short enough to maintain and complete enough to reproduce the decision.

The repository-harness project can carry this packet next to task envelopes, source-of-truth maps, validation contracts, and handoff records.

# Multi-agent review packet — <change>

## Review identity
- Requested outcome:
- Base commit:
- Candidate commit:
- Working-tree state:
- Review owner:
- Contract owners:

## Scope
- Task graph:
- Worker checkpoints:
- Integration record:
- Explicit non-goals:

## Claim inventory
| ID | Claim | Owner | Contract/source | Evidence | State |
|---|---|---|---|---|---|
| C1 | | | | | pending |

## Changed contracts
### <contract>
- Authoritative source:
- Producer:
- Consumers:
- Compatibility requirement:
- Acceptance decision:
- Boundary proof:

## Integration evidence
- Integration order:
- Candidate checkpoints:
- Boundary gates:
- Final outcome gate:
- Generated-output status:
- Working-tree status:

## Conflict decisions
- Classification:
- Authority:
- Resolution:
- Replayed evidence:
- Durable prevention:

## Independent review probes
- Claim challenged:
- Counterexample tested:
- Command or inspection:
- Result:

## Omitted checks
- Check:
- Reason:
- Owner and next gate:

## Residual risks
- Risk:
- Consequence:
- Mitigation or acceptance owner:

## Rollback
- Last known-good checkpoint:
- Disposable outputs:
- Evidence to preserve:

## Decision
- [ ] accept
- [ ] request repair from owning worker or contract
- [ ] reject and replan
- Rationale:

The review checklist

Identity and outcome

• one exact base and candidate are recorded;
• the candidate is stable and the working tree is understood;
• requested behavior is stated in observable terms;
• constraints and non-goals are explicit;
• approval authority is named.

Claims and contracts

• every important completion statement is a falsifiable claim;
• every claim has one owner and stable checkpoint;
• changed public, persisted, generated, security, and configuration contracts are listed;
• every shared contract has an authoritative source;
• producer-consumer dependencies match the task graph;
• compatibility and rollback expectations are visible.

Evidence

• exact commands and observed results are recorded;
• evidence refers to the checkpoint that produced the claim;
• worker checks prove bounded claims rather than general activity;
• boundary checks prove producer-consumer agreement;
• final checks run on the integrated candidate;
• omitted checks and residual risks are explicit;
• generated output can be reproduced from accepted sources.

Targeted code inspection

• trust and authorization boundaries received deep review;
• migrations, retries, rollback, and failure states were inspected;
• concurrency and ordering assumptions were challenged;
• integration glue received more attention than mechanical output;
• weakly tested code received more attention than strongly proven code;
• conflict resolutions match recorded authority decisions.

Decision and recovery

• representative user-visible behavior passes;
• the final repository state is clean and reproducible;
• rejected claims return to their owning source instead of being patched silently;
• the last known-good checkpoint is preserved;
• repeated review findings become durable repository repairs;
• acceptance rationale names both evidence and remaining risk.

Common review failures

Reading every diff before reading the task

The reviewer learns implementation order instead of intended behavior. Read the outcome, claim graph, and contracts first.

Treating agent confidence as evidence

A detailed explanation can still describe the wrong checkpoint. Require exact state and reproducible proof.

Counting green worker branches

Five green branches can encode five incompatible assumptions. Review contract edges and the combined candidate.

Reviewing generated files line by line

This spends attention on derived output. Review the source, generator, version, and deterministic reproduction.

Asking another agent for a generic second opinion

“Review this PR” often produces style comments and broad reassurance. Give the verifier the claim inventory, risk priorities, candidate commit, and required output format.

Fixing findings directly in the review branch

A quick patch can leave the worker checkpoint, handoff, and source contract wrong. Return the finding to the owner, repair the source, rebuild the candidate, and replay affected gates.

Hiding omissions behind a broad test command

A repository-wide suite can pass while skipping the changed browser, migration, or generator path. Record what the command covered and what it did not.

Approving a moving target

A new integration commit can invalidate reviewed evidence. Pin the candidate and reopen affected claims when it changes.

When to reject the packet before code review

Return the change without line-level review when:

• the outcome is ambiguous;
• the candidate commit is missing or moving;
• worker claims cannot be mapped to task ownership;
• a changed shared contract has no authority;
• handoffs report commands without results;
• relevant omissions are silent;
• integration order contradicts producer-consumer dependencies;
• generated output cannot be reproduced;
• conflict decisions exist only in chat;
• no proof covers the combined user-visible outcome;
• rollback or recovery is required but undefined.

This is not process theater. Reviewing code without these inputs forces the reviewer to reconstruct the entire operation from a diff, and that reconstruction is easy to get wrong.

Make review a repository capability

The review format should not depend on which model wrote the code.

Put the stable rules in the repository:

## Multi-agent code review

- Review one exact integration candidate against the accepted task outcome.
- Require a claim inventory, changed-contract map, integration evidence, omissions, and residual risks.
- Review contracts and producer-consumer boundaries before implementation detail.
- Use diffs to test claims; do not use file order as the review plan.
- Regenerate derived output from canonical sources instead of hand-reviewing or hand-merging it.
- Return failed claims to their owning worker or contract source.
- Final acceptance requires representative combined proof and a clean tree.

Keep the root rule short. Link it to the packet template and executable validation commands. The broader operating model is in How to Manage Multiple Coding Agents in One Repository, and the instruction layer can start from the AGENTS.md template.

Review the claims, then the code

Do not begin Monday with five agent diffs open in five tabs.

Freeze one candidate. Reconstruct the outcome. Build the claim inventory. Review changed contracts. Challenge the evidence. Inspect risky code and cross-agent seams. Reproduce the combined outcome. Return failed claims to their owners.

Then accept only the candidate whose claims survive.

Use repository-harness on GitHub to add the task packets, handoffs, validation contracts, review packet, and recovery checkpoints that make this workflow repeatable.

Related pages

• CI Gates for Multiple Coding Agents
• Task Decomposition for Multiple Coding Agents
• Coding-Agent Handoff Template
• How to Integrate Changes from Multiple Coding Agents Safely
• How to Resolve Merge Conflicts Between Coding Agents
• How to Manage Multiple Coding Agents in One Repository
• Git Worktrees for Multiple Coding Agents
• Repository Harness Patterns
• How to Audit a Repository for Agent-Readiness
• AGENTS.md Template
• repository-harness on GitHub

FAQ

How should I review code from multiple coding agents?

Review the combined change as a set of claims. Reconstruct the requested outcome, map each claim to its owning task and contract, verify the supplied evidence, inspect high-risk boundaries, and rerun representative integration checks on one exact candidate. Use the diff to investigate claims, not as the review plan.

Should I read every coding-agent diff line by line?

Not as the first pass. Start with the outcome, contracts, dependency graph, handoffs, and integration evidence. Then inspect the lines that implement risky claims, cross trust boundaries, change public contracts, touch recovery paths, or lack strong executable proof.

What should be in a multi-agent review packet?

Include the requested outcome, exact base and candidate commits, task graph, worker checkpoints, claim inventory, changed contracts, integration order, exact commands and results, omitted checks, residual risks, conflict decisions, generated-output status, and rollback point.

Can green tests from every agent branch prove the change is correct?

No. Worker tests prove bounded claims against separate bases and assumptions. Review also needs producer-consumer checks and final evidence from the integrated candidate, including representative user-visible behavior and a clean repository state.

Who should review an integrated multi-agent change?

One review owner should control the final decision, while contract owners review the boundaries they own. A separate verification agent can reproduce evidence or search for counterexamples, but it should not silently redefine accepted behavior or replace human approval where policy requires it.

How do I review generated files from coding agents?

Review the authoritative schema, template, specification, lockfile, and generator version first. Regenerate the output from the accepted source and require a second generation run to produce no diff. Do not spend the main review budget reading or hand-editing generated lines.

When should a multi-agent code review be rejected?

Reject or return the review when the requested outcome is ambiguous, the candidate cannot be reproduced, shared contracts have no owner, claims lack evidence, relevant checks are silently omitted, the integration order contradicts dependencies, generated output cannot be recreated, or the final user-visible outcome remains unproven.