让 Agent 帮你编排

这条路径是什么

装了 CodeDAG Guide 插件的 Claude Code 或 Codex 知道怎样使用 cdg。你用自然语言说清要做成什么，它来拆分任务、写工作流文件、校验并提交，然后在执行期间跟踪进度，结束后向你汇报。这时替你操作 cdg 的这个 Agent 称为编排 Agent；工作流里的每个任务仍由一个全新的会话执行，那个会话称为任务 Agent。更多角色分工见谁负责什么。

和手写相比，变化的只是由谁来写文件、由谁来运行命令。工作流文件照样放在主仓库的 .codedag/dags/ 下，字段、命令和状态都与手写时一样。你可以在它提交之前打开文件审阅、修改，也可以随时自己运行 cdg 命令查看或干预。不过，已提交的工作流按提交时的定义执行，之后再改文件，影响不到这一次运行。

前提

这条路径的前提是 CodeDAG 已经可用，你的 Claude Code 或 Codex 装有 CodeDAG Guide 插件，并且使用的是插件装好之后打开的会话。

• 已完成安装与登录。
• Claude Code 的完全授权警告已经接受过。这台电脑上从没跑过完全授权的 Claude Code 任务时，要先做一次：在终端里运行 claude --permission-mode bypassPermissions，选 “Yes, I accept” 后退出，以后都不会再问。漏做也可以事后补上，任务会搁置下来等你接受，处理办法见提前接受 Claude Code 的完全授权警告。
• 插件已安装。在这个仓库里运行 cdg init 时选择过安装插件，或者以 User 范围装过（在哪个仓库里装的都算），这一步就已完成；否则运行 cdg plugin install --scope user，为本机装有的 Claude Code 和 Codex 安装插件，对你所有的仓库生效。
• 会话是在插件装好之后打开的。插件只在新会话中生效，已经开着的会话要先退出，再用 claude --resume 或 codex resume 恢复。

拿不准时，在这个仓库里运行 cdg plugin status 确认：对应 Agent 下的 Plugin installed 与 Enabled 都为 true，说明插件已装好并处于启用状态；显示未安装时，输出里的 Action 一行会给出补装命令。安装范围与更新方式见管理 CodeDAG Guide 插件。

一段可以直接粘贴的提示词

在要处理的仓库根目录新开一个 Claude Code 或 Codex 会话，贴入下面这段提示词。它要做的事与第二个工作流教程相同：先找出两个待办，再由两个任务分别实现。

用 CodeDAG 帮我完成下面这件事。先把工作流文件写好给我看，我确认之后再提交。

目标：在这个项目里找出两个最快能完成的待办，把它们各自实现，每一项都先写最小的测试，再实现到测试通过。待办要按我的角色和负责范围来筛选，可以来自代码里的 TODO、FIXME 注释，文档里的待办清单，被跳过的测试，也可以来自你能访问的 issue 跟踪工具，比如 GitHub Issues、Linear、Jira。找不到合适的待办时，根据这个项目的产品定位和现状，以及我的职责，提出两个小改动来代替。

拆分：由你决定。我的设想是先用一个任务挑出这两项，把每一项的目标、涉及的文件和完成标准写进 docs/plans/agent-todos.md；再用两个任务各实现其中一项，同时进行。

授权：所有任务都用完全授权，让它们无人值守地跑完。运行中如果某个任务仍然弹出审批，先把审批内容告诉我，不要替我同意。

审核：挑选待办的任务完成后停下来，等我看过计划再继续；其余任务完成后自动接受。

工作区：项目里登记过的工作区都可以用；只有主仓库时，就让任务依次执行。以主仓库当前的提交为起点。提交前确认这些工作区没有未提交的改动，有的话告诉我，不要替我提交或丢弃。

汇报：全部结束后，告诉我每个任务做了什么、结果在哪个分支、测试是否通过，以及需要我注意的地方。合入主分支由我自己来。

提示词第一句点明用 CodeDAG 来做，并要求它提交前先给你过目。点明 CodeDAG 这一点不能省：不点明的话，Agent 很可能直接在当前会话里动手改代码，而不是写成工作流。后面六项各有分工：目标写成可以检验的结果；拆分可以完全交给它，给出你的设想能少来回几轮；汇报写明结束时你想知道什么；授权、审核和工作区三项划定这次运行的边界，是它提交之前需要知道的，含义见提交前要和它确认的三件事。换成你自己的目标时，保留这个结构，改写内容即可。

提交前要和它确认的三件事

授权、工作区和人工审核，分别决定这次运行能做什么、在哪里做、在哪里停下。第一次使用时，只有授权需要你拿主意，另外两项不提就按默认值执行。

• 授权。 完全授权下，任务 Agent 操作之前不再征求同意，工作流可以无人值守地跑完；中等授权下，任务遇到要审批的操作会停下来，等你应答，或者由编排 Agent 在你约定的范围内代为应答。你没有说明用哪一档时，它会先问你再提交。两档的取舍见决定无人值守还是有人值守。
• 工作区。 默认情况下，项目里登记过的工作区都会参与执行，主仓库也在其中，工作流从主仓库当前的提交开始。如果运行期间，你在主仓库里还有其他开发任务，让它把主仓库排除在 CodeDAG 工作区外，见想在工作流运行时同时手动开发。
• 人工审核。 默认每个任务完成后自动接受，工作流不会中途停下。想先看过某个任务的结果再继续，就在提示词里点名这个任务，见审核门禁与自动接受。

它会做什么

从拿到提示词到汇报结果，编排 Agent 按 CodeDAG Guide 规定的默认做法推进；你另有要求时，它以你的要求为准。

1. 检查准备情况。 它先确认项目是否已经初始化、有哪些工作区可用。项目还没初始化时，它会替你运行 cdg init。
2. 写工作流，交给你审阅。 它把目标拆成任务，写成 .codedag/dags/ 下的一个工作流文件，按你的要求先给你过目。你可以直接打开文件核对，读法见编写工作流文件。
3. 校验并提交。 它先运行 cdg dag validate，有错误就修正，有警告就先弄清原因，然后运行 cdg dag submit；你要求先审阅时，它会等你确认再提交。
4. 跟踪执行。 提交后的头几分钟，它会频繁查看状态和日志，确认任务都已正常启动；稳定之后放慢到每 5 到 10 分钟看一次，因为查得再勤也不会让任务更快，只会占用它自己会话的上下文。某个任务长时间没有新输出，不一定是卡住了：任务 Agent 可能派出了子 Agent 在后台工作，所以它通常要等十分钟以上毫无动静，才会介入查看。
5. 应答执行中的操作审批。 审批针对的是任务执行途中的某一步操作：任务 Agent 要做一件所用授权档没有放行的事，比如运行一条命令，就会停下来等人批准。这时编排 Agent 会在 tmux 里运行 cdg task view 进入这个任务的会话，读出屏幕上的审批内容：在约定范围内，它代你应答，然后退出会话，让任务继续执行；超出范围，它把审批内容转述给你，等你决定。它执行命令的环境通常没有可交互的终端，所以这一步需要本机装有 tmux；没有 tmux 时，审批只能由你自己进入会话应答，做法见想应答一个审批。
6. 推进完成后的结果审核。 审核针对的是任务做完之后的整份结果：结果要先被接受，才会交给下游任务。任务完成后停下等审核时（你设了人工审核，或者任务没有产生任何改动而被拦下），编排 Agent 先查看这个任务的日志和改动，再按约定推进：接受结果，让任务 Agent 在现有结果上接着改，或者把决定交给你。
7. 汇报结果。 工作流结束后，它告诉你每个任务做了什么、改动在哪个分支。默认的隔离分支模式下，所有任务的结果都合并在集成分支 cdg/<工作流名>/integration 上，每个任务还有各自的任务分支，主分支保持不变。如果它选用了共享工作区模式，就没有这些分支，结果直接留在工作目录里。

跟踪只在这个会话开着时进行。关掉会话不影响工作流，它会在后台照常执行，只是没人替你盯着了；你随时可以自己运行 cdg status 查看进度，也可以新开一个会话，让它接着跟进。

长时间运行时，任务 Agent 可能撞上 Claude Code 或 Codex 自身的用量限制，例如 5 小时窗口。这时任务会在中途停下，编排 Agent 会先停掉其余受影响的任务；等限额重置后，它让停下的任务在原来的会话里接着做，这一步不再消耗 CodeDAG 额度。完整的处理步骤见Agent 用量限额或速率限制。

它不会替你做的事

编排 Agent 替你省去的是写文件、敲命令和盯进度，安全边界和最终结论仍然由你掌握。

• 不替你划定安全边界。 用哪一档授权、任务里的审批由谁应答，由你决定，它只执行你定下的方案。
• 不在约定之外同意审批。 超出约定范围的审批，以及删除、覆盖这类破坏性操作，它都会先问你。
• 不合入主分支，也不推送远程。 结果只留在本地仓库里，CodeDAG 本身也不会向你的远程仓库推送或从中拉取。检查与合入的做法见收口、合入主分支与清理；你明确要求时，它也可以替你运行这些 Git 命令。
• 不替你判断目标是否达成。 工作流结束只说明每个任务都执行完、并按规则被接受了，而默认的自动接受并不检查结果对不对。它汇报每个任务做了什么、哪里需要注意，代码能否合入，由你检查之后决定。

这些边界来自 CodeDAG Guide 的指引和你们之间的约定，并不是程序强制的限制。编排 Agent 自己运行命令时，只受你这个会话本身的权限设置约束；想让某些操作（例如推送远程）必须经过你同意，要靠这些设置来保证。

下一步

• 管理 CodeDAG Guide 插件：选择安装范围、更新插件，以及定制编排行为时怎样不改动插件自带的技能文件。
• 选择 Agent、模型与权限模式：为每个任务定授权档之前，先了解完全授权与中等授权各自的代价。