Claude Code Agent Teams Task Decomposition, Step by Step

Turn a high-level objective into self-contained, checkable tasks with clear boundaries and dependencies before an Agent Team starts parallel work.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

Task decomposition is the first thing a lead does in an Agent Team, and most of what goes wrong later traces back to it. The lead takes a high-level objective and converts it into smaller tasks before assigning them to teammates. The Claude Code agent teams documentation also advises explicitly asking Claude to split the work into smaller pieces when it does not create enough tasks on its own. This page covers how to do that conversion well. For background on the lead, teammates and shared task list, see the Claude Code Agent Teams method page.

Decomposition carries so much weight because teammates cannot read the lead's mind. Each one starts from its own context and works from the task text it claims. The coordinator checklist in the Claude Code architecture guide lists breaking the goal into independent subtasks with clear boundaries and passing context explicitly to each worker as core responsibilities. A task that says fix the checkout bug forces a teammate to guess which bug, which files and what counts as fixed. A task that names the failing test, the module and the expected behaviour does not.

The inputs to this skill are the objective, the repository's structure, and the constraints that already exist: shared schemas, open design questions, files that several features touch. The output is a task list in which every task has clear inputs, outputs and dependencies, the shape the DataCamp agent teams tutorial recommends producing in a planning pass before any parallel work starts. Each task should also pass the SPEC test, and the list as a whole should be sized to the team you intend to run.

You can tell decomposition went wrong from the symptoms. Teammates message the lead asking what a task means. Two teammates edit the same file and collide. Tasks sit blocked because a prerequisite was never written down as its own task. Or a teammate reports done and nobody can verify it without rereading everything it touched. Each symptom maps to a specific cause covered below: missing context, overlapping boundaries, unmapped dependencies, or an output with no checkable success criterion.

Decomposition is not the same as designing roles or deciding what can safely run at the same time. Those have their own pages. Here the focus is the task itself: what it says, how big it is, and how you know it is ready to hand out.

How It Works

Decomposition runs as a short planning pass that happens before any teammate is spawned. The DataCamp tutorial frames the rule as plan first, parallelize second: break the work into tasks with clear inputs, outputs and dependencies, then hand the plan to the team. Skipping this and letting teammates start from a broad objective produces ambiguous ownership, because nobody decided where one teammate's work ends and another's begins.

flowchart TD
  A[Objective] --> B[Planning pass]
  B --> C[Draft tasks]
  C --> D[Inputs]
  C --> E[Outputs]
  C --> F[Dependencies]
  D --> G{SPEC test}
  E --> G
  F --> G
  G -->|fails| C
  G -->|passes| H[Shared task list]

The planning pass produces draft tasks, and for each one you record three things. Inputs are what the teammate needs to start: the files or modules it owns, the relevant spec or ticket, and any interface it must honour. Outputs are what it hands back, and they should be checkable on their own, such as code in an assigned module, tests for that module, a design decision or a structured report, as the agent teams workflow guide and the architecture guide both suggest. Dependencies are the tasks that must finish first. Tasks that need an interface, schema, migration or architectural decision from another task stay blocked until that prerequisite is complete, while tasks with no dependencies can start immediately, per Fastio's orchestration walkthrough.

Boundaries come from the codebase. The agent teams workflow guide recommends non-overlapping file sets, for instance backend endpoints, frontend components and database migrations assigned to separate agents. When the directory layout does not offer clean seams, the claudefa.st best practices guide advises creating the separation in the decomposition itself rather than letting several teammates edit the same area.

Each draft task then goes through the SPEC test described in the agent teams workflow guide: the task is Programmatically evaluable, has Explicit scope, and is Constrained by a defined output format, length or schema. A task that fails goes back to drafting. The table shows what the difference looks like in practice.

Finally, size the list. The claudefa.st guide suggests aiming for 5-6 tasks per teammate, and the DataCamp tutorial suggests starting with three to five teammates for most workflows because coordination overhead grows faster than parallel speedup. Treat both as practitioner starting points rather than measured optima. If a teammate holds one enormous task, split it so progress shows on the shared list. If it holds a dozen trivial ones, merge them so coordination does not outweigh the work.

Step-by-Step Guide

Step 1: Define the objective and done criteria

Write the objective in one or two sentences, then list what must be true when the whole team has finished. Name observable checks: tests that pass, endpoints that respond, a report that exists. This gives every later task something to trace back to and tells you when decomposition is complete. If you cannot say what done looks like for the whole objective, no individual task will have a checkable output either.

Pro tip: Put the done criteria at the top of the plan so the lead can quote them when writing each task.

Step 2: Run a planning pass before spawning

Ask the lead to research the relevant code and produce a task plan before any teammate starts, following the plan first, parallelize second rule from the DataCamp tutorial. The plan should list tasks with inputs, outputs and dependencies, not just topic headings. Review it yourself before execution begins. If the lead produces too few tasks, the agent teams documentation recommends explicitly asking it to split the work into smaller pieces.

Pro tip: Tell the lead not to spawn teammates until you approve the plan, so a weak decomposition costs one review instead of a round of rework.

Step 3: Cut boundaries along files and modules

Walk the repository and give each task a set of files or directories that no other task touches. Separating work by directory or module reduces merge conflicts, as the claudefa.st guide notes. Replace a broad instruction such as refactor the API layer with bounded pieces like user endpoints and billing endpoints in separate directories. Where two tasks would need the same file, merge them or make one depend on the other.

Pro tip: List owned paths explicitly in each task, for example src/billing/ only, instead of describing the area in prose.

Step 4: Write self-contained task descriptions

Each description should state the relevant context, the scope and the expected result so the teammate does not have to infer missing requirements, as the architecture guide advises. Include the owned files, the relevant spec or ticket excerpt, any interface it must match, and what to hand back. Do not rely on context the lead gathered while planning, because the teammate works from its own context and sees only what you wrote. Read each description as if you had never seen the codebase.

Pro tip: Use a fixed template with fields for context, scope, owned files, output and done check, so a missing field is obvious at a glance.

Step 5: Map dependencies and sequence

For every task, list the tasks that must finish before it can start. Anything that consumes an interface, schema, migration or architectural decision from another task stays blocked until that prerequisite completes, while independent tasks can start right away, per Fastio's walkthrough. Turn unresolved shared decisions into their own tasks at the front of the graph. Then check the graph for cycles and for long chains that would leave most of the team idle.

Step 6: Apply the SPEC test

Check each task against the SPEC test: Programmatically evaluable, Explicit scope, Constrained output. Ask whether a script or test could confirm it is done, whether a reader knows exactly which files are in and out, and whether the output has a defined format, length or schema. Rewrite any task that fails a criterion before it reaches the shared list. Research and review tasks need this as much as code tasks, since an unconstrained report is hard to synthesize.

Pro tip: For review tasks, specify the report schema, for example one row per finding with file, line, severity and suggested fix.

Step 7: Size the list against the team

Count tasks per teammate and compare the result with the claudefa.st guide's suggestion of 5-6 tasks per teammate. Pick a team size with the DataCamp tutorial's advice to start with three to five teammates in mind. If the work does not yield enough independent tasks to keep a team busy, run fewer teammates rather than inventing overlapping work. Split oversized tasks and merge trivial ones until the load is roughly even.

Best Practices

• Plan before you parallelize. A reviewed plan with inputs, outputs and dependencies exposes overlap and missing prerequisites while they are still cheap to fix, which is why the DataCamp tutorial puts planning first.
• Draw boundaries along files, not topics. Topic splits such as performance or cleanup cut across the same files, while directory and module splits give each teammate an area it can change without collisions, as the claudefa.st guide recommends.
• Make every output independently checkable. Code in an assigned module, tests for that module, a decision record or a structured report can each be verified alone, which shortens the lead's integration work. The agent teams workflow guide lists these as useful task outputs.
• Turn open decisions into tasks. If several tasks depend on a schema or interface nobody has chosen, create a task that makes the decision and block the others on it. Otherwise each teammate quietly picks its own answer and the integration step inherits the conflict.
• Write for a reader with no history. Teammates do not share the lead's planning context, so the description has to carry context, scope and expected result explicitly, as the architecture guide advises.
• Treat sizing heuristics as starting points. Practitioner numbers for tasks per teammate and team size come from experience rather than controlled studies, so adjust after watching how long tasks actually take and how often teammates ask for clarification.

Common Mistakes

• Handing teammates the raw objective and letting them divide it among themselves.: Run a planning pass first and hand out tasks with defined inputs, outputs and dependencies. The DataCamp tutorial is explicit: plan first, parallelize second.
• Assigning broad, overlapping instructions such as refactor the API layer to more than one teammate.: Split the area into bounded pieces, for example user endpoints and billing endpoints in separate directories, as the claudefa.st guide suggests. Each task should name the paths it owns.
• Parallelizing tasks that depend on a shared decision nobody has made yet.: The agent teams workflow guide warns that such boundaries create conflicts or force rework. Make the decision its own prerequisite task and keep dependent tasks blocked until it completes.
• Writing tasks with verbs like improve, clean up or look into and no success criterion.: Rewrite them to pass the SPEC test: a check that can confirm completion, an explicit file scope and a defined output format. If you cannot describe the check, the task is not ready.
• Inventing extra tasks to keep a large team busy.: Run fewer teammates instead. The DataCamp tutorial notes coordination overhead grows faster than parallel speedup, so filler tasks add cost and collision risk without adding value.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: Claude Code Agent Teams

Related Skills

• Designing Agent Roles and Scopes
• Coordinating Inter-Agent Communication
• Reviewing and Synthesizing Teammate Outputs
• Parallelizing Independent Work Across Sessions
• Choosing Agent Teams Versus Subagents
• Managing Shared Task State

Sources

• Orchestrate teams of Claude Code sessions - Claude Code Docs
• Agent Teams Workflow - claude-code-ultimate-guide - GitHub
• Claude Code Agent Teams Best Practices & Troubleshooting
• How to Orchestrate Multi-Agent Workflows in Claude Code | Fastio
• Claude Code Architecture & Agent Loop | Claude Code Guide
• Claude Code Agent Teams: The Future of AI-Assisted Development

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.