name: 系统化调试 description: 提供系统化调试方法论，采用四阶段过程（根因调查、模式分析、假设测试、实施）。在遇到任何漏洞、错误、失败、功能损坏、测试失败、意外行为、故障排除问题或调查某事为何不工作时使用。在提出修复或进行更改前始终应用。 user-invocable: false

系统化调试

概述

随机修复浪费时间并创造新漏洞。快速补丁掩盖了潜在问题。

核心原则： 根因调查必须先于任何修复尝试。症状修复代表过程失败。

违反此过程的文字就是违反调试的精神。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

在完成阶段1之前不能提出修复。

何时应用

系统化调试适用于任何技术问题：

测试失败
生产中的漏洞
意外行为
性能问题
构建失败
集成问题

尤其有价值当：

时间压力产生猜测的诱惑
“快速修复”看起来明显
已经尝试了多次修复
之前的修复失败
问题未完全理解

即使当以下情况也不应跳过过程：

问题看似简单（简单漏洞也有根因）
时间紧张（系统化方法比混乱更快）
存在紧急情况（调查比返工更快）

四个阶段

每个阶段必须在进行下一个阶段前完成。

阶段1：根因调查

在尝试任何修复之前：

仔细阅读错误消息
- 错误消息和警告通常包含解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码
一致地重现
- 确定问题是否可靠触发
- 识别确切步骤
- 确认可重现性
- 如果不可重现，收集更多数据而不是猜测
检查最近更改
- Git差异和最近提交
- 新依赖项、配置更改
- 环境差异

在多组件系统中收集证据

对于具有多个组件的系统（CI -> 构建 -> 签名、API -> 服务 -> 数据库）：

在提出修复之前应添加诊断仪器：

对于每个组件边界：
  - 记录进入组件的数据
  - 记录退出组件的数据
  - 验证环境/配置传播
  - 检查每层的状态

运行一次以收集证据显示在哪里断裂
然后分析证据以识别失败组件
然后调查该特定组件

多层系统示例：

# 层1：工作流程
echo "=== 工作流程中可用的密钥： ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 层2：构建脚本
echo "=== 构建脚本中的环境变量： ==="
env | grep IDENTITY || echo "IDENTITY 不在环境中"

# 层3：签名脚本
echo "=== 密钥链状态： ==="
security list-keychains
security find-identity -v

# 层4：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"

这揭示了哪一层失败。

跟踪数据流

当错误在调用堆栈深处时：

参见 ./references/root-cause-tracing.md 获取完整的向后跟踪技术。

快速方法：
- 识别坏值起源于哪里
- 确定是什么用坏值调用了这个
- 继续向上跟踪直到找到源
- 在源处修复，而不是在症状处

阶段2：模式分析

模式识别应先于任何修复：

找到工作示例
- 在同一代码库中找到类似的工作代码
- 识别与损坏代码类似的工作代码
与参考进行比较
- 如果实现一个模式，完全阅读参考实现
- 阅读每一行，不要略读
- 在应用前完全理解模式
识别差异
- 列出工作和损坏代码之间的每个差异
- 不要将小差异视为无关紧要
理解依赖项
- 此操作所需的其他组件
- 需要的设置、配置、环境
- 模式所做的假设

阶段3：假设和测试

科学方法应用：

形成单一假设
- 清晰地陈述：“X 是根因因为 Y”
- 具体，而不是模糊
最小化测试
- 做最小的可能更改来测试假设
- 一次一个变量
- 不要同时修复多个事物
在继续之前验证
- 如果假设确认：进行到阶段4
- 如果未确认：形成新假设
- 不要在上面添加更多修复
当理解缺失时
- 承认缺乏理解
- 请求帮助
- 更多研究

阶段4：实施

修复根因，而不是症状：

创建失败测试案例
- 最简单可能的再现
- 如果可能，自动化测试
- 如果没有框架，一次性测试脚本
- 在修复前必须存在测试
实施单一修复
- 解决识别的根因
- 一次一个更改
- 没有“既然我在这里”的改进
- 没有捆绑的重构
验证修复
- 测试现在通过？
- 没有其他测试损坏？
- 问题实际上解决了？
如果修复不起作用
- 停止
- 计算尝试的修复次数
- 如果 < 3：返回到阶段1，用新信息重新分析
- 如果 >= 3：质疑架构
3+次失败修复后的架构质疑

指示架构问题的模式：
- 每个修复揭示新的共享状态/耦合/问题在不同地方
- 修复需要“大规模重构”
- 每个修复在其他地方创造新症状
停止并质疑基本面：
- 模式根本上是合理的？
- 方法是否因惯性而继续？
- 应该重构架构而不是修复症状？
在尝试更多修复前与人类伙伴讨论

这不是一个失败的假设 - 这是错误的架构。

复杂漏洞和规划

对于复杂漏洞，规划必须先于任何代码更改：

当漏洞复杂时

漏洞在以下任何情况应用时需要进入规划模式：

多组件参与 - 问题跨越多个文件、模块或子系统
架构影响 - 修复可能影响系统设计、合约或接口
多个潜在方法 - 存在几个有效的实施路径
副作用风险 - 更改可能影响不相关功能
需要重构 - 修复需要超出最小补丁的结构更改
未完全理解 - 阶段1调查后，根因仍不清楚

规划过程

完成阶段1（根因调查）
- 必须理解什么被破坏以及为什么在规划前
- 首先收集所有证据
使用进入规划模式工具
- 这向用户发出信号，您需要批准
- 允许用户在实施前审查方法
编写实施计划覆盖：
- 根因摘要（来自阶段1）
- 提议的修复策略
- 将被修改的文件
- 将创建/修改的测试
- 潜在风险和缓解
- 考虑的替代方法
等待用户批准
- 用户可能建议不同方法
- 用户可能提供额外上下文
- 用户可能批准原样

为什么为复杂漏洞规划

防止错误架构选择导致的昂贵返工
确保与用户偏好和约束一致
早期捕捉被忽视的依赖项
在执行前提供提议更改的可见性

对于简单漏洞： 直接继续进行阶段2-4，无需规划。

红旗

这些思维模式指示过程违反并需要返回到阶段1：

“现在快速修复，稍后调查”
“只是尝试改变 X 看看是否工作”
“添加多个更改，运行测试”
“跳过测试，我手动验证”
“可能是 X，让我修复那个”
“我不完全理解但这可能工作”
“模式说 X 但我会不同地适应它”
在跟踪数据流前提出解决方案
“再试一次修复”（当已经尝试2+次）
每个修复在不同地方揭示新问题

如果3+次修复失败： 质疑架构。

人类伙伴信号

注意这些重定向：

“那没有发生？” - 指示未经验证的假设
“它会显示我们…？” - 指示缺失的证据收集
“停止猜测” - 指示没有理解地提出修复
“深思熟虑这个” - 指示需要质疑基本面，不仅仅是症状
“我们卡住了？”（沮丧） - 指示当前方法不起作用

当遇到这些信号时： 返回到阶段1。

常见合理化

借口	现实
“问题简单，不需要过程”	简单问题也有根因。过程对于简单漏洞很快。
“紧急情况，没有时间用于过程”	系统化调试比猜测-检查的混乱更快。
“先尝试这个，然后调查”	第一次修复设置模式。从一开始就做正确。
“在确认修复工作后写测试”	未经测试的修复不持久。先测试证明它。
“一次多个修复节省时间”	无法隔离什么工作。导致新漏洞。
“参考太长，我会适应模式”	部分理解保证漏洞。完全阅读它。
“我看到问题，让我修复它”	看到症状 != 理解根因。
“再试一次修复”（在2+次失败后）	3+次失败 = 架构问题。质疑模式，不要再修复。

快速参考

阶段	关键活动	成功标准
1. 根因	阅读错误、重现、检查更改、收集证据	理解什么和为什么
2. 模式	找到工作示例、比较	识别差异
3. 假设	形成理论、最小化测试	确认或新假设
4. 实施	创建测试、修复、验证	漏洞解决、测试通过

当过程揭示无根因时

如果系统化调查揭示问题是环境性的、时间依赖的或外部的：

过程已完成
记录调查了什么
实施适当的处理（重试、超时、错误消息）
添加监控/日志以便未来调查

注意： 95%的“无根因”案例代表不完整调查。

支持技术

这些技术是系统化调试的一部分：

./references/root-cause-tracing.md - 跟踪漏洞通过调用堆栈向后以找到原始触发器
./references/defense-in-depth.md - 在找到根因后在多个层添加验证
./references/condition-based-waiting.md - 用条件轮询替换任意超时
./references/condition-based-waiting-example.ts - 条件等待的示例实施

相关技能：

superpowers:behavior-driven-development - BDD原则包括测试设计的Gherkin场景

真实世界影响

从调试会话：

系统化方法：15-30分钟修复
随机修复方法：2-3小时的混乱
首次修复率：95% vs 40%
新漏洞引入：近零 vs 常见