Design Multi-Instance and Multi-Pass Review Architectures
This module is about designing review systems that catch more real issues with fewer blind spots.
The exam’s core idea:
The Claude instance that generated code should not be the only reviewer.
Use independent review instances and structured review passes.
Anthropic’s Claude Code best-practices docs recommend adding an adversarial review step: have a subagent review the diff in a fresh context before treating work as done. The key reason is that a fresh reviewer sees only the diff and review criteria, not the reasoning that produced the change. (Claude)
1. Core mental model
Use this decision rule:
Generated code needs review → use an independent instance.
Large multi-file change → split review into passes.
Candidate finding needs trust calibration → run verification pass.
| Problem | Best architecture |
|---|---|
| Model may not question its own implementation | Independent reviewer instance |
| Review diff is too large | Per-file local passes |
| Bug depends on interaction between files | Cross-file integration pass |
| Many candidate findings include false positives | Verification pass |
| Need triage | Confidence + evidence fields |
| Large codebase audit | Multi-agent / dynamic workflow |
Claude Code’s managed Code Review system uses a fleet of specialized agents to inspect PRs for logic errors, security vulnerabilities, edge cases, and regressions, then applies verification, deduplication, and severity ranking before posting findings. (Claude)
2. Self-review limitations
The official task statement says:
A model retains reasoning context from generation, making it less likely to question its own decisions in the same session.
This is the same reason a human engineer should not be the only reviewer of their own PR.
Bad pattern
Why weak:
The same session remembers the intended approach.
It may preserve assumptions from implementation.
It may judge the diff against intent rather than actual behavior.
It may miss omissions because it believes they were handled.
Better pattern
Session A:
Generate implementation.
Session B:
Independently review the diff with only:
- diff
- relevant source files
- review criteria
- project standards
Claude Code docs explicitly say an independent reviewer in a fresh subagent context sees only the diff and criteria, not the reasoning that produced the change; this improves the quality of the check before work is counted as complete. (Claude)
3. Independent review instances
An independent review instance should receive:
1. The diff or changed files
2. Relevant surrounding code
3. Review criteria
4. Project standards
5. Test expectations
6. No implementation reasoning unless needed
It should not receive:
The generator's chain of decisions
The failed attempts
The rationale for why the generator chose a shortcut
A prompt that says “confirm this is correct”
Good independent review prompt
Review this diff as an independent reviewer.
You did not implement this code. Evaluate only the final diff and surrounding code.
Report only:
- correctness bugs
- security issues
- broken edge cases
- missing required behavior from the stated requirements
- data-flow or integration issues introduced by the diff
Skip:
- style preferences
- formatting/lint issues
- speculative concerns without a realistic failure path
For every finding include:
- file
- line
- issue
- severity
- evidence
- realistic failure scenario
- suggested fix
- confidence: high | medium | low
This is stronger than:
4. Why independent instances work better
Subagents are isolated Claude instances with their own context windows; Anthropic’s subagent guidance says each starts fresh, unburdened by conversation history, and can be used when a fresh perspective is needed for verification. (Claude)
That matters because review quality depends on skepticism.
The generator asks:
The independent reviewer asks:
What does this diff actually do?
What can go wrong?
What edge cases are unhandled?
Does this integrate correctly with the rest of the system?
Exam shortcut:
5. Multi-pass review
Large reviews fail when one reviewer tries to evaluate everything at once.
Problems with one giant review pass:
Attention dilution
Missed local bugs
Missed cross-file interactions
Contradictory findings
Duplicate comments
Over-focus on obvious files
Under-review of small but critical files
Multi-pass review solves this by separating concerns.
Pass 1: Per-file local review
Pass 2: Cross-file integration review
Pass 3: Verification / deduplication / confidence routing
Claude Code’s Code Review architecture uses multiple agents and a verification step to check candidate findings against actual code behavior, then deduplicates and ranks findings by severity. (Claude)
6. Pass 1: Per-file local analysis
Per-file review asks:
It catches:
Null handling bugs
Incorrect conditionals
Wrong default values
Local validation bugs
Missing local error handling
Unsafe parsing
Obvious security mistakes
Wrong unit test assertions
Per-file reviewer prompt
Review only this file's changes.
Focus on local issues:
- incorrect conditionals
- null/empty/boundary handling
- wrong field names
- unsafe parsing
- local security checks
- local test gaps for changed branches
Do not report cross-file integration issues unless they are directly visible in this file.
Do not infer behavior from files not provided.
Return findings with:
- file
- line
- issue
- severity
- evidence
- suggested fix
- confidence
Example
Changed file:
Per-file pass might find:
Refund amount comparison uses > instead of >=.
Null currency code throws before validation error.
New branch for chargeback has no local test.
It should not overreach into:
Whether the API route sends the right status code.
Whether the frontend handles the new error.
Whether downstream analytics expects a different enum.
Those belong in the integration pass.
7. Pass 2: Cross-file integration analysis
Integration review asks:
It catches:
API schema mismatch
Frontend/backend contract mismatch
Producer/consumer enum mismatch
Data flow bugs
Missing migration for model change
Changed error code not handled by client
Auth check moved but not preserved
Test updated in one layer but not another
Config changed without deployment update
Integration reviewer prompt
Review this PR for cross-file integration issues.
Focus on:
- changed interfaces and their callers
- producer/consumer mismatches
- API request/response contract changes
- database schema and application model consistency
- error codes and client handling
- authentication/authorization flow across layers
- side effects across services
- tests that no longer cover the integrated behavior
Do not repeat purely local findings from per-file review unless needed to explain an integration bug.
Return findings with:
- affected files
- integration path
- issue
- severity
- evidence from both sides of the mismatch
- suggested fix
- confidence
Example integration issue
File A:
File B:
Finding:
Backend introduces a new status value `requires_review`, but the frontend status switch does not handle it. Users may see a blank or fallback state.
A per-file pass might miss this because each file looks locally reasonable. The integration pass catches the mismatch.
8. Pass 3: Verification pass
A verification pass reviews candidate findings, not the original diff alone.
It asks:
Is this finding actually valid?
Is it introduced by the diff?
Is the severity justified?
Is the evidence sufficient?
Is it a duplicate of another finding?
Claude Code’s Code Review docs describe a verification step that checks candidate findings against actual code behavior to filter false positives, then deduplicates and ranks the results. (Claude)
Verification prompt
Verify these candidate findings.
For each finding, decide:
- valid
- invalid
- uncertain
A valid finding must have:
1. Evidence in the changed code or directly affected surrounding code.
2. A realistic failure path.
3. A clear expected-vs-actual behavior difference.
4. Evidence that the issue was introduced or exposed by this diff.
5. Severity consistent with the rubric.
Return:
- finding_id
- verdict: valid | invalid | uncertain
- confidence: high | medium | low
- reason
- recommended_action: post | suppress | route_to_human
Verification output example
{
"finding_id": "F-017",
"verdict": "valid",
"confidence": "high",
"reason": "The backend now returns requires_review, but the frontend switch has no default handling and no case for this value.",
"recommended_action": "post"
}
9. Confidence reporting and calibrated routing
The official task statement says:
Run verification passes where the model self-reports confidence alongside each finding to enable calibrated review routing.
Confidence should not be treated as truth. It is a routing signal.
Good confidence rubric
High confidence:
Finding has direct code evidence, realistic failure path, and clear expected-vs-actual behavior.
Medium confidence:
Finding appears plausible but depends on an assumption about runtime configuration, data shape, or caller behavior.
Low confidence:
Finding is speculative, lacks complete evidence, or depends on missing context.
Routing table
| Verification result | Confidence | Action |
|---|---|---|
| valid | high | Post as PR comment |
| valid | medium | Route to human reviewer or summarize separately |
| valid | low | Suppress or ask for more context |
| uncertain | any | Route to human or hold |
| invalid | any | Suppress |
| duplicate | any | Merge with original finding |
Finding schema
{
"finding_id": "F-001",
"files": ["api/orders.ts", "web/orderStatus.tsx"],
"category": "integration",
"severity": "important",
"issue": "Backend returns a new status that the frontend does not handle.",
"evidence": [
"api/orders.ts returns status requires_review",
"web/orderStatus.tsx switch handles only approved and rejected"
],
"failure_scenario": "An order requiring manual review renders with no visible state in the UI.",
"suggested_fix": "Add requires_review handling in the frontend status switch.",
"confidence": "high",
"recommended_action": "post"
}
Exam trap:
Confidence is not a replacement for evidence. It helps decide whether to post, suppress, or route to a human.
10. Example multi-pass architecture for a large PR
Suppose a PR changes 18 files:
A single review pass is likely to miss something.
Better architecture
Step 1: Partition changed files
- backend
- frontend
- database
- tests
- config
Step 2: Run local per-file reviewers
- each reviewer focuses on one file or small cluster
Step 3: Summarize local findings
- remove obvious duplicates
- preserve candidate findings
Step 4: Run integration reviewer
- look across API ↔ shared types ↔ frontend ↔ migration
Step 5: Run verification reviewer
- validate each candidate finding
- assign confidence
- deduplicate
- route findings
For very large reviews, dynamic workflows can orchestrate many subagents at scale; Claude Code docs describe dynamic workflows as useful for codebase audits, large migrations, and cross-checked research where one conversation cannot coordinate all the agents effectively. (Claude)
11. Local vs integration finding examples
Local finding
Why local:
Integration finding
Files:
- api/refunds.ts
- web/refundForm.tsx
Issue:
Backend now requires refund_reason, but frontend still submits only amount and order_id.
Why integration:
Neither file alone proves the full issue. The bug appears in the contract between producer and consumer.
Verification finding
Candidate:
Verification result:
{
"verdict": "invalid",
"confidence": "high",
"reason": "The loop iterates over a constant array of three enum values and performs no I/O.",
"recommended_action": "suppress"
}
Why verification matters:
12. Common architecture patterns
Pattern A: Independent reviewer after generation
Generator instance:
Implements feature.
Reviewer instance:
Reviews final diff with no generation reasoning.
Verifier instance:
Checks candidate findings and confidence.
Use for:
Pattern B: Per-file fanout + integration pass
Per-file reviewers:
Review each changed file locally.
Integration reviewer:
Reviews interactions across changed files.
Verifier:
Deduplicates and validates findings.
Use for:
Pattern C: Specialist reviewers
Security reviewer
Correctness reviewer
Test coverage reviewer
Migration reviewer
Frontend/backend contract reviewer
Use when:
The risk categories are distinct.
Different review criteria apply.
The PR touches multiple technical domains.
Caution:
Too many reviewers can create duplicate or contradictory findings.
Always use a verification/deduplication pass.
13. Prompt examples
13.1 Independent review prompt
You are an independent reviewer. You did not implement this change.
Review the diff and surrounding code for:
- correctness bugs
- security issues
- broken edge cases
- requirement gaps
- integration mismatches
Do not use or assume the implementer's reasoning.
Evaluate the final code behavior only.
For each finding, include:
- location
- issue
- severity
- evidence
- failure scenario
- suggested fix
- confidence
13.2 Per-file pass prompt
Review this file in isolation for local correctness.
Report:
- wrong conditionals
- null/empty/boundary handling bugs
- unsafe parsing
- local validation errors
- changed branches without local tests
Skip:
- cross-file contract issues
- speculative performance concerns
- style preferences
Return concise candidate findings with confidence.
13.3 Cross-file integration pass prompt
Review the changed files together for integration issues.
Focus on:
- API contract mismatches
- shared type changes not reflected in callers
- frontend/backend status or enum mismatches
- database migration and model mismatches
- auth flow changes across layers
- changed error codes not handled by consumers
Use evidence from at least two files for each integration finding.
13.4 Verification pass prompt
Verify the candidate findings.
For each finding:
1. Check whether the evidence supports the claim.
2. Confirm the issue is introduced or exposed by this diff.
3. Identify a realistic failure path.
4. Reclassify severity if needed.
5. Mark confidence as high, medium, or low.
6. Recommend post, suppress, or route_to_human.
Suppress findings that are speculative, duplicate, pre-existing, or unsupported by the code.
14. When not to use multi-instance review
Do not over-engineer tiny changes.
Small change:
Usually enough:
Multi-instance review has overhead. Anthropic’s subagent guidance notes that subagents are useful when context isolation, parallelism, or fresh perspective helps, but for small or tightly sequential tasks the overhead may outweigh the benefit. (Claude)
Exam shortcut:
15. Common exam traps
Trap 1: Same-session self-review
Wrong:
Better:
Trap 2: One giant review pass for a large PR
Wrong:
Better:
Trap 3: Only local review
Wrong:
Why wrong:
Better:
Trap 4: Only integration review
Wrong:
Why wrong:
Better:
Trap 5: Posting unverified candidate findings
Wrong:
Better:
Trap 6: Treating confidence as proof
Wrong:
Better:
16. Scenario-based practice questions
Question 1
Claude implemented a feature in a long session. The user asks the same session to review its own changes before merge.
What is the best improvement?
A) Ask the same session to think longer.
B) Use a second independent Claude instance or fresh subagent to review the diff without the generator’s reasoning context.
C) Skip review because Claude wrote the code.
D) Ask for only style comments.
Answer
B. Self-review is weaker because the generator retains assumptions from implementation. A fresh reviewer evaluates the final diff independently.
Question 2
A PR modifies 45 files across backend routes, shared types, frontend UI, and database migrations. One review pass returns shallow and contradictory findings.
What is the best architecture?
A) One larger prompt with all files.
B) Per-file local passes, a cross-file integration pass, and a verification/deduplication pass.
C) Ask only for style issues.
D) Disable review.
Answer
B. Large multi-file reviews need separated attention. Local passes catch file-specific issues; integration passes catch cross-file mismatches; verification reduces false positives.
Question 3
A backend change adds a new enum value, but the frontend switch statement does not handle it.
Which review pass is most likely to catch this?
A) Cross-file integration pass
B) Per-file local pass only
C) Spellcheck pass
D) Formatting pass
Answer
A. The bug is in the interaction between backend output and frontend handling.
Question 4
A local function now returns true when startDate > endDate.
Which review pass should catch this?
A) Per-file local analysis
B) Cross-file integration only
C) CI batching only
D) Release-note generation
Answer
A. The issue is visible within one function or file.
Question 5
Candidate findings include duplicates and speculative comments. What should happen before posting PR comments?
A) Post everything.
B) Run a verification pass that checks evidence, deduplicates, assigns confidence, and routes findings.
C) Convert all findings to Important.
D) Delete all findings.
Answer
B. Verification filters false positives and improves trust.
Question 6
A verification pass marks a finding as valid but medium confidence because it depends on a runtime configuration not provided.
What is the best routing?
A) Automatically post as blocking.
B) Route to a human reviewer or summarize as needs-review.
C) Delete the code.
D) Treat confidence as irrelevant.
Answer
B. Medium-confidence findings can be valuable but should often be routed for human review rather than posted as definitive.
Question 7
A team runs only per-file reviewers on a large API/client PR. No reviewer compares the changed API response to frontend consumers.
What is missing?
A) Cross-file integration pass
B) More formatting checks
C) User-level CLAUDE.md
D) A spelling dictionary
Answer
A. Per-file review alone misses producer/consumer mismatches.
Question 8
A reviewer reports:
It gives no evidence, no production path, and no failure scenario.
What should a verification pass do?
A) Post it as Important.
B) Suppress it or mark invalid/low confidence.
C) Duplicate it across all files.
D) Convert it into a security issue.
Answer
B. Speculative findings without evidence should not be posted.
Question 9
A team wants to scale review across hundreds of files and many independent reviewer agents.
What extra step becomes especially important?
A) Verification and deduplication of candidate findings.
B) Removing all severity fields.
C) Asking every agent to post directly.
D) Avoiding structured output.
Answer
A. More agents produce more candidates, duplicates, and contradictions. Verification and deduplication are essential.
Question 10
A small PR fixes a typo in one error message.
What review architecture is appropriate?
A) 20 independent review agents and integration analysis.
B) Simple direct check or normal review; multi-instance architecture is unnecessary.
C) Cross-file data-flow review.
D) Dynamic workflow.
Answer
B. Multi-instance review has overhead and is best for larger or riskier changes.
17. Final D4.6 checklist
Memorize this:
1. Same-session self-review is weaker than independent review.
2. The generator retains assumptions from implementation.
3. Use a fresh independent instance or subagent for review.
4. Independent reviewers should see the diff, criteria, and relevant code, not the generator’s reasoning.
5. Large reviews should be split into passes.
6. Per-file passes catch local correctness issues.
7. Integration passes catch cross-file data-flow and contract issues.
8. Verification passes validate candidate findings.
9. Verification should check evidence, failure path, diff introduction, severity, and duplicates.
10. Confidence should be reported with each verified finding.
11. Confidence is a routing signal, not proof.
12. High-confidence valid findings can be posted.
13. Medium/uncertain findings can be routed to humans.
14. Invalid, duplicate, speculative, or unsupported findings should be suppressed.
15. Use multi-instance review for large, high-risk, or Claude-generated changes; avoid overkill for tiny fixes.
D4.6 mental model
Generator builds.
Independent reviewer questions.
Per-file pass finds local bugs.
Integration pass finds cross-file bugs.
Verification pass filters false positives.
Confidence routes findings.
The exam’s favorite distinction is:
A bigger single review prompt is not the best answer for large diffs. Use independent instances and multi-pass review so each pass has a focused job.