Module 3: Parallel Sub-Agent Delegation

1. Module Introduction — When Sequence Doesn't Scale

Description

Your subagents from Module 1 have defined roles. With Module 2, they have persistent memory. They work well — the reviewer analyzes, the implementer fixes, the tester verifies. But they work single file. One waits for the other to finish. In a 3-agent pipeline this is tolerable: 2 minutes + 3 minutes + 1 minute = 6 minutes total. But what happens when you need 4 agents refactoring independent modules? 4 × 3 minutes = 12 minutes. And if it were 8 modules, 24 minutes waiting for each agent to finish before the next one starts.

Parallel delegation breaks that barrier. If the 4 modules are independent, the 4 agents can work simultaneously. 4 × 3 minutes in parallel ≈ 3.5 minutes. It's not magic — it's concurrency. The same logic that makes a team of 4 developers finish a sprint faster than one alone, applied to Claude Code subagents.

But parallelism introduces complexity that sequential execution doesn't have. What if two agents modify related files? What if one agent fails while the other 3 continue? How do you combine the results of 4 parallel runs? How do you decide which tasks are really independent? These questions define the difference between "launching agents at the same time" and "orchestrating parallel delegation."

This module closes Phase 1 because parallel delegation is the synthesis of everything before it: well-defined subagents (Module 1) + shared memory for consistency (Module 2) + the ability to coordinate simultaneous work (this module). By the end, you'll have the complete foundation for Agent Teams in Phase 2.

Where Are We in the Guide?

Context in the Path

Phase 1: Advanced Subagents
├── Module 1: Custom Subagents                    ← completed
├── Module 2: Agent Memory and Scopes             ← completed
└── Module 3: Parallel Sub-Agent Delegation       ← YOU ARE HERE

Phase 2: Agent Teams and Plugins (Modules 4-6)
Phase 3: Orchestration (Modules 7-8)

In Module 1 you created subagents with an identity of their own — roles, restrictions, system prompts. In Module 2 you gave them persistent memory — they remember patterns, conventions, and decisions across sessions. Now you put them to work at the same time. Without the two previous modules, parallel delegation would be launching generic agents without shared context — coordinated chaos.

Where are we headed?

This module is the close of Phase 1. The complete progression:

Module 1: Create agents with identity ← completed
Module 2: Give those agents memory ← completed
Module 3: Put them to work in parallel ← HERE — the synthesis of Phase 1
Module 4: Formalize coordination with Agent Teams — what you do manually here, Agent Teams automate
Module 5: Package into plugins — distribute subagent configurations
Module 6: Automate with hooks and the SDK — programmatic control
Module 7: Operate remotely — remote control and team CLAUDE.md
Module 8: Integrate everything into a complete multi-agent system

The parallel delegation you master here is what Agent Teams formalize in Module 4. Think of it this way: this module teaches you to coordinate manually; Agent Teams give you the infrastructure to make coordination automatic. You need to understand "how it works underneath" before using the abstraction.

The Problem: Sequential Execution Doesn't Scale

A real scenario

You have a project with 4 independent modules: auth, products, orders, notifications. Each one needs a refactor — update type hints, improve error handling, and standardize the response models. The 4 modules don't depend on each other for the refactor — each one is self-contained.

With sequential execution:

Refactor auth          → 3 min
  ↓ (waits)
Refactor products      → 4 min
  ↓ (waits)
Refactor orders        → 3 min
  ↓ (waits)
Refactor notifications → 2 min

Total: 12 minutes (wall-clock time)

Each agent waits for the previous one to finish. The notifications agent has 10 minutes of idle time before starting. If you were a tech lead with 4 developers, you'd never tell them "wait for María to finish the auth module before starting on products." You'd say "each of you grab a module and we'll merge at the end."

With parallel delegation:

Refactor auth          ──┐
Refactor products      ──┤ → ~4 min (the slowest one defines the total)
Refactor orders        ──┤
Refactor notifications ──┘
         ↓
    Merge coordinator  → 1 min

Total: ~5 minutes (wall-clock time)

From 12 minutes to 5. A 58% reduction. And the benefit grows with more independent tasks.

When sequence is fine

Not everything benefits from parallelism. If the tasks have real dependencies, parallelizing them is a mistake:

❌ Don't parallelize:
implementer → tester    (the tester NEEDS the implementer to finish first)
schema → migration      (the migration NEEDS the updated schema)
auth → protected routes (the protected routes NEED the auth system)

✅ Do parallelize:
refactor auth ║ refactor products    (independent modules)
review backend ║ review frontend     (code areas with no dependency)
update docs ║ update tests           (different files, no conflict)

The rule: if task B needs task A's result to start, you can't parallelize them. If both can start right now with the information that already exists, they're candidates for parallelization.

The cost of parallelizing poorly

Parallelizing tasks with hidden dependencies produces silently incorrect results:

Two agents edit the same file → one overwrites the other's changes
One agent assumes a schema that another agent is changing → inconsistency
One agent generates tests for an interface that another agent is refactoring → invalid tests

These problems don't generate immediate errors — the changes are applied, the tests may pass, but the result has logical conflicts that are only discovered later. That's why correct dependency identification is the most important skill of this module.

Module Objective

By the end of this module you'll be able to:

✅ Identify independent tasks that benefit from parallel delegation vs tasks with dependencies that must be sequential
✅ Launch multiple subagents in parallel using delegation prompts and the background: true field in frontmatter
✅ Use isolation: worktree so parallel agents edit files without conflicts via git worktrees
✅ Design a mental dependency graph to determine which tasks go in parallel and which wait
✅ Coordinate the merge of results when multiple agents complete at the same time
✅ Implement timeout with maxTurns and error handling with fallback strategies
✅ Orchestrate a parallel refactor of 4 modules with a merge coordinator at the end

Professional objective

When you have a refactor that touches 4 independent modules, you won't spend 15 minutes waiting for each agent to finish in sequence. You'll launch 4 agents in parallel, each in its isolated worktree, and a coordinator will merge the results. Your team will see a clean PR with changes in 4 modules — completed in a fraction of the sequential time.

Module Roadmap

Capsule map

#	Capsule	What you'll learn	Type
01	Introduction (this one)	When sequence doesn't scale, the case for parallelism, dependency graphs	Intro
02	Parallel Delegation: Syntax and Patterns	How Claude Code runs subagents in parallel, `background: true`, Ctrl+B, worktrees, limits	Technical
03	Dependency Resolution and Merge	Identifying dependencies, coordinating results, git worktrees for clean merge, conflicts	Technical
04	Timeout and Error Handling	`maxTurns`, failure handling, permissions in background, fallback strategies, debugging	Technical
05	Project: Parallel Refactor of 4 Modules	4 subagents in parallel + merge coordinator, step by step, with real errors	Project

Learning flow

First you'll understand how to launch subagents in parallel — the syntax, the frontmatter fields, and the prompting patterns that trigger concurrent execution (capsule 02). Then you'll learn how to coordinate results — what happens when 4 agents finish at different times and how conflicts are resolved when two touch related files (capsule 03). Next you'll see what happens when something fails — timeout, background permission errors, and fallback strategies (capsule 04). Finally, you'll build a real parallel refactor of 4 modules with isolation via worktrees and a merge coordinator (capsule 05).

The progression is: launch in parallel → coordinate results → handle errors → build complete system.

Each capsule builds on the previous one. Don't jump to 03 without understanding the parallel launch from 02 — coordination assumes you already know how agents run concurrently.

Estimated module duration: 1-1.25 hours.

Connection to the Project

This module's mini-project: Parallel Refactor of 4 Modules

In capsule 05 you'll build a parallel refactoring system:

4 worker subagents — Each one refactors an independent module (auth, products, orders, notifications). Each operates in an isolated git worktree to avoid file conflicts.
1 coordinator subagent — Waits for the 4 workers to finish, reviews each one's changes, resolves any inconsistency, and produces a consolidated report.

Your prompt:
"Refactor the 4 modules in parallel and consolidate the results"

↓

worker-auth          ──┐
worker-products      ──┤  (parallel, each in its worktree)
worker-orders        ──┤
worker-notifications ──┘
         ↓
merge-coordinator    → Consolidated report + PR-ready changes

Connection to the final project (Module 8)

The Module 8 multi-agent system operates with parallel delegation as default behavior. The frontend agent and the backend agent work in parallel. The tester waits for both (dependency). The documenter works in parallel with the tester (independent). Without mastering parallel delegation, the final project would be a sequential system in disguise — slow and underutilized.

Prerequisites

Required knowledge

✅ Module 1 completed — You know how to create custom subagents with YAML frontmatter and system prompts
✅ Module 2 completed — Your subagents have persistent memory configured
✅ Intermediate Git — You understand branches, merge, and are familiar with the concept of worktrees
✅ Basic concurrency — You understand the difference between sequential and parallel (you don't need threading or async)

You don't need

❌ Experience with Agent Teams — covered in Module 4
❌ Knowledge of git worktrees — explained in this module
❌ Experience with distributed systems — the concurrency here is coordinated by Claude Code
❌ Automation scripts — everything is configured with subagent files and prompts

Module Setup

What you need to have ready

1. A project with 4+ modules in src/:

You need a project with multiple independent modules. They don't need to be exactly 4, but at least 2 for parallelization to make sense. The ideal structure is:

your-project/
├── src/
│   ├── auth/           ← module 1
│   ├── products/       ← module 2
│   ├── orders/         ← module 3
│   └── notifications/  ← module 4
├── tests/
├── CLAUDE.md
└── ...

If you don't have a project with this structure, you can adapt the exercises to the modules you have. What matters is that there's code in separate directories that you can refactor in parallel.

2. Module 1 subagents configured:

The Module 1 subagent files (code-reviewer.md, code-implementer.md, code-tester.md) should exist in .claude/agents/. We won't use them directly, but this module's workers follow the same design patterns.

ls .claude/agents/

3. Module 2 memory configured:

If your subagents have memory: project, the shared memory helps the parallel workers follow the same conventions. It's not mandatory but it improves consistency.

ls .claude/agent-memory/ 2>/dev/null

4. Claude Code up to date:

claude --version

Make sure you have v2.1.63 or later — the most recent versions support background: true, isolation: worktree, and all the frontmatter fields we'll use.

5. Clean git:

git status

Git worktrees require a clean git state (no uncommitted changes). If you have pending changes, commit them or stash them before starting.

git stash

How Parallel Delegation Works — Overview

Before diving into the detailed mechanics (capsules 02-04), here's an overview of how everything fits together:

The three pillars

Parallel delegation in Claude Code rests on three mechanisms:

1. Background execution — A subagent runs in the background while Claude continues with other subagents or with your conversation. It's activated with background: true in the frontmatter or with Ctrl+B.

---
name: worker
background: true     ← runs in the background
---

2. Worktree isolation — Each subagent works in its own copy of the repository (a temporary git worktree). One agent's changes don't affect the others until a merge is done at the end.

---
name: worker
isolation: worktree  ← works in an isolated copy of the repo
---

3. Merge coordination — A subagent (or Claude main) reviews the results of all the workers, verifies consistency, and combines the changes into a coherent result.

These three mechanisms work together:

Background → enables simultaneous execution
Worktree   → prevents file conflicts
Merge      → produces a coherent result

What Claude Code handles automatically

Creating and destroying temporary worktrees
Waiting for all background subagents to finish
Pre-approving permissions for background subagents
Managing each subagent's lifecycle

What you need to manage

Design the dependency graph (what's parallel, what's sequential)
Define the subagent files with the correct fields
Write the orchestration prompts
Decide the error-handling strategy (fail-fast vs resilient)
Verify the consistency of the results

Key Concepts We'll Use

Before diving into the technical capsules, make sure these concepts are clear:

Parallel delegation: Launching multiple subagents simultaneously so they work at the same time on independent tasks. Reduces wall-clock time proportionally to the number of parallel tasks.
Background execution: A subagent that runs in the background while you (or Claude) continue with something else. It's activated with background: true in the frontmatter or by pressing Ctrl+B during execution.
Git worktree: An isolated copy of the repository that shares the same git history but has its own working directory. It lets multiple agents edit files without simultaneous-write conflicts. It's activated with isolation: worktree.
Dependency graph: The mental model of which tasks depend on which. Tasks with no dependencies between them are candidates for parallelization. Those with dependencies must run in sequence.
Merge coordination: The process of combining the results of parallel agents into a coherent result. It includes detecting conflicts, resolving inconsistencies, and producing a unified output.
maxTurns: A frontmatter field that limits how many agentic turns a subagent can take. It works as a timeout to prevent infinite runs.

Limits: What Is NOT Covered in This Module

❌ Agent Teams — Covered in Module 4. Here you coordinate manually; Agent Teams automate the coordination
❌ Plugins — Covered in Module 5. Here subagents are local files
❌ Advanced hooks — Covered in Module 6. Here hooks are mentioned only when they're relevant for error handling
❌ Headless SDK — Covered in Module 6. Here everything is interactive in Claude Code
❌ CI/CD pipelines — Covered in the next guide. Here parallelization is at development time
❌ Code-level concurrency (threads, async) — Parallelization is at the subagent level, not source code

Evidence of Success

By the end of this module, you'll know you succeeded if:

✅ You can identify in 30 seconds whether a set of tasks is parallelizable or has dependencies that require sequence
✅ You've run at least 2 subagents in parallel and verified that both completed correctly
✅ You understand the difference between background: true and isolation: worktree — and when to use each one
✅ You can handle a scenario where a parallel subagent fails — without losing the others' work
✅ You've completed the parallel refactor of 4 modules with coordinated merge
✅ You can explain to a colleague why not everything is parallelized — and when sequence is the right decision

Quick self-assessment test

If you can answer these questions by the end of the module, you're on the right track:

When is it better to run subagents in parallel vs in sequence?
What is a git worktree and why do you need it for parallel edits?
What happens if a background subagent fails for lack of permissions?
How are results coordinated when 4 agents finish at different times?
Which frontmatter field limits a subagent's execution as a timeout?

The Development Team Analogy

If you have experience leading teams, parallel delegation is intuitive. Think of it as managing a sprint:

Project manager (you) with 4 developers:

Option A — Sequential:
"María, do the auth module. When you finish,
 Juan, do products. When Juan finishes,
 Ana, do orders. When Ana finishes,
 Carlos, do notifications."
→ 4 sprints of 1 week each = 4 weeks

Option B — Parallel:
"María: auth. Juan: products. Ana: orders. Carlos: notifications.
 All 4 start today. We meet on Friday to integrate."
→ 1 sprint of 1 week + 1 day of integration ≈ 1.2 weeks

Parallel delegation with Claude Code is exactly Option B. Each subagent is a "developer" with its own workspace (worktree), its own work scope, and its own restrictions. The merge coordinator is the Friday meeting where everything gets integrated.

Where the analogy breaks down

Unlike a human team, subagents:

Don't communicate with each other during execution — there's no Slack, no real-time questions
Don't have shared implicit context — what one knows the other doesn't (unless they have memory: project)
Can't improvise — if the system prompt doesn't cover a scenario, they can't ask
Have no ego — they never argue about the best way to name a variable

This makes upfront planning (dependency graph, conventions in CLAUDE.md, detailed system prompts) more important than in a human team. A human team can coordinate ad-hoc. Parallel subagents need everything defined in advance.

Note on Features

The parallel delegation features we cover — background: true, isolation: worktree, and maxTurns — are stable Claude Code functionality. Background execution and worktree isolation work with custom subagents. The environment variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is available for debugging.

Last functionality check: March 2026

Summary

Sequential execution doesn't scale when you have multiple independent tasks — 4 tasks × 3 min = 12 min sequential vs ~4 min in parallel
Parallel delegation is the synthesis of Phase 1: subagents with identity (M1) + shared memory (M2) + concurrent execution (M3)
The dependency graph is the key mental tool: if task B doesn't need A's result, they can go in parallel
Git worktrees (isolation: worktree) let parallel agents edit files without write conflicts
Result coordination — not the launch — is the skill that distinguishes effective parallelization from concurrent chaos
The mini-project builds a parallel refactor of 4 modules with a final merge coordinator
Everything learned here is formalized in Agent Teams (Module 4) — this module gives you the manual understanding that Agent Teams automate

Additional Resources

Create Custom Subagents (Anthropic Docs) — Official documentation including the background, isolation, and maxTurns frontmatter fields
Claude Code Sub-agents — Background Execution — Reference for background execution and pre-approved permissions
Claude Code Best Practices — Delegation and parallelization best practices
Claude Code CLI Reference — Reference for flags and environment variables like CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
Git Worktrees Documentation — Official git worktrees reference to understand the underlying mechanism
Claude Code Overview — General context of Claude Code's execution model

Next capsule: In capsule 02 you'll learn the concrete mechanics of parallel delegation — how Claude Code runs subagents in the background, the syntax of the background: true field, the Ctrl+B shortcut, the prompts that trigger concurrent execution, and the isolation: worktree field that prevents file conflicts. You'll move from understanding why to parallelize to knowing how to do it.

← Previous5. Project — Memory Hierarchy for 3 Subagents Next →2. Parallel Delegation — Syntax, Patterns, and Limits