focused-fix

聚焦修复

类别： 工程 领域： 调试与维护

概述

聚焦修复技能要求以严谨、最小化变更的方式修复错误。修复错误时，它不会顺便重构或改进代码，而是找出能够解决问题的最小变更集。这样可以降低风险、简化代码审查，并防止范围蔓延。

适用场景

• 用户要求“以最小改动修复错误”“进行聚焦错误修复”或“限定最小修复范围”
• 需要对错误报告进行分类，以找出需要修改的最少文件
• PR 有范围蔓延的风险（无关重构、样式变更、“顺手”修复）
• 需要以低风险、易审查的变更集处理热修复或发布阻断问题
• 用户询问“修复 X 的最小改动是什么？”或“修复这个错误需要改哪些文件？”

先澄清

在确定修复范围之前，先确认以下信息。如果有任何信息未知或含糊不清，请提问，不要自行假设：

• 可观察到的故障 — 确切症状、复现步骤，以及预期行为与实际行为（这是分析器要匹配的错误描述，也是修复必须解决的问题，而不是对原因的猜测）
• 代码库路径和文件类型 — 要搜索的目录和扩展名（用于设置 --path/--extensions）
• 最小修复还是结构性修复 — 确认这是聚焦修复，而不是重构（用于判断是否应拒绝超出范围的“既然改到这里了，顺便……”变更）

停止规则：只询问最可能影响输出的 2-3 项。如果用户说“直接起草”，就继续，并在产物开头列出假设。

快速入门

# Analyze a bug description to identify minimal change scope
python scripts/change_scope_analyzer.py --bug "Login fails when email has + character" --path ./src

# Analyze with JSON output
python scripts/change_scope_analyzer.py --bug "API returns 500 on empty array input" --path ./src --format json

# Analyze with specific file extensions
python scripts/change_scope_analyzer.py --bug "CSS overflow on mobile" --path ./src --extensions .css .scss .html

工具概览

工具	用途	关键标志
change_scope_analyzer.py	找出修复错误所需的最少文件	--bug、--path、--extensions、--format

change_scope_analyzer.py

根据错误描述分析代码库，找出：

• 最可能与错误相关的文件（关键词匹配、导入追踪）
• 预估变更范围（文件数、代码行数）
• 变更风险评估
• 建议的修复方式（最小修复或结构性修复）

工作流

聚焦错误修复工作流

1. 撰写清晰的错误描述 — 包含复现步骤、预期行为与实际行为
   • 验证： 描述指出可观察到的故障，而不是对原因的猜测
2. 运行 change_scope_analyzer.py 确定范围
   • 验证： 分析器输出列出具体文件和预估行数
3. 审查建议的文件和处理方式
   • 验证： 建议的处理方式为“最小修复”——如果显示“结构性修复”，就停止，并单独确定重构 PR 的范围
4. 只进行修复错误所需的变更
   • 验证： git diff --stat 与分析器的建议一致（或变更更少）
5. 确认没有混入无关变更
   • 验证： git diff 中没有仅涉及格式的变更、无关导入或“既然改到这里了，顺便……”的修改
6. 提交包含聚焦变更集的 PR
   • 验证： 提交说明准确指出修复的错误，并包含回归测试

范围验证

1. 完成变更后，重新运行分析器
2. 将实际变更与建议范围进行比较
3. 将任何超出范围的修改标记为单独 PR
   • 验证： 对于任何不在分析器建议范围内但被修改的文件，都有一行说明其理由，否则应还原该修改

参考文档

• 聚焦修复方法论 - 原则、反模式和决策框架

常见模式

应做

• 修复报告中指出的确切错误
• 为修复添加回归测试
• 在提交说明中说明修复有效的原因
• 尽可能缩小差异

不应做

• 在修复错误时重构周边代码
• 在同一个 PR 中修复“顺带发现”的问题
• 更改已修改文件的格式或样式
• 添加伪装成错误修复的新功能

反模式

反模式	失败模式	修复方法
在缺陷修复 PR 中顺手重构	影响范围急剧扩大；审查时间成倍增加；无关回归被真正的修复掩盖	为重构单独提交 PR，并标记为 refactor: 而非 fix:
在改动的文件中重新格式化或更改自动保存样式	差异变得难以阅读；真正的修复被 200 行空白字符改动掩盖	提交前撤销样式改动；将编辑器配置为仅对新文件在保存时格式化
在错误的层修复症状	缺陷以新形式再次出现；变通方案债务不断累积	追溯到根本所在层——分析器的关键词匹配输出只是线索，并非答案
因为“修复显而易见”而跳过回归测试	6 个月后的一次重构可能导致缺陷悄然复发	每个 fix: 提交至少添加一个先失败后通过的测试
将 change_scope_analyzer.py 的输出视为权威结论	分析器基于关键词和导入关系，而非语义——会漏掉动态分派、反射和配置驱动的路径	将其作为初步范围；在确定范围前，用 grep 搜索调用方和测试
将修复与依赖升级打包在一起	一个 PR 中包含两种风险；如果需要回滚，两者都会丢失	先单独合入升级，再基于升级后的基线提交修复