第 15 章 | 角色分工——避免"全能 agent"陷阱

更新于 2026/5/10
💡 进群学习加 wx: agentupdate
(申请发送: agentupdate)

第 15 章：角色分工——避免"全能 agent"陷阱

学习目标

学会按职责拆 agent，让多个 agent 互相制衡而不是各自圈地。

全能 agent 的陷阱

如果你只配一个 agent，它会：

让我又写代码 → 又写测试 → 又审自己的代码 → 又验证

结果：
✗ 测试是为"让自己代码通过"写的
✗ 审查是"找自己看着顺眼的地方"
✗ 验证是"挑容易过的场景"

→ 跟人一样：自己监督自己 = 没监督。

doc2video 的 4 个核心角色

flowchart LR
    Dev["developer
实现 task"]
    Tester["tester
写单元/功能测试"]
    E2E["e2e-tester
黑盒端到端"]
    Rev["reviewer
对照 spec 评审"]

    Spec["📜 specs/"] -.读.-> Dev
    Spec -.读.-> Tester
    Spec -.读.-> E2E
    Spec -.读.-> Rev

    Dev -->|代码| Files["src/"]
    Tester -->|测试| TFiles["tests/"]
    Rev -.审.-> Files
    Rev -.审.-> TFiles
    E2E -.黑盒跑.-> Build["dist/"]

    style Dev fill:#bbdefb
    style Tester fill:#c8e6c9
    style E2E fill:#fff9c4
    style Rev fill:#f8bbd0

关键拆分原则

原则 为什么
dev 不写测试 自证陷阱——会写"刚好让自己代码通过的测试"
tester 不改 src 角色越界——测试该揭露问题，不该掩盖
reviewer 不写代码 写代码就有 ego，会偏袒自己的方案
e2e-tester 不读 src 黑盒视角——只看用户能看到的，避免被实现细节误导

写权限矩阵

              src/  tests/  specs/  design.md  review/  test-reports/  STUCK.md
developer      ✅     ❌      ❌       ❌         ❌          ❌            ❌
tester         ❌     ✅      ❌       ❌         ❌          ✅            ❌
e2e-tester     ❌     ❌      ❌       ❌         ❌          ❌            ❌
reviewer       ❌     ❌      ❌       ❌         ✅          ❌            ❌
architect      ❌     ❌      ❌       ❌         ❌          ❌            ✅
main Claude    ❌     ❌      ❌       ❌         ❌          ❌            ❌

→ main Claude 不写任何东西——它只是 dispatcher。

读权限：基本都能读

✅ 所有 agent 都能读 proposal / design / spec
✅ developer / tester / reviewer 都能读 src / tests
❌ e2e-tester 不读 src（黑盒视角硬约束）

角色与 OpenSpec 工件的对应

flowchart TB
    Tasks["tasks.md
(- [ ] 任务)"] -->|developer 勾选| Dev2["完成"]

    Spec["spec.md
(Scenario)"] -->|tester 翻译| TestFile["tests/test_group_N.py"]

    Diff["git diff
(developer + tester 改动)"] -->|reviewer 评审| Review["review/N.md"]

    Build["doc2video CLI"] -->|e2e-tester 黑盒| E2EReport["e2e-report.md"]

    Stuck["全员卡住"] -->|architect 诊断| StuckMD["STUCK.md"]

    style Dev2 fill:#bbdefb
    style TestFile fill:#c8e6c9
    style Review fill:#f8bbd0
    style E2EReport fill:#fff9c4
    style StuckMD fill:#e1bee7

→ 每个角色有专属"输出文件"——不重叠、不打架。

反模式

❌ 一个 agent 同时写代码和测试            自证
❌ reviewer 也能改 src                   独立性丧失
❌ 多个 agent 写同一份 review/N.md       状态混乱
❌ 角色定义太宽（"全栈 agent"）          没分工 = 没制衡
❌ 角色过细（每个文件夹一个 agent）       dispatch 成本爆炸

复杂项目的角色扩展

如果项目特殊，可以加：

场景 加的角色
安全敏感（金融/医疗） security-reviewer（独立扫漏洞）
文档/SDK 项目 doc-writer（同步更新文档）
重构密集 refactor-agent（专门重构）
数据迁移 migration-agent（专门 schema migration）

→ 但4 个核心角色是底线——少于这 4 个就不算"多 agent 制衡"。

你现在能做什么

  • 画出自己项目的角色权限矩阵
  • 解释每个"不能做"的硬约束的理由
  • 判断什么时候该加新角色

下一章把这些角色变成可被 dispatch 的 agent 文件。