AI Agent / 系统课时
定位并修复缺陷
定位并修复缺陷
本课用一条可复现的失败测试串起 Claude Code 的缺陷修复流程:先把症状和日志变成证据,再缩小到根因,实施最小修复,最后用原复现路径和回归测试证明问题确实消失。
学习目标
- 能把报错、日志和复现步骤整理成 Claude Code 可验证的输入
- 能按证据链缩小故障范围,并约束 Claude 只做最小必要修改
- 能用原复现命令、相关测试和差异审查验证修复没有引入回归
先把现象固定成可复现证据
不要只说“修一下这个 bug”。Claude Code 能读取代码、运行命令并编辑文件,但定位质量取决于输入是否可验证。至少给出失败现象、稳定或偶发、复现步骤,以及能触发问题的命令。以下假设当前 Node.js 项目已经定义了 test 脚本。
npm test预期输出
> <PACKAGE>@<VERSION> test
> <TEST_COMMAND>
<FAILURE_OUTPUT><PACKAGE>、<VERSION>、<TEST_COMMAND> 与 <FAILURE_OUTPUT> 都由当前项目决定。把真实失败输出保留下来,它既是定位线索,也是修复后的验收基线。
给 Claude Code 的第一轮提示词应先要求调查而不是立即改文件:
我能稳定复现一个缺陷。
复现命令:npm test
现象:<FAILURE_OUTPUT>
请先不要修改文件。重新复现问题,定位最早出现异常状态的位置,
列出相关调用链、关键证据文件与行号,并给出一个最可能的根因假设。这样可以把“模型觉得哪里可疑”转换为“命令、调用链和源码位置共同支持哪一个假设”。
按证据链缩小根因
排查时从失败边界向前追,而不是从最后一条异常信息直接猜修法。先确认失败断言或错误返回,再找到产生错误值的函数,继续追输入来源、分支条件和最近相关变更;每缩小一次范围,都要求 Claude 指出它依据的代码或运行结果。

一个可靠根因通常能同时解释“为什么这里失败”和“为什么此前没有失败”。如果 Claude 提出多个可能性,优先让它设计能排除分支的小实验,例如运行单个测试、检查边界输入或追踪某个返回值,而不是同时修改多个位置。
实施最小修复
根因成立后,再明确修改范围和不变量。对修复型任务,好的约束是“只改变导致缺陷的行为,保持其他公开行为不变”,并要求补上能在旧代码上失败、在新代码上通过的回归测试。
根据已经确认的根因实施最小修复。
只修改与该根因直接相关的文件;不要顺手重构无关代码。
补充一个能覆盖原缺陷的回归测试,并解释为什么这个测试在修复前会失败。
修改完成后先运行最小相关测试,再运行项目现有完整测试命令。如果 Claude 开始扩大改动面,可以立即要求它解释每个文件为什么必须修改;无法说明必要性的改动应撤回或单独处理。
用同一条路径证明修复有效
修复后首先重复最初的复现命令,因为“新增测试通过”不能替代“原问题消失”。随后检查邻近边界条件和完整测试集,最后审查差异是否夹带格式化、依赖升级或无关重构。
npm test预期输出
> <PACKAGE>@<VERSION> test
> <TEST_COMMAND>
<ALL_TESTS_PASS>如果原命令仍失败,不要继续堆补丁,而应回到失败边界重新判断根因。通过测试后还要查看实际 diff,确认修改与根因一一对应;测试、差异和原复现路径三者同时成立,才算完成闭环。
遇到不稳定缺陷时换策略
偶发问题不要让 Claude 直接“猜一个修复”。先让它增加可撤销的诊断信息,记录触发条件、输入、并发顺序或时间窗口;收集到足够样本后再归纳共同条件。对可能影响共享环境、数据库或远端服务的复现步骤,应先要求只读调查或在隔离环境验证。
缺陷修复的关键不是让 Claude 写得更快,而是把它约束在可重复的证据循环里:复现、定位、假设、最小修改、再次复现、回归检查。只要任一环缺少证据,就应继续调查,而不是用更大的补丁掩盖不确定性。