Decomposing Code Reviews and Open-Ended Codebase Tasks

1.Per-file passes plus a cross-file integration pass

A large review asks one call to keep a very large number of considerations in view at the same time. Anthropic's guidance on decomposition points the other way: "LLMs generally perform better when each consideration is handled by a separate LLM call, allowing focused attention on each specific aspect." The exam guide calls the failure *attention dilution*: one pass spread across dozens of files gives each file less scrutiny.

The fix has two stages. In the first, per-file local analysis, each file gets its own pass. These passes don't depend on each other, so they can run side by side. In the second, an integration pass takes the per-file findings as input and works across them: merging, deduplicating and ranking, and looking at how the files interact. Since stage two consumes stage one's output, the whole thing is a chain whose first link fans out. Claude Code's workflow documentation gives this exact job as an example: "review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary." The orchestrator-workers cookbook makes the same suggestion from the other direction: "Add a synthesis phase where an LLM combines worker outputs."

The documentation's route-audit example shows the first stage in code. One agent maps the structure by listing the files, then pipeline runs one focused audit per file:

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

Sources123

2.Making the pipeline hold: structure in code, not instructions

If a review is described as "first each file, then integrate" in a prompt, it only holds as long as the model follows the instruction. Claude Code's dynamic workflows move the orchestration into a script, and the cookbook describes what that gets you: "The plan is enforced by code." The later pass runs after the earlier ones because the script's control flow says so, and "nothing depends on Claude remembering an instruction."

The building blocks map directly onto the decomposition patterns. agent() "spawns one subagent with a clean context", so each per-file reviewer sees only its own prompt. parallel() runs a batch and waits for all of it, which is the barrier you need before an integration pass. pipeline() sends each item through the stages on its own, so one file can be in stage two while another is still in stage one. Filtering, deduplicating and merging between calls happen in plain JavaScript, which is exact and uses no tokens. The Claude Code docs add that, "besides agent(), pipeline(), and parallel(), you can call phase() to group the agents that follow under a title in the progress view", which makes it easy to see that the local stage and the integration stage really are separate.

Determinism is built in too. Claude Code makes Date.now() and Math.random() throw inside the script "so that a relaunched run repeats the same agent() calls."

Use these tools in proportion to the job. The cookbook's guide:

Sources14

3.Open-ended tasks: map, plan, then adapt

"Add comprehensive tests to a legacy codebase" is the opposite of a fixed review. At the start you don't know which modules exist, which are already covered, or what each one depends on, so you can't write the chain in advance. Claude Code's best-practices guide gives the bare "add tests for foo.py" as its example of an underspecified prompt. The scoped version names a file, a scenario and a constraint: "write a test for foo.py covering the edge case where the user is logged out". The decomposition job is to get from the vague request to many prompts like that.

Map the structure first. Claude Code's common-workflows guide starts unfamiliar code with "give me an overview of this codebase" and advises: "Start with broad questions, then narrow down to specific areas." Its testing recipe then asks Claude to find gaps directly, for example "find functions in NotificationsService.swift that are not covered by tests". After that it generates scaffolding, adds edge-case tests, and runs and fixes the tests.

Then make the plan an explicit artifact. The best-practices workflow goes Explore ("read /src/auth and understand how we handle sessions and login."), then Plan ("What files need to change?" … "Create a plan."), then Implement ("implement the OAuth flow from your plan."), then Commit. These sources don't describe a method for ranking areas by impact. The exam guide expects the plan to be prioritized, but the documentation here only establishes that the plan is written down before implementation starts.

Then let the plan change. Discovering a dependency during implementation, such as a module that can't be tested until another one has fixtures, is a finding just like a research lead. The Research system's lead agent keeps its plan in memory and revises it after each round. The cookbook recommends subagents for exactly the case where "the lead agent should adapt the plan as results come in".

Sources564

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Running a separate review on each file is enough on its own; concatenating the per-file outputs completes the review.Why is that wrong?

   The documented pattern adds a separate step after the per-file passes that merges their findings into one ranked summary.

   Covered in Per-file passes plus a cross-file integration pass

2. 2.For "add tests to a legacy codebase", the agent should start writing tests file by file right away.Why is that wrong?

   Open-ended codebase work starts by mapping: broad questions about the code first, then narrowing to specific areas and untested code before planning.

   Covered in Open-ended tasks: map, plan, then adapt