Lesson 1.6
Task Decomposition Strategies
How to split a large task into pieces an agent can complete reliably, and how to decide the granularity, ordering and verification of each piece.
Large tasks fail in agents for a predictable reason: the context fills with partial work, the model loses track of what is done, and errors in early steps compound silently. Decomposition is the remedy, but careless decomposition creates its own failures, such as subtasks that cannot be verified or that depend on state the worker cannot see. The exam tests whether you can choose a decomposition strategy that matches the task's structure.
Three axes of decomposition
By step. Sequential phases where each produces an artefact the next consumes: understand, plan, implement, test, document. This is prompt chaining applied to one task. It suits work where the order is fixed and each phase has a different skill.
By data. The same operation applied to many independent units: one subagent per module, one call per document chunk, one worker per customer record. This is map-reduce. The map phase runs in parallel, and a reduce phase merges results. It suits anything where the input is naturally partitioned and units do not interact.
By expertise. Different specialists for different concerns: a security reviewer, a performance reviewer, a style reviewer. Each has a focused system prompt and tool set, and a synthesiser combines their reports. It suits review and analysis tasks where breadth of perspective matters.
Real tasks often combine axes: plan by step, then fan out by data within the implementation phase.
Planning before acting
Claude Code's plan mode (--permission-mode plan or the /plan toggle) lets the agent explore and produce a plan without editing anything. The plan is reviewed, then executed. For an architect this separates two different risks: a bad plan is cheap to reject; a bad edit is expensive to undo. Programmatically, the same effect comes from a first call that returns a structured plan (a JSON list of steps with their dependencies) which your code then executes step by step, possibly with a fresh context per step.
Task lists inside the session (the harness's todo tooling) serve a different purpose: they keep the model's own progress visible to it, so that a long run does not forget step four after finishing step seven.
Choosing granularity
Too coarse and a subtask overflows its context or fails without a clear cause. Too fine and the overhead of briefing each worker, plus the loss of shared understanding, outweighs the benefit. Useful tests for a candidate subtask:
- Can its completion be verified mechanically (a test passes, a file exists, a schema validates)?
- Can it be described in a brief short enough that the worker starts productively?
- Does it need less than a fraction of the context window to complete, leaving room for tool output?
- Does it avoid shared mutable state with concurrent subtasks (the same file edited by two workers)?
If a subtask fails the first test, split it until it passes or add an explicit verification step after it.
Ordering and dependencies
Draw the dependency graph before scheduling. Independent nodes run in parallel; dependent nodes run in sequence; a node whose output feeds many others is a bottleneck worth making robust. Pass results between dependent subtasks through files or structured output rather than through a shared conversation. Git worktrees are a practical isolation tool when several agents edit the same repository: each works on its own copy and merges are explicit.
Checkpoints and recovery
Long decompositions need checkpoints: a recorded state after each completed subtask from which a run can resume. In Claude Code this is a session that can be resumed plus the repository's commit history; in a custom orchestrator it is a persisted job table. Design subtasks to be idempotent where possible, so that re-running one after a crash does not duplicate side effects.
Worked example
Migrating a codebase from one HTTP client library to another:
- Plan (step): one call lists every affected file and classifies the migration pattern for each.
- Implement (data): parallel subagents, one per directory, each applying the pattern to its files and running that directory's tests.
- Verify (expertise): a reviewer subagent checks the diff for missed call sites; the full test suite runs as a deterministic gate.
- Report (step): the orchestrator synthesises a summary and lists anything that needs a human decision.
Each subtask has a verifiable outcome, a narrow brief and no shared mutable state, and the dependency graph is explicit.
Exam focus
- Decompose by step (sequential phases), by data (map-reduce over independent units) or by expertise (specialist reviewers), often in combination.
- Plan mode separates the cheap risk of a bad plan from the expensive risk of a bad edit.
- A good subtask is mechanically verifiable, briefly describable, fits comfortably in context and shares no mutable state with concurrent peers.
- Pass results between subtasks via files or structured output, not a shared conversation.
- Checkpoint after each subtask and make subtasks idempotent so runs can resume safely.
- Over-decomposition adds briefing overhead and loses shared understanding; split only until subtasks become verifiable.
Check yourself
5 questions
1.A long-horizon task requires migrating forty services to a new logging library. Which decomposition approach best balances reliability and cost?
2.When is it appropriate to decompose a task into sequential steps rather than parallel ones?
3.A team decomposed a document-analysis task into fifteen tiny steps, each a separate API call with its own instructions. Output quality dropped and total cost rose compared with the original three-step version. What is the most likely diagnosis?
4.Between the steps of a multi-step pipeline, what is the best way to pass intermediate results?
5.A task such as 'research this topic and produce a briefing' has subtasks that cannot be known before starting. Which decomposition approach is appropriate?