Bug 排查通用流程
遇到 Bug 时,不要让 Claude Code 直接猜原因。用现象、复现、范围、假设、验证、最小修复这条线,把排查变成可控流程。
Bug 排查最怕两件事:一是描述不清,二是还没定位就开始改。Claude Code 很适合排查 Bug,但前提是让它按工程流程走。
描述现象 -> 固定复现 -> 只读定位 -> 提出假设 -> 验证假设 -> 最小修复 -> 回归检查
先把 Bug 讲清楚
不要只说“页面坏了”“接口不对”“构建失败”。这些说法会让 CC 只能猜。
更好的输入结构:
请帮我排查一个 Bug,先不要修改文件。 现象: 【看到什么错误】 复现步骤: 1. 打开【页面/接口/功能入口】 2. 执行【操作】 3. 期望看到【正确结果】 4. 实际看到【错误结果】 环境: 【浏览器、设备、账号角色、运行环境、分支等】 限制: 1. 先定位原因。 2. 不要直接重构。 3. 不要修改无关文件。 4. 每个判断都要说明依据。
复现步骤越清楚,CC 越容易找到真正原因。
让 CC 先列排查地图
排查前先让 CC 画出相关链路。
请先只读梳理这个 Bug 的排查地图。 请输出: 1. 用户操作入口在哪里。 2. 前端状态或参数从哪里来。 3. 是否涉及接口、缓存、路由、权限或环境变量。 4. 最可能相关的文件。 5. 不应该优先修改的文件。 6. 你准备按什么顺序排查。
这一步能避免它一上来就改第一个看到的文件。
假设必须可验证
一个好的 Bug 假设应该长这样:
假设:问题可能出在【具体位置】。 依据:【代码、日志、复现现象】 验证方式:【运行什么、看什么、对比什么】 如果成立:【最小修复方案】 如果不成立:【下一条假设】
可以要求 CC 按这个格式输出:
请列出 3 个以内最可能的原因假设。 每个假设都要包含: 1. 假设内容。 2. 支持依据。 3. 如何验证。 4. 验证失败后下一步做什么。 不要列无法验证的泛泛猜测。
没有验证方式的假设,暂时不要改代码。
先修最小原因,不顺手优化
定位到原因后,仍然要限制修复范围。
请只做最小修复。 要求: 1. 只修改导致这个 Bug 的直接原因。 2. 不做样式美化。 3. 不重构无关代码。 4. 不顺手改命名。 5. 修改后说明为什么这个改动能解决复现问题。
Bug 修复阶段最常见的失控,就是把“修问题”变成“重写一片”。
前端 Bug 的排查重点
前端问题常见来源:
- 布局宽度、溢出、层级。
- 状态没有同步。
- 条件渲染漏了边界。
- 数据为空时没有兜底。
- 路由参数不一致。
- 组件复用时传参不完整。
可用模板:
请按前端 Bug 思路排查: 1. 先确认 DOM 结构和样式来源。 2. 再确认状态和 props 从哪里来。 3. 再确认是否有响应式或边界数据问题。 4. 最后给出最小修复。 不要一开始就改全局样式。
后端 Bug 的排查重点
后端问题常见来源:
- 参数校验不完整。
- 权限判断遗漏。
- 数据库查询条件不对。
- 异常没有被正确处理。
- 返回格式和前端约定不一致。
- 缓存或环境变量导致结果不一致。
可用模板:
请按后端 Bug 思路排查: 1. 先找到入口接口或方法。 2. 梳理参数、权限、查询、返回值。 3. 对照当前行为和期望行为。 4. 找最小修改点。 5. 给出正常、异常、边界三类验收方式。 不要修改数据库结构,除非先明确说明必要性。
构建失败的排查重点
构建失败时,不要让 CC 只看最后一行报错。
请排查构建失败。 要求: 1. 先识别错误类型:语法、依赖、类型、路径、环境变量、构建配置。 2. 找到第一处真正错误,不要只看最后一行。 3. 说明错误和最近改动是否相关。 4. 给出最小修复。 5. 修复后重新执行必要检查。
很多构建错误的最后一行只是结果,不是原因。
回归检查不能省
Bug 修完后至少问三件事:
请做 Bug 修复后的回归总结。 请输出: 1. 原 Bug 是否已经按复现步骤验证。 2. 本次改动可能影响哪些相邻功能。 3. 已检查哪些相邻功能。 4. 是否需要补测试。 5. 是否还有无法确认的风险。
如果只验证“现在不报错”,还不够。
Bug 排查失败时怎么收敛
如果 CC 排查半天没有结果,不要继续让它发散。
当前排查没有定位成功,请先暂停修改。 请总结: 1. 已排除的原因。 2. 尚未验证的原因。 3. 当前改动了哪些文件。 4. 是否建议回退临时改动。 5. 下一步最小排查动作是什么。
失败时先收敛,往往比继续猜更快。
验收结果
- 你知道 Bug 排查要先讲现象和复现。
- 你知道让 CC 先列排查地图,而不是直接改。
- 你知道假设必须可验证。
- 你知道修复后要做回归检查。