用 Claude Code 子代理拆分并行开发任务

Claude Code 的 Subagents 要解决一个具体问题：长任务里，大量查文件、跑命令和排查细节挤进主对话，容易冲淡真正需要记住的目标。作者的建议是，把边界清楚的工作交给专门的子代理，让主代理负责协调和决策。

这套方法值得看的地方，是把委派拆成了权限、上下文、任务依赖和结果验收。不过，原文没有给出效率、成本或准确率的对照实验。它更适合作为配置与工作流指南，不能直接当成「多开几个代理就更快」的证据。

什么任务值得交给子代理

Subagent 是带有独立上下文窗口、工具集和系统提示词的 AI 助手。它可以读几十个文件完成调查，再把结论交回来，主对话不必接收全部阅读过程。

适合委派的任务，应当目标独立、产物明确，而且中间细节不需要主代理反复参与判断。

安全审查、依赖升级调查、测试覆盖分析都符合这个条件。相反，需要持续向用户确认需求、经常改变方向的工作，留在主对话更合适。作者指出，子代理按收到的提示工作，不能指望它随时找用户补齐信息。

委派也有开销，包括启动、交接上下文和合并结果。原文所说「花两分钟写提示，省十分钟往返」没有实验支撑，应理解为经验表达。

任务说明至少要交代目标、约束、允许修改的文件和返回格式。结果最好是简短摘要，加上文件路径、行号、证据与建议。返回几千字调查日记，会把节省下来的上下文再次占满。

并行取决于依赖关系。前端、后端和基础设施审查可以独立展开；先定位性能瓶颈、再实施优化，则应串行。多个子代理不共享实时状态，同时写同一个文件可能互相覆盖。作者给出的稳妥做法是按文件划分，或者并行调查，最后统一修改。

配置文件真正决定了什么

子代理用带 YAML frontmatter 的 Markdown 定义：头部配置身份和能力，正文写工作要求。

单次会话可以用 --agents；项目共享放在 .claude/agents/，个人跨项目使用放在 ~/.claude/agents/，也可以由插件提供。原文给出的优先级是 managed、CLI、project、user、plugin，内置代理不参与同名覆盖。/agents 提供交互管理入口。

下面的原始示例把审查范围、权限和检查顺序放在同一份定义中：

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

## Code Reviewer Agent

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

## Review Priorities (in order)
1. Security Issues - Authentication, authorization, data exposure
2. Performance Problems - O(n^2) operations, memory leaks, inefficient queries
3. Code Quality - Readability, naming, documentation
4. Test Coverage - Missing tests, edge cases
5. Design Patterns - SOLID principles, architecture

重点看 tools：这个示例需要执行 git diff，所以包含 Bash。原文另一个 security-reviewer 示例只开放 Read, Grep, Glob，却要求先运行 git diff HEAD，指令与工具权限存在冲突，不能直接照搬。

不写 tools 会继承所有可用工具。disallowedTools 可进一步排除工具，permissionMode 设置权限模式。只做审查的代理，应尽量避免修改能力；需要网络时，还要约束访问范围，把获取的网页当资料，不能当指令。

模型方面，原文列出 haiku、sonnet、opus 和继承父模型的 inherit。支持的模型可通过 effort 选择 low、medium、high、xhigh、max、auto；maxTurns 限制运行轮次。skills、mcpServers、initialPrompt 分别用于预加载技能、配置代理范围内的 MCP，以及自动提交首轮提示。

memory: user 则让记忆跨会话保留，记忆目录中 MEMORY.md 的前 200 行会自动载入系统提示。它适合记录长期发现，也需要定期清理过时结论。

隔离、后台和团队协作各解决什么

isolation: worktree 为子代理创建独立的 git worktree 和分支，完成后返回路径与分支名，供审核合并。没有修改时会自动清理；运行期间会加锁，结束后释放。

这里容易踩坑的是起点：按原文描述，默认从 origin/HEAD 对应的仓库默认分支创建。设置 worktree.baseRef 为 head，才从本地 HEAD 开始并带上未推送的提交。

工作目录之外的资源和外部工具，可以通过以下命令补充：

claude --add-dir ~/projects/shared-types --add-dir ~/projects/design-tokens
claude --mcp-config ./ci-servers.json

注意 --add-dir 授予额外目录 Read/Edit 权限，新增目录里的 .claude/skills/ 也会自动加载；长期设置对应 permissions.additionalDirectories。--mcp-config <path> 只对当前会话生效，默认合并用户和项目来源，加 --strict-mcp-config 才只使用指定配置。

调度方面，description 用于自动匹配，use proactively 只是鼓励调用。必须使用特定代理时，作者建议显式指定，例如 @"agent-name (agent)"，或者直接用自然语言点名。claude --agent <name> 可启动指定代理会话，Agent(...) 工具允许列表可限制协调者能派出哪些代理。

background: true 强制后台运行，前台任务也可按 Ctrl+B 转入后台。claude agents 查看会话状态，--cwd <path> 筛选目录，--json 输出包含 pid、cwd、kind、startedAt 等字段的数据；等待状态还可能通过 waitingFor 区分权限提示或输入请求。CLAUDE_CODE_DISABLE_AGENT_VIEW=1 可禁用该视图。

独立上下文也有例外。原文称，启用 CLAUDE_CODE_FORK_SUBAGENT=1 后，子代理继承主会话完整上下文，所有派生任务在后台运行，/fork 也改为创建派生子代理，而非 /branch 的别名。上下文隔离带来的收益，需要据此重新判断。

实验性的 Agent Teams 使用共享任务列表和邮箱协调多个实例，需启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 或 --agent-teams。原文标注，自 v2.1.178 起移除 TeamCreate、TeamDelete，会话自带隐式团队，通过 Agent 的 name 参数创建队友，退出时自动清理；SendMessage 会自动恢复已停止的代理。这些属于版本敏感说明，不能假定所有安装版本都适用。

我的判断

我认同作者把任务边界和权限放在模型选择前面。审查代理能读什么、交付什么、如何报告失败，通常比给它一个「资深专家」身份更有用。

但原文把示例称为可用于生产，证据不足。除了前面的权限冲突，测试示例提出最低 80% 覆盖率、关键路径 100%，也没有解释指标口径或适用条件。这是作者设定的目标，不能直接变成团队验收标准。

相比在主对话里直接完成，子代理适合隔离大量调查细节；相比固定脚本，它适合需要判断和探索的工作。规则已经清楚、结果能够确定计算的检查，脚本往往更容易复现。原文没有提供这些方案的成本或准确率对照。

故障处理部分很实用：答案含糊先收紧任务说明；工具失败先看错误和权限；运行失控则靠轮次、调用次数、token 或时间预算限制损失。作者说偶发工具失败重试一次合理，连续五次重试通常需要排查环境。这是操作建议，不是经过验证的阈值。

另外，「结果不对几乎总是提示或工具问题」说得过满。工具调用日志能帮助定位问题，但不能据此排除模型判断错误。复用代理前，也应记录 MCP 和技能配置，检查提示是否相互矛盾，并按原文建议每季度、或仓库大改后复查一次。

能拿来做什么

• 先把代码审查做成一个范围明确的子代理，只检查本次修改，返回文件、行号、问题和修复建议，并确认运行 git diff 所需权限已经开放。
• 给 Node 性能调查设定可验证的产物。原文提供了 node --prof app.js，可以要求代理先收集剖析结果，再提出优化，最后用相同方法复测。
• 将独立模块的调查并行执行，把依赖调查结论的修改放在后续步骤；需要修改时，按文件划分责任，使用 worktree 后仍要审核和合并。
• 把稳定的定义提交到 .claude/agents/，随代码一起评审，写清使用时机、输出格式和失败条件；失效或被替代的代理应明确弃用。