Step 1 of 4Learn
Subagent or Agent Team?
The most important decision is: Do I need a team or is a subagent sufficient? Here's the clear distinction:
Subagent -- when the task:
- Is a clearly self-contained subtask
- The result should flow back to the main agent
- Doesn't require independent, long-running work
- Example: "Research how the auth middleware is structured"
Agent Team -- when the task:
- Consists of multiple independent subtasks
- The subtasks can run in parallel
- The agents work independently over a longer period
- Example: "Implement three new API endpoints with tests"
If you can describe the task in one sentence and only need one result back -- use a subagent. If you have a todo list with multiple independent items -- use an Agent Team.
Pattern 1: Parallel Feature Development
The most common pattern. The lead plans the features, and each teammate implements one in its own Git worktree:
Lead: "We need three new endpoints: /users, /posts, /comments"
Teammate 1 (worktree-1): Implements /users
Teammate 2 (worktree-2): Implements /posts
Teammate 3 (worktree-3): Implements /comments
Lead: Merges the results together
Each teammate works in their own worktree, so there are no Git conflicts during development. The lead merges the branches together at the end.
When useful: For clearly separated features that don't modify shared files.
Pattern 2: Code + Tests in Parallel
One teammate implements the feature, another writes the tests in parallel:
Lead: "Implement and test Feature X"
Teammate 1: Implements Feature X
Teammate 2: Writes tests (waits for API interface, then parallel)
Lead: Checks whether tests and implementation match
Here you use dependencies: The test task depends on the interface definition (not the complete implementation) being in place. As soon as Teammate 1 has defined the interfaces, Teammate 2 can start.
When useful: For TDD-like workflows or when you want to ensure that tests aren't "written to match the implementation."
Pattern 3: Review + Fix in Parallel
One teammate reviews code, another fixes the issues found:
Lead: "Codebase review and fixes for the auth module"
Teammate 1: Reviews the code, creates issues as tasks
Teammate 2: Picks up completed review tasks and fixes them
Lead: Reviews the fixes and closes out the review
Here the teammates work in a pipeline: Teammate 1 produces review findings as tasks, Teammate 2 consumes and processes them. The messaging system is used to inform the fix teammate about priorities.
When useful: For larger code reviews or refactorings where review and fix go hand in hand.
Step 2 of 4Understand
Cost Considerations
Each teammate is its own Claude instance with its own context window. This means: Costs scale linearly with the number of teammates.
A realistic cost estimate:
| Setup | Approximate Cost* |
|---|---|
| 1 Agent (normal) | 1x base |
| Lead + 2 Teammates | ~3x base |
| Lead + 4 Teammates | ~5x base |
*Actual costs depend on task complexity and session duration.
When teams are financially worthwhile: When the time savings justify the additional costs. Three features in 10 minutes instead of 30 minutes -- at the same cost per feature -- can be worth the 3x premium if your time is more expensive than the API costs.
When you should stick with subagents: For tasks that must run sequentially, or on a tight budget. A single agent handling three tasks one after another costs less than three parallel agents.
Comparison Table: Subagents vs. Agent Teams
| Criterion | Subagents | Agent Teams |
|---|---|---|
| Activation | Automatic or via prompt | Feature flag + explicit start |
| Cost | Low (partly Haiku) | High (each teammate = full instance) |
| Parallelism | Limited | True parallelism |
| Communication | Result return only | Messages + broadcasts |
| Coordination | None needed | Shared Task List |
| Complexity | Low | Medium to high |
| Stability | Production-ready | Experimental |
| Typical Use | Research, planning, individual tasks | Parallel features, large refactorings |
| Git Workflow | Optional worktree | Worktrees recommended |
| Session Resume | Not relevant (short-lived) | Lead only, not teammates |
Step 3 of 4Apply
Checklist: Is an Agent Team Worthwhile?
Before starting an Agent Team, check these points:
- Do you have at least two independent tasks that can run in parallel?
- Are the tasks large enough that parallelism provides a noticeable time advantage?
- Are the tasks in different files/modules so there are no merge conflicts?
- Is the cost budget available? (Calculate N+1 instances for N teammates)
- Are you willing to work with an experimental feature?
If you can check fewer than three points, stick with subagents.
Step 4 of 4Reflect
Agent Teams are a powerful tool, but not a silver bullet. The right decision between subagent and Agent Team depends on the task structure, budget, and risk tolerance. Start small -- a lead with two teammates and clear, independent tasks -- and increase complexity as you gain experience.