前言

上周我花了两天时间，把团队的开发流程从"一个人对着 AI 聊天"升级成了"5 个 Agent 同时开工"。不是标题党，是真的折腾完了，想把踩过的坑和拿到的结果写下来。

起因是看到一篇文章——Designing a team of agents，作者是 Nicolas Frankel，Jetbrains 的技术布道师。他用 Claude Code 的实验性功能 Agent Teams，让多个 Agent 并行处理一个任务。

我读完最大的感受是：这个方向是对的，但文档太少了，坑太多。于是我决定自己动手，边踩坑边记录。

先搞清楚：在哪个 level？

Nicolas 那篇文章引用了一个框架——The 8 Levels of Agentic Engineering。这个框架把 AI 辅助编程分成了 8 个层级：

大多数团队目前在 Level 3-4：用好上下文、用 MCP 连接工具。但 Agent Teams 已经是 Level 8 的东西了，它代表的是"你不再是直接写代码的人，而是管 Agent 的人"。

Nicolas 提了几个数字：Anthropic 用 16 个并行 Agent 从零构建了一个能编译 Linux 的 C 编译器。Cursor 跑了上百个并发 Agent，花了几周时间，从零构建了一个 Web 浏览器，并把自己的代码库从 Solid 迁移到了 React。

我的目标没那么宏大——我只是想把一个中等复杂度的功能（合并两个 CSV 层级结构、跨两个代码仓库），交给 Agent 团队来处理。

Agent Teams 是什么？

Claude Code 的 Agent Teams（目前是实验性功能）允许你在一个项目中定义多个 Agent 实例，它们共享代码库，但各自有独立的上下文窗口，可以互相通信。

开启方式很简单，在 settings.json 里加一行：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

然后，你需要在 .claude/agents/ 目录下创建 Agent 定义文件。

Agent 文件怎么写

每个 Agent 是一个 Markdown 文件，用 frontmatter 定义元数据：

---
name: planner
description: "负责需求分析和任务拆解"
model: sonnet
tools: Read, Glob, Grep, WebSearch
---

Agent 的 body 部分写的是它的指令（instructions），也就是它的角色定义。

Nicolas 最初的方案里有 5 个 Agent：

• planner：规划任务
• challenger：质疑方案的合理性（有点像代码审查）
• coder：写代码
• tester：写测试
• documenter：写文档

他提到了一篇研究说"3-5 个 Agent 是最优团队规模"，所以把 documenter 砍了。我后来也砍掉了 challenger，因为在我的场景里它的沟通成本太高。

团队架构：Agent 之间怎么通信

这是最关键的部分。多个 Agent 如果只是各自干各自的，那就不是团队，是乌合之众。

Claude Code Agent Teams 的通信机制是这样的：

每个 Agent 有一个状态（state），Agent 之间通过消息传递来更新状态。

Nicolas 画了一张图，我用自己的语言描述一下：

[需求输入]
     ↓
[Planner] → 分析需求，输出任务列表
     ↓
[Coder]   → 接收任务，开始实现
     ↓
[Tester]  → 接收代码，运行测试
     ↓
[结果汇总]

但实际上更复杂。每个 Agent 在执行过程中会输出中间结果，这些结果会成为其他 Agent 的输入。比如 Tester 发现了一个测试失败，它会通知 Coder 重新实现。

这不是流水线，是网状通信。

在 Claude Code 里，这种通信是通过 Skill 文件来定义的。Skill 文件描述的是"当触发某个技能时，哪些 Agent 要参与，它们各自的职责是什么"。

我的实际配置

折腾了两天之后，我的最终配置是 3 个 Agent：

1. planner

---
name: planner
description: "分析需求，拆解任务，输出可执行的任务列表"
model: sonnet
tools: Read, Glob, Grep
---

planner 的职责是拿到需求后，先理解代码库结构，然后把需求拆成具体的子任务。每个子任务有前置条件（blocked by）和依赖关系。

2. coder

---
name: coder
description: "实现具体功能，遵守代码规范，处理 PR"
model: sonnet
tools: Read, Glob, Grep, Bash, Write, Edit, WebSearch
---

coder 是主力，负责具体实现。我给它开了 Bash 权限，可以执行命令。

3. tester

---
name: tester
description: "编写测试，验证功能，报告问题"
model: haiku
tools: Read, Glob, Grep, Bash
---

注意 tester 用的是 Haiku——最便宜的模型。测试逻辑不复杂，不需要 Sonnet 的推理能力。

autonomia vs 安全性：最大的坑

如果你以为配置好 Agent 就能跑起来了，那你想多了。

最大的问题是：autonomy 和 security 之间的权衡。

在普通 Claude Code 对话里，Claude 每次要执行危险命令都会问你确认。一对一的时候还好。但在 Agent Teams 里，每个 Agent 都会频繁请求权限，加起来可能是普通对话的 10 倍。

你会被权限提示淹没。

Nicolas 提到了三种解法：

解法 1：预设权限

在 settings.json 里预设一些高频权限：

{
  "permissions": {
    "allow": [
      "Bash:git *",
      "Bash:npm test",
      "Bash:npm run build",
      "Read:./src/**",
      "Write:./src/**"
    ]
  }
}

这招管用，但需要提前知道 Agent 会执行哪些命令。调试阶段你根本不知道它会干嘛。

解法 2：--dangerously-skip-permissions

加了这个 flag，Agent 执行命令不再询问。但这是真正的"危险模式"——它可以执行任意命令，包括删除文件、重写代码。

我建议永远不要在生产环境用这个。调试的时候可以试试。

解法 3：Auto Mode

Anthropic 最近推出了 Claude Code Auto Mode，可以理解为"半自动模式"——Agent 在执行前会显示计划，用户确认后才执行，同时允许连续自动运行。

目前还在灰度阶段，不是所有账号都能用。

实际跑起来的体验

我用一个具体的任务测试：把两个仓库里的 CSV 合并逻辑统一，需要 planner 拆任务、coder 实现、tester 写测试。

整个过程是这样的：

4 tasks (0 done, 4 open)
 ◻ Approve plan › blocked by #3
 ◻ Implement merged CSV hierarchy changes › blocked by #1
 ◻ Plan: materialize merged CSVs with new hierarchy across both repos
 ◻ Write tests for merged CSV changes › blocked by #2

planner 先输出了任务计划，然后等待 approve。coder 拿到任务开始实现，同时 tester 在准备测试用例。

平均耗时：一个中等复杂度的功能（涉及两个仓库的代码修改），从需求输入到测试通过，大约 45 分钟。纯人工的话，同样的任务我需要 2-3 小时。

节省的时间：主要是重复性代码的生成和测试用例编写。planner 的任务拆解也有价值——它会分析代码库的依赖关系，拆出来的任务比我手动拆更无遗漏。

什么场景适合 Agent Teams

值得用的场景：
- 跨多个文件的重构
- 需要写测试的增量功能
- 两个有关联仓库的同步修改
- 文档和代码需要保持一致

不值得用的场景：
- 单文件修改（普通对话就够了）
- 需要频繁查看业务上下文的任务（Agent 的上下文窗口有限）
- 探索性开发（你还不知道要做什么的时候）

现在的局限性

Agent Teams 还是实验性的，我有几点担忧：

1. 调试困难：当任务失败时，我很难判断是哪个 Agent 的问题。日志不够详细。
2. 上下文窗口竞争：多个 Agent 共享同一个项目的上下文，如果某个 Agent 消耗了大量上下文，其他 Agent 的质量会下降。
3. 不可复现：同样的任务，跑两次结果可能不一样。有些是因为随机性，有些是因为 Agent 之间的消息时序不确定。

总结

Agent Teams 是 AI 编程的下一个台阶，但不是银弹。

它最核心的价值是把"任务规划 + 实现 + 测试"这个流程自动化了，让你从执行者变成管理者。但它对权限管理、团队设计、任务定义都有不低的要求。

如果你已经用熟了 MCP、用熟了 Claude Code 的子 Agent，工作流已经比较稳定了，可以试试 Agent Teams——它会把你从具体的代码细节里再往外拔一步。

如果你还是新手，先把基础打好：一个 Agent 用好，远比五个 Agent 乱飞要强。

延伸阅读

• The 8 Levels of Agentic Engineering
• Designing a team of agents（Nicolas Frankel，Jetbrains）
• Claude Code Agent Teams 官方文档
• Claude Code Auto Mode