Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 9 of 30

Task decomposition

0 of 30 complete

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

Two units, one written seamInteractive
11 nodes · 3 branches
validation gatestagerootfileruled out or rejected

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

Step 1/8 · Cut at observable behaviour

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.

  1. Identify the smallest change that produces observable behaviour and can be tested alone.
  2. Write down the interface each unit exposes: function signatures, schema fields and event names.
  3. Order units so dependencies land first and the tree compiles after every merge.
  4. Write the test for a unit before starting the next, so an integration failure is attributable.
  5. Keep a shared contract file or type definition when two units must agree on a shape.
  6. Stop splitting when a unit cannot be described without referring to another unfinished unit.

Trade-offs

ChoiceGood forCostFails when
One large changeNo integration seamsUnreviewable diff, long feedback loopChange touches many subsystems
File-by-file splitEasy to assignBuild breaks between unitsFiles are coupled through types
Behaviour-sliced unitsEach unit testableInterface design up frontBehaviour is cross-cutting
Parallel units with a contractThroughputContract drift, merge conflictsContract is still being discovered
Trade-off mapInteractive

Good for

No integration seams

Cost

Unreviewable diff, long feedback loop

Fails when

Change touches many subsystems

  1. Change touches many subsystems
  2. Files are coupled through types
  3. Behaviour is cross-cutting
  4. 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