Post-Merge Cleanup 生产故事撰写指南：为 loop-engineering 提交一份可复用的实战校准样本

人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址https://gitcode.com/gh_mirrors/lo/loop-engineering点击查看免费下载摘要导读本文围绕 loop-engineering 仓库中 Post-Merge Cleanup 模式 的生产故事征集规范展开说明一篇合格的实战故事需要覆盖哪些验收要素工具与节奏、首周捕获/遗漏、安全闸门、一条教训并结合仓库内已有的模式文档、示例故事、GitHub Actions 配置与 starter 脚手架给出可直接照做的撰写流程与素材来源。读完本文你将掌握如何把一次真实的技术债清扫 loop 运行记录整理成一篇结构完整、可被其他团队引用的 Post-Merge Cleanup 校准样本。一、这个征集在要什么一篇诚实的实战记录仓库 scripts/issue-bodies/post-merge-cleanup-story.md 是一份面向社区的生产故事production story征集说明。它的目标Goal非常明确分享一个真实的Post-Merge Cleanup生产故事——成功或诚实的失败——以帮助其他团队校准他们自己的技术债扫描 loop。注意措辞中的两个关键词真实real必须是实际运行过的 loop而不是设想中的流程成功或诚实的失败win or honest failure允许且鼓励记录失败。在 loop engineering 中失败记录的价值不亚于成功记录——stories/README.md 的索引里专门收录了why-we-killed-ci-sweeper.md、score-climbs-then-budget-burns.md这类我们关掉了它或预算烧穿的故事它们共同构成了模式设计的反面教材。该征集同时给出了明确的产出文件要求与验收标准Acceptance criteria这是整篇文章的核心骨架下面逐条展开。二、产出文件与索引一篇故事落在哪里原文档的 Files 部分规定了故事的落盘位置在stories/目录下新建一个故事文件遵循stories/README.md中内嵌的故事模板或参考一篇已有故事更新 stories/README.md 的索引行在表格中追加一行| 故事文件 | 所属模式 | 核心教训 |。关于模板需要澄清一点仓库中不存在独立的stories/TEMPLATE.md文件故事模板以内嵌形式维护在 stories/README.md 末尾结构如下# Title — Context ## Setup ## What Worked ## What Broke ## Metrics (if any) ## Lesson这份模板与征集规范中的验收标准高度一致Setup对应工具与节奏What Broke对应捕获或遗漏了什么与依赖的闸门Lesson对应给下一个团队的一条教训。写作时直接套用即可。仓库中最典型的范本是 stories/post-merge-cleanup-honest-win.md它的开头就给出了完整的故事元信息pattern 链接、cadence、工具、等级、结果一句话总结然后在 Setup 部分交代了团队背景12 人 SaaS 团队、约每周 40 次合并、loop 配置、技能清单、状态文件、第一周 L1 report-only 策略和 denylistauth/、payments/、公共 API 契约相关路径。三、验收标准逐条拆解一篇合格故事必须回答的四个问题原文档给出了四条验收标准这是文章的主体。逐条展开并结合仓库素材说明怎么写才达标。3.1 你用了哪个工具和什么节奏Which tool and cadence you used第一条要求写清楚工具tool与节奏cadence。这是其他团队复现你经验的前提不能只写用了 loop。Post-Merge Cleanup 模式文档 给出了可选的调度方式撰写故事时应从其中选取并注明实际使用的那一种调度方式说明/loop 1d或/loop 6h常规轮询式调度紧急度低于 CI sweeperGitHub webhook → Action由 merge 事件触发事件驱动见 examples/github-actions/post-merge-cleanup.yml每周 cron适合小团队工具侧模式文档提供了各工具的具体写法故事中应注明用的是哪一种Grok Build TUI/loop 1d Scan merges to main in the last 24h. Identify cleanup items. For small low-risk items: worktree minimal fix verifier. Update post-merge-state.md. Create tickets for larger items.Claude Code/loop 6h /post-merge-sweeperCodexdaily cadence 自动化 Post-merge sweeper结果进入 Triage inboxGitHub Actions参考 examples/github-actions/post-merge-cleanup.ymlpush到main分支即触发示例故事的写法stories/post-merge-cleanup-honest-win.md 开头一行就交代了全部关键信息——Cadence: 1d (off-peak)、Tool: Grok Build TUI GitHub Actions fallback、Level: L1 → cautious L2 (docs/comments only)。其中 off-peak21:00 本地时间正是模式文档中反复强调的要点合并后清扫 loop 应当在晚间或隔夜运行避免与活跃开发 loop 争抢资源见 patterns/post-merge-cleanup.md。3.2 loop 在第一周捕获或错过了什么What the loop caught or missed in the first week第二条要求记录第一周的实际效果重点是捕获caught或错过missed。模式文档定义了典型的运行周期见 patterns/post-merge-cleanup.md故事应围绕它描述第一周的实际情况列出上次运行以来的 main 分支合并记录逐个扫描 diff 中的 TODO、deprecation、// remove after注释、feature flag、损坏的文档链接交叉引用关联的 Linear/GitHub issue 寻找显式后续项优先级排序小且低风险 → 在 worktree 中提出修复大项 → 建 ticket 并标记人工Verifier 确认清理不改变行为有意删除除外打开小 PR或按天合并为一个 cleanup PR更新状态文件清理已完成项。示例故事把捕获与错过都写得很具体捕获过期 TODO 注释移除首个 L2 PR人工 LGTM 后 6 分钟合并doc fix 被 verifier 拦下——见下文 3.3。错过/误报Dependabot 与 Renovate 的合并提交被连续三天过度归类产生了 11 个候选但全是 lockfile-onlylegacyAuthfeature flag 因// remove after Q2注释被建议移除但该 flag 仍被 loop 看不到的移动端独立仓库引用——这是典型的跨仓库盲区被人工发现后才补进了LOOP.md。这一节的核心价值在于量化示例故事给出了 4 周 pilot 的完整指标表见 stories/post-merge-cleanup-honest-win.mdMetricBeforeAfter L1L2 (docs only)合并到首次后续动作的中位时间6.2 天1.4 天每周打开的后续 PR 数0–1临时3–5loop 提议、人工批准误报率人工判定—约 18%第 1 周→ 约 6%第 4 周工程师对报告有用度评分1–5—第 3 周均值 4.13.3 你依赖的 kill switch、verifier 或人工闸门Kill switch, verifier, or human gate you relied on第三条要求写清楚安全机制。对 Post-Merge Cleanup 这类具备自动修复能力L2的 loop这一条尤其关键。Verifier校验器模式文档规定清理不得改变行为有意删除死代码除外verifier 需跑完整测试套件回归即移交人工见 patterns/post-merge-cleanup.md。实现层面这是 maker/checker 分离原则的落地skills/loop-verifier/SKILL.md 规定 verifier 默认立场是除非证据充分否则拒绝REJECT until proven otherwise必须亲自运行测试而非相信 implementer 的自述输出APPROVE | REJECT | ESCALATE_HUMAN三态判定。示例故事中最具说服力的一段正是 verifier 的价值证明见 stories/post-merge-cleanup-honest-win.md第 4 天loop 为 PR #892 的合并提出一行 README 修正verifier 却标记了它示例响应体已从{ id: string }变成{ userId: number }与未文档化的 API 漂移一致。实施者把它归类为仅文档。没有 verifier 的拆分这就会作为一次无害的文档微调被合入。这正是模式文档Human Handoff Points中deprecations with external API consumers一类情况的实例见 patterns/post-merge-cleanup.md。人工闸门human gate模式文档列出的交接点包括——需要设计讨论的架构债、影响生产配置的 feature flag 移除、有外部 API 使用方的弃用、同一回归 loop 尝试两次仍未过测试。示例故事中的legacyAuth事件正是跨仓库 feature flag → 始终升级人工的教训来源。Circuit breaker断路器作为 fix-capableL2模式loop-init会自动脚手架loop-guardskill 与种子化的loop-ledger.json。同一次回归每次重试前都先跑断路器npx cobusgreyling/loop-context --check --ledger loop-ledger.json \ --budget-from-pattern post-merge-cleanup --budget-level L2非零退出码表示同一失败已重复或尝试次数上限已到此时必须停止并升级给人工详见 docs/safety.md。示例故事中Max 2 fix attempts per run的规则也体现在 starter 的 LOOP.md 与 skill 规则里。Denylist黑名单路径这也是故事应记录的一类闸门。示例故事与 starters/post-merge-cleanup/post-merge-state.md.example 都把auth/、payments/、infra/列为永不自动修改的路径故事中还新增了ignored_authorsdependabot、renovate和min_diff_lines: 3两个状态字段来压制 bot-merge 噪音。3.4 给下一个团队的一条教训One lesson for the next team trying Post-Merge Cleanup第四条要求提炼一条教训这是故事的可移植资产。示例故事的 Lesson 段落给出了教科书式的写法见 stories/post-merge-cleanup-honest-win.md先跑两周 L1——报告会校准你的团队到底把什么视为债务。只有当 verifier 把 API 示例当作代码来对待时才为文档、注释与 lint 路径启用 L2。把架构债留在 Linear 里而不是留在 loop 里。Post-Merge Cleanup 是 PR Babysitter 的补充而非替代它在非高峰时段处理已经落地的合并。这条教训与模式文档Success Metrics一节的定位完全呼应Post-Merge Cleanup 风险低于 CI sweeper是 daily triage 稳定之后的第二个 loop见 patterns/post-merge-cleanup.md。四、写作前的素材清单模式、配置与脚手架为了让故事达到可被复现的精度撰写前建议先通读以下仓库资源它们分别对应故事中需要填写的字段模式全貌patterns/post-merge-cleanup.md——调度、技能、状态文件格式、循环步骤、断路器、验证策略、交接点、各工具命令、失败模式与缓解、成本画像、成功指标。其中 状态文件示例post-merge-state.md的 Pending / Completed / Deferred 三段式应作为故事中状态管理部分的对照物。可用技能post-merge-scan扫描最近合并产出优先级修复清单、minimal-fix小型后续修复、loop-verifier独立校验。post-merge-scan技能的可执行定义见 starters/post-merge-cleanup-opencode/skills/post-merge-scan/SKILL.md其中分类规则Small fix / Architectural debt / Denylist path可直接引用到故事的第一周捕获部分。CI 集成示例examples/github-actions/post-merge-cleanup.yml——push到main触发 每晚 22:00 cron 聚合扫描用git log --merges列合并、用git diff扫描TODO|FIXME|remove after|deprecated信号。注意该示例只做扫描与状态追加自动修复需另行接入 Agent这与L1 report-only的起步策略一致。脚手架starters/post-merge-cleanup/README.mdGrok 路径loop-init一键生成或手动拷贝与 starters/post-merge-cleanup-opencode/README.mdopencode 路径含opencode run报告模式的启动命令。starter 中的 LOOP.md 定义了人工闸门架构债建 ticket 不修、feature flag 移除需人工批准、多文件重构升级与预算L2 每次运行最多 2 次子代理 spawn、非高峰运行。成本画像模式文档给出了 token 参考No-op 约 5k、Scan prioritize 约 40k、Small fix L2 约 150k与建议预算每日上限 200k tokens见 patterns/post-merge-cleanup.md并可用npx cobusgreyling/loop-cost --pattern post-merge-cleanup --cadence 1d --level L1实测估算。故事若涉及预算话题可引用这些基线。五、从草稿到合并一小时的完整工作流原文档给出的预估时间是约 45 分钟。按下面这个流程推进可以稳定控制在这个预算内确认事实10 分钟回看运行记录状态文件、PR 列表、run log挑出 1 个最有代表性的捕获和 1 个遗漏/误报搭骨架10 分钟按 stories/README.md 模板写出Setup / What Worked / What Broke / Metrics / Lesson五个小节标题在文件头部补上 Pattern / Cadence / Tool / Level / Outcome 元信息行填内容15 分钟逐条对照本文第三部分的四个验收标准填写每个论点尽量给出一组可验证的数字或一个具体 PR/SHA 案例补索引5 分钟在 stories/README.md 表格中追加一行索引Takeaway 列用一句话概括核心教训自检5 分钟用第四节的素材清单核对——工具与节奏是否具体、闸门是否点名verifier / human gate / kill switch / denylist、教训是否只有一条且可执行。六、优秀故事的通用检查清单综合原文档验收标准与仓库内既有故事stories/post-merge-cleanup-honest-win.md、stories/README.md 中的其他条目一篇高质量 Post-Merge Cleanup 故事应当同时满足可复现工具名、调度表达式、技能清单、状态文件名都写全读者照抄即可搭建同一套 loop有证据每个结论都有 merge 编号、PR 编号或 SHA 支撑指标有前后对比诚实明确写什么没被捕获和误报了多少而不是只报喜安全透明点明依赖了哪些 verifier 规则、人工闸门和 denylist说明没有它们会发生什么有单点教训Lesson 只提炼一条、可直接执行的建议而不是泛泛的多测试。写完后把故事文件提交到stories/目录并更新索引即可。如果希望为故事补充更多背景可以继续研读 patterns/README.md 了解全部模式体系或参考 docs/safety.md 中的安全设计约定——但一篇故事的灵魂始终是那四个验收标准工具与节奏、首周捕获与遗漏、安全闸门、一条教训。赞分享人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址https://gitcode.com/gh_mirrors/lo/loop-engineering点击查看免费下载相关推荐Loop Engineering 实战用 Opencode 搭建 Post-Merge Cleanup 循环清理合并后的技术债Loop Engineering 实战用 Opencode 搭建 Post Merge Cleanup 循环清理合并后的技术债 核心导读 本文基于 exa人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务Post-Merge Cleanup 循环实战用 Grok 的 /loop 命令在 loop-engineering 中自动清扫合并后的遗留工作Post Merge Cleanup 循环实战用 Grok 的 /loop 命令在 loop engineering 中自动清扫合并后的遗留工作 本指南围绕人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务在 Cursor 中落地 Post-Merge Cleanup 循环基于 loop-engineering 的合并后清理自动化实战指南在 Cursor 中落地 Post Merge Cleanup 循环基于 loop engineering 的合并后清理自动化实战指南 导读 本文讲解如何在人工智能AI AgentAgent 工作流CLI研发协作AI 技能MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考