42atom/subagent

subagent skill

能力

教主脑如何把复杂任务拆给子代理执行臂，并在完成后自己验收结果。

这里的“子代理”指：

• codex
• claude-code

主脑负责：

• 判断是否适合委派
• 写清楚子任务卡
• 监控是否完成
• 验收真实产物
• 最后再向用户汇报

不要把子代理当成新的主脑。它只是执行臂。

何时使用

• 默认策略：只要任务明显超过“一步完成的小任务”，主脑就应先评估是否委派，而不是本能地自己下场。
• 用户明确说“交给 codex”“交给 claude-code”“让子代理去做”
• 任务本身更像一个完整的小项目，而不是一次简单工具调用
• 需要把主脑的上下文压力降下来，让外部执行臂独立完成一段工作

典型场景：

• “让你的子代理 codex 创建一个项目，写一个贪吃蛇 HTML 游戏，完成后告诉我”
• “把这个 review 拆给 claude-code 去做，完成后你再汇总给我”
• “让 codex 自己去改代码、跑测试、整理结果，你盯着它直到完成”

不适用

• 当前原生工具已经能直接完成的短任务
• 只是读一个文件、改一个小函数、跑一条命令
• 还没有正式 subagent 合同、也没有 tmux 执行臂可用时

不要为了“看起来高级”而强行委派。 也不要因为主脑自己“也能做”，就把本该委派的中大型任务重新揽回自己身上。

当前状态

msgcode 现在已有最小正式 subagent CLI 主链：

• msgcode subagent run codex --goal '...' --watch
• msgcode subagent run claude-code --goal '...' --watch
• msgcode subagent say <task-id> --message '...'
• msgcode subagent list
• msgcode subagent status <task-id>
• msgcode subagent stop <task-id>

这里要特别看清：

• subagent list = 列出当前 workspace 下已有的子代理任务
• 不是列出“可安装的执行臂”
• 不是列出“系统支持哪些 client”

注意：

• 当前是 CLI/runtime 主链已接线
• 原生 LLM tool 仍未独立接线
• 所以主脑应优先把它当成正式程序合同使用，而不是自己编造 bash 套壳

正式合同优先级

优先级固定如下：

1. 正式程序合同
   • canonical：
     • msgcode subagent run codex --goal '...' --watch
     • msgcode subagent run claude-code --goal '...' --watch
     • msgcode subagent say <task-id> --message '...'
     • msgcode subagent list
     • msgcode subagent status <task-id>
     • msgcode subagent stop <task-id>
2. 当前已接线的原生工具/命令
3. SKILL.md 说明书

说明：

• SKILL.md 负责教你怎么拆任务、怎么验收
• 不负责伪造一个并不存在的程序接口

先检查什么

1. 检查正式合同

先用 help_docs 查当前程序里是否已经存在 subagent：

• 看是否有 subagent run
• 看是否有 subagent say
• 看是否有 subagent list
• 看是否有 subagent status
• 看参数名是不是 --goal / --watch

其中：

• subagent say <task-id> 用来对正在运行的子代理继续补一句话
• 每次会落到 .msgcode/subagents/<taskId>.messages.ndjson
• subagent list 用来列当前 workspace 下已有任务
• subagent status <task-id> 用来继续观察某个任务
• 不要把 list 误读成“查看有哪些执行臂可安装/可用”

如果没有，就说明当前程序版本还没带上这条正式主链。

2. 检查子代理执行臂是否已安装

最低要求：

• codex --version 能运行
• claude --version 能运行（claude-code 在 tmux 执行臂层实际对应的是 claude CLI）

如果用户希望获得更强子代理能力，而当前机器没有这些执行臂，要直接提示：

• 安装或启用 Codex CLI
• 安装或启用 Claude CLI / Claude Code
• 再回来使用 subagent 主链

对 claude-code 的安装提示可以明确说：

• 若 claude 命令不存在或安装了错误包，按仓库当前 tmux 约定，应安装正确的 Claude Code CLI（例如：npm install -g @anthropic-ai/claude-code），并确保 PATH 中的命令名是 claude

对 codex：

• 先要求用户确保 codex --version 可用
• 若不可用，提示用户按本机标准方式安装 Codex CLI

委派前先做这四件事

1. 选择合适的 persona

Persona 是人格说明书，告诉子代理"怎么做"。

当前可用 persona（示例）：

• frontend-builder：前端实现、UI 打磨、交互细节
• code-reviewer：代码审查、问题发现、改进建议

硬约束：

• persona id 只能来自真实存在的 persona 文档
• 先看 docs/protocol/personas/ 里有没有，再决定用哪个
• 没有就明确说明当前不存在该 persona，必要时先问用户或回退到已存在的默认 persona
• 不要编造 frontend-dev、general-purpose 这类仓库里并不存在的 id
• 规划态如果还没核实 persona，就直接写“persona 未定，待核实 docs/protocol/personas/”或使用已确认存在的 id；不要先报一个猜测值

读取 persona 文档：

docs/protocol/personas/<persona-id>.md

当前正式 persona：

• frontend-builder
• code-reviewer
• api-builder

Persona 告诉子代理：

• 适用场景
• 工作流程
• 质量门槛
• 禁止动作
• 回传格式

当前要看清：

• msgcode subagent run ... 已正式接上 persona
• runtime 会从 docs/protocol/personas/<persona-id>.md 读取 persona 文档并注入子代理上下文
• task card 会和 persona 一起进入委派 prompt

2. 把任务缩成一个独立包

子代理应该拿到的是一个可独立完成的小任务，不是整段聊天历史。

3. 写清验收标准

必须告诉子代理：

• 要产出什么文件
• 文件放哪里
• 测试怎么跑
• 成功算什么

来源约束：

• 验收标准默认来自用户原话、任务文档、已有产物或正式协议
• 如果关键细节缺失，先问用户一个最高杠杆问题来收敛
• 不要自行发明尺寸、颜色、文案、布局等用户没说过的要求
• 如果仍未澄清，就把该项明确标成“未定/待确认”，不要先给一个想当然版本
• 在“先不要执行、只讨论怎么派/怎么验收”的规划态，不要把前一轮自己编的草稿继续当成已确认需求

4. 给唯一 token

每次委派都带唯一 token，方便后续监控、grep 日志、回收结果。

子任务卡模板

把任务按下面结构交给子代理：

goal:
  用一句话描述最终目标

context:
  只给完成任务必须知道的背景

cwd:
  明确工作目录

constraints:
  约束、禁区、风格要求、是否允许联网

acceptance:
  至少 2-4 条可验证验收条件

artifacts:
  预期产物路径

token:
  本轮唯一 token

监控原则

主脑必须自己盯结果，不要只转述子代理的话。

至少要做这些检查：

1. 看任务是否仍在运行
2. 若需要继续补要求，用 msgcode subagent say <task-id> --message '...'
3. 若忘了 taskId，先用 msgcode subagent list
4. 看输出里是否出现唯一 token
5. 看产物文件是否真实存在
6. 必要时再自己读产物、跑测试、做抽查

subagent list 的正确用途是：

• 找回当前 workspace 里的 taskId
• 看有哪些任务仍在 running / completed / failed / stopped

不是：

• 枚举支持哪些 client
• 枚举安装说明

不要只因为子代理说“完成了”，就向用户宣布完成。

回收结果时的要求

向用户汇报前，至少要回收这些信息：

• 项目/产物路径
• 是否通过自测
• 还有没有未完成项
• 用户下一步该怎么验证

用户要的是结果，不是 tmux 噪音。

自然语言 BDD 示例

用户说：

让你的子代理 codex 创建一个项目，写一个可直接打开运行的贪吃蛇 HTML 游戏，完成后告诉我项目路径和启动方式。

主脑应该这样理解：

1. 这是完整编码任务，适合委派
2. 先检查正式 subagent 合同是否存在
3. 再确认 codex 执行臂已可用
4. 写子任务卡，至少包含：
   • goal: 创建贪吃蛇 HTML 游戏
   • cwd: 指定工作目录
   • acceptance:
     • 项目目录存在
     • index.html 存在
     • 用户可直接打开运行
   • artifacts: 项目目录、关键文件路径
   • token: 唯一标识
5. 持续监控，不是发完就不管
6. 主脑自己核验 index.html 和项目目录是否存在
7. 最后再告诉用户“已完成 + 路径 + 打开方式”

禁止事项

• 不要在程序没有正式 subagent 合同时，假装已经把任务派出去了
• 不要把“切到 /backend tmux 整体透传”伪装成“已完成主脑对子代理的正式委派”
• 不要只转述子代理文本，不看真实产物
• 不要把整个聊天上下文原封不动丢给子代理
• 不要忘记唯一 token

一句话原则

主脑负责决策、监控、验收；子代理负责执行。

程序合同优先，skill 只负责教你怎么把这件事做对。