Systematic Debugging_开发编程 skill-PHP中文网

Systematic Debugging

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

确保在尝试修复前深挖根本原因的四阶段调试框架，切勿盲目求解。

Random 修正浪费时间并创建新错误

功能概述

Random 修正浪费时间并创建新错误是一项面向实际任务的技能，主要用于@ @ @ labeldes 掩盖了基本问题；核心原则: ALWAYS 在尝试修正前找到根原因。

核心要点

它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

系统化调试

概述

随机修复浪费时间，并引入新缺陷。快速补丁掩盖了根本问题。

核心原则：在尝试任何修复之前，必须先定位根本原因。仅修复表象即为失败。

违背本流程的字面要求，即等于违背调试的精神内核。

铁律

未经根本原因调查，不得实施任何修复  
未经上下文回顾，不得开展任何调查

若未完成第 0 阶段，则不可进入第 1 阶段；若未完成第 1 阶段，则不可提出任何修复方案。

适用场景

适用于所有技术问题：

测试失败
生产环境缺陷
非预期行为
性能问题
构建失败
集成问题

尤其应在以下情况中严格执行：

时间紧迫时（紧急状况易诱发盲目猜测）
“只需一个快速修复”看似显而易见时
已尝试过多次修复时
此前修复未奏效时
尚未完全理解问题本质时

切勿跳过流程的情形：

问题看似简单（简单缺陷同样具有根本原因）
你正赶时间（仓促操作必然导致返工）
上级要求“立刻修复”（系统化方法比盲目试错更快）

五个阶段

你必须完整执行每个阶段，方可进入下一阶段。

第 0 阶段：上下文回顾（强制首步）

在执行任何其他操作之前：

从错误信息中提取关键词
- 错误类型是什么？（OOM、超时、连接失败、类型错误……）
- 涉及哪个组件？（server、browser、API、database……）
- 影响代码库的哪个区域？
检索既有知识
- 查阅项目文档、MEMORY 文件或历史对话记录
- 在代码库中搜索类似错误模式：grep -r "ErrorType" .
- 检查近期相关变更：git log --oneline -20
复盘检索结果
- 找到相关经验？→ 直接应用，跳转至第 4 阶段
- 找到部分匹配项？→ 作为第 1 阶段的起点
- 未发现任何线索？→ 进入第 1 阶段，务必后续记录解决方案

输出格式

Context Recall:
- Query: "xxx"
- Found: [相关知识的描述]
- Action: [应用已有经验 / 继续调查 / 无匹配]

违规行为：未生成上下文回顾输出即进入第 1 阶段 = 流程失败。

第 1 阶段：根本原因调查

在尝试任何修复之前：

仔细阅读错误信息
- 不跳过任何错误或警告
- 它们往往已包含确切解决方案
- 完整阅读堆栈跟踪
- 记录行号、文件路径、错误码
稳定复现问题
- 能否可靠触发该问题？
- 精确步骤是什么？
- 是否每次必现？
- 若无法稳定复现 → 收集更多数据，禁止猜测
核查近期变更
- 哪些变更可能导致此问题？
- Git diff、近期提交记录
- 新增依赖、配置变更
- 环境差异

在多组件系统中收集证据

当系统含多个组件时（如 CI → build → signing，或 API → service → database）：

在提出修复前，须添加诊断性埋点：

对于每个组件边界：
  - 记录进入该组件的数据
  - 记录离开该组件的数据
  - 验证环境/配置是否正确传递
  - 检查各层级的状态

运行一次以获取证据，明确故障发生位置  
随后分析证据，定位失效组件  
最后深入调查该特定组件

追踪数据流向
- 异常值源自何处？
- 谁向当前函数传入了异常值？
- 持续向上追溯直至源头
- 在源头修复，而非在表象处修补

第 2 阶段：模式分析

修复前，先识别模式：

寻找正常工作的示例
- 在相同代码库中定位功能正常的相似代码
- 与当前故障逻辑相似、但能正常工作的案例是什么？
对照参考实现进行比对
- 若正在实现某设计模式，请完整通读其参考实现
- 切勿略读——逐行审阅
- 彻底理解该模式后，再着手应用
识别差异点
- 正常与异常实例之间有何不同？
- 逐条列出所有差异，无论多细微
- 切勿假设“这不可能有影响”
理清依赖关系
- 该模块还依赖哪些其他组件？
- 需要哪些设置、配置或环境？
- 它隐含了哪些前提假设？

第 3 阶段：假设与验证

遵循科学方法：

提出单一假设
- 清晰陈述：“我认为 X 是根本原因，因为 Y”
- 书面记录该假设
- 表述需具体，避免模糊
最小化验证
- 为验证假设，仅做最小必要改动
- 每次只改变一个变量
- 禁止一次性修复多个问题
验证通过后再推进
- 是否生效？是 → 进入第 4 阶段
- 未生效？→ 提出全新假设
- 禁止叠加更多修复
当你尚不了解时
- 坦诚表达：“我不理解 X”
- 切勿假装知晓
- 主动寻求帮助
- 进一步调研

第 4 阶段：实施修复

修复根本原因，而非表象：

编写失败测试用例
- 最简可行复现方式
- 尽可能自动化（单元/集成测试）
- 若无测试框架，提供一次性脚本
- 修复前必须完成
执行单一修复
- 仅针对已确认的根本原因
- 每次仅做一项变更
- 禁止“顺手优化”类修改
- 禁止捆绑式重构
验证修复效果
- 测试是否通过？
- 其他测试是否仍全部通过？
- 问题是否真正解决？
若修复未生效
- 立即停止
- 统计：已尝试多少次修复？
- 若少于 3 次：返回第 1 阶段，结合新信息重新分析
- 若已达或超过 3 次：立即停止并质疑架构（见下方第 5 步）
- 未经架构讨论，严禁尝试第 4 次修复
3 次以上修复均失败：质疑架构

此类现象暗示存在架构级问题：
- 每次修复均暴露出不同位置的新共享状态/耦合/缺陷
- 修复需依赖“大规模重构”才能落地
- 每次修复均在别处引发新症状
立即暂停，审视基础设计：
- 该模式本身是否合理？
- 我们是否仅因惯性而坚持沿用？
- 应重构架构，还是继续修补表象？
在尝试更多修复前，务必与用户讨论。

危险信号 — 立即停止并回归流程

若你发现自己产生如下想法：

“先快速修复，之后再深入调查”
“只改一下 X，试试看是否有效”
“同时应用多项修改，再运行测试”
“跳过测试，我手动验证即可”
“大概率是 X 问题，我这就修复”
“我虽未完全理解，但这个方案可能有效”
“虽然模式规定如此，但我打算换种方式适配”
“主要问题如下：[直接罗列修复项，未做调查]”
未完成数据流追踪就提出解决方案
“再试一次修复”（已尝试 2 次及以上）
每次修复均在不同位置暴露新问题

以上任一情形出现，均须：立即停止，退回第 1 阶段。

若已失败 3 次及以上：启动架构审查（参见第 4.5 步）

常见借口辨析

借口	事实
“问题很简单，无需走流程”	简单问题同样具备根本原因。流程对简单缺陷同样高效。
“紧急状况，没时间走流程”	系统化调试比盲目试错更快。
“先试一下，再正式调查”	首次修复即定调。必须从第一步就做对。
“等确认修复有效，我再补测试”	未经测试的修复难以持久。测试先行方能确证。
“多改几处能省时间”	无法定位真正起效的变更，反而引入新缺陷。
“参考文档太长，我按自己理解适配”	片面理解必然导致缺陷。请完整通读。
“我已看到问题，马上修复”	看见表象 ≠ 理解根本原因。
“再试一次”（已失败 2 次及以上）	3 次失败 = 架构问题。应质疑模式，而非重复修复。

速查表

阶段	关键活动	成功标准
0. 上下文回顾	提取关键词，检索既有知识	输出回顾摘要
1. 根本原因	细读错误、稳定复现、核查变更、收集证据	明确 WHAT 与 WHY
2. 模式分析	寻找正常示例，横向比对	精准识别差异点
3. 假设验证	提出理论，最小化验证	假设被证实，或生成新假设
4. 实施修复	编写测试、修复问题、全面验证	缺陷解决，所有测试通过