---
id: ka-guidance-调试排查
kind: guidance
title: 调试排查
sync_policy: engine_only
status: active
triggers:
  - bug
  - 调试
  - 排查
  - 报错
  - 异常
  - 失败
  - 排障
  - 定位
  - 日志排查
  - 缺陷修复
  - bugfix
extra:
  name: debug-investigation
  scope:
    - '*'
  products:
    - '*'
  category: procedure
  version: 1.0.0
  last_reviewed: '2026-06-17'
  verification_layer: L2
  stage: build
  domain: build
  owner_mechanism: mc-verifier
---

# 调试排查：出了 bug 怎么定位根因

> 吸收旧的「调试排查」「Bug分析」「调试方法论」「全栈流程修复」「新老逻辑比对日志」。
> [[工程执行总纲]] 思考先行：禁止只修表象不找根因。

## 第一步：稳定复现

- 先找到稳定复现路径（无复现=瞎改）
- 记录复现步骤、环境、输入、预期 vs 实际

## 第二步：定位根因（不是表象）

- 读日志/堆栈，追到真实失败点
- 区分：症状（报什么）vs 根因（为什么报）
- 二分法/日志插桩缩小范围
- 靠证据，不靠猜（[[证据驱动与反幻觉]]）

## 第三步：最小修复

- 只改根因点，不扩大范围（[[工程执行总纲]] 精准修改）
- 改老系统先比对新老逻辑差异
- 修复限于同一上下文；跨模块回到任务拆解

## 第四步：回归测试

- 先写复现测试（证明 bug 存在）→ 修复后证明 bug 消失
- 跑相关测试，确认没引入新问题

## 第五步：防复发

- 补测试守住这个修复
- 想想同类问题会不会在别处出现（举一反三）
- 必要时沉淀成规则/检查

## 禁止

- 不复现就改（违规，改了也不知道对不对）
- 只修表象不找根因（违规，bug 会回来）
- 改一大片"可能相关"的代码（违规，扩大风险）
- 修复后不写回归测试（违规，无法证明修好）