企业官网建设流程全解析

get-shit-done 修订循环模式（Revision Loop Pattern）：Check-Revise-Escalate 迭代修订与停滞检测实战指南

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

导读

在 get-shit-done（GSD）这类以"生产 Agent 产出 → 检查器校验 → 反馈修订"为核心编排方式的 spec-driven 开发系统中，如何控制 Agent 的迭代修订过程、避免无限循环和空转，是编排层最关键的工程问题之一。本文以 references/revision-loop.md 为骨架，完整拆解 GSD 项目内置的Check-Revise-Escalate（检查-修订-升级）标准模式：包括最多 3 轮迭代的循环控制、基于 BLOCKER/WARNING 计数递减的停滞检测、修订重生成时的提示结构，以及如何在 plan-phase、execute-phase、discuss-phase 等工作流中落地。读完本文，你将掌握一套可直接复用到任何多 Agent 校验场景的修订循环协议。

一、模式定位：什么时候需要修订循环

GSD 的核心工作流是一个"生产-校验-修订"的闭环：Agent 产出产物（计划、导入、缺口闭环计划等），然后由独立的检查器/验证器评估该产出，发现问题后回到生产 Agent 进行修订。revision-loop.md定义的就是这套迭代修订的标准模式，它适用于同时满足以下三个条件的场景：

1. 有 Agent 产出物—— 计划（PLAN.md）、导入结果、缺口闭环计划等；
2. 有独立的检查器/验证器对该产出物进行评估（如 gsd-plan-checker、gsd-verifier）；
3. 发现问题需要修订—— 且问题未达到可通过的阈值。

该模式的核心设计意图是：把"无界的人类式来回修改"收敛为"有上限、有停滞检测、有升级出口的确定性循环"。修订不是无限重试，而是最多 3 次迭代、每次都必须看到问题数量下降，否则立即升级给用户决策。

在仓库中，该模式被 plan-phase.md 第 12 节（## 12. Revision Loop (Max 3 Iterations)）直接引用为编排协议，也被 plan-review-convergence.md 作为required_reading引入（见该工作流<required_reading>段落中对revision-loop.md的引用），测试 plan-review-convergence.test.cjs 还专门断言命令源码必须引用revision-loop.md以获得停滞检测模式（见该测试文件 L69-L74）。

二、核心模式：Check-Revise-Escalate（最多 3 次迭代）

2.1 完整循环流程

原文档给出的标准流程伪代码如下，这是整个修订循环的控制骨架：

prev_issue_count = Infinity iteration = 0 LOOP: 1. Run checker/validator on current output 2. Read checker results 3. If PASSED or only INFO-level issues: -> Accept output, exit loop 4. If BLOCKER or WARNING issues found: a. iteration += 1 b. If iteration > 3: -> Escalate to user (see "After 3 Iterations" below) c. Parse issue count from checker output d. If issue_count >= prev_issue_count: -> Escalate to user: "Revision loop stalled (issue count not decreasing)" e. prev_issue_count = issue_count f. Re-spawn the producing agent with checker feedback appended g. After revision completes, go to LOOP

理解这个流程的关键点：

• 循环退出条件只有两个：检查通过（PASSED 或仅 INFO 级问题），或者升级给用户（超限或停滞）。不存在"检查器一直不满意就一直改"的路径；
• prev_issue_count初始化为Infinity，保证第一轮检查永远不会被误判为"停滞"——只有从第二轮起，问题数不下降才会触发停滞升级；
• 每次修订都重新 spawn 生产 Agent，而不是在同一上下文中继续修改（详见第五节）。

2.2 与 plan-phase 工作流中实现的对应关系

revision-loop.md的伪代码在 plan-phase.md 第 12 节被具体实现为可运行的编排协议。对比可见其变量与规则完全同构：

• 跟踪iteration_count（首轮计划+检查后从 1 开始）；
• 跟踪prev_issue_count（循环开始前初始化为Infinity）；
• 若iteration_count < 3：解析检查器返回中 YAML issues 块内的 BLOCKER + WARNING 条目数；若返回中没有 YAML issues 块（即计划通过），则issue_count记为 0 并跳过停滞检查，直接进入通过流程；
• 每次修订前显示进度：Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings；
• 若iteration_count >= 3：显示Max iterations reached. {N} issues remain:并给出"强制继续 / 提供指引后重试 / 放弃"三个选项。

这里有一个值得注意的实现细节：plan-phase 在停滞检测上还引入了stall_reentry_count（初始为 0），每次用户选择 "Adjust approach" 重新进入规划步骤时递增，并且该计数器在重入期间持续存在（重入会重置iteration_count和prev_issue_count，但stall_reentry_count上限为 2）。也就是说：停滞升级后允许用户选择"调整方法再试"，但最多允许 2 次重入；超过 2 次仍停滞则显示Stall persists after 2 re-planning attempts，并建议手动解决剩余问题或运行/gsd:debug排查根因。这比原文档的基础协议多了一层"可重试但有限"的护栏。

三、问题计数跟踪：停滞检测的量化基础

3.1 计数规则

每次迭代时，统计检查器返回的BLOCKER + WARNING 问题总数。判断规则：

• 若相邻两次迭代的问题数没有下降（issue_count >= prev_issue_count），说明生产 Agent 已陷入僵局，继续迭代不会有帮助，提前中断并升级给用户；
• 显示格式：Revision iteration {N}/3 -- {blocker_count} blockers, {warning_count} warnings；
• INFO 级问题不计入——它们不触发修订，也不参与停滞判断（详见第七节）。

3.2 停滞检测在 plan-phase 中的落地

plan-phase 工作流中的停滞检测显示文案为：

Revision loop stalled — issue count not decreasing ({issue_count} issues remain after {N} iterations)

随后根据stall_reentry_count分流：小于 2 时询问用户"Issues remain after {N} revision attempts with no progress. Proceed with current output?"（选项：Proceed anyway / Adjust approach）；达到 2 时则直接列出无法自动解决的剩余问题，并提供Proceed anyway / Abandon两个选项。

3.3 跨 AI 收敛循环中的变体：CYCLE_SUMMARY 契约

在 plan-review-convergence.md 这一跨 AI 计划收敛循环中，停滞检测的"问题计数"被替换为HIGH 严重度未解决数，逻辑同源于 revision-loop：初始化prev_high_count = Infinity，若HIGH_COUNT >= prev_high_count则判定⚠ Convergence stalled — HIGH concern count not decreasing。

但该工作流有一个关键改进，值得深入理解：不允许通过 grep REVIEWS.md 来统计 HIGH 数量，因为 REVIEWS.md 会跨循环累积历史，之前已解决的 HIGH 仍留在文件中作为审计轨迹，原始 grep 会被虚高计数、导致误报停滞（false stall）。正确的做法是从审查 Agent 的返回值中解析机器可读契约行：

CYCLE_SUMMARY: current_high=<N>

其中<N>统计仍未被解决的 HIGH：包含本轮新提出的 HIGH、仅部分解决（已承认且缓解进行中但未验证）的 HIGH、以及先前未解决的 HIGH；排除完全解决（已关闭 ticket、有验证日志或审查者签字确认）的 HIGH 以及对比性摘要表格中的历史提及。若契约缺失或格式错误（current_high非整数），工作流会区分"契约存在但畸形"与"契约完全缺失"两种错误并中止。这一机制正是为了避免"修订循环看似在推进、实际计数失真"的问题，是对停滞检测可靠性的工程加固。

四、Re-spawn 提示结构：如何把检查器反馈喂给修订 Agent

4.1 标准提示模板

当重新生成生产 Agent 进行修订时，必须把检查器的YAML 格式问题块原样传递。检查器输出包含## Issues标题及随后的 YAML 块，解析该块并**逐字（verbatim）**传给修订 Agent。标准模板如下：

<checker_issues> The issues below are in YAML format. Each has: dimension, severity, finding, affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING issues where feasible. {YAML issues block from checker output -- passed verbatim} </checker_issues> <revision_instructions> Address ALL BLOCKER and WARNING issues identified above. - For each BLOCKER: make the required change - For each WARNING: address or explain why it's acceptable - Do NOT introduce new issues while fixing existing ones - Preserve all content not flagged by the checker This is revision iteration {N} of max 3. Previous iteration had {prev_count} issues. You must reduce the count or the loop will terminate. </revision_instructions>

模板设计的核心原则有三条：

1. 反馈必须内联（inline）—— 修订 Agent 必须能看到"精确失败点"，而不是被要求"回去自己看报告"；
2. BLOCKER 与 WARNING 处理策略不同—— BLOCKER 必须改，WARNING 可以"解决或说明为何可接受"；
3. 明确告知迭代上下文—— 告诉修订 Agent"这是第 N 轮、上一轮有 N 个问题、必须减少否则循环终止"，把停滞检测的约束前置到提示中，引导 Agent 收敛。

4.2 plan-phase 中的修订上下文结构

plan-phase 工作流（第 12 节）将上述模板落地为<revision_context>+<instructions>结构，并额外注入了上下文文件（现有计划与/gsd:discuss-phase的用户决策）与AGENT_SKILLS_PLANNER技能提示，然后通过Agent(prompt=revision_prompt, subagent_type="gsd-planner", model="{planner_model}")重新生成规划 Agent。其<instructions>明确要求：

Make targeted updates to address checker issues. Do NOT replan from scratch unless issues are fundamental. Return what changed.

即：默认做定向修补，不重写——这与 revision-loop 的"外科医生而非建筑师"理念完全一致。

4.3 检查器 YAML 输出实例

检查器的问题块由## Issues标题引导，每条问题包含dimension（维度）、severity（严重度）、finding（发现）、affected_field（受影响字段）、suggested_fix（建议修复）。以 plan-checker.md 中的正向示例为准，实际输出形如：

issues: - dimension: task_completeness severity: BLOCKER finding: "Task T1 action says 'implement the authentication feature' without naming target files, functions to create, or middleware to apply. Executor cannot determine what to build." affected_field: "<action>" suggested_fix: "Specify: create authMiddleware in src/middleware/auth.js, apply to routes in src/routes/api.js lines 12-45, verify with integration test"

好的 finding 必须做到：引用具体维度、引用问题原文、解释为什么构成阻塞（如"执行器无法确定要构建什么"）、给出带文件路径与函数名的具体修复建议。而负向示例则展示了检查器应避免的行为——例如把规模合规（3 个任务本就在scope_sanity允许的 2-3 个范围内）误报为 INFO 级问题，这种个人偏好式检查只会浪费规划者的修订时间并侵蚀检查器可信度。

五、修订 Agent 的执行纪律：外科医生而非建筑师

被重新生成的修订 Agent 应当遵循 planner-revision.md（Revision Mode 参考）的纪律。该参考明确：

Mindset: Surgeon, not architect. Minimal changes for specific issues.

（心态：外科医生而非建筑师，只为特定问题做最小改动。）

其标准执行步骤为：

1. 加载现有计划——cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md，建立对当前结构、既有任务、must_haves 的心智模型；
2. 解析检查器问题—— 按plan、dimension、severity分组；
3. 制定修订策略—— 按维度匹配对应动作（见下方策略表）；
4. 做定向更新—— 只编辑被标记的部分，保留正常工作的部分，依赖变化时更新 wave；
5. 验证改动—— 所有标记问题已解决、无新问题引入、wave 号仍有效、依赖仍正确、磁盘文件已更新；
6. 提交—— 使用gsd-sdk query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md；
7. 返回修订摘要—— 以## REVISION COMPLETE开头，包含已解决问题数、变更表（Plan / Change / Issue Addressed）、更新文件清单；未解决的问题需单列## Unaddressed Issues并说明原因（需要用户输入、架构变更等）。

维度-策略映射表（来自 planner-revision.md）是修订 Agent 的决策核心：

配套的 DO / DO NOT 清单进一步约束修订边界：DO编辑特定标记区段、保留可用部分、依赖变化时更新 wave；DO NOT为小问题重写整个计划、添加不必要任务、破坏已有可工作的计划。这份参考与 revision-loop 的 Re-spawn 模板一前一后，分别定义了"检查器如何要求修订"与"修订 Agent 如何执行修订"。

六、3 次迭代后的处理：升级给用户

如果 3 轮修订后问题仍然存在，循环必须升级给用户而非继续空转。标准处理流程：

1. 将剩余问题呈现给用户；
2. 使用 yes-no 门禁提示（模式定义见 gate-prompts.md）：
   • question:"Issues remain after 3 revision attempts. Proceed with current output?"
   • header:"Proceed?"
   • options:
     • Proceed anyway—— 接受带有剩余问题的产出
     • Adjust approach—— 讨论不同的方法
3. 选择Proceed anyway：接受当前产出并继续；
4. 选择Adjust approach或Other（自由输入）：与用户讨论后，带着更新后的上下文重新进入生产步骤。

gate-prompts.md 还给出了一条通用规则：必须始终处理 "Other" 分支（用户输入自由文本而非选择项），header最多 12 字符，multiSelect恒为false，每个提示最多 4 个选项（超出需拆成两步流程）。当用户选择 "Adjust approach" 时，plan-phase 的stall_reentry_count机制会限制重入次数（上限 2），形成"升级 → 重试 → 再升级 → 放弃"的完整终止路径。

七、工作流特定变体与使用要点

7.1 变体对照表

revision-loop 模式在 GSD 各工作流中按"生产 Agent / 检查 Agent"配对实例化：

在 execute-phase.md 中可以看到该配对的运行细节：gsd-verifier负责阶段完成验证与质量门禁检查，验证结果中human_needed类项目会持久化为 UAT 文件并保持阶段挂起，直到验证重跑通过；发现缺口时进入缺口闭环：/gsd:plan-phase {X} --gaps读取 VERIFICATION.md 生成gap_closure: true的缺口计划 →/gsd:execute-phase {X} --gaps-only→ 验证器重跑。这套"验证-缺口-再验证"机制同样是修订循环理念在阶段粒度上的延伸。

7.2 重要注意事项（必须遵守的铁律）

原文档在结尾列出四条修订循环的强制性注意事项，任何实现都必须遵守：

• INFO 级问题始终可接受—— 它们不触发修订；只有 BLOCKER 和 WARNING 才进入循环；
• 每次迭代都是全新的 Agent spawn—— 不要在同一个上下文中"继续改"，避免上下文污染与幻觉式自我修正；
• 检查器反馈必须内联—— 修订 Agent 必须精确看到失败点（YAML 问题块逐字传递）；
• 不要静默吞掉问题—— 无论以何种方式退出循环，都必须把最终状态呈现给用户。

结合前述源码，还可补充两条工程化推论：其一，停滞检测的计数必须来自结构化契约（plan-phase 解析 YAML issues 块、plan-review-convergence 解析 CYCLE_SUMMARY），而不是对累积性文件做原始 grep，否则历史记录会污染计数并造成误报；其二，升级路径必须完备且有限（3 次迭代上限 + 停滞检测 + 重入上限 + 放弃选项），保证循环在最坏情况下也能确定性终止。

结语：把修订循环当作一等公民来设计

get-shit-done 的 Revision Loop Pattern 提供了一个可移植的多 Agent 校验协议模板：用prev_issue_count做停滞检测、用结构化 YAML 反馈做内联修订、用 3 次迭代上限和 yes-no 门禁做升级出口。这套模式的价值在于把"Agent 迭代质量"从不可控的对话运气变成了可预测的编排纪律——生产 Agent 知道何时该收敛，检查器知道如何给出可执行的 finding，编排器知道何时该停下来问用户。无论是规划阶段的 plan-checker 校验，还是执行阶段的 verifier 验证，抑或是跨 AI 的 plan-review-convergence 收敛循环，其底层都是同一套 Check-Revise-Escalate 协议。对于任何构建多 Agent 系统的工程团队，revision-loop.md都是可以直接复用的模式参考：先定上限，再定停滞判据，最后留好升级出口。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done