- name
遇到任何 bug、测试失败或异常行为时使用,在提出修复方案之前执行
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jnMetaCode/superpowers-zh --skill systematic-debugging -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jnMetaCode/superpowers-zh --skill systematic-debugging -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jnMetaCode/superpowers-zh --skill systematic-debugging -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add jnMetaCode/superpowers-zh --skill systematic-debugging -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/jnMetaCode/superpowers-zh/tree/HEAD/skills/systematic-debuggingFrom the publisher
核心原则: 在尝试修复之前,务必先找到根本原因。只修症状就是失败。
敷衍走流程等于违背调试的精神。
不做根因调查,不许提修复方案
如果你还没完成第一阶段,就不能提出修复方案。
用于任何技术问题:
尤其在以下情况必须使用:
以下情况也不要跳过:
你必须完成每个阶段后才能进入下一个。
在尝试任何修复之前:
仔细阅读错误信息
稳定复现
检查近期变更
在多组件系统中收集证据
当系统有多个组件时(CI → 构建 → 签名,API → 服务 → 数据库):
在提出修复方案之前,先添加诊断埋点:
对每个组件边界:
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置的传递
- 检查每一层的状态
执行一次以收集证据,确定断裂点在哪里
然后分析证据,定位故障组件
然后针对该组件深入调查
示例(多层系统):
# 第 1 层:工作流
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
# 第 2 层:构建脚本
echo "=== Env vars in build script: ==="
printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
# 第 3 层:签名脚本
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# 第 4 层:实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"
由此可以看出: 哪一层出了问题(secrets → workflow ✓, workflow → build ✗)
跟踪数据流
当错误发生在调用栈深处时:
参见本目录下的 root-cause-tracing.md,了解完整的反向追踪技术。
简要版本:
先找到模式,再修复:
找到可正常工作的示例
与参考实现对比
识别差异
理解依赖关系
科学方法:
提出单一假设
最小化测试
继续之前先验证
当你不确定时
修复根本原因,而非症状:
创建失败的测试用例
test-driven-development 技能来编写规范的失败测试实施单一修复
验证修复
verification-before-completion 技能如果修复不起作用
如果 3 次以上修复都失败了:质疑架构
以下模式表明存在架构问题:
停下来质疑根本性问题:
在尝试更多修复之前,和你的搭档讨论
这不是假设失败——这是架构有误。
如果你发现自己在想:
以上这些都意味着:停下来。回到第一阶段。
如果 3 次以上修复都失败了: 质疑架构(见第四阶段第 5 步)
留意这些提醒:
当你看到这些信号时: 停下来。回到第一阶段。
如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的:
但是: 95% 的"找不到根因"其实是排查不充分。
以下技术是系统化调试的组成部分,可在本目录中找到:
root-cause-tracing.md - 沿调用栈反向追踪 bug,找到最初的触发点defense-in-depth.md - 找到根因后,在多个层级添加校验condition-based-waiting.md - 用条件轮询替代硬编码等待时间© 2026 Skills Rack.
---name: systematic-debuggingdescription: 遇到任何 bug、测试失败或异常行为时使用,在提出修复方案之前执行---# skills/systematic-debugging/SKILL.mdFAQ
Download skills/systematic-debugging/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/jnMetaCode/superpowers-zh.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.