Chapter 12 · Sub-agents and Parallel Workflows

Chapter goals: Master Claude Code's sub-agent dispatch mechanism, learn to build efficient multi-agent workflows using parallel edits, maker-checker patterns, and git worktree isolation.

12.1 What Is a Sub-agent

Claude Code's Agent tool allows the主 agent to dispatch independent "sub-task executors." Each sub-agent has:

• An independent context window — does not占 the主 conversation's space;
• A专属 toolset —其能力范围 can be restricted;
• A clear task goal — returns only a result summary to the主 agent upon completion.

Main agent (coordinator)
├── Sub-agent A: Search all API endpoints in the codebase
├── Sub-agent B: Read test files to understand test patterns
└── Sub-agent C: Check package.json dependency versions

The core value of this design is context isolation:大量 intermediate exploration results stay inside the sub-agent; the主 agent只 receives refined conclusions.

12.2 Dispatching Sub-agents

In conversation, Claude Code automatically judges when to dispatch sub-agents. You can also explicitly request:

> Use one sub-agent to search all places in the project using deprecated APIs,
  and another sub-agent to check test coverage, simultaneously.

Internally implemented via the Agent tool:

{
  "tool": "Agent",
  "parameters": {
    "description": "Search deprecated APIs",
    "prompt": "Search the codebase for uses of deprecated APIs...",
    "tools": ["Read", "Grep", "Glob"]
  }
}

12.3 Parallel File Editing

When multiple unrelated files need modification, multiple sub-agents can work in parallel:

> Do the following three things simultaneously:
1. Add pagination parameter support to src/api/users.ts
2. Add sorting functionality to src/api/orders.ts
3. Update corresponding type definitions in src/types/api.ts

Claude Code assesses whether these modifications冲突:

• No conflict → dispatch multiple sub-agents to execute in parallel;
• Conflict (e.g.共享 the same file) → execute串行ly or合并 into one sub-agent.

Prerequisite for Parallelism

Parallel sub-agents are safest when各自操作 different files. If two sub-agents both need to modify the same file, the last one wins andoverwrites the first. Claude Code通常能识别 this and自动 serializes.

12.4 Maker-Checker Pattern

The pattern recommended by Anthropic for高 reliability: have one sub-agent write code, another independent sub-agent review it.

Main agent
│
├── Maker sub-agent: implement the user auth module
│   └── Output: auth.ts, auth.test.ts
│
└── Checker sub-agent: review auth.ts for security and correctness
    ├── Input: diff + original requirement description
    ├── Tool restriction: Read/Grep only (cannot write files)
    └── Returns: PASS or FAIL + a list of specific issues

Why not let the same agent check itself? Anthropic research found: models have a systematic positive bias when评价 their own work — they倾向 to give positive assessments even when质量不达标. Separating "the one who works" from "the one who checks" is the solution.

In Anthropic's controlled experiment, the same Opus 4.5 model and prompt:

• Single agent bare run: 20 min / $9 / core features unusable;
• Three-agent architecture (planner + generator + evaluator): 6 hr / $200 / game fully playable.

12.5 Worktree Isolation

For long tasks that may产生 destructive modifications, use git worktree to create an isolated workspace:

# The main repo remains unaffected
git worktree add ../feature-auth -b feature/auth

# Run Claude Code in the isolated环境
cd ../feature-auth
claude

~/my-project/           ← Main repo (main branch)
~/feature-auth/         ← Worktree (feature/auth branch)

After the experiment, merge back to the main branch:

cd ~/my-project
git merge feature/auth
git worktree remove ../feature-auth

This ensures that even if the sub-agent产生错误 modifications, the main branch remains干净.

Chapter Summary

• Sub-agents have独立 context and toolsets; only return a summary upon completion;
• Unconflicting file modifications can be dispatched in parallel; conflicts are auto-serialized;
• Maker-Checker separates the creator and the reviewer, overcoming self-assessment bias;
• Git worktree provides物理级 isolation, suitable for high-risk long tasks.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the core advantage of sub-agents?

2. In the Maker-Checker pattern, which tools should the Checker sub-agent be restricted to?

3. When should you use git worktree to isolate a sub-agent's work?

4. Two sub-agents both need to修改 the same区域 of the same file. How does Claude Code handle it?

🛠️ Hands-on Practice

1. Have Claude Code use two parallel sub-agents to add JSDoc comments to two different modules in your project; observe the execution过程.
2. Implement a Maker-Checker flow: have one sub-agent写 a function, another review it; feed the review feedback to the first for修正.
3. Use git worktree to create an isolated environment; have Claude Code do a large-scale refactor inside it; compare whether the main branch is affected.

After completing, proceed to Chapter 13: Hooks Automation.