get-shit-done 修订循环模式Revision Loop PatternCheck-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-doneGSD这类以生产 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定义的就是这套迭代修订的标准模式它适用于同时满足以下三个条件的场景有 Agent 产出物—— 计划PLAN.md、导入结果、缺口闭环计划等有独立的检查器/验证器对该产出物进行评估如 gsd-plan-checker、gsd-verifier发现问题需要修订—— 且问题未达到可通过的阈值。该模式的核心设计意图是把无界的人类式来回修改收敛为有上限、有停滞检测、有升级出口的确定性循环。修订不是无限重试而是最多 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} warningsINFO 级问题不计入——它们不触发修订也不参与停滞判断详见第七节。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_highN其中N统计仍未被解决的 HIGH包含本轮新提出的 HIGH、仅部分解决已承认且缓解进行中但未验证的 HIGH、以及先前未解决的 HIGH排除完全解决已关闭 ticket、有验证日志或审查者签字确认的 HIGH 以及对比性摘要表格中的历史提及。若契约缺失或格式错误current_high非整数工作流会区分契约存在但畸形与契约完全缺失两种错误并中止。这一机制正是为了避免修订循环看似在推进、实际计数失真的问题是对停滞检测可靠性的工程加固。四、Re-spawn 提示结构如何把检查器反馈喂给修订 Agent4.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 its 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模板设计的核心原则有三条反馈必须内联inline—— 修订 Agent 必须能看到精确失败点而不是被要求回去自己看报告BLOCKER 与 WARNING 处理策略不同—— BLOCKER 必须改WARNING 可以解决或说明为何可接受明确告知迭代上下文—— 告诉修订 Agent这是第 N 轮、上一轮有 N 个问题、必须减少否则循环终止把停滞检测的约束前置到提示中引导 Agent 收敛。4.2 plan-phase 中的修订上下文结构plan-phase 工作流第 12 节将上述模板落地为revision_contextinstructions结构并额外注入了上下文文件现有计划与/gsd:discuss-phase的用户决策与AGENT_SKILLS_PLANNER技能提示然后通过Agent(promptrevision_prompt, subagent_typegsd-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.mdRevision Mode 参考的纪律。该参考明确Mindset: Surgeon, not architect. Minimal changes for specific issues.心态外科医生而非建筑师只为特定问题做最小改动。其标准执行步骤为加载现有计划——cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md建立对当前结构、既有任务、must_haves 的心智模型解析检查器问题—— 按plan、dimension、severity分组制定修订策略—— 按维度匹配对应动作见下方策略表做定向更新—— 只编辑被标记的部分保留正常工作的部分依赖变化时更新 wave验证改动—— 所有标记问题已解决、无新问题引入、wave 号仍有效、依赖仍正确、磁盘文件已更新提交—— 使用gsd-sdk query commit fix($PHASE): revise plans based on checker feedback --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md返回修订摘要—— 以## REVISION COMPLETE开头包含已解决问题数、变更表Plan / Change / Issue Addressed、更新文件清单未解决的问题需单列## Unaddressed Issues并说明原因需要用户输入、架构变更等。维度-策略映射表来自 planner-revision.md是修订 Agent 的决策核心维度策略requirement_coverage为缺失需求添加任务task_completeness为既有任务补齐缺失元素dependency_correctness修复 depends_on重算 wavekey_links_planned添加接线任务或更新 actionscope_sanity拆分为多个计划must_haves_derivation推导并将 must_haves 加入 frontmatter配套的 DO / DO NOT 清单进一步约束修订边界DO编辑特定标记区段、保留可用部分、依赖变化时更新 waveDO NOT为小问题重写整个计划、添加不必要任务、破坏已有可工作的计划。这份参考与 revision-loop 的 Re-spawn 模板一前一后分别定义了检查器如何要求修订与修订 Agent 如何执行修订。六、3 次迭代后的处理升级给用户如果 3 轮修订后问题仍然存在循环必须升级给用户而非继续空转。标准处理流程将剩余问题呈现给用户使用 yes-no 门禁提示模式定义见 gate-prompts.mdquestion:Issues remain after 3 revision attempts. Proceed with current output?header:Proceed?options:Proceed anyway—— 接受带有剩余问题的产出Adjust approach—— 讨论不同的方法选择Proceed anyway接受当前产出并继续选择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配对实例化工作流生产 Agent检查 Agent备注plan-phasegsd-plannergsd-plan-checker通过 planner-revision.md 生成修订提示execute-phasegsd-executorgsd-verifier执行后验证discuss-phaseorchestratorgsd-plan-checker由编排器内联修订在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考