Agent Team & TDD superpowers

4195 字
21 分钟
Agent Team & TDD superpowers
2026-05-16
2026-05-21
教程
无标签

最近写了个 Claude Code 插件 agent-team，把我这段时间踩过的多 agent 协作坑总结成两个 skill，配合 superpowers 的 TDD 工作流可以跑长程开发任务。本文介绍它的设计动机和用法

Fomalhaut647
/
plugins
Waiting for api.github.com...
00K
0K
0K
Waiting...

平台支持#

目前只有 Claude Code 原生支持 Agent Team（TeamCreate / SendMessage 这一套 primitive），所以 agent-team 这个 skill 本身只能在 Claude Code 里用。Codex、Cursor、Cline 等编程工具的用户暂时跑不了多 agent 长程协作

但本仓库 references/ 目录下的 TDD + 两阶段 review 工作流文档对所有编程 agent 都有借鉴价值——这套流程在 Claude Code 之外仍然成立，只是协调层得换成”开多个会话窗口手动复制粘贴”。其他工具的用户可以读 superpowers-implementer.md 和 code-review.md，把里面”用 SendMessage 通知 reviewer”之类的句子改成自家工具的等价物，剩下的 TDD 节奏和 spec compliance + code quality 两阶段 review 思路是通用的

为什么需要 Agent Team#

最大的优点不是”能并行”，而是 分配上下文，让长程任务保持稳定

单 Agent 的瓶颈：上下文挤爆，指令跟随能力下降#

让一个 agent 直接 inline 写代码会发生什么？它的 context 会被具体的工作细节填满——读了一堆代码、跑了一堆测试、看了一堆 error、回滚了几次。当 context 长到几十 k token，agent 对最初指令的跟随能力会显著下降：忘记用户立下的规矩，不再严格走 TDD（跳过 RED 阶段直接写实现）、忘了 commit 粒度约定、忘了某些路径不能动

这是写大工程时最常见的失败模式：开头很守规矩，到 70% 进度时已经在自由发挥

superpowers 的第一层抽象：subagent-driven-development#

superpowers:subagent-driven-development 的解法是：让 controller agent 别自己写代码，派 subagent 写。controller 给 subagent 一份 brief，subagent 在干净 context 里实现 + commit + 返回结果，controller 读结果决定下一步。具体的代码细节（哪行报错、哪个测试 fail）只留在 subagent 的 context 里，controller 始终保持小组长视角

这样 controller 的 context 增长慢得多，指令跟随能力维持得更久。同样，code review 也派 subagent 做——还得用两阶段：spec compliance reviewer 看是否符合 plan，code quality reviewer 看代码本身健康度，互相抓不同的 bug

subagent-driven-development 的天花板#

但这套模式还是有上限：

  1. 一个 controller 只能管一个模块的构建——前端 + 后端两个模块的工作量，单 controller 的 context 仍然会挤爆
  2. review 不能由 implementer 同一个 agent 做（防作弊）。理论上 review 整个开发分支的 reviewer 应该是独立 agent
  3. 于是用户被迫自己开多个 Claude Code 会话手动协调：
    • 一个窗口跑 implementer，一个窗口跑 reviewer
    • 把 reviewer 的反馈复制粘贴给 implementer
    • 或者让 reviewer 在 PR 上评论，然后切回 implementer 窗口让它去拉评论
    • 手动管理实现前端的 branch 和实现后端的 branch
    • 用户一直在多个窗口间切换、复制信息

这时用户自己变成了协调者——这正是上下文挤爆问题的人类版本：用户的注意力被低级的”把 A 窗口的字粘到 B 窗口”消耗，没精力做高层决策

agent team 的第二层抽象#

agent-team 在 controller + subagents 之上再加一层抽象：team lead 协调多个 teammate，每个 teammate 都是 controller 级

  • team lead 制定整个 plan，把任务分给不同的 teammate（一个写前端、一个写后端、一个审前端 PR、一个审后端 PR）
  • 每个 teammate 在自己的 worktree 里跑完整的 subagent-driven-development 循环
  • teammate 之间通过 SendMessage 直接对话，不再需要人类用户转发
  • team lead 监督 teammate 是否在正确时机激活该激活的 skill、是否严格走 TDD

人类用户从协调者位置上摘下，只需要：

  • 向 team lead 提需求、讨论细节
  • 仔细阅读设计文档，粗略阅读实现文档
  • 完成程序难以完成的测试（比如在 web app 里点点点）并反馈给 team lead

人类不再需要逐行看代码，也不再需要在多窗口间复制粘贴

由于 team lead 不深入开发和审查细节，它的 context 用量很小，整个长程任务里指令跟随能力一直保持高水平——这就是”分配上下文”的核心价值

设计哲学#

投顾比喻#

如果说：

  • Claude Code 的底层工具（Read / Write / Bash / Agent / TeamCreate …）是 股票——直接、原始、灵活，但你得自己懂市场
  • superpowers 这种独立 skill（TDD / debugging / writing-plans）是 基金——把一类通用能力打包成 best practice，你买入就能用
  • agent-team 这种建立在其他 skill 之上、协调其他 skill 的 skill 是 投顾——它不直接产生 alpha，而是告诉你”什么场景该买哪只基金、什么场景该直接买股票”

投顾的价值不在于推荐的某只基金多牛，而在于资产配置和择时：lead 决定何时调 superpowers:brainstorming、何时让 teammate 调 subagent-driven-development、何时让 reviewer 调 code-review:code-review

不重复提示词#

投顾的另一面是克制：它不应该把基金的招股说明书再抄一遍。这是 agent-team 的核心约束：

  • 能通过 ToolSearch 查到的 Tool Description（TeamCreate / SendMessage 的具体参数和用法），不出现在 SKILL.md 或 references 里
  • superpowers 系列 skill 已经写了的内容（TDD 怎么走、subagent-driven-development 模式），不出现在 references 里
  • references 里写过的内容（superpowers workflow 的步骤映射），不出现在 SKILL.md 里

每段提示词只存在于唯一一个地方。重复 = 漂移源：当 TeamCreate 的描述更新了而你的 SKILL.md 抄了一份旧版本，下一次 coordination 就出 bug。所以 SKILL.md 反复用 “the descriptions returned are the authoritative reference”，强制 agent 去查 live schema 而不是读 skill 里的转述

两个 subskill 的拆分#

为什么不合成一个 skill？因为 lead 和 teammate 的 “first action” 和 ongoing protocol 几乎不重叠：

  • lead 关心：TeamCreate 调用、spawn prompt 模板、什么时候 shutdown、git cleanup 顺序
  • teammate 关心：inbox sync 协议、dispatch 上限、什么时候该 SendMessage、怎么报告 DONE

混在一起每个角色要读 500+ 行的”和我无关”的内容。拆开后 lead 不需要知道 inbox sync 细节（那是 teammate 自己的事），teammate 不需要知道 TeamCreate 怎么调（lead 派完才轮到 teammate 活）

superpowers workflow 作为 reference doc 而非第三个 skill#

obra/superpowers 提供了一套 TDD 驱动的开发工作流：brainstorming → writing-plans → TDD implementer → reviewer → PR fix loop → merge。这套流程和 multi-agent team 正交——你可以用 team 跑非开发任务（research、文档梳理），也可以用 superpowers 但不开 team

所以接入方式不是写成第三个 skill，而是放在每个 skill 的 references/ 目录下：

  • lead/references/superpowers-workflow.md：lead 怎么把 superpowers 步骤映射到 team lifecycle
  • teammate/references/superpowers-implementer.md：implementer teammate 怎么走 TDD + 两阶段 review
  • teammate/references/code-review.md：reviewer teammate 怎么用 code-review:code-review 跟 implementer 反复迭代

reference doc 不占常驻 context，需要时 lead 在 Step 3 决定要不要 Read，spawn prompt 告诉新 teammate 去 Read 对应那份。plain team coordination 和 full superpowers workflow 复用同一套底层 primitive

最重要的一段：inbox sync 协议#

TeamCreate 描述里有句话：“Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.” 这句话只在 turn 边界成立。单个 turn 内，你的 worldview 是冻结的，即便 peer 几毫秒前刚写了消息进你的 inbox

rendezvous failure

A 和 B 约好在 X 见面。A 朝 X 走。B 中途反悔，发消息说改到 Y。A 不查 inbox 继续走到 X，到了之后才发”我到 X 了”，然后才读 inbox，发现要去 Y。A 改道去 Y。同时 B 收到”我到 X 了”反悔回 X，发”那回 X”。循环下去两人永远差一步

修复方法：每个 step 完成后、每次主动 SendMessage 前，都 Read 一次 inbox。如果非空就停掉这一 turn，让 framework 在下一 turn 注入并清空 inbox。Read 是用来 check 的，不是用来 act 的——如果 inline 处理 inbox 而不停 turn，那条消息下一 turn 会被 framework 再次注入，处理两遍

hub-and-spoke 是 framework 硬限制#

Claude Code 的 agent team 是扁平的：teammate 不能 Agent(team_name=..., name=...) spawn 别的 teammate，也不能调 TeamCreate / TeamDelete。所有 team membership 都由 lead 管

实际后果：

  • teammate 觉得工作量大，应该 SendMessage lead 求人，而不是自己尝试 spawn
  • 整个 team 的 dispatch 深度上限是 lead → teammate → subagent，再深被 framework 拒
  • 工作流设计时不要假设 teammate 能调 teammate

安装#

两步装好：

Terminal window
/plugin marketplace add Fomalhaut647/plugins
/plugin install agent-team@fomalhaut647-plugins

@ 前的 agent-team 是 plugin name，@ 后的 fomalhaut647-plugins 是 marketplace name

怎么用#

模式一：纯协作（无 superpowers）#

让 Claude Code 调用 Skill('agent-team:lead')，它会引导你跑完整 lifecycle。spawn prompt 里只需让新 teammate 第一动作调 Skill('agent-team:teammate')，剩下协议由那个 skill 接管。适合 research、文档梳理之类不涉及 spec/plan/PR 的任务

模式二：完整 superpowers workflow#

从 Skill('agent-team:lead') 进，让 lead 在 Step 3 Read superpowers-workflow.md。spawn prompt 里告诉每个 teammate 也 Read 对应那份 reference doc

lead 视角#

docs/ layout 约定

长周期、跨多 session 推进的项目下推荐用一套标准 docs/ 目录：vision.md（永恒愿景）/ overview.md（当前版本地图）/ specs/<module>.md（按功能模块切分）/ plans/PlanN-<teammate>.md（每 session × 每 teammate 一份独立 plan）/ progress/PlanN-<teammate>.md（与 plan 1:1 对应的交付报告）/ archive/（冻结历史）。下面 lead 步骤里出现的路径都来自这套约定，不采用时把它当作”随 brief 说的位置”即可

  1. 在 main 分支调 superpowers:brainstorming 跟用户对齐方案，结果覆盖 docs/specs/<module>.md（brainstorm 产物必须存活在 main 历史里，每个 worktree 后续都对照它）
  2. 仍在 main 分支调 superpowers:writing-plans，每个 teammate 一份独立的 docs/plans/PlanN-<teammate>.md——不写共享 PlanN.md overview（cross-cutting context：session scope、为何这样切分、teammate 间依赖，全部写进 lead 的 spawn prompt 而不入 doc）。plan 里显式标注哪些任务能并行（决定要派几个 implementer teammate）
  3. 调 superpowers:using-git-worktrees，按 plan 的并行切分串行创建 worktree（EnterWorktree → ExitWorktree(action="keep") 循环，因为单会话只能 active 一个 worktree）
  4. TeamCreate + TaskCreate，一条消息里并行 spawn 所有 implementer teammate（多条消息会串行）
  5. 监控 SendMessage，等 implementer 发来 PR URL
  6. 每收到一个 PR URL，spawn 一个 reviewer-pr-<N> teammate（无 worktree，code-review:code-review 操作 PR diff 经 gh）
  7. 监控 implementer ↔ reviewer 之间的 fix loop，不干预除非卡住
  8. 全部 **APPROVED** 后，先向用户报告状态、要 shutdown approval，再单独要 merge approval（不要捆绑）
  9. 并行 shutdown_request → 等所有 shutdown_response 回来
  10. 对每个 implementer：EnterWorktree(name=...) + ExitWorktree(action="remove") 清 worktree，然后 gh pr merge 合 PR
  11. 验证每个 docs/progress/PlanN-<teammate>.md 已落在 main（implementer 在自己 PR 里写的，merge 完应该都在）。少了就 placeholder 一段或问用户怎么处理——这些文件是项目对 “实际发生了什么” 的永久记录
  12. TeamDelete()

implementer teammate 视角#

被 spawn 后第一动作：

  1. Skill('agent-team:teammate')——加载 team primitive 协议（inbox sync / dispatch 上限）
  2. Read references/superpowers-implementer.md——加载 implementer 角色工作流
  3. 立刻 TaskCreate 把整个 session 要做的事建成 task list——在 EnterWorktree / Read docs / 派任何 subagent 之前。每个 Task A/B/C… 都拆成”implementer subagent dispatch”+“spec reviewer dispatch”+“code-quality reviewer dispatch”三条，最后再补 wrap-up + PR + fix loop 各一条。理由：implementer 经验上最常见的失败模式是”做完一件忘了下一件”——漏激活 skill / 漏读 prompt 模板 / 漏派 reviewer subagent / PR 开完忘记 fix loop。Task list up-front 让每个 skill 激活、reference 读取、subagent dispatch 都被显式承认 + 完成后被 mark off，比仰赖记忆稳健得多

然后 startup：

  1. 先调两个 superpowers skill：subagent-driven-development / dispatching-parallel-agents——在第一个任务开始之前就把”orchestrate don’t code”的纪律设上，防止工作压力一来就退回直接写代码。using-superpowers 由 hook 自动注入，不需要显式 invoke
  2. EnterWorktree(path="...") 进 lead 预创建的 worktree
  3. 读 overview / vision（若存在）/ 自己 module 的 spec / 自己那份 docs/plans/PlanN-<your-name>.md——你只读自己的 plan，其他 teammate 的 plan 路径不进你的 context

每个任务的工作循环：

  1. 派 implementer subagent：dispatch prompt 必须显式列出该激活的 skill 和触发条件（superpowers:test-driven-development 在起手、systematic-debugging 在遇 bug、verification-before-completion 在报 DONE 前），并要求 subagent 在 DONE 报告里列出激活了哪些 skill。不能写”use TDD”这种含糊指令，subagent 会伪服从（跳过 RED 阶段、编造验证报告）
  2. 派 spec-compliance reviewer subagent 用 superpowers:requesting-code-review
  3. 派 code-quality reviewer subagent——两阶段 review 抓不同抽象层
  4. 收 reviewer 反馈走 superpowers:receiving-code-review 五步流程（read → understand → verify → evaluate → respond），不凭直觉判断 false positive
  5. 修复 → 重派 reviewer，直到两个 reviewer 都通过
  6. TaskUpdate(status="completed") → 读 inbox check → 继续下一任务

所有任务做完：

  1. superpowers:finishing-a-development-branch 选 Option 2 (Push and Create PR)
  2. 创建自己的 docs/progress/PlanN-<your-name>.md——和 plan 文件 1:1 对应，写你 module 实际发生了什么：实现了什么、哪里偏离 spec/plan、跳过了什么及为何、未解决 concern、follow-up 建议。每 teammate 独立文件，所以并行 PR 永远不会在这条路径冲突
  3. commit-commands:commit-push-pr 处理 commit + push + 开 PR（progress 文件作为同一 PR 的一部分一起 commit）
  4. SendMessage lead 报 PR URL（先做 before-SendMessage 的 inbox check）
  5. 不要 ExitWorktree(action="remove")——lead 在 Step 10 自己清，你保留 worktree on disk 等着（实际上 teammate 不是 worktree 的创建者，本来就清不掉）

收到 reviewer “go pull review” 消息后：

  1. gh api repos/{owner}/{repo}/pulls/{N}/comments 拉完整 review thread
  2. superpowers:receiving-code-review 评估每条
  3. 派 subagent 修复（先 systematic-debugging 调查，再 implementer 改，再两阶段 review 自审）
  4. git push → SendMessage reviewer 求重审
  5. reviewer 回 **Changes requested** → 循环；**APPROVED** → SendMessage lead 报最终状态后 idle

reviewer teammate 视角#

被 spawn 后：

  1. Skill('agent-team:teammate')
  2. Read references/code-review.md
  3. 不 EnterWorktree——你不需要（code-review:code-review 通过 gh 操作 PR diff，不需要本地 checkout）
  4. Skill('code-review:code-review')——只调一次。这是个知识型 skill，激活后内部 pipeline（5 并行 reviewer subagent + Haiku confidence-score 过滤）操作步骤已驻在 context 里，后续每轮 review 直接按它的方法跑，不重复 invoke

每轮 review 循环：

  1. 跑 review pipeline（startup 已激活的 code-review:code-review）。派 subagent 时要在 prompt 里点名 PR head sha——subagent 默认 Read 拿的是 main checkout 的文件，不指就会审错版本（用 gh pr view <PR#> --json headRefOid -q .headRefOid 拿 sha，配合 gh pr diff / git show pr-<PR#>:<path> 等命令对齐 PR head）
  2. gh pr comment <PR#> 把结论贴回 PR，首行必须是 **APPROVED** 或 **Changes requested**（implementer 解析首行判断 verdict）
  3. SendMessage implementer 通知”已发 review”（before-SendMessage inbox check 先做）
  4. idle 等 implementer 推 fix 来求重审，loop 回 1
  5. **APPROVED** 后 SendMessage lead 报最终状态，idle 等 shutdown
为什么用 gh pr comment 而不是 gh pr review --approve？

GitHub 禁止 PR author 给自己 PR --approve。在单人开发 setup 里 reviewer 和 implementer 共用同一个 host gh 身份，会被算成”PR author”——所以 gh pr comment 加首行约定是 workaround

实战须知#

它仍然是实验性 feature，需要人工盯着#

抽象层级越往上堆，“转述”导致的指令漂移风险越大：lead 把纪律转述给 teammate，teammate 又转述给 subagent，每一层都有可能丢约束。哪怕 plugin 已经反复用 “the descriptions returned are the authoritative reference” 把转述压到最低，多 agent 协调本质上依然不稳定

实操时人类要盯着 teammate 是否在按约定走——尤其 session 刚开始那几步。经验是：teammate 前几步走对了（按 task list 推进、显式调该激活的 skill、有派 reviewer subagent），后续大概率会持续遵循；前几步偷懒了，剩下整个 session 一路漂移到面目全非的概率不低。不要 spawn 完就走开，盯到 teammate 跑过第一个 implementer + reviewer 周期、确认纪律真的设上了再放手

不要在文档和提示词里加时间限制#

不要在 plan、spec、spawn prompt、dispatch prompt 里写”XX 分钟内完成”、“先做最重要的 N 个”、“快速 review 一下”这类时间或优先级限制。AI 严重高估任务用时（在它眼里复杂工作可能只是几秒钟的 tool call），一旦感到”时间紧”就会优先跳过 review 这种非生产性步骤——伪服从地报 DONE 但实际跳过了 verification、跳过了 spec compliance check、跳过了 receiving-code-review 的五步流程

纪律本身没有时间成本上的浪费（review 不通过反而省时间），但 AI 不会自己做这个权衡。让纪律无条件成立，不给它任何借口跳过

什么时候用 team#

满足以下任一条件再考虑：

  • 工作跨多 turn（你会把控制交还用户再回来继续）
  • 两个以上角色要在共享代码库上并行推进
  • implementer 和 reviewer 要跑多轮 fix loop

如果只是一次性的并行 read / draft / analyze，用 superpowers:dispatching-parallel-agents 的 plain subagent fan-out 就够了，不要为了用 team 而用 team——协调有 overhead

后记#

这个 plugin 还在持续迭代，每次跑完真实的 multi-agent 任务都会回来调一些 wording。skill 里的每句话都来自一次具体的 coordination failure，所以 CLAUDE.md 里专门写了一条：“不要根据 ‘theoretically’ 的猜测改 skill”——动 wording 前必须跑一次真实 session 验证新版本不退化

仓库：https://github.com/Fomalhaut647/plugins/tree/main/plugins/agent-team，欢迎试用、提 issue

文章分享

如果这篇文章对你有帮助，欢迎分享给更多人！

Agent Team & TDD superpowers
https://fomalhaut647.com/posts/agent-team/
作者
Fomalhaut
发布于
2026-05-16
许可协议
CC BY-NC-SA 4.0
Skill Simplifier
挑战宿舍最佳实践
相关文章 智能推荐
1
Skill Simplifier
教程 给 Skill 和 CLAUDE.md 去重的审计 skill
2
为什么 AI 时代更应该使用双拼
教程 让中文输入跟上和 AI 协作的思考速度
3
程序员键盘的最佳实践
教程 全世界打字速度不变而我提高 1000 倍
4
为什么 Mac 比 Windows 优越
教程 Linux 是工作, Mac 是生活, Windows 是游戏
5
校园网自救手册
教程 解决 90% 软件导致的网络问题
随机文章 随机推荐

评论区

分享你的想法，与大家交流讨论

Profile Image of the Author
Fomalhaut
Hi, I'm Fomalhaut~
公告
寒舍装修中
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
32
分类
4
标签
0
总字数
45,684
运行时长
0 天
最后活动
0 天前
© 2026 Fomalhaut. All Rights Reserved. / RSS / Sitemap
Powered by Astro & Firefly

目录