bug-iterate

Bug Iterate

用于处理多项 Bug 报告的顺序循环。你与用户之间的约定很简单：调查、提出方案、等待，然后执行——每个 Bug 都重复这个流程。

黄金规则：在用户明确批准某个 Bug 之前，绝不为该 Bug 修改代码。对 Bug N 的批准不适用于 Bug N+1。不要根据用户的热情推断其已批准。等用户明确表态。

两种模式

• 即时模式（默认）： 修复并提交每个已批准的 Bug，然后再处理下一个（每个 Bug 都执行阶段 4）。
• 批处理模式（先讨论，后修复）： 用户希望先逐一讨论所有修复方案，然后在最后一次性修复——通常由一个全新的“最终 Agent”会话来完成。触发短语：“先讨论每项修复”“然后一次性处理全部”“最终 Agent 会修复所有问题”。在批处理模式下：
  1. 对每个 Bug，照常执行阶段 1–3（调查 → 问题卡 → 结论）。阶段 4 替换为记录：不修改代码；将经过讨论达成一致的修复方案（包括讨论中做出的任何修订）追加到交接文档中。
  2. 交接文档位于 .claude/bug-iterations/{YYYY-MM-DD}-{slug}.md。批处理模式启动时创建该文档，并用完整的 Bug 列表初始化；每次得出结论后都要更新——它是最终 Agent 的唯一事实来源。每个 Bug 都必须记录：状态（agreed / revised / dropped / already-fixed）、根本原因及其文件:行号、各代码库达成一致的修复步骤、证据位置（日志查询、测试结果、复现输出、文件:行号）以及测试预期。文档必须自成一体——最终 Agent 不会记得讨论内容。
  3. 得出最后一个结论后，完善文档（执行顺序、Bug 之间的相互影响、验证计划），并根据文档生成最终 Agent 提示词（如果用户需要团队提示词，则使用 agent-team-prompt-builder 技能）。
  4. 在用户提出批处理模式之前已修复的 Bug，保持已修复状态——在文档中记录为 already-fixed 并附上提交 SHA，避免最终 Agent 重复处理。

---

步骤 0：收集 Bug 列表

找到 Bug 报告。它通常来自：

• 本次会话中助手之前的消息（例如调试或调查报告）。
• 用户粘贴的消息。
• 工单或问题链接（Notion、Linear、GitHub 等）。如有需要，获取其内容。

提取带编号的 Bug 列表，并为每项拟定一个简短标题。开始前向用户复述计划：

Bug plan:
  1. <short title> — <repo>
  2. <short title> — <repo>
  3. <short title> — <repo>
Starting with Bug 1.

记录本次流程的开始位置（例如会话标记或笔记中的一行），以便之后轻松查找整个迭代过程。

如果列表含糊不清或可能有多种解读方式，只问一个澄清问题，然后开始。

---

循环 — 逐个处理 Bug

对每个 Bug 重复以下四个阶段。不要跳过阶段，也不要合并阶段。

阶段 1 — 调查

记录该 Bug 的开始位置（会话标记或笔记中的一行），以便之后轻松查找每个 Bug 的处理过程。

收集实际证据。根据 Bug 的情况：

• 阅读相关代码路径（查看实际文件内容，而不是根据 grep 猜测）。
• 如果 Bug 有生产环境特征，则调取生产日志。
• 如果 Bug 涉及“某些内容发生了变化”，则检查 git 历史（git log、git blame）。
• 视情况对照代码树状态或数据库。
• 在作出任何判断前，先阅读实际的权威依据——上游报告或审计中的发现只是线索，不是证据。引用时记录准确行号，并确认对用户造成的实际影响确实存在（系统针对给定输入按预期运行，就不算 Bug）。

摘要中的每项主张都必须引用日志条目、文件:行号、工具调用结果或数据值。无法引用证据的内容，不要声称。

阶段 2 — 摘要卡片

向用户发送一份符合以下格式的报告。先说明出了什么问题，然后提供证据，最后再说明原因和修复方案——用户会先阅读背景和证据，再判断修复方案。内容要简洁，但绝不能为了节省篇幅而省略证据。

每张卡片的标题都必须显示进度——Bug N of M——让用户始终知道还剩多少个问题。

## Bug N of M — <title>
`<severity>` · <pattern> · <repo>

**① What went wrong:** <1–3 plain sentences — what the system actually did and the user-visible harm>

**② Evidence:** <bullets, each a REAL citation: log line, tool result, file:line, or repro output. No "likely"/"probably" in place of a citation. Note reproduction status if reproduced.>

**③ Cause:** <root cause, with file:line>

**④ Suggested fix:**
- Bullet (what changes, which file)
- Which repo: <repo> (a run may span multiple repos)

**Not in scope:** <what you're deliberately NOT touching — usually other bugs in the list or known follow-ups>

Approve, deny, or revise?

卡片的质量取决于证据——如果你无法引用实际日志、代码或复现结果来说明出了什么问题，就要继续调查后再发送（对问题的描述有误会浪费用户的时间，并损害信任）。

如果你认为某个问题是误报，仍然要提交给用户——撰写卡片时，应将 ① 写成它不是真实问题的证据，然后由用户决定（舍弃 / 保留）。绝不要擅自舍弃任何问题，即使你确信它是误报也不行——每个问题都由用户裁定，包括是否舍弃。自动舍弃和自动修复属于同一种失败模式：替用户做了决定。“逐个处理”意味着用户按顺序逐个决定。

然后停止。不要打开文件，不要开始起草代码，也不要准备“以防万一”的改动。放下工具。

请在普通聊天文本中询问用户的裁定——绝不要通过 AskUserQuestion 工具询问。该界面只显示问题及其选项，因此用户在其中看不到上面的卡片，只能在不了解情况的前提下做出裁定。请以 Approve, deny, or revise? 结束消息，然后等待。对于选项本身已包含全部必要背景的独立选择（例如选择两种修复策略之一、决定如何处理重复工单、是否部署），仍可使用 AskUserQuestion——但绝不能用它来询问用户对问题的裁定。

阶段 3 — 等待裁定

解读用户的下一条消息：

用户的回复	你的操作
approve / yes / go / yup / ok / 👍	继续执行阶段 4
deny / nah / strip / skip / no	转到下一个问题。如果误提交了任何内容，就撤销（见下文“撤销”）
其他任何内容	视为“修改”。回答用户的问题或回应异议，发送修订后的摘要卡片，然后再次等待

如果用户提出问题，就回答并发送修订后的摘要卡片。不要“趁着讨论时先开始修复”——这正是此技能旨在防止的反模式。

阶段 4 — 修复并提交

获得批准后：

1. 如果这是本次会话中的首次编辑，在修改任何文件之前，先阅读项目的编码标准 / 规范文档（如果有）。
2. 将改动严格限制在你提议的范围内。任何超出范围的内容都应作为新问题列入清单，而不是偷偷加入。
3. 扩展现有测试。如果已有测试覆盖同一模块，就不要堆叠新的测试文件。运行相关测试套件，并在提交前修复失败项。
4. 在当前工作分支上提交。每个获批的问题都单独提交；不要悄悄切换分支。
5. 使用 HEREDOC 编写提交消息，并以项目采用的共同作者 / 页脚约定结尾。
6. 除非用户要求，否则不要推送。在许多环境中，推送会触发部署——由用户在准备就绪后推送 / 部署。
7. 如果项目维护变更日志或记忆文件，在顶部添加一行：日期、代码库、提交 SHA，以及具体说明改了什么、为什么改的一句话。注明本轮迭代中的问题编号（例如：“修复流中的 Bug 3 of 7”），以便之后轻松还原处理流程。
8. 给用户的页脚消息：Bug N/M done. Next: <title of bug N+1>.

然后返回阶段 1，处理下一个问题。

---

撤销误应用的修复

如果用户在你提交修复后才否认存在该 bug（可能是你操之过急，也可能是他们改变了主意）：

1. 在受影响的仓库中运行 git log --oneline -3，确认该提交是最新提交。
2. 运行 git reset --hard HEAD~1 将其丢弃。仅当该提交尚未推送时才这样做——运行 git status -sb 检查。如果已经推送，先询问用户是否要重写历史。
3. 如果你添加了对应的变更日志／记忆文件条目，请将其删除。
4. 简短确认已撤回该修复，然后继续处理下一个 bug。

对于尚未推送的提交，如果直接运行 reset --hard 就能干净地撤销，不要使用 git revert（它会创建一个新提交）。

---

收尾

处理完最后一个 bug 后：

1. 发送最终汇总：

   Done. <N> applied, <M> stripped, <K> skipped.
   Commits:
     - <repo> <sha> — <title>
     - <repo> <sha> — <title>
   

2. 列出讨论中出现的所有后续事项（用户说“我们会另行处理”的事项，或迭代过程中浮现的新 bug），以免遗漏。
3. 不要建议部署。如果用户想部署，他们会提出。

---

不要做的事

• 不要为了“提高效率”而在一次编辑或一次提交中批量处理多个 bug。每个获准处理的 bug 都应单独提交。
• 修复 bug 时，不要顺手重构相邻代码，即使代码就在眼前。超出范围的内容留给下一个 bug，不要顺手处理。
• 不要逐步讲述 Phase 1 的每个内部步骤。用户看到的是 Phase 2。工具调用之间的调查过程最多用一句话说明。
• 不要因为已经处理了 5 个 bug，觉得模式已固定，就跳过 Phase 3。等待正是整个流程的关键。
• 不要把用户在 Phase 2 中途提出的修正（例如“其实，先跳过 Bug 3”）当作需要再来回确认——只需确认并继续。

反模式

用户：“我们来处理这 5 个 bug” Claude：调查 Bug 1，发送摘要 用户：“批准” Claude：修复并提交，然后调查 Bug 2，发送摘要，并在撰写摘要时开始编辑 Bug 2 用户：“不，撤掉这个” Claude：只好回滚

之所以要等待，是因为 Claude 一旦开始编辑，就会倾向于完成编辑，因此它开始编辑后再发送的摘要，不如编辑前发送的摘要客观。设置这道关卡，能让摘要保持客观。