当一个任务太大、太复杂，或者需要大量文件探索时，子 Agent（Subagent）是你的秘密武器。它们在独立的上下文窗口中工作，不会污染你的主会话，完成后只返回精炼的结果。
什么是子 Agent？
子 Agent 是 Claude Code 主会话中可以启动的独立 Claude 实例：
- 独立上下文窗口：不消耗主会话的上下文
- 并行执行：多个子 Agent 可以同时工作
- 结果汇总：只把精炼的结果返回主会话
- 自动清理：完成后释放资源
何时使用子 Agent？
✅ 适合的场景
-
大范围代码搜索
text搜索整个代码库中所有使用 deprecated API 的地方 -
并行文件分析
text分析 10 个模块的测试覆盖率 -
独立功能实现
text为用户模块添加邮箱验证功能 -
研究型任务
text调研最适合我们项目的状态管理方案
❌ 不适合的场景
- 需要频繁与主会话交互的任务
- 依赖主会话上下文的工作
- 简单的单文件编辑
实战示例
示例 1：并行代码重构
text
这个项目有 5 个模块需要从 CommonJS 迁移到 ESM。
为每个模块启动一个子 Agent 并行处理。Claude 会启动 5 个子 Agent，每个负责一个模块：
子 Agent 1 → src/auth/ → CJS → ESM
子 Agent 2 → src/database/ → CJS → ESM
子 Agent 3 → src/api/ → CJS → ESM
子 Agent 4 → src/utils/ → CJS → ESM
子 Agent 5 → src/workers/ → CJS → ESM
示例 2：代码库审计
text
对整个项目做安全审计。检查：
1. SQL 注入风险
2. XSS 漏洞
3. 硬编码的密钥
4. 不安全的依赖每个检查项由独立子 Agent 处理，最后汇总报告。
示例 3：研究 + 实现
text
第一步：派一个子 Agent 调研我们项目最适合的缓存策略。
第二步：基于调研结果，实现选定的方案。示例 4：PR 大范围代码审查
text
审查 PR #156 的所有更改：
- 逻辑正确性
- 性能影响
- 是否遵循项目规范
- 是否有足够的测试子 Agent 配置
内置 Agent
Claude Code 可以自动启动子 Agent，无需额外配置。直接在提示中描述你想要的并行工作方式即可。
自定义 Agent
在 .claude/agents/ 目录中创建自定义 Agent：
markdown
# .claude/agents/security-auditor.md
---
name: security-auditor
description: Specialized security code reviewer
model: sonnet
effort: high
maxTurns: 30
disallowedTools: Write, Edit
---
You are a security specialist. Analyze code for:
- Injection vulnerabilities (SQL, XSS, command)
- Authentication and authorization flaws
- Sensitive data exposure
- Insecure dependencies
Report findings with severity (Critical/High/Medium/Low).
Provide specific file paths and line numbers.
Suggest concrete fixes for each finding.Agent 配置选项
| 选项 | 说明 |
|---|---|
| model | 使用的模型（sonnet, opus, haiku） |
| effort | 思考深度（low, medium, high） |
| maxTurns | 最大交互轮次 |
| disallowedTools | 禁用的工具（防止修改代码） |
| isolation | 设为 "worktree" 在独立 Git 分支工作 |
| background | 后台运行，不阻塞主会话 |
成本优化
用合适的模型
- 研究/搜索：用 Haiku（快速、便宜）
- 分析/审查：用 Sonnet（性价比高）
- 复杂实现：用 Opus（最强质量）
控制规模
- 限制
maxTurns避免子 Agent 无限循环 - 用
disallowedTools限制只读 Agent 的权限 - 给明确的完成标准
子 Agent vs Agent Teams
| 特性 | 子 Agent | Agent Teams |
|---|---|---|
| 通信 | 只向主 Agent 报告 | 队友间互相通信 |
| 适用 | 独立任务 | 需要协作的任务 |
| 开销 | 较低 | 较高 |
| 复杂度 | 简单 | 需要协调 |
实用技巧
- 给子 Agent 足够的上下文：告诉它文件在哪里、关键约束是什么
- 定义清晰的完成标准："找到所有问题并列出" vs "修复所有问题"
- 用只读 Agent 做审查：
disallowedTools: Write, Edit确保只看不改 - worktree 隔离：让子 Agent 在独立分支工作，避免冲突
- 后台运行：
background: true让子 Agent 在后台执行
原文整理自 Claude Code Sub-agents 文档 和实战经验 | 来源：Claude Code 官方文档