build-loop-engineering

name

build-loop-engineering

description

Interview users in at most 10 adaptive rounds and create a minimal, document-first Loop Engineering control system for a recurring goal, including bounded single-round or multi-round execution and an explicit round-to-round handoff interface. Use when a user wants to clarify core requirements, design an Agent loop, prevent long-running goal drift, govern autonomous optimization and memory updates, define human approval boundaries, or establish controlled continuous iteration. Generate Markdown control documents by default; do not create runtime code, APIs, schedulers, or live automations unless the user separately requests an implementation phase.

Build Loop Engineering

目标

通过最多 10 轮渐进式提问，把用户模糊的持续目标转化为一套可审核、可持续优化的 Loop Engineering 文档系统。需求提前收敛时立即结束，不为凑满轮数继续提问。

默认只设计文档控制面，不写运行程序。把工作分成三份契约：

1. 目的契约：为什么做、为谁做、完成标准、非目标、不可漂移项，以及系统长期希望优化和记住什么。这里只定义意图，不授予自动改写核心规则的权限。
2. 运行契约：一轮如何触发、执行、验证、停止和交接；需要多轮时，上一轮如何通过标准接口启动下一轮，以及整个周期如何结束。
3. 进化契约：哪些内容和记忆可自动更新，哪些只能形成候选提案，如何评估、批准、晋升、失效和回滚。

先锁定目的契约，再讨论 Agent、工具、API 或自动化。

提问规则

• 每轮只问 1–3 个会改变架构的问题。
• 初始访谈最多 10 轮；每轮标明 第 N/10 轮、当前契约和本轮要解决的决策。
• 优先询问会阻塞目的、权限、防漂移或进化边界的最高价值未决项，不平均分配轮数。
• 复用用户已经说过的内容，不重复索取答案。
• 使用用户的业务语言，不要求用户理解状态机、幂等性或编排器等术语。
• 用户不确定时，给出 2–3 个具体选项、推荐项和影响。
• 每组问题后，分别汇总 已确认、推断、默认值 和 未决项。
• 答案矛盾时先指出矛盾，不用猜测填平。
• 核心需求未确认前，不生成完整文档，不进入实现阶段。
• 到第 10 轮仍有阻塞项时，输出需求缺口清单并停止；只有用户明确同意，才能延长访谈。

将“访谈轮次”和“执行回合”分开计数。最多 10 轮只约束前期需求访谈；生成后的 Loop 可以包含多个执行回合，但必须受周期轮数、预算、继续门和停止条件约束。

满足以下条件时可提前结束访谈：北极星目标可验收，运行闭环完整，漂移信号可观察，自动更新边界明确，权限、停止和回滚责任均有归属。

提问流程

1. 锁定目的契约

优先问：

1. 如果这个 Loop 只能持续完成一件事，那件事是什么？
2. 它为谁服务，解决什么重复发生的问题？
3. 每一轮必须产生什么可观察产物，什么结果才算真正完成？
4. 哪些事情明确不做，哪些原则、用户或结果不得在长期运行中改变？
5. 谁拥有修改核心目标、成功标准和权限边界的最终决定权？
6. 系统希望长期自动改进什么、记住什么？哪些内容不得进入长期记忆？

把答案压缩成一句北极星目标，并列出成功标准、非目标、不可变约束、自主优化目标和记忆意图。不要用“提升质量”“持续优化”等无法验收的表述。自主优化和记忆只记录目标；具体写入权限在进化契约中定义。

2. 定义运行契约

根据目的继续问：

• 一轮由什么事件开始，以什么状态结束？
• 输入来自哪里，哪些是可复核事实，哪些只是线索或推断？
• 一轮最少需要哪些阶段？每个阶段的输入、动作、产物和退出条件是什么？
• 谁执行、谁验证、谁批准？同一个 Agent 是否可以同时执行和宣布验收通过？
• 哪些动作可以自动完成，哪些必须先由人确认，哪些始终禁止？
• 这是单轮任务、固定轮数、满足条件前持续运行，还是长期周期循环？
• 一轮完成后必须向下一轮交接哪些状态、证据、剩余问题和预算？谁或什么条件有权启动下一轮？
• 单轮完成和整个周期完成分别如何判断？
• 一轮和一个周期的时间、费用、调用、Agent、并发和重试上限分别是多少？
• 失败、无新增结果、证据不足、预算耗尽或连续偏离时如何停止和恢复？

只添加完成目标所需的阶段。不要因为工具可用就增加 Agent、数据源或流程层级。

2.1 定义单轮与多轮接口

先选择最小可用循环模式：

模式	适用情况	结束方式
单轮	一次执行即可验证目标	本轮验收后结束
固定轮数	明确需要 N 次处理、实验或迭代	达到 N 轮或提前命中停止条件
条件循环	需要持续缩小缺口直至成功或失败	命中周期完成条件或停止条件
长期周期	需要持续运营、研究或维护	每个周期仍有轮数、时间和预算上限；周期边界复审后再开启下一周期

禁止没有上限的永久循环。长期周期必须由多个有边界、可审核、可恢复的小周期组成。

当目标需要两轮以上时，在 LOOP.md 中定义以下状态流：

CYCLE_READY → ROUND_READY → ROUND_RUNNING → ROUND_VERIFYING → ROUND_COMPLETE
ROUND_COMPLETE → NEXT_ROUND_READY | CYCLE_REVIEW | STOPPED
NEXT_ROUND_READY → ROUND_RUNNING ...
→ CYCLE_REVIEW → CYCLE_COMPLETE | NEXT_CYCLE_READY | STOPPED
NEXT_CYCLE_READY → CYCLE_READY

每一轮结束时生成一个 ROUND_HANDOFF，作为下一轮唯一有效入口。至少包含：

handoff_id: <交接 ID>
previous_handoff_ref: <首轮留空；后续轮引用上一轮交接>
cycle_id: <周期 ID>
round_id: <本轮 ID>
round_status: <ROUND_COMPLETE、CYCLE_REVIEW 或 STOPPED>
purpose_version: <目的契约版本与哈希>
goal_links: [<本轮对应的目标或成功标准>]
round_objective: <本轮具体目标>
input_refs: [<输入、证据和上一轮交接引用>]
outputs: [<本轮产物引用>]
validation: <通过、失败、证据不足或等待审批>
facts: [<已验证事实>]
inferences: [<仍需验证的推断>]
remaining_gaps: [<尚未完成的缺口>]
budget_remaining: <剩余时间、费用、调用和轮数>
drift_check: <L0、L1 或 L2 及依据>
approval_state: <有效审批和下一步权限>
allowed_next_actions: [<下一轮被允许执行的动作>]
next_round_trigger: <启动下一轮所需事件或条件>
next_round_objective: <只针对剩余缺口的下一轮目标>
next_state: <NEXT_ROUND_READY、CYCLE_REVIEW、CYCLE_COMPLETE 或 STOPPED>
stop_reason: <继续时留空；停止时必填>
checkpoint_ref: <恢复所需检查点>

只有同时满足以下条件，才能从 ROUND_COMPLETE 进入 NEXT_ROUND_READY：本轮验证已记录；下一轮目标仍关联获批目的；审批继续有效；预算和轮数未耗尽；没有人工 Gate、L2 漂移或强制停止条件。缺少任一项时停在 CYCLE_REVIEW 或 STOPPED。

下一轮只继承已验证事实、获批产物、剩余缺口、预算和权限引用。不得把未验证推断升级为事实，也不得用新的局部发现重写周期目标。恢复中断任务时，先核对最近有效 ROUND_HANDOFF、目的哈希、审批和工作区版本，再决定是否继续。

3. 定义防漂移机制

重点问：

• 运行多久后最容易偏离？常见偏离表现是什么？
• 用哪些可观察信号判断“仍在解决原问题”？
• 每个新任务必须关联哪一条目标或成功标准？
• 什么变化属于正常执行，什么变化已经构成范围变更？
• 检测到偏离时，是立即停止、回到检查点，还是提交人工复审？

将防漂移规则写成可执行检查，而不是提醒 Agent“保持专注”。

4. 定义进化契约

重点问：

• 每轮结束后收集哪些反馈：验收结果、失败、用户纠正、成本、速度还是外部效果？
• 哪些字段允许自动更新，允许范围是什么？
• 哪些运行事实可以自动进入日志或记忆候选？哪些内容可以晋升为正式长期记忆？
• 哪些变化只能生成候选提案，不能直接生效？
• 如何用冻结评估集、基线和护栏指标在草稿或隔离环境中验证更新？
• 谁批准正式晋升？失败时回滚到哪个版本？
• 记忆如何去重、设置适用范围、记录反例，并在过期或被新证据推翻时失效？

把“执行循环”和“进化循环”分开：

执行循环：读取契约 → 执行一轮 → 验证 → 记录 → 更新状态
进化循环：收集反馈 → 诊断 → 生成变更提案 → 隔离验证 → 批准 → 晋升或回滚

初始 10 轮访谈结束后，进入持续优化模式。后续只在真实运行结果、失败或用户纠正触发时提出 1–2 个针对性问题，生成差异化改进提案；不要重新发起完整访谈，也不要仅凭 Agent 自己生成的案例证明已经改进。

5. 只在需要时追问

• 涉及外部数据：询问来源、授权、隐私、版权、保存和复核方式。
• 涉及多 Agent：询问独立首轮、少数意见、汇总权限和最大 Agent 数。
• 涉及定时运行：询问节奏、时区、并发、遗漏补跑和通知方式。
• 涉及代码开发：询问仓库、允许写入范围、测试、分支和部署边界。
• 涉及长期记忆：询问保存范围、失效条件和人工晋升方式。

生成前确认

在写文档前，先提交一份简短的“核心需求确认单”：

北极星目标：
目标用户与重复场景：
每轮产物：
完成标准：
非目标：
不可漂移项：
自动允许事项：
必须审批事项：
循环模式与周期边界：
每周期最大轮数：
ROUND_HANDOFF 交接字段：
下一轮触发条件：
周期完成条件：
自动更新范围：
只能提案的变化：
正式记忆的晋升条件：
冻结评估与护栏指标：
停止与回滚条件：
未决问题：

只有影响核心目的、权限或进化边界的未决项需要阻塞。可逆的本地文档细节可以采用明确标注的默认值。

防止长期漂移

在生成的文档中落实以下机制：

1. 为目的契约记录版本、批准状态和内容哈希；任务不得修改它。
2. 每轮启动时重新读取目的、运行、状态和有效审批，不依赖聊天记忆恢复方向。
3. 要求每个任务和阶段产物关联具体目标或成功标准；无法关联时停止。
4. 在每个阶段开始前检查：仍在范围内、输入有效、权限足够、验收标准未改变。
5. 将任务队列与核心目标分离；新增任务不能自动扩大项目范围。
6. 定期执行漂移审计，对比当前任务、产物和指标与获批目的契约。
7. 将范围变化写成变更提案；批准前不得进入正式契约。
8. 保留上一有效版本和回滚点。状态游标和记忆都不能创造权限或覆盖目的契约。
9. 每一轮启动前核对上一轮 ROUND_HANDOFF 与目的契约；无法确认交接来源、下一轮权限或剩余缺口时停止。
10. 连续多轮没有减少缺口、没有新增有效证据或重复同一失败时，进入周期复审，不得靠增加轮数维持运行。

控制自动更新

按影响等级处理更新：

更新对象	默认处理
运行日志、验证通过的状态游标、已授权队列状态、客观指标	自动追加或更新
原始运行事实、失败、用户纠正和记忆候选	自动追加到候选区，标注来源、范围、反例和失效条件
预先声明为可调且仍在批准范围内的参数	通过冻结评估和护栏后自动更新；记录差异、版本和回滚点
新经验、流程优化、新角色、新数据源、超出范围的参数	只生成候选提案
正式长期记忆	只能从候选晋升，并由 Human Owner 明确批准；系统可自动去重、复查和提出失效建议
北极星目标、成功标准、非目标、权限、审批门、禁止事项	永不自动修改，必须人工批准

禁止 Loop 直接重写自己的核心规则。自动迭代必须经过“反馈证据 → 变更差异 → 隔离验证 → 晋升决定 → 观察与回滚”。每次只验证边界清楚的改进，保留旧版本；护栏恶化或收益不可复现时自动回滚。

生成最小文档

默认只创建：

• AGENTS.md：规则优先级、启动读取顺序、权限、防漂移检查、停止和变更协议。要求每轮先读取 AGENTS.md、SOUL.md、LOOP.md、STATE.md 和适用的 MEMORY.md；状态和记忆不能创造权限。
• SOUL.md：目的契约、成功标准、非目标和不可变约束。
• LOOP.md：运行契约、单轮与多轮状态流、ROUND_HANDOFF 接口、阶段契约、事实与推断分离、验证和进化契约。
• STATE.md：当前周期与回合游标、最近有效交接、剩余预算、有效版本、审批引用、阻塞和下一允许动作。

仅在确有需求时增加：

• MEMORY.md：在需要跨轮学习时保存已批准的长期记忆，并分开候选区与正式区；候选经验不能自行晋升。
• AUTO_START.md：记录已批准的自动启动条件；默认关闭。
• 一个追加式 Run 模板：Loop 准备正式运行时必须创建，用于记录输入、工具、事实证据、Agent 推断、成本、状态变化、审批、失败和停止原因；纯设计草稿阶段可以暂缓。

优先把相关内容合并进四份核心文档。不要默认生成 README、Schema、脚本、锁目录、多个模板或重复制度文件。

批准前桌面演练

生成文档后，先保持全部文件为 DRAFT，不要宣布系统已经建立完成。使用一个正常案例和一个失败或越界案例，按文档进行桌面演练：

1. 检查启动读取顺序和有效权限。
2. 单轮 Loop 模拟输入进入、阶段转换、验证、日志和停止；多轮 Loop 至少连续模拟三轮，验证 ROUND_HANDOFF 能启动下一轮。
3. 验证越界动作会停在人工 Gate，而不是继续执行。
4. 模拟一次偏航检查和一次改进提案，确认不会改写北极星。
5. 模拟记忆候选产生、复核和拒绝晋升。
6. 模拟轮数或预算耗尽、连续无进展和中断恢复，确认系统进入 CYCLE_REVIEW 或 STOPPED，不会形成无限循环。

发现矛盾时修改草稿、更新版本和哈希，然后重新演练。

最终人工复审

桌面演练通过后，提交复审包，提示用户自主逐份审查和跨文档核对。复审包至少列出：文件、用途、版本、内容哈希、关键默认值、自动权限、人工 Gate、禁止事项、未决项和演练结果。

明确告诉用户：

• 文档当前仍是 DRAFT，Agent 无权批准自己生成的制度。
• 沉默、超时、“看起来可以”或批准继续研究都不构成正式通过。
• 用户可以选择 APPROVE、REVISE、BACKLOG、REJECT 或 STOP。
• 只有批准对象、版本、哈希和允许范围明确时，才能把对应文档改为 APPROVED。
• 获批内容发生实质变化时，旧批准立即失效并重新进入复审。

建议用户使用：

Decision: APPROVE | REVISE | BACKLOG | REJECT | STOP
Object: loop-doc-package/<id>
Version: <version>
Hash: <content-hash>
Allowed actions: <scope>
Conditions: <optional>

用户批准后，记录审批人、时间、原始确认引用、允许和禁止范围，再更新 STATE.md。文档批准只允许进入其声明的下一阶段，不自动授权 API、调度、执行代码、部署或外部动作。

验证与交付

验证：

• 每个阶段都能追溯到北极星目标和至少一项完成标准。
• 初始访谈没有超过 10 轮；提前结束或延长均有明确原因。
• 多轮 Loop 能从第 N 轮的有效 ROUND_HANDOFF 唯一地恢复或进入第 N+1 轮；单轮完成不会被误报为整个周期完成。
• 下一轮只有在验证、目的关联、审批、预算和漂移检查全部通过时才能启动；长期周期不存在无上限自循环。
• 越界任务、非法状态跳转和未批准的核心修改都会停止。
• 自动更新只发生在声明范围内，并有冻结评估、护栏、差异、版本和回滚证据。
• 正式记忆没有绕过候选、证据、适用范围和晋升规则。
• 文档之间没有相互冲突的目标、权限、状态或批准。
• 所有文档在用户复审前保持 DRAFT，且演练、复审包和批准记录能够相互追溯。

交付时只报告核心需求、循环模式、跨轮接口、创建文件、自动更新范围、审批边界、未决项、演练结果和用户下一决定。把 API、调度器和运行代码留到用户明确要求且文档获批后的第二阶段。