Prompt & Review Anti-Patterns

This lesson dissects two review anti-patterns that quietly drain quality from agentic code review: single-pass multi-file review and same-session self-review.

Both share one root cause: asking a single context to do too much at once. When you cram many files into one pass, attention gets diluted. When the same session that wrote the code also reviews it, the author keeps its own reasoning and won't challenge itself.

On the Claude Certified Architect exam (Scenario 5, CI/CD), these are classic distractors. Recognizing them — and knowing the correct structure — is worth real points.

Imagine handing the model 14 changed files and saying "review this PR." The model spreads finite attention across all of them simultaneously. Subtle per-file bugs get missed, and the cross-file story — how a renamed function ripples through its callers — is never examined deliberately.

Two mechanisms compound the failure:

• Attention dilution: more files in one pass means shallower scrutiny per file.
• Lost-in-the-middle: models attend most to the start and end of context, so files in the middle of a large dump get the least scrutiny.

The fix is not a bigger context window — it is better decomposition.

The correct pattern is multi-pass review: a focused per-file local pass on each file, THEN a separate cross-file integration pass that examines how the pieces fit together.

The local passes catch in-file defects with full attention. The integration pass catches the bugs that only exist between files: broken contracts, mismatched signatures, stale callers, inconsistent error handling.

This mirrors a broader exam principle: use fixed pipelines / prompt chaining for known sequential steps, and reserve adaptive decomposition for open-ended investigation. Review has a known shape, so a pipeline fits.

The second anti-pattern: letting the same session that generated the code also review it. The exam is blunt here — independent / fresh-instance review beats same-session self-review.

The reason is cognitive lock-in. The author retains the reasoning, assumptions, and rationalizations it used while writing. It already "decided" the code is correct, so it tends to confirm rather than challenge. A clean reviewer carries none of that baggage and sees the code as an artifact to interrogate.

Put differently: the generation context biases the review. You want the reviewer biased toward skepticism, not toward the author's earlier conclusions.

The remedy is to run review in an isolated session, decoupled from the generation context. In Claude Code CI/CD this is natural: generation and review are separate non-interactive invocations.

For pipelines, always run review with -p / --print (non-interactive) and emit --output-format json so results are machine-parseable. The review job gets only the diff and the criteria — not the chat history that produced the code.

Session controls matter. --resume <name> continues a named session; fork_session branches from a shared point. For review, beware: forking from the generation session carries the author's reasoning forward, recreating the same-session bias you were trying to escape.

Prefer a genuinely fresh session fed a structured summary of what to review. There is also a freshness angle: resumed tool results can be stale if the codebase changed since — sometimes a fresh session with a structured summary beats resuming.

An isolated reviewer is only as good as its instructions. Vague prompts ("be more precise," "find bugs") produce noisy, inconsistent output. Explicit criteria win: "flag a comment only when it contradicts the code" beats "check the comments."

For CI specifically, the goal is to minimize false positives — a review that cries wolf gets ignored. Tight, testable criteria keep signal high.

Where ambiguity remains, add 2-4 targeted few-shot examples per ambiguity. The model generalizes from them — it does not merely repeat them. Few-shot is the best lever for consistency, edge cases, output format, and reducing hallucinated findings.

For a reviewer, show one example that should be flagged and one that should NOT. That calibrates the false-positive boundary far better than another paragraph of prose.

To make review results reliable and parseable, force structured output with a tool plus a JSON Schema. Setting tool_choice to "any" guarantees the model calls some tool, eliminating free-text drift; a forced specific tool gives even tighter control.

Schema discipline matters: mark a field required ONLY if it is always present. Never require a possibly-absent field — the model will fabricate one to satisfy the schema. Use an enum with an "other" value plus a free-text detail field for extensibility.

Review runs repeatedly as a PR evolves. When you re-run, include the prior results and report only new or still-unfixed issues. Re-flagging everything from scratch buries the genuinely new problems and trains reviewers to ignore the bot.

This also keeps the integration pass honest: a fix in one file may introduce a fresh cross-file break, and that is exactly what the next run should surface — not the noise that was already resolved.

One last trap. Pre-merge / blocking review is time-sensitive, so it does NOT belong on the Message Batches API. Batches are 50% cheaper with up to a 24h window but carry no latency SLA and do not support multi-turn tool calling — wrong for anything blocking a merge.

Reserve the Batch API for non-blocking jobs: overnight audits, nightly full-repo sweeps, bulk report generation. Use custom_id to correlate requests and re-submit only the failures. Pre-merge gating stays on standard, low-latency calls.

A teammate's CI calls Claude Code to review pull requests. It resumes the same session that generated the code and asks it to review all 14 changed files in one prompt. False positives are high and real cross-file bugs slip through. Which redesign best fixes this?

Key takeaways:

• Avoid single-pass multi-file review — it dilutes attention and the middle gets lost. Do per-file local passes THEN a separate cross-file integration pass.
• Avoid same-session self-review — the author retains its reasoning and won't challenge itself. Review in a fresh, isolated session; beware that forking/resuming carries bias and stale results.
• Prompt with explicit criteria + 2-4 few-shot examples to minimize false positives.
• Force structured output (tool + schema, tool_choice:"any"); require only always-present fields.
• On re-runs, report only new/unfixed issues.
• Keep blocking review off the Batch API — no latency SLA; reserve batches for overnight audits.