Why it matters
A large request exceeds both the context window and the agent's ability to hold several invariants at once. Splitting it into units with independent tests creates checkpoints where a failure is attributable. The hard part is not the split itself but the seams: two units that share a type or a call site can each pass alone and still fail together, so the boundary has to be chosen where an interface can be written down.
Mental model
It is slicing a loaf so that each slice holds together on its own. The metaphor breaks because code slices share types and call sites, so a clean cut in one place opens a seam somewhere else, and the seam stays invisible until both slices sit on the same plate.
How it works
Step 1 of 8
Cut at observable behaviour
The unit is the smallest behaviour that can be tested alone. Cutting at the file line instead gives two units that cannot compile apart, which the crossed branch records.
root · current
Task · add annual-plan proration
The request names a behaviour, not a directory. The first decision is where to cut so each piece has an observable result.
Root of the hierarchy
Figure. A task split at a verification boundary: two units, each with its own test, joined by a written interface and checked again on the merged branch. The three crossed branches are the splits that fail on either side of it — by file, as one change, and below the test boundary.
What to notice. The task, the function and the test files are an authored example; the page gives no measurements, so no counts are drawn. Depth is one level because a unit that needs its own sub-units is a sign the boundary was chosen below the test; width is the work, not a fan-out budget. Omitted: how the units are assigned or run in parallel, which the page covers as a contract problem rather than as part of the split.
Text version
A task decomposition drawn as a hierarchy. The root is one task: add annual-plan proration, authored as two units and one written seam. Unit 1 defines prorationFor(plan, date) and lands first, with an interface gate that writes the signature and exported type before any code, and a check that its own test passes. Unit 2 changes invoice totals to call the function, depends on unit 1, and has its own test. A shared contract file types/proration.ts holds the shape both units agree on. A merge gate runs the build and both tests on the combined branch. Three branches are rejected and drawn crossed: splitting by file leaves the build broken between units, one large change has no checkpoint, and a split below the test boundary needs the next unit before any unit means anything.
- Identify the smallest change that produces observable behaviour and can be tested alone.
- Write down the interface each unit exposes: function signatures, schema fields and event names.
- Order units so dependencies land first and the tree compiles after every merge.
- Write the test for a unit before starting the next, so an integration failure is attributable.
- Keep a shared contract file or type definition when two units must agree on a shape.
- Stop splitting when a unit cannot be described without referring to another unfinished unit.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| One large change | No integration seams | Unreviewable diff, long feedback loop | Change touches many subsystems |
| File-by-file split | Easy to assign | Build breaks between units | Files are coupled through types |
| Behaviour-sliced units | Each unit testable | Interface design up front | Behaviour is cross-cutting |
| Parallel units with a contract | Throughput | Contract drift, merge conflicts | Contract is still being discovered |
Good for
No integration seams
Cost
Unreviewable diff, long feedback loop
Fails when
Change touches many subsystems
- Change touches many subsystems
- Files are coupled through types
- Behaviour is cross-cutting
- Contract is still being discovered
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: One large change is good for No integration seams, costs Unreviewable diff, long feedback loop, and fails when Change touches many subsystems. File-by-file split is good for Easy to assign, costs Build breaks between units, and fails when Files are coupled through types. Behaviour-sliced units is good for Each unit testable, costs Interface design up front, and fails when Behaviour is cross-cutting. Parallel units with a contract is good for Throughput, costs Contract drift, merge conflicts, and fails when Contract is still being discovered
Failure modes
- Phantom interface. Two units assume different signatures and neither compiles after merge. Debug: build the combined branch rather than each unit alone.
- Split below the test boundary. Every unit needs the next one before it means anything. Debug: check whether each unit's test fails on the base commit for the intended reason.
- Decomposition by file. The change is spread across units that cannot merge independently. Debug: merge the units in a different order and see whether the build survives.
In production
Track unit size and how often a unit passes alone but fails after merge. Cap units per task and require an integration check before the task is called complete.
Common misconceptions
People think: Smaller tasks are always safer.
Actually: Below the test boundary, smaller units add integration risk without adding a checkpoint.
People think: Decomposition is only a planning artefact.
Actually: It determines how branches and tests are structured, so it is an engineering decision with merge consequences.
Interview angle
Describe the boundary you would cut on and the interface you would write down. A strong answer decomposes by verifiable behaviour, orders units so the build survives each merge and checks the combined branch. Splitting by file or directory, with no mention of shared types or integration, is the common weak response.
Sources
- Zhou et al., Least-to-Most prompting — decomposing a problem into easier subproblems.
- Anthropic, Claude Code best practices — scoping work into verifiable steps.
- Xia et al., Agentless — a fixed localise, repair and validate pipeline that beats many agents.