用途
Debug 是一项结构化的调试技能,把排查缺陷的过程拆成 7 个固定阶段,要求按顺序推进。当某个阶段未满足其门槛时,应回退到前一阶段,而不是跳过。它还强调修复前必须先有一个可复现的失败测试。
主要能力:7 个阶段与门槛
阶段 1 — 症状捕获:在改动任何代码前完整收集症状,记录:精确错误文本(不能转述)、堆栈或日志片段、受影响的路由/组件/模块、环境(本地、CI 或生产)、首次出现的提交或部署(若已知)。门槛:在工作笔记中写出一段式的事件描述。
阶段 2 — Git 历史排查:找出最可能的因果变更。文档给出如下命令:
git log --oneline -20 git diff HEAD~5..HEAD -- <suspected-path> git log --oneline --all -- <suspected-path>
门槛:指出最可能的因果提交,或记录无法确定。
阶段 3 — 用针对性测试复现:没有可复现的失败前,不得进入阶段 4。选择能复现症状的最小命令;若无现成测试覆盖,先写一个最小失败测试,这一步是 TDD Red 步骤,不可省略。文档示例:
Targeted test
<test-runner> <specific-test-file>
Broader search
<test-runner>
门槛:记录确切的测试名称和失败信息;若无法产生红色测试,回到阶段 1。
阶段 4 — 日志检查:症状已被定位后读取日志。
Local
<dev-server-command> 2>&1 | tee /tmp/debug.log
Production
<log-command> --tail 100
关注:缺失环境变量、API 错误码、未处理的 rejection、数据库错误、时序漂移。门槛:抓到相关日志片段。
阶段 5 — 假设 + 最小验证:改动前先给出单个可证伪的假设,格式为「我认为缺陷由 X 引起,因为 Y。我将用 Z 验证。」写最小测试或探针来证实或证伪,此阶段不做修复。若被证伪,带着新证据回到阶段 2。门槛:假设通过验证。
阶段 6 — 修复 + 确认通过:做最小的代码改动让阶段 3 的测试变绿,不多改。然后运行完整检查:
<typecheck-command> <test-command>
要求填写修复前后基线对比表(指标列:通过测试数、失败测试数、新增测试数,新增测试基线为 0)。门槛:失败数相较基线不得增加。
阶段 7 — 回归测试 + 提交:确认阶段 3 的复现测试为绿并已提交。提交信息格式:
fix(<area>): <short description>
Root cause: <why> Symptom: <what the user saw> Fix: <what changed> Regression: tests/<path>
Closes #<issue-number>
推送到分支并开 PR,绝不直接推 main。
阶段-门槛清单
文档末尾给出逐项核对清单:阶段 1 用精确错误文本捕获症状;阶段 2 指出最可能的因果提交;阶段 3 红色测试存在且观察到失败;阶段 4 抓到相关日志片段;阶段 5 在任何修复前陈述假设;阶段 6 填好前后基线表且失败数未增加;阶段 7 回归测试已提交并在分支上开 PR。
使用方式与适用场景
该技能以可复用的工作流清单形式提供,通过 skills.sh 上的技能页面使用,适合在本地开发、CI 和生产缺陷排查中作为团队统一的调试流程,尤其适合需要留下可审计排查记录、强调测试先行与最小改动的场景。
限制
资料未提供具体安装命令、支持的测试运行器类型、与特定语言或框架的绑定情况、自动化程度,也未说明收费或平台支持情况;文中命令中的 <test-runner>、<dev-server-command>、<log-command>、<typecheck-command>、<test-command> 等均为占位符,需使用者按自身项目替换。