Agent 三层分工模型：协调者 / 执行者 / Coding Agent¶
概述¶
在多 Agent 协作的工作流中，我们采用三层分工模型来最大化效率、最小化心智负担。每一层有明确的职责边界，互不越界。
主人（决策者）
↕ 实时沟通
协调者（小墨）
↓ 派发任务
执行者（Subagent）
↓ 调度工具
Coding Agent（Cursor / Codex / Claude Code）
↓ 写代码
代码仓库
三层角色¶
🎯 协调者（Coordinator）¶
代表： 小墨（主 Agent）
职责： - 和主人实时沟通，理解需求 - 把控方向，做架构决策 - 拆分任务，派发给执行者 - 验证结果，汇报进展 - 管理上下文空间，不被细节消耗
不做： - ❌ 写代码、改文件 - ❌ Debug 具体问题 - ❌ 直接操作 Coding Agent
核心原则： 协调者的上下文空间是最宝贵的资源。一旦开始写代码，上下文就会被实现细节淹没，无法继续做沟通和决策。
⚙️ 执行者（Executor）¶
代表： Subagent
职责： - 理解协调者派发的任务 - 拆分为具体的 Coding Agent 调用 - 调度 Coding Agent 执行代码修改 - 验证修改结果（跑测试、grep 检查） - 如果出错，把报错扔给 Coding Agent 修复 - 向协调者汇报结果
不做： - ❌ 和主人直接沟通 - ❌ 做架构决策 - ❌ 自己手写代码
工作流：
🔨 Coding Agent¶
代表： Cursor Agent CLI / Codex / Claude Code
职责： - 接收自然语言 prompt - 在代码仓库中执行修改 - 读文件、写文件、运行命令
特点： - 有完整的代码上下文（整个仓库） - 擅长大范围重构和模式匹配 - 但不理解业务方向，需要精确的 prompt
为什么要三层？¶
上下文隔离¶
| 层级 | 上下文内容 | 大小 |
|---|---|---|
| 协调者 | 用户意图、架构方向、进展状态 | 小（保持精简） |
| 执行者 | 具体任务、文件结构、错误信息 | 中（任务级别） |
| Coding Agent | 完整代码库、AST、类型系统 | 大（仓库级别） |
如果协调者直接写代码，它的上下文会被代码细节占满，就无法再和主人有效沟通。
错误恢复¶
- Coding Agent 出错 → 执行者把报错扔回去，让它修
- 执行者方向偏了 → 协调者 steer 或 kill，重新派发
- 协调者理解错了 → 主人纠正，协调者调整方向
每一层只处理自己能处理的错误，不越级。
实践配置¶
Cursor Agent CLI 调用模板¶
export CURSOR_API_KEY=$(grep CURSOR_API_KEY ~/.bashrc | cut -d= -f2)
cd <repo>
agent -p --trust --force --output-format text "<prompt>"
参数说明：
- -p (print mode)：非交互，适合脚本调用
- --trust：信任工作目录
- --force：允许修改文件（不加则只建议不执行）
- --output-format text：纯文本输出
Subagent 派发模板¶
协调者派发任务时，prompt 应包含：
- 角色声明：你是 XX 的执行者，不自己写代码，通过 Cursor 执行
- 环境信息：仓库路径、Cursor 命令格式、超时设置
- 任务描述：要做什么、为什么、约束条件
- 验证标准：怎样算完成（测试通过、无悬空引用等）
- Git 操作：commit message 格式
TDD 验收模式¶
用 TDD 方式验证实现是否正确：
- 让 Cursor 写验收测试（覆盖所有设计点）
- 运行测试
- 全绿 = 实现正确
- 红色 = 让 Cursor 修复实现 → 再跑
这种方式特别适合 AI 编码——强制每一步都有验证，防止"写了一堆代码但没验证"的问题。
反模式¶
| 反模式 | 为什么不好 | 正确做法 |
|---|---|---|
| 协调者自己写代码 | 上下文被细节淹没 | 派 subagent |
| 执行者手写代码不用 Cursor | 质量不稳定，浪费 token | 让 Cursor 做 |
| 一个 subagent 任务太大 | 超时风险，错误难定位 | 拆分成多个小任务 |
| 协调者轮询 subagent 状态 | 浪费 token 和时间 | 用 sessions_yield 等完成通知 |
| Coding Agent 做架构决策 | 它不理解业务上下文 | 协调者做决策，Cursor 只执行 |
总结¶
保持每一层的纯粹性，是高效协作的关键。