common-systematic-debugging

# 系统化调试技能 ## 功能描述 提供结构化的 bug 排查流程，确保在动手修复前先定位根因，避免头痛医头式的猜测式修复。 ## 触发条件 - 遇到 bug 需要排查根因时 - 测试失败、线上报错、非预期行为时 - 已经试过多个修复还没解决时 ## 何时使用 **遇到任何技术问题时都用它：** - 测试失败 - 生产 bug - 非预期行为 - 性能问题 - 构建失败 - 集成问题 **尤其在以下情况务必使用：** - 时间压力大（紧急情况最容易让人想猜测） - "快速修一下"似乎很明显 - 已经试过多个修复 - 上一次修复没生效 - 不完全理解问题 ## 核心原则 ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` 没完成 Phase 1 就不能提修复方案。症状修复 = 失败。 ## 核心功能 - **Phase 1 根因调查**：读错误、复现、查变更、多组件加诊断日志、数据流追踪 - **Phase 2 模式分析**：找正常例子、对比差异、理解依赖 - **Phase 3 假设验证**：科学方法，单一假设，最小化验证 - **Phase 4 实施修复**：先写失败测试再修根因，3+ 次失败质疑架构 ## 输入参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | issue | String | 是 | 问题描述（错误信息、现象） | | environment | String | 否 | 环境（本地/CI/生产） | | attempts | Number | 否 | 已尝试的修复次数 | ## 输出格式 ```json { "phase": "Phase 1", "rootCause": "已定位根因", "hypothesis": "当前假设", "evidence": ["证据1", "证据2"], "nextAction": "下一步行动", "fixNeeded": false } ``` ## 四阶段流程详解 ### Phase 1: 根因调查（未完成不能提修复） 1. **仔细读错误信息** - 不要跳过 error/warning - 完整读 stack trace - 记下文件路径、行号、错误码 2. **稳定复现** - 能稳定触发吗？ - 精确复现步骤是什么？ - 每次都发生还是偶发？ - 不能复现 → 收集更多数据，别猜 3. **检查最近变更** - `git diff` / 最近提交 - 新增依赖、配置变更 - 环境差异（本地 vs CI vs 生产） 4. **多组件系统加诊断日志** **系统有多层时（CI→构建→签名 / API→服务→DB）：** 在每个边界加日志，记录数据进出： ```bash # 示例：工作流层 echo "Secrets available: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 示例：构建脚本层 env | grep IDENTITY || echo "IDENTITY not in environment" # 示例：签名脚本层 security find-identity -v ``` 跑一次收集证据 → 确认**哪一层断了** → 去查那层。 5. **数据流追踪** - 坏值从哪来的？ - 谁传进来的？ - 一路往上追到源头 - **在源头修，不是在症状处修** ### Phase 2: 模式分析 1. **找正常工作的例子** - 同代码库里有没有类似且正常的？ - 它们和问题代码有什么不同？ 2. **对照参考实现** - 如果是某个模式，完整读参考实现 - 不要扫一眼就应用 3. **列出所有差异** - 工作和不工作的代码有什么不同？ - 一个不漏地列出来，再小的差异都算 - 不要假设"这个不会影响" 4. **理解依赖** - 这个组件需要什么？ - 什么配置/环境/前置条件？ - 它对外部世界有什么假设？ ### Phase 3: 假设与验证（科学方法） 1. **形成单一假设** - 明确陈述："我认为 X 是根因，因为 Y" - 写下来，别凭感觉 - 要具体，不能模糊 2. **最小化验证** - 做**最小**改动测试假设 - 一次只改一个变量 - 不同时修多个问题 3. **验证后再继续** - 成功？→ Phase 4 - 失败？→ 形成**新**假设，**不要**在旧假设上叠加修修修 4. **不懂就说不懂** - "我不理解 X" - 别装懂 - 去查去问去研究 ### Phase 4: 实施修复 1. **先写失败测试**（见 common-test-driven-development） - 最简复现 - 能写自动化测试就写 - 没有框架就写临时脚本 - **修之前必须有测试** 2. **实施单一修复** - 只解决 Phase 1 定位的根因 - 一次一个 change - 别"顺便"重构其他东西 3. **验证修复** - 测试通过？ - 其他测试没坏？ - 问题真的解决了？ 4. **如果修复没生效：STOP** - 统计：已经试过几个修复了？ - < 3 次 → 回到 Phase 1，用新信息重新分析 - **≥ 3 次 → 停下来质疑架构（见下条）** 5. **3+ 修复都失败了？质疑架构** 典型症状： - 每个修复都在不同地方暴露新问题 - 修复需要"大重构"才能落地 - 修完 A 又在 B 出问题 **STOP**，和人讨论： - 这个模式本身合理吗？ - 是不是因为惯性在硬扛？ - 要不要重构架构？ ## 红线警告 - 回到 Phase 1 如果发现自己在想这些，**停下，回到调查阶段：** - "先快速修一下，回头再查" - "改一下 X 试试看" - "多改几个一起测" - "跳过测试，手动验证" - "大概是 X 的问题" - "我不完全懂但可能有用" - "修过 2 次了，再试一个方案"（≥3 次 = 架构问题） ## 调试后处理 修复完成后： 1. 记录根因和修复方式 2. 加监控/日志，防止下次再猜 3. 如果根因是环境/依赖问题，考虑加防御性检查 4. 如果这是架构问题，列入重构清单 ## 四阶段速查 | 阶段 | 关键活动 | 成功标准 | |------|----------|----------| | **1. 根因调查** | 读错误、复现、查变更、收集证据 | 理解「是什么」和「为什么」 | | **2. 模式分析** | 找正常例子、对比差异 | 定位真正的不同点 | | **3. 假设验证** | 形成理论、最小化测试 | 确认或推翻假设 | | **4. 实施修复** | 写测试、修根因、验证 | bug 解决、测试通过 | ## 与现有 skill 的关系 - **common-test-driven-development**：Phase 4 必须配合使用，修 bug 先写失败测试 - **common-coding**：修复时遵循编码规范 - **common-code-review**：修复后走代码审查 ## 参考来源 原始 skill：`obra/superpowers@systematic-debugging` 来源仓库：https://github.com/obra/superpowers 安装命令：`npx skills add obra/superpowers@systematic-debugging -y -g`