多智能体使用指南

0. 结论先行#

先说这次协作的真实收益，避免把「多 Agent」讲成玄学：

一句话概括：多 Agent 的价值不是「多几个窗口」，而是让「产品判断 / 工程实现 / 风险质疑」三件事同时发生，而不是串行返工。

1. 为什么这次拆了三个角色#

一个助手同时处理多类问题时，需要留意下面三种情况：

而「TODO 追踪 CLI」恰好是一个横跨三类职责的需求：

• 产品判断：完成的任务还要不要默认显示？Markdown 笔记里的 TODO 要不要一起收录？
• 工程实现：怎么区分不同语言的注释？代码移动后，怎样认出原来的 TODO？扫描 5 万个文件能否达到 5 秒的性能目标？
• 风险质疑：直接用 rg 搜索不够用在哪里？索引会不会保存敏感代码？这个看板以后会不会没人维护？

这三类问题的正确答案来自互相矛盾的直觉——工程师想「全量诚实」，UX 想「首屏别劝退」，风险官想「先证明需求存在」。让一个 Agent 同时扮演三种角色，结果通常是「谁也没说服谁，然后悄悄选了一个」。

2. 角色设计：把通用四角色映射到这个需求#

通用模型是 FE / BE / TEST / RV 四类：

这次没有前后端，我按**「职责而非技术栈」**重新映射，这是最关键的一步：

禁止越界原则（四条，写进建队提示词里）：

• UX Agent 不得规定实现方案（只提约束与验收，比如「首屏 ≤10 条」而不是「用 SQLite 分页」）
• Architecture Agent 不得跳过验收直接宣称完成（性能预算写进验收标准，不是优化项）
• Devil’s Advocate 不得「顺手改设计」，只产出质疑与缓解方案
• Team Lead 不直接大改方案，只裁决与纠偏

Sub-agent 还是 Agent Teams？ 简单、独立、一次性任务用 Sub-agent（主 Agent 分派 → 子 Agent 返回）。 跨角色、需要持续协调、需要互相质疑的任务用 Agent Teams。 本次三者之间存在真实冲突（见 §5、§6），必须靠成员互通解决，所以选 Teams。

3. 开工前：开关、检查清单、建队#

1
codebuddy          # 打开 CLI

1
export CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=1

1
我正在设计一个帮助开发者追踪代码中 TODO 注释的 CLI 工具。
2
请创建一个团队从不同角度探索这个问题：
3
- 一个负责用户体验设计；
4
- 一个负责技术架构；
5
- 一个扮演"挑刺者"，专门提出质疑与风险。
6
请先完成团队创建并给出每位成员的职责分工与首轮任务。

1
pending -> in_progress -> completed
2
                 \-> blocked -> in_progress

4. Round 1：并行产出，各自为战#

1
[任务ID] ARCH-1
2
目标：给出技术选型、分层架构、数据模型与扫描流水线设计
3
边界：只写 docs/architecture.md，不改 UX 文档，不写实现代码
4
输入：需求一句话 + 设计约束（5 万文件 P95 < 5s、单二进制、零外网请求）
5
输出：架构文档（伪代码接口 + 表结构 + 性能预算 + 里程碑）
6
验收标准：三条核心取舍有明确取舍理由；性能预算写进验收标准而非优化项；
7
          每个失败模式都有降级路径
8
禁止项：替 UX 决定默认视图；把"待优化"当"已达标"

1
[任务ID] UX-1
2
目标：给出命令体系、输出格式、零配置上手路径与空态/错误态文案
3
边界：只写 docs/ux-design.md，不规定实现方案
4
输入：需求一句话 + 三类用户画像（独立开发者 / Tech Lead / CI Bot）
5
输出：设计文档（命令表 + 终端输出样例 + 五条设计原则）
6
验收标准：每条示例命令可直接复制；首屏 ≤10 行结论；空态与错误态有文案
7
禁止项：指定存储方案或解析算法；引入需要 init 的前置步骤

1
[任务ID] DA-1
2
目标：质疑需求前提、挑出致命风险、给出可验证的止损线
3
边界：只写 docs/risks.md，不顺手改设计
4
输入：需求一句话 + UX-1 / ARCH-1 的产出
5
输出：10 个尖锐问题 + 16 条代码级反例 + 风险总表 + 9 条止损信号
6
验收标准：每条质疑必须配缓解方案；每条止损信号必须有阈值与判定方式
7
禁止项：只提问题不给出路；用"可能有问题"这类不可验证的表述

1
## Round 1 汇总
2
- 完成：ARCH-1 选型 Go + SQLite + 语言感知状态机；UX-1 给出命令体系与三个画像；
3
        DA-1 给出 Q1~Q10 与 R-01~R-16
4
- 阻塞：无（三者输入不互相依赖，是本次能并行的唯一原因）
5
- 新增风险：DA-1 指出 Q10 —— 真正的瓶颈可能是"不想做"而不是"找不到"，
6
           若成立，整个产品定位要转向
7
- 需人工决策：默认视图全量 vs 活跃子集
8
- 下一轮：三者交叉评审，把质疑逐条落到设计修改

5. Round 2：冲突是价值，不是故障#

这一轮是整场协作收益最高的部分。冲突按「契约 → 规则 → 实现优先级」的顺序处理。

1
@Architecture Agent
2
你当前跑偏点：identity 设计把易变字段（context_hash、repo_id）放进了 fingerprint。
3
请仅做以下修改：
4
1) base_fp 收敛为 sha256(kind + normalized_text)，context_hash 降级为非身份属性；
5
2) repo_id 从 fingerprint 中移除（索引本就按仓库分库）；
6
3) 浅克隆（git rev-parse --is-shallow-repository = true）时硬失败富化，
7
   created_at 置 null，UI 显示 age: unknown，绝不显示错误 age；
8
4) 编码探测顺序改为：BOM 优先 → 严格 UTF-8 → latin1 兜底。
9
禁止修改：UX 文档、UX 的指纹需求（UX 会另行提"路径也不能进指纹"）。
10
输出：变更章节 + 每条修正的理由。

1
scan:
2
  blame: auto        # 检测 CI=1 时自动降级为 never
3
  blame_budget: 800ms

6. Round 3：唯一需要人类拍板的问题#

三轮讨论后仍需要人工决定的是：todo done <id> 之后，默认视图还显示它吗？

裁决判据是风险的不对称性：挫败感无法用提示消解，认知偏差可以。所以选隐藏，并补三条兜底：

1. 汇总行永远显示全貌：3 open · 2 closed（注释仍在源码）· 1 vanished
2. 首次 done 的回执必须写明「源码注释还在，去 todo ls --unsynced 看」
3. 给这个状态一个出口：--unsynced 视图，作为「v1 不写回源码」下唯一的收敛路径

裁决记录在架构文档 §6.1，并且连带改了里程碑——--unsynced 从「可选视图」升级为 M2 必过项。

这条要特别注意：这类问题不该由任何一个 Agent 单方面默认。架构负责人最初的选择是「默认显示」，如果没人挑战它，它会一路带进代码里，等到用户反馈「工具无视我的操作」时为时已晚。

同一轮里还定了一条产品价值观：不做任何形式的债务评分 / 健康度 / 团队排行榜。理由是可验证的：一旦出现单一标量，它必然被考核，被考核必然被操纵（删 TODO 而不是修 TODO）。统计改为只报双向流量，作者分组按平均 age 排序而不是条数。

7. 什么时候该降级#

三条触发条件，命中任意一条立即停止并行：

• 同类错误连续 2 轮未收敛
• 跨模块修改范围不可控
• 验证结果与改动结论冲突

降级指令模板：

1
进入降级模式：
2
1) 暂停所有并行任务；
3
2) 保留主任务 UX-1；
4
3) 将 ARCH-1、DA-1 转为串行；
5
4) 先修订 Speckit 中的冲突字段定义；
6
5) 修订后重新执行并输出差异报告。

本次没有触发降级，但第二轮一度接近：UX 在 v0.4 二次反馈中指出「指纹不含路径」带来两个新问题（同一指纹对应多处出现、改一个字等于换一条身份）。这类「修好一个 bug 引入另一个」的信号，就是降级的预警——幸好它附了缓解方案（用 context_hash 做编辑配对锚点、Crockford Base32 去形近字符），才没有真的停下来。

8. 红线与证据链#

1
# 隐私：证明零外网请求
2
mitmproxy 抓包，默认配置下外网请求数 = 0
3

4
# 性能：写进验收标准，不是优化项
5
5 万文件冷扫描 P95 < 5s（macOS/Linux）· < 8s（Windows）
6
二次扫描（无变更）< 0.3s
7

8
# 定位：证明不是 rg 别名
9
增量信息率 = 本工具独有字段数 / 总字段数
10
（age / owner / status / due / 引入 commit —— rg 一个都给不了）
11
止损线：增量信息率 < 30% 立即停手重定位

1
## 交付摘要
2
- 目标功能：
3
- 完成任务：
4
- 阻塞与解决：
5
- 风险处理：
6
- 验证结果：
7
- 可复用模板：

9. 团队协作指令速查#

口令固定四段式：目标 / 边界 / 验收标准 / 禁止项。

每轮固定产物五条：本轮目标 · 实际改动 · 验证结果 · 风险与阻塞 · 下一轮建议。

1
## Round N 汇总
2
- 完成：
3
- 阻塞：
4
- 新增风险：
5
- 需人工决策：
6
- 下一轮计划：

10. 小结#

三个可复制的经验：

1. 角色按职责切，不按技术栈切。 没有前后端的需求，照样能映射出 UX / 架构 / 挑刺者的三角。挑刺者这个角色在单 Agent 模式下几乎必然缺失——因为没人愿意质疑自己刚写得挺顺的方案。

2. 并行的前提是输入不互相依赖。 能让三个角色读同一份需求、写三份不同文档，才谈得上并行。一旦 UX 要等架构的存储方案，就直接串行，别硬撑。

3. 留裁决记录，而不是留结论。 三个月后没人记得「为什么默认视图是活跃子集」，但只要有裁决记录（双方判据 + 风险不对称性 + 三条兜底），后来者就能判断这个决定要不要推翻。

这次分工是否值得，最终还是要看它发现了哪些遗漏、减少了多少返工，以及协调本身花了多少时间。角色数量本身说明不了收益。