基于 SOC 职业分类
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/DawnMoon1542/agents-skills --skill systematic-debugging命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | systematic-debugging |
| description | 遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用 |
随机修复浪费时间并产生新 bug。快速补丁掩盖了底层问题。
核心原则： 在尝试修复之前，务必先找到根本原因。仅修复症状即为失败。
违反此流程的文字精神，即是违反调试的灵魂。
未完成根本原因调查之前，不得进行任何修复
如果你尚未完成阶段 1，就不能提出修复方案。
适用于任何技术问题：
以下情况尤其需要使用：
以下情况不要跳过：
每个阶段完成之后才能进入下一阶段。
在尝试任何修复之前：
仔细阅读错误消息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：
在提出修复方案之前，添加诊断工具：
对每个组件边界：
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
运行一次以收集证据，显示问题发生在哪里
然后分析证据以确定出错的组件
然后深入调查该特定组件
示例（多层系统）：
# 第 1 层：工作流
echo "=== 工作流中可用的密钥：==="
echo "IDENTITY: ${IDENTITY:+已设置}${IDENTITY:-未设置}"
# 第 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。
快速版本：
修复之前先找到模式：
寻找正常工作的示例
对照参考资料进行比较
识别差异
理解依赖关系
科学方法：
形成单个假设
最小化测试
验证后再继续
当你不确定时
修复根本原因，而不是症状：
创建失败的测试用例
test-driven-development 技能编写合适的失败测试实施单一修复
验证修复
如果修复不生效
如果 3 次以上修复失败：质疑架构
表明存在架构问题的模式：
停止并质疑基础：
与用户讨论后再尝试更多修复
这不是假设失败——这是架构错误。
如果你发现自己在想：
以上所有情况都意味着：停止。返回阶段 1。
如果 3 次以上修复失败： 质疑架构（见阶段 4.5）
注意以下纠正信号：
当看到这些信号时： 停止。返回阶段 1。
| 借口 | 现实 |
|---|---|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 来说也很快。 |
| "紧急情况，没时间走流程" | 系统化调试比猜测-检查式的反复折腾更快。 |
| "先试试这个，然后再调查" | 第一次修复定下基调。从一开始就做对。 |
| "确认修复生效后再写测试" | 未经测试的修复不会稳固。先写测试来证明。 |
| "一次修多个省时间" | 无法隔离什么起了作用。还会产生新 bug。 |
| "参考太长了，我适配一下模式就行" | 部分理解必然导致 bug。完整阅读。 |
| "我看到问题了，我来修" | 看到症状不等于理解根本原因。 |
| "再试一次修复"（2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要再修了。 |
| 阶段 | 关键活动 | 成功标准 |
|---|---|---|
| 1. 根本原因 | 阅读错误、复现、检查变更、收集证据 | 理解是什么和为什么 |
| 2. 模式 | 寻找正常工作的示例、对比 | 识别差异 |
| 3. 假设 | 形成理论、最小化测试 | 确认或形成新假设 |
| 4. 实施 | 创建测试、修复、验证 | bug 解决、测试通过 |
如果系统化调查显示问题确实是环境性的、时间相关的或外部性的：
但是： 95% 的"没有根本原因"案例都是不完整的调查。
这些技术是系统化调试的组成部分，可在本目录中找到：
root-cause-tracing.md - 通过调用栈反向追踪 bug 以找到原始触发点defense-in-depth.md - 在找到根本原因后在多个层级添加验证condition-based-waiting.md - 用条件轮询替代任意超时来自调试实践的数据：