Descomposición en varias pasadas

When you ask Claude to review a changeset spanning many files in a single pass, attention gets diluted. The model spreads finite focus across every file at once, so subtle per-file bugs slip through and genuine cross-file issues get buried.

The architect's answer is multi-pass decomposition: split the work into a per-file local pass first, then a separate cross-file integration pass. Each pass has one clear job, so attention stays sharp.

The two passes ask fundamentally different questions, which is exactly why they shouldn't be merged:

• Local pass: "Is THIS file internally correct?" — logic errors, null handling, naming, dead code, style within the file's own boundary.
• Integration pass: "Do these files work TOGETHER?" — mismatched function signatures, broken contracts, inconsistent assumptions across module boundaries.

Single-pass review forces both questions into one diluted prompt. Two passes keep each focused.

The local pass starts with discovery. Use Claude Code's built-in tools incrementally: Glob to find files by pattern, then Read each one in isolation.

Reviewing one file per request keeps the context small and the attention concentrated. This is the opposite of dumping the whole diff into a single prompt.

In the local pass, give Claude a tight, explicit boundary: review only this file, and judge it on its own terms. Vague instructions like "be thorough" underperform; explicit criteria win.

State exactly what counts as a finding so the model doesn't drift into speculation about files it hasn't seen.

Have each local pass emit structured output so findings are machine-mergeable for the next pass. Use tool_choice with a schema-backed tool to guarantee well-formed JSON.

Critically: mark a field required only if it is always present. Never require a field that may be absent — the model will fabricate a value to satisfy the schema.

Once every file passes its local review, run a separate integration pass. Now the goal flips: you deliberately load the relevant files together and ask whether their contracts line up.

Typical integration defects:

• A caller passes three arguments; the callee now expects four.
• One module returns None on "not found"; the consumer treats it as an empty list.
• A renamed enum value still referenced by a sibling file.

The integration pass mirrors incremental investigation. Start at the boundaries and follow the wiring: Grep for a changed function's name to find every call site, then Read those consumers.

This way the integration pass concentrates on the seams between files — the exact place single-pass review tends to miss.

Run local before integration, not the reverse. If a file is internally broken, integration findings about it are noise — you'd flag a contract mismatch that disappears once the local bug is fixed.

Clean each file in isolation first, then the integration pass can trust that every file is locally sound and focus purely on how they fit together.

Because the steps are known and sequential — discover, local pass, integration pass, report — this is a job for a fixed pipeline (prompt chaining), not adaptive, open-ended exploration.

Reserve adaptive decomposition for genuinely open investigations ("why is this flaky?"). Multi-pass review has a defined shape, so encode that shape.

Run each review pass in a fresh, isolated session, separate from whatever session generated the code. Independent review beats same-session self-review: an author retains its own reasoning and won't challenge its own assumptions.

In CI, drive this non-interactively with -p / --print and --output-format json so results are parseable. When re-running, feed in prior results and report only new or still-unfixed issues.

For large changesets, fan out the local pass across subagents in a hub-and-spoke pattern: the coordinator splits files among parallel workers, then runs the integration pass itself once results return.

Remember the rule: subagents do not inherit the coordinator's history. Each subagent prompt must carry all the context it needs explicitly. Multiple Task calls in one response run in parallel.

An architect must review a 9-file pull request and wants the highest-quality findings. What is the soundest decomposition?

Multi-pass decomposition, distilled:

• Two passes, two questions: local = is each file internally correct; integration = do the files work together.
• Local first, then integration — a broken file makes integration findings noise.
• One file per local request to keep attention sharp; emit structured output for clean merging.
• Fixed pipeline (discover → local → integration → report), not adaptive improvisation.
• Isolated/fresh sessions beat same-session self-review; in CI use -p and --output-format json.
• Scale the local pass across parallel subagents — each one needs context passed explicitly.

Single-pass multi-file review is the anti-pattern. Decompose, and your reviews get sharper, not just longer.