Files

T

KeyInfo Bot c9d4e644de Sync third-party and MCP marketplace plugins

Constraint: Public skills are published only by explicit administrator action unless they are tracked third-party market sources.
Confidence: high
Scope-risk: narrow
Directive: Keep private/internal skills out of the public marketplace and preserve normal incremental market Git history.
Tested: Marketplace validation passed.

2026-07-24 14:20:35 +08:00

9.7 KiB

Raw Blame History

name, description

name	description
systematic-debugging	在遇到任何缺陷、测试失败或意外行为时使用，且应先于提出修复方案

系统化调试

概述

核心原则： 在尝试修复之前，始终先找出根因。只修复症状就是失败。

违反此流程的字面规定，就是违背调试的精神。

铁律

未先调查根因，绝不进行修复

如果你尚未完成阶段 1，就不能提出修复方案。

何时使用

用于任何技术问题：

测试失败
生产环境中的缺陷
意外行为
性能问题
构建失败
集成问题

以下情况尤其要使用：

面临时间压力时（紧急情况会诱使人凭猜测行事）
“只做一个快速修复”看起来显而易见时
你已经尝试过多个修复方案时
之前的修复没有奏效时
你并未完全理解问题时

以下情况也不要跳过：

问题看起来很简单（简单的缺陷也有根因）
你正赶时间（仓促行事必然导致返工）
管理者要求现在就修好（系统化方法比盲目折腾更快）

四个阶段

在进入下一个阶段之前，你必须完成当前阶段。

阶段 1：根本原因调查

在尝试任何修复之前：

仔细阅读错误消息
- 不要略过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 记录行号、文件路径、错误代码
稳定复现
- 你能可靠地触发它吗？
- 确切的步骤是什么？
- 它是否每次都会发生？
- 如果无法复现 → 收集更多数据，不要猜测
检查近期变更
- 哪些变更可能导致了这个问题？
- Git diff、近期提交
- 新依赖、配置变更
- 环境差异

在多组件系统中收集证据

当系统包含多个组件时（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"

这会揭示： 哪一层发生故障（机密信息 → 工作流 ✓，工作流 → 构建 ✗）

追踪数据流

当错误位于调用堆栈深处时：

有关完整的反向追踪方法，请参阅此目录中的 root-cause-tracing.md。

快速版本：
- 错误值源自哪里？
- 是什么用这个错误值调用了这里？
- 持续向上追踪，直到找到源头
- 在源头修复，而不是在症状处修复

阶段 2：模式分析

修复前先找到模式：

寻找可用示例
- 在同一代码库中找到类似且正常工作的代码
- 与出问题的代码相似且能够正常工作的是什么？
与参考实现进行比较
- 如果要实现某种模式，请完整阅读参考实现
- 不要略读——阅读每一行
- 在应用该模式之前，先充分理解它
识别差异
- 正常工作的代码与出问题的代码之间有什么不同？
- 列出每一处差异，无论多么细微
- 不要假定“那不可能有影响”
理解依赖项
- 这还需要哪些其他组件？
- 需要哪些设置、配置和环境？
- 它基于哪些假设？

阶段 3：假设与测试

科学方法：

提出单一假设
- 明确陈述：“我认为 X 是根本原因，因为 Y”
- 把它写下来
- 要具体，不要含糊
最小化测试
- 做出可能的最小改动来测试假设
- 一次只改变一个变量
- 不要同时修复多个问题
继续之前先验证
- 成功了吗？是 → 阶段 4
- 没成功？提出新的假设
- 不要在此基础上叠加更多修复
当你不知道时
- 说“我不理解 X”
- 不要假装知道
- 寻求帮助
- 进一步研究

阶段 4：实施

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

创建失败测试用例
- 尽可能简单的复现
- 如果可能，使用自动化测试
- 如果没有测试框架，则使用一次性测试脚本
- 修复前必须具备
- 使用 superpowers:test-driven-development 技能编写正确的失败测试
实施单一修复
- 处理已识别出的根本原因
- 一次只做一项更改
- 不要做“既然都到这里了”式的改进
- 不要捆绑重构
验证修复
- 测试现在通过了吗？
- 是否没有破坏其他测试？
- 问题是否确实已解决？
- 在宣称成功之前，使用 superpowers:verification-before-completion 技能
如果修复不起作用
- 停止
- 计数：你已经尝试了多少个修复方案？
- 如果 < 3：返回阶段 1，结合新信息重新分析
- 如果 ≥ 3：停止并质疑架构（见下方第 5 步）
- 未经架构层面的讨论，不要尝试第 4 个修复方案
如果 3 个以上修复方案均告失败：质疑架构

表明存在架构问题的模式：
- 每个修复方案都会在不同位置暴露新的共享状态、耦合或问题
- 修复方案需要“重大重构”才能实施
- 每个修复方案都会在其他地方产生新的症状
停止并质疑根本原则：
- 这种模式从根本上来说是否合理？
- 我们是否“仅仅因为惯性而坚持下去”？
- 我们应该重构架构，还是继续修复症状？
在尝试更多修复方案之前，与你的人类伙伴讨论

这不是假设失败——而是架构错误。

红旗项——停止并遵循流程

如果你发现自己在想：

“暂时快速修一下，之后再调查”
“只要试着修改 X，看看是否有效”
“加入多项改动，然后运行测试”
“跳过测试，我会手动验证”
“可能就是 X，让我修一下”
“我并不完全理解，但这样也许有效”
“模式要求 X，但我会用不同的方式调整它”
“以下是主要问题：[lists fixes without investigation]”
在追踪数据流之前提出解决方案
“再尝试修一次”（已经尝试 2+ 次时）
每次修复都会在不同位置暴露出新问题

所有这些都意味着：停止。回到阶段 1。

**如果 3+ 次修复均告失败：**质疑架构（见阶段 4.5）

你的人类伙伴发出的、表明你做错了的信号

留意这些纠偏信号：

“那不是正在发生吗？”——你未经验证就作出了假设
“它会向我们显示……吗？”——你本应加入证据收集环节
“别再猜了”——你在尚未理解问题时就提出修复方案
“超深入地思考这个问题”——质疑根本前提，而不只是症状
“我们卡住了吗？”（感到沮丧）——你的方法行不通

**看到这些信号时：**停止。回到阶段 1。

常见的自我合理化

借口	事实
“问题很简单，不需要流程”	简单问题也有根本原因。对于简单缺陷，这个流程也很快。
“紧急情况，没时间走流程”	系统化调试比猜测—检验式的反复折腾快得多。
“先试一下这个，然后再调查”	第一次修复会定下后续模式。从一开始就把它做对。
“确认修复有效后，我再写测试”	未经测试的修复无法持久。先写测试才能证明它。
“同时进行多项修复能节省时间”	无法确定究竟是哪项改动起了作用。还会引入新的缺陷。
“参考资料太长了，我会调整这个模式”	一知半解必然导致缺陷。完整阅读它。
“我看到了问题，让我修复它”	看到症状 ≠ 理解根本原因。
“再尝试修一次”（在 2+ 次失败后）	3+ 次失败 = 架构问题。质疑这个模式，不要再次尝试修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误信息、复现问题、检查变更、收集证据	理解发生了什么以及为什么会发生
2. 模式	找到可正常工作的示例、进行比较	识别差异
3. 假设	形成理论，以最小范围进行测试	假设得到确认，或形成新假设
4. 实施	创建测试、修复、验证	缺陷已解决，测试通过

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

如果系统化调查表明问题确实由环境因素、时序依赖或外部因素导致：

你已经完成了该流程
记录你调查过的内容
实施适当的处理措施（重试、超时、错误消息）
添加监控/日志记录，以供将来调查

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

辅助技术

这些技术是系统化调试的一部分，可在此目录中找到：

root-cause-tracing.md - 沿调用栈反向追踪 bug，以找到最初的触发因素
defense-in-depth.md - 找到根本原因后，在多个层级添加验证
condition-based-waiting.md - 使用条件轮询替代任意超时

9.7 KiB Raw Blame History