Agent Conductor 🎼
You conduct. Agents perform.
Route all implementation work — file changes, scripts, data processing — to coding sub-agents. The orchestrating session stays lean: it plans, decides, and validates. Agents do the execution.
Supported Agents
Agent-agnostic. Set your invoke command once:
| Agent | Invoke Command |
|---|
| Claude Code | INLINECODE0 |
| OpenAI Codex |
codex '<task>' |
| Cursor Agent |
cursor-agent '<task>' |
| Gemini Code |
gemini-code '<task>' |
| Any other |
your-agent-cmd '<task>' |
Use AGENT_CMD as a placeholder in the examples below.
When to Dispatch
Dispatch when the task involves any of:
- - Writing or modifying files (even one line)
- Running scripts or processing data
- Execution time > 10 seconds
- Batch operations over multiple items
If it produces file changes → dispatch it.
Dispatch Template
CODEBLOCK0
Execution Mechanism
| Duration | Mechanism |
|---|
| < 5 min | Foreground: INLINECODE6 |
| 5–30 min |
Background:
exec pty:true background:true timeout:1800 command:"AGENT_CMD '...'" |
| > 30 min | Agent writes script → run in
screen /
tmux |
Use pty:true if your platform requires it (needed for Claude Code; check other agents' docs).
Task Decomposition
Split large projects by stage, not by feature. Each stage must be independently verifiable.
Split when any of these apply:
- - Runtime > 30 minutes
- More than one script needed
- Batch > 100 items
- Output of one step feeds the next
CODEBLOCK1
See references/patterns.md for parallel coordination, checkpoint/resume, and domain examples.
Acceptance Checklist
After any "done" signal, always verify:
- 1. File exists — confirm output path
- Count correct — expected N vs. actual N records
- Non-empty — spot-check 2–3 outputs
- No silent errors — check error fields and null rates
A completion signal ≠ acceptance. Run the checklist.
Error Handling
| Symptom | Action |
|---|
| Timeout, no output | Check process log → kill and re-dispatch with more context |
| File missing after "done" |
Read execution log → add context → re-dispatch |
| Partial completion | Check
progress.json → resume from checkpoint |
| Fails twice in a row | Stop re-dispatching → debug in orchestrator session |
What NOT to Dispatch
- - Simple reads → use read tools directly
- Orchestrator config changes → orchestrator session only
- Messages/notifications → use messaging tools directly
- Design decisions → orchestrator decides first, agent implements
Agent Conductor 🎼
你指挥,智能体执行。
将所有实现工作——文件变更、脚本运行、数据处理——路由给编码子智能体。编排会话保持精简:它负责规划、决策和验证。智能体负责执行。
支持的智能体
与智能体无关。只需设置一次调用命令:
| 智能体 | 调用命令 |
|---|
| Claude Code | claude <任务> |
| OpenAI Codex |
codex <任务> |
| Cursor Agent | cursor-agent <任务> |
| Gemini Code | gemini-code <任务> |
| 其他 | your-agent-cmd <任务> |
在以下示例中使用 AGENT_CMD 作为占位符。
何时分派
当任务涉及任何以下情况时进行分派:
- - 写入或修改文件(即使只有一行)
- 运行脚本或处理数据
- 执行时间 > 10 秒
- 对多个项目进行批量操作
如果会产生文件变更 → 就分派。
分派模板
任务:[名称]
需求
[一句话:要生成什么以及在哪里生成]
上下文
- - 项目:[名称和用途]
- 相关文件:[路径]
- 数据格式:[输入/输出的简要描述]
验收标准
- - [ ] 输出文件存在于 [路径]
- [ ] 包含 [N] 条记录 / 通过 [特定检查]
- [ ] [错误字段/日志] 中无错误
注意事项
环境
- - 语言/运行时:[python3 / node / go / 等]
- 工作目录:[路径]
- 特殊配置:[代理、认证、环境变量(如需要)]
完成后,通过以下方式通知:
[你的完成通知命令]
执行机制
| 时长 | 机制 |
|---|
| < 5 分钟 | 前台:exec pty:true command:AGENTCMD ... |
| 5–30 分钟 |
后台:exec pty:true background:true timeout:1800 command:AGENTCMD ... |
| > 30 分钟 | 智能体编写脚本 → 在 screen / tmux 中运行 |
如果你的平台需要,请使用 pty:true(Claude Code 需要;请查看其他智能体的文档)。
任务分解
按阶段而非功能拆分大型项目。每个阶段必须可独立验证。
当以下任一情况适用时进行拆分:
- - 运行时间 > 30 分钟
- 需要多个脚本
- 批次 > 100 个项目
- 一个步骤的输出作为下一步的输入
阶段 1:准备数据 → clean_data.csv (< 2 分钟)
阶段 2:处理 → results.json (需要阶段 1)
阶段 3:报告 → report.md (需要阶段 2)
有关并行协调、检查点/恢复和领域示例,请参见 references/patterns.md。
验收检查清单
在任何完成信号后,始终验证:
- 1. 文件存在 — 确认输出路径
- 数量正确 — 预期 N 条记录 vs. 实际 N 条记录
- 非空 — 抽查 2–3 个输出
- 无静默错误 — 检查错误字段和空值率
完成信号 ≠ 验收。执行检查清单。
错误处理
| 症状 | 操作 |
|---|
| 超时,无输出 | 检查进程日志 → 终止并重新分派,提供更多上下文 |
| 完成后文件缺失 |
读取执行日志 → 添加上下文 → 重新分派 |
| 部分完成 | 检查 progress.json → 从检查点恢复 |
| 连续失败两次 | 停止重新分派 → 在编排器会话中调试 |
不要分派的内容
- - 简单读取 → 直接使用读取工具
- 编排器配置变更 → 仅在编排器会话中进行
- 消息/通知 → 直接使用消息工具
- 设计决策 → 编排器先决策,智能体再实现