7.4 Bug 修复与重构路径¶
Bug 修复和重构最能检验 Agent 使用流程是否规范。需求不难说明，但证据、边界和回滚点一个都不能少。
本节不要求一次修大问题。先选一个能复现、能验证、影响范围小的 bug，练会流程再扩大任务范围。
Bug 修复路径¶
输入材料¶
先收集完整证据：
- 错误现象。
- 复现步骤。
- 日志或 stack trace。
- 最近相关改动。
- 期望行为。
如果缺少复现步骤，先让 Agent 做只读分析和复现计划。不要让它直接改代码。
Agent 流程¶
1. 先复现或解释如何复现。
2. 提出 2-3 个可能根因。
3. 用代码和日志验证假设。
4. 做最小修复。
5. 补回归测试。
6. 跑验证。
7. 写复盘。
禁止¶
这些做法看起来省时间，通常会增加下一轮返工风险：
- 不复现直接改。
- 猜一个原因就改。
- 修完不补测试。
- 改大范围无关代码。
还要避免把“顺手重构”和 bugfix 混在一起。bugfix 先追求最小修复，结构调整另开任务。
重构路径¶
重构前先把这几个问题问完：
- 外部行为是否保持不变？
- 现有测试是否足够？
- 是否需要 characterization test？
- 重构范围是否清楚？
- 是否有回滚点？
Agent 流程¶
1. 分析当前结构。
2. 找重复、复杂度、边界问题。
3. 写重构计划。
4. 人审计划。
5. 小步改动。
6. 每步跑测试。
7. 最后做 diff 审查。
重构时可以让 Agent 先补 characterization test。它们不证明现有行为正确，只负责把现有行为固定下来，避免重构把行为改掉。
验证标准¶
Bug 修复：
- 原 bug 可复现。
- 修复后不再复现。
- 有回归测试。
重构：
- 外部行为不变。
- 测试通过。
- diff 中没有无关功能变化。
停止条件¶
遇到下面情况，先停：
- bug 无法复现，也无法给出可信复现路径。
- 修复需要改动权限、支付、数据删除、认证等高风险区域。
- 重构范围越过原计划。
- 测试失败原因说不清。
- Agent 要引入新依赖绕过问题。
停止不是失败。先把状态、证据和未解决问题写进任务记录，再决定是否拆分任务。
复盘沉淀¶
任务结束后，让 Agent 回答这些问题，再决定要不要沉淀到规范：
这个 bug 为什么会出现？
哪些测试原本应该发现它？
AGENTS.md / CLAUDE.md 需要新增什么规则？
是否应该做成 bug-fix skill？