systematic-debugging Skill：让 AI 调试从”猜猜猜”变”系统分析”的结构化神器

systematic-debugging Skill：让 AI 调试从”猜猜猜”变”系统分析”的结构化神器

功能与原则

systematic-debugging 是 Superpowers 技能体系中的核心调试技能，本质是一套强制执行根因分析的结构化方法论。它的铁律是：在找到根因之前，绝不提议任何修复方案。这听起来是常识，但在实际调试中，AI 和人类都极易跳过这一步直接”试试这个”。该 Skill 通过四阶段流程 + 红线警告 + 人机协作信号，把调试从随机试错变成可重复的科学过程。

认可度

• GitHub Star：obra/superpowers 截至 2026-08-03 约 26.5 万星，是当前最热门的 AI Coding Agent 技能框架之一
• SkillHub 评级：S-Rank（9.2 分），Hot Skills 排名第 3，热度分数 48.8
• 多 Agent 兼容：Claude Code、Codex、Claude CLI、OpenCode、OpenClaw、GitHub Copilot、Cursor、Windsurf、Cline、Roo、Kiro、Junie、Augment、Warp、Goose 等 15 个平台通吃
• 行业认可：SkillHub 官方将其列入 S 级推荐，是 SkillHub 评价体系中最高档位

GitHub：https://github.com/obra/superpowers

原作者

@obra（GitHub），Superpowers 技能框架作者。obra 同时也是 systematic-debugging、test-driven-development、verification-before-completion、subagent-driven-development 等多个高评级 Skill 的创建者，专注于为 AI Coding Agent 构建工程方法论体系。

介绍

Superpowers 是一个完整的 AI 编码智能体软件开发方法论，而 systematic-debugging 是其核心技能之一。它解决的核心问题是：随机修复（random fixes）浪费时间，还引入新 bug。

该 Skill 提供了一个四阶段调试流程：

• 第一阶段：根因调查——仔细阅读错误信息、稳定复现、检查近期变更、在多组件系统中逐层收集证据
• 第二阶段：模式分析——找到同类正常工作的代码，与坏掉的代码逐项对比，找出差异
• 第三阶段：假设与测试——形成单一假设，最小化改动测试，验证后推进
• 第四阶段：实施——创建失败的测试用例、实施单一修复、验证修复有效

当连续 3 次修复都失败时，Skill 会强制停止并提示”质疑架构”，防止在错误基础上继续浪费。

特点

• 铁律执行：NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST——Phase 1 未完成，禁止提议修复
• 多组件诊断：提供跨层诊断命令模板（Layer 1: 工作流 → Layer 2: 构建脚本 → Layer 3: 签名脚本），逐层追踪数据流
• 红牌警告：9 条红线信号，覆盖”快速修复””多改并行””跳过测试”等常见错误思维
• 人机协作信号：内置”你的伙伴在发信号”模块，识别”Stop guessing””Ultrathink this”等人发出的停止猜测提示
• 量化效果：结构化调试 15-30 分钟 vs 随机修复 2-3 小时；首次修复率 95% vs 40%

使用方法

安装（任意 Agent）：

在支持的 Agent 中直接安装对应插件，或手动复制 SKILL.md 到本地技能目录。以 Claude Code 为例：

# 方式一：Claude 官方插件市场
/plugin install superpowers@claude-plugins-official

# 方式二：手动安装
将 SKILL.md 放入 ~/.claude/skills/ 目录

触发方式：当遇到 Bug、测试失败或异常行为时，直接描述问题，Skill 自动激活四阶段流程。

最小调用示例：

User: CI 构建报错 "No identity found"，本地正常
↓
Agent 自动进入 Phase 1：
  - 检查错误信息：codesign: No identity found
  - 复现：仅在 CI 环境触发
  - 检查变更：昨天新增了 GitHub Actions workflow
  - 多组件证据收集：逐层验证 secrets → workflow → build script → signing script
↓
根因定位：CI 使用临时 keychain，证书未持久化
↓
Phase 4 修复：添加 keychain 导入步骤

使用场景与人群

• 适用场景：测试失败排查、生产 Bug 定位、CI/CD 异常、多服务集成问题、构建失败
• 目标用户：软件开发者、工程师、技术负责人，尤其适合 AI Coding Agent 用户（Cursor/Claude Code/Windsurf 等）
• 特别适用：时间紧迫时（”紧急情况更不能猜”）、连续多次修复失败后、问题”看起来简单但一直修不好”

输入与输出案例

案例 1：CI iOS 签名失败

• 输入：CI 报错 codesign: No identity found，本地 Mac 签名正常
• Agent 根因调查：逐层诊断发现 secrets → workflow ✓，workflow → build script ✓，build script → signing script ✗（证书未导入临时 keychain）
• 输出：Phase 4 添加 keychain 导入步骤，CI 通过，应用签名成功 ✅

案例 2：API 返回错误数据

• 输入：某 API 端点在生产返回 null，但预发正常
• Agent 多组件追踪：API service → database proxy → database，三层日志对比
• 输出：发现数据库连接池配置差异（预发 max_connections=100，生产=10），根因定位后优化连接池配置修复

GitHub: https://github.com/obra/superpowers