概述
Runbook 把一个工作目标分解成一个可操控的自主循环,然后驱动它运行。整个过程分为两个阶段:Seed(播种)阶段负责开展对齐对话,并写入承载意图的持久化状态;Execute(执行)阶段把当前会话变成编排器,依据这些状态驱动循环。
两种模式共用同一技能,在做任何事之前必须先完成路由。
路由规则
路由是分层的:优先应用显式信号;只有在没有显式信号触发时,才回退到“产物是否存在”这一判断依据。
显式信号:出现“execute mode against a directory”“run/continue/resume the runbook”等表述时进入 Execute 模式;出现“create a runbook”“set up an autonomous loop”“start a hardening pass”等表述时进入 Seed 模式。
无显式信号时:目标目录中存在 FOCUS.md 则进入 Execute,缺失则进入 Seed。
目标目录是用户指定的目录;若用户未指定,则为当前工作目录。
两条例外守卫会覆盖上述规则:若产物已存在但用户要求重新设计运行手册,需在覆盖任何内容前进行确认,不得静默覆盖既有状态;若用户要求执行但没有任何产物,则无可运行内容,应改为提供播种模式。
上下文加载
仅在当前阶段需要时加载引用文件,每个阶段只加载自己的文件。对齐阶段加载 references/alignment-guide.md;门禁检查加载 references/checklist.md;播种加载 references/seeding-guide.md;执行加载 references/execution-guide.md。
阶段一:对齐
加载 references/alignment-guide.md 并遵循其协议。
对齐对话会浮现七个要素:
- What(做什么)——待完成的工作,拆解到可套用单一镜头的粒度
- Why(为什么)——动机,用于让发现环节排定优先级
- Lens(镜头)——循环寻找或构建的目标(功能需求、风格合规、设计改进、安全、性能、迁移目标)
- Authority(依据)——循环参考的权威来源(PRD、设计规范、风格指南、问题追踪器、架构文档)
- Scope(范围)——纳入与排除的目录、文件或区域
- Success(成功)——具体而言“完成”是什么样子
- Mode(模式)——紧循环(默认)或递归分解(需显式选择)
对齐对话还会浮现行为排除项(no-gos)与风险,作为范围与分解讨论的一部分。它们不是独立要素,而是从探查范围边界与隐藏风险中自然产生的。
可使用内联可视化、范围图和 AskUserQuestion 进行结构化选择,把模糊意图拆解为具体、可测试的目标。
紧循环与递归分解:多数工作是紧循环——一个镜头、一个范围,反复打磨直至收敛,这是默认方式。递归分解需显式选择,适用于存在可从不同镜头处理的独立子问题的工作;选择后,父 FOCUS.md 会播种子 FOCUS.md 文件,每个子文件范围更窄,子级通过 LEARNINGS.md 向上汇报结果,父级进行汇总。仅当问题结构确实需要时才提议递归模式。
退出条件按顺序应用三条:
- 收敛检测——察觉到问题不再产生新约束时,明确说明这一观察。
- 清单门禁——加载 references/checklist.md,验证每个门禁,向用户呈现通过/未通过。
- 显式批准——在播种前暂停并请求确认;未经用户“go”绝不播种。
阶段二:播种
加载 references/seeding-guide.md。
进入计划模式前,向用户询问两件事:产物(FOCUS.md、TASKS.md、LEARNINGS.md)的目标目录;执行路线——有人值守或无人值守。有人值守指调用会话连续运行轮次,以每轮紧凑摘要作为操控点;无人值守指一个精简的定时存根启动全新会话,仅运行一轮后停止,由文件在各轮之间承载全部状态。
进入计划模式,按 references/seeding-guide.md 中的结构写计划文件。计划只写三个持久化产物,不写循环提示词。计划文件包含:Context(为何存在此循环——动机与预期结果);FOCUS.md → path(完整的 FOCUS.md,所有章节均已填充,含 Route: 行);TASKS.md → path(空的任务板骨架);LEARNINGS.md → path(空的结构化记忆);Execution & Deployment(一次性接线:所选路线,若为无人值守则含调度目标)。
退出计划模式供用户审阅。对齐对话中没有任何内容以对话残留的形式留在计划里;计划读起来应像是一个已经了解需求的人写的。
执行模式
前提:目标目录中恰好有一个 FOCUS.md。带有 ## Children 表格的父 FOCUS.md 是协调文档而非可运行的循环——应列出其子项并询问要运行哪一个。
加载 references/execution-guide.md 并遵循其协议。编排器从不直接实现;所有实现、发现和产生副作用的工作都委托给子代理。如果环境无法委托给子代理,应停止并告知用户,绝不退回到自己实现。
从 FOCUS.md 的 Route: 行读取路线;若该行缺失,则按有人值守处理。保持每轮开销低廉:每轮只重新读取 TASKS.md 和 LEARNINGS.md 的 Summary 章节。
规则
播种规则:
- 对齐是对话,不是表单。应探索、反思,让用户纠正,不要一开始就用清单盘问。
- 未经显式批准绝不播种。清单门禁是必要但不充分的,用户确认是硬性停止点。
- 对话内容是短暂的。阶段一中的解释、图表与 AskUserQuestion 交互不出现在计划文件中,计划应能独立成立。
- 默认使用紧循环。仅当子问题明显独立时才提议递归分解。
- LEARNINGS.md 为只追加。循环写入,用户读取,绝不覆盖或删除条目。
- 范围应放在 FOCUS.md 中,而非机制中。把具体细节保留在镜头文件里,而非执行协议中。
- 抵制增加机制。若某件事可以在 FOCUS.md 中写成一行,就不要把它做成协议里的一个功能,应放进 FOCUS.md。
执行规则:
- 编排器从不实现。把所有实现、发现和产生副作用的工作委托给子代理。
- 状态存在于文件中,而非对话里。每轮都重新读取 FOCUS.md、TASKS.md 和 LEARNINGS 摘要;重启后可干净地恢复。
- 每轮一个任务。任务解决后,本轮结束。
- 失败即回退。把失败的任务连同备注退回 Open,绝不在同一轮中修复它。
- 路线决定驱动方式。无人值守只运行一轮后停止;有人值守连续运行,以每轮摘要作为操控点。
附加资源
参考文件:
- references/alignment-guide.md——阶段一的对话协议:分解技巧、提问模式、可视化方法
- references/checklist.md——在播种前验证对齐完整性的结构化门禁
- references/seeding-guide.md——FOCUS.md、TASKS.md、LEARNINGS.md 的产物模板与产出说明
- references/execution-guide.md——执行模式协议:轮次生命周期、委托简报、放置框架和收敛