Skip to content

Practice Patterns

  • Claude Code · Module 08
  • Lesson 4 of 4 · then sources and quiz

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"
Tip
Rule of Thumb

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.

Question · Self-check
You need to refactor a single function and want to make sure all callers are updated. Subagent or Agent Team?

Step 2 of 4Understand

Cost Considerations

Warning
Keep Costs in Mind

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:

SetupApproximate 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

CriterionSubagentsAgent Teams
ActivationAutomatic or via promptFeature flag + explicit start
CostLow (partly Haiku)High (each teammate = full instance)
ParallelismLimitedTrue parallelism
CommunicationResult return onlyMessages + broadcasts
CoordinationNone neededShared Task List
ComplexityLowMedium to high
StabilityProduction-readyExperimental
Typical UseResearch, planning, individual tasksParallel features, large refactorings
Git WorkflowOptional worktreeWorktrees recommended
Session ResumeNot 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.