名称: 调试描述: 在遇到任何错误、测试失败或意外行为时使用，在提出修复前 - 四阶段框架（根因调查、模式分析、假设测试、实施）确保在尝试解决方案前理解问题

系统化调试

概述

随机修复浪费时间并产生新错误。快速补丁掩盖根本问题。

核心原则: 务必在尝试修复前找到根本原因。症状修复是失败。

违反此流程的字面意义就是违反调试的精神。

铁律

没有根本原因调查前，不进行任何修复

如果你没有完成第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"

这揭示： 哪一层失败（秘密 → 工作流 ✓，工作流 → 构建 ✗）

追踪数据流

当错误在调用栈深处时：

必需子技能： 使用超能力根因追踪进行反向追踪技术

快速版本：
- 坏值源于何处？
- 什么用坏值调用了这个？
- 持续向上追踪直到找到源头
- 在源头修复，不在症状处

第2阶段：模式分析

在修复前找到模式：

找到工作示例
- 定位同一代码库中类似的工作代码
- 什么工作与什么坏了类似？
对比参考
- 如果实现模式，完整阅读参考实现
- 不要略读 - 阅读每一行
- 完全理解模式后再应用
识别差异
- 工作和坏了之间有什么不同？
- 列出每个差异，无论多小
- 不要假设"那不重要"
理解依赖关系
- 这需要哪些其他组件？
- 哪些设置、配置、环境？
- 它做了什么假设？

第3阶段：假设和测试

科学方法：

形成单一假设
- 清晰陈述：“我认为X是根本原因，因为Y”
- 写下来
- 具体，不模糊
最小化测试
- 做出最小的可能变更来测试假设
- 一次一个变量
- 不要同时修复多个东西
在继续前验证
- 它工作了吗？是 → 第4阶段
- 没工作？形成新假设
- 不要在顶部添加更多修复
当你不了解时
- 说"我不理解X"
- 不要假装了解
- 请求帮助
- 多研究

第4阶段：实施

修复根本原因，不是症状：

决定测试策略

基于复杂性自动决定：
- 编写测试用于： 复杂算法、业务逻辑、数据转换，其中错误可能发生
- 跳过测试用于： UI组件、React hooks、简单CRUD、直接映射、任何你100%确定正确的
- 测试类型： 仅确定性单元测试 - 没有集成测试、没有复杂模拟、没有异步复杂性
如果编写测试：
- 最简单可能的复现
- 修复前失败的自动化测试
- 验证逻辑，不是实现细节
如果跳过测试：
- 用类型检查/代码检查验证修复
- 手动验证UI变更
- 代码审查信心修复正确
实施单一修复
- 解决已识别的根本原因
- 一次一个变更
- 不要"既然在这里"的改进
- 不要捆绑重构
验证修复

如果编写了测试：
- 现在测试通过了吗？
- 没有其他测试坏了吗？
如果没有测试：
- 类型检查通过了吗？
- 代码检查干净了吗？
- 手动验证确认修复了吗？
总是检查：
- 问题实际解决了吗？
- 相关功能没有回归吗？
如果修复没起作用
- 停止
- 计数：你尝试了多少个修复？
- 如果 < 3：返回第1阶段，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（见步骤5）
- 没有架构讨论，不尝试第4个修复
如果3+修复失败：质疑架构

指示架构问题的模式：
- 每个修复揭示新的共享状态/耦合/不同地方的问题
- 修复需要"大规模重构"来实现
- 每个修复在其他地方产生新症状
停止并质疑基础：
- 这个模式根本健全吗？
- 我们是否"纯粹通过惯性坚持它"？
- 我们应该重构架构vs.继续修复症状吗？
在尝试更多修复前与你的伙伴讨论

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

红旗 - 停止并遵循流程

如果你发现自己思考：

“现在快速修复，稍后调查”
“就尝试改变X看看是否工作”
“添加多个变更，运行测试”
“可能是X，让我修复它”
“我不完全理解，但这可能工作”
“模式说X，但我会不同适应它”
“这里是主要问题：[列出修复而没有调查]”
在追踪数据流前提出解决方案
“再试一个修复”（当已经尝试2+）
每个修复揭示不同地方的新问题
当你确定修复正确时，为UI组件编写测试

所有这些意味着：停止。返回第1阶段。

如果3+修复失败：质疑架构（见第4.5阶段）

你的伙伴的信号你在做错

注意这些重定向：

“那不是发生吗？” - 你假设了而没有验证
“它会展示我们…？” - 你应该添加了证据收集
“停止猜测” - 你不理解就提出修复
“超思这” - 质疑基础，不仅仅是症状
“我们卡住了？”（沮丧） - 你的方法无效

当你看到这些：停止。返回第1阶段。

常见合理化

借口	现实
“问题简单，不需要流程”	简单问题也有根本原因。流程对简单错误更快。
“紧急，没时间进行流程”	系统化调试比猜测和检查更快。
“先尝试这个，然后调查”	第一次修复设置模式。从一开始就做对。
“一次多个修复节省时间”	无法隔离什么工作了。导致新错误。
“参考太长，我会适应模式”	部分理解保证错误。完全阅读它。
“我看到问题，让我修复它”	看到症状 ≠ 理解根本原因。
“再试一个修复”（在2+失败后）	3+失败 = 架构问题。质疑模式，不要再修复。
“UI修复不需要测试”	正确！UI组件通过类型检查/手动测试验证，不是单元测试。

快速参考

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

当流程揭示"没有根本原因"时

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

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

但： 95%的"没有根本原因"案例是不完整调查。

与其他技能的集成

这个技能需要使用：

根因追踪 - 必需当错误在调用栈深处时（见第1阶段，步骤5）

测试技能（当需要时）：

测试驱动开发（如果可用） - 用于修复需要测试覆盖的复杂业务逻辑时
跳过用于UI组件、简单CRUD或任何可通过类型检查/手动测试验证的

现实世界影响

从调试会话：

系统化方法：15-30分钟修复
随机修复方法：2-3小时乱试
第一次修复率：95% vs 40%
新错误引入：近乎零 vs 常见

名称: 调试 描述: 在遇到任何错误、测试失败或意外行为时使用，在提出修复前 - 四阶段框架（根因调查、模式分析、假设测试、实施）确保在尝试解决方案前理解问题