---
name: debugging-methodology
when: '调试, debug, 排查问题, 修复Bug, 定位错误, 根因分析, 排障, 故障排查'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-pattern-debugging-methodology
asset_kind: pattern
lifecycle_status: active
owner_mechanism_id: mc-general-pattern
authority: supporting
routes:
  - '*'
primary_triggers:
  - 调试
  - debug
  - 排查问题
  - 修复Bug
  - 定位错误
  - 根因分析
  - 排障
  - 故障排查
priority: P2
specificity: 3
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
stages: ["架构设计"]
---

## 决策规则
- 一次只验证一个假设，一次只改一个变量，记录所有结果包括被否定的假设
- 禁止从观察直接跳到修复，必须经过假设验证
- 修复范围只覆盖确认的根因，禁止顺手改其他代码
- 同一现象修复失败 3 次后停止猜测，重新审视假设，考虑是否为架构问题而非 Bug
- 使用 RED-GREEN 回归验证：回退修复 → 确认失败 → 恢复修复 → 确认通过
- 禁止通过删除断言、增加 sleep、降低覆盖率、增加 mock 来制造通过
- 调试必须先复现问题（确定环境、数据、步骤），禁止在未复现的情况下猜测修改
- 必须使用二分法定位问题范围（注释一半代码/回退一半提交），禁止全量排查
- 线上问题排查必须优先查看日志和监控，禁止直接登录服务器修改代码
- 修复后必须验证根因是否消除，而非只验证症状消失

## 验收项
- [AC-01] 调试过程有假设-验证记录
- [AC-02] 修复范围仅限确认的根因
- [AC-03] 3次失败后重新审视假设
- [AC-04] 使用 RED-GREEN 回归验证
- [AC-05] 先复现再排查
- [AC-06] 使用二分法定位
- [AC-07] 修复后验证根因消除
