15｜Worktrees 与 Agent Teams：安全并行工作

用 Worktree 隔离写入，并判断哪些任务适合并行。

并行不是让两台挖掘机同时挖同一个坑。真正可并行的任务依赖少、文件重叠小、验收独立；worktree 则为每条施工队提供独立车道和现场。

本课交付物

创建两个 worktree，分别完成文档与测试改动；比较它们的分支、依赖与合并点，并故意识别一个不应并行的共享接口修改。

---

限制可启动的 Subagents

你可以限制 Claude 只能 spawn 某些 subagent，以降低风险。

示例

• 只允许审查类 agent
• 禁止高风险自动化 agent

claude agents CLI 命令

用于查看和管理当前可用的 agent。

Agent Teams（实验性）

Agent teams 是更高级的协作模式，适合多个 subagent 并行处理复杂任务。

Subagents vs Agent Teams

• Subagents 侧重委派单个任务
• Agent teams 侧重多角色协作

启用 Agent Teams

通过设置打开实验性功能。

启动团队

团队模式会把不同任务分配给不同角色。

显示模式

可以选择更适合终端或图形界面的显示方式。

导航

你可以在 team 中切换角色、查看状态和读取消息。

团队配置

适合为大型流程定义清晰角色。

架构

agent team 本质上是多个专门角色围绕同一任务协作。

任务分配与消息

主 agent 会负责把任务拆分并转发给对应 subagent。

计划审批流程

如果是 plan 驱动流程，团队会先审计划再执行。

团队相关 hook 事件

一些 hook 可以在 team 生命周期里触发。

最佳实践

• 角色定义要清楚
• 任务边界要明确
• 不要让多个 agent 做重复工作

局限

• 实验性功能可能会变化
• 复杂团队需要更多配置

插件中的 Subagent 安全

插件分发的 subagent 要特别注意权限、工具范围和边界条件。

架构

高层架构

主 agent、subagent、文件系统和工具权限共同构成执行链。

生命周期

1. 创建
2. 分配任务
3. 执行
4. 返回结果
5. 结束或恢复

上下文管理

关键点

• 子上下文尽量小
• 让每个 subagent 只负责自己的事
• 避免把所有信息都塞进去

性能考虑

过多的上下文会拖慢速度并降低准确性。

关键行为

subagent 在隔离上下文里工作，但仍能把结果汇总回主会话。

什么时候使用 Subagents

• 任务可拆分
• 需要隔离上下文
• 需要明确角色分工
• 需要并行协作

最佳实践

设计原则

• 单一职责
• 描述明确
• 工具权限最小化

System Prompt 最佳实践

• 任务说明要具体
• 不要写太长
• 只保留执行任务所需的信息

工具访问策略

• 审查型 subagent 只读
• 实现型 subagent 适度开放写权限
• 高风险动作要保持审批

本目录中的示例 Subagents

1. Code Reviewer

用于全面代码质量审查。

2. Test Engineer

用于测试策略、覆盖率和测试生成。

3. Documentation Writer

用于技术文档写作和更新。

4. Secure Reviewer

用于安全检查，通常只读。

5. Implementation Agent

用于功能实现和代码修改。

6. Debugger

用于定位 bug 和分析异常。

7. Data Scientist

用于分析数据、解释结果和生成报告。

8. Clean Code Reviewer

用于按 Clean Code 原则做专门审查。

安装说明

方法 1：使用 /agents

/agents

方法 2：复制到项目

mkdir -p .claude/agents
cp 04-subagents/*.md .claude/agents/

方法 3：复制到用户目录

mkdir -p ~/.claude/agents
cp 04-subagents/*.md ~/.claude/agents/

验证

• 运行 /agents
• 检查对应 agent 是否出现在列表中
• 试着让 Claude 委派一个简单任务

文件结构

.claude/agents/
├── clean-code-reviewer.md
├── code-reviewer.md
├── data-scientist.md
├── debugger.md
├── documentation-writer.md
├── implementation-agent.md
├── secure-reviewer.md
├── test-engineer.md
└── README.md

相关概念

• Skills 中文指南
• Memory 中文指南
• Hooks 中文指南
• Plugins 中文指南

---

输出格式

每个实现任务都要提供：

• Files Created: 新文件列表
• Files Modified: 已修改文件列表
• Tests Added: 测试文件路径
• Build Status: Pass/Fail
• Notes: 重要说明

实现检查清单

在标记完成前：

• [ ] 代码符合项目规范
• [ ] 所有测试通过
• [ ] 构建成功
• [ ] 没有 lint 错误
• [ ] 已处理边界情况
• [ ] 已实现错误处理

---

本站实战工作台

并行的前提是依赖图，不是空闲线程

先画任务依赖：文档说明和独立测试夹具可能同时进行；共享类型必须先确定，使用它的前后端才适合并行。若两项工作会改同一文件、同一数据库或同一部署槽位，就需要显式协调。

Worktree 提供独立现场

Git worktree 让一个仓库同时检出多个分支，每条施工队拥有独立工作目录。它隔离未提交文件，却仍共享 Git 对象和远程，不会自动隔离数据库、端口与依赖缓存。

git worktree add ../project-docs -b kimi/docs-course
git worktree add ../project-tests -b kimi/course-tests
git worktree list

创建前确认主工作区状态，目录名称清楚表达任务。每个 worktree 使用不同开发端口和测试数据库；不要让两条任务同时写同一生产资源。

设计两个真正独立的任务

任务 A 只改课程文档，验收是链接与 Markdown 检查；任务 B 只补现有接口的测试，验收是测试套件。它们都不修改接口实现。分别提交后，在主分支按依赖顺序合并，并在合并态重新跑全量检查。

再识别一个不该并行的任务：改变 API 响应字段同时修改其测试。若两边各自猜最终契约，会产生假失败和冲突。先用一个提交稳定契约，再拆消费者。

依赖与生成物会泄漏

node_modules 可能独立安装，也可能链接共享；Prisma Client、构建缓存和生成类型必须确认对应当前分支。不要因为另一个 worktree 已生成就认为本地状态正确。每条任务记录运行环境与生成命令。

合并不是复制文件

审查每个分支提交，使用正常 Git 合并或挑选，不从目录 A 手工复制到目录 B。合并后检查冲突语义，而不只解决标记。最后删除 worktree 前确保分支已提交并可恢复。

并行收益报告

记录理论串行时间、实际墙钟时间、协调时间和冲突数。只有总时间下降且证据质量不降，才算并行成功。Worktree 是隔离工具，不是让所有任务同时开始的理由。