关于 debug-tools
一种迭代式调试技能，引导问题调查、证据收集、修复与验证。它会记录反复失败，并在三次尝试后停止局部修补，转而要求进行架构评估。
主要功能
- 01基于清单的调试工作流
- 02依据证据为假设排序
- 03与正常工作的代码比较
- 04通过日志收集运行时证据
- 05验证修复并清理调试日志
- 06三次失败后升级评估
适用场景
- 01调查已报告的错误
- 02对照正常代码追踪回归问题
- 03需要运行时证据时添加日志
- 04验证后清理调试日志
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/debug-tools确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
README.mdagents/openai.yamlreferences/debugging-patterns.mdinvestigation.mdlog-cleanup.mdlog-injection.mdscripts/debug_logs.py详细介绍
调试工具
通过迭代式调试工作流，要求修复必须有证据支持，并在反复失败后升级处理。
触发条件
- 调试 bug（“调试这个”“调查”“追踪问题”“修复 bug”“为什么 X 出问题了”）→ 第 1 步
- 回归或对比（“以前能用”“更新后坏了”“那里能用，但这里不能用”）→ 第 2 步
- 添加调试日志（“添加调试日志”“注入日志”“用日志追踪”）→ 第 3 步
- 清理日志（“移除调试日志”“清理日志”）→ 第 5 步
工作流
复制此检查清单并逐项勾选：
Progress:
- [ ] Step 1: Investigate
- [ ] Step 2: Compare against working code (when needed)
- [ ] Step 3: Gather runtime evidence (when needed)
- [ ] Step 4: Fix and verify
- [ ] Step 5: Clean up logs
从会话状态所指示的步骤开始；已有证据的会话无需从第 1 步重新开始。
第 1 步。调查。 加载 investigation.md，并按顺序完成其中从“理解 bug”到“排列假设”各节的工作。完成标准：每个假设都有评分和证据类型，且排在首位的假设要么已有证据，要么明确指出所需的运行时数据。
第 2 步。与可正常工作的代码对比。 当分析陷入停滞，需要将出错的代码与正常工作的示例进行差异对比，或用户报告某项功能以前能用时，加载 debugging-patterns.md。完成标准：已取得对比结果或回归追踪记录；然后返回第 1 步，重新排列假设。
第 3 步。收集运行时证据。 当阅读代码无法揭示运行机制，且只有观察运行中的系统才能查明时，加载 log-injection.md。完成标准：已查看复现过程的输出；然后返回第 1 步，重新排列假设。
第 4 步。修复并验证。 完成 investigation.md 中的“提出修复方案”“验证”和“报告”各节。完成标准：复现时不再出现该症状，并已撰写报告。如果症状依然存在，请根据本次运行结果返回第 1 步。
第 5 步。清理日志。 修复验证通过后，或收到明确请求时，加载 log-cleanup.md。在将更改提交到版本控制之前运行该流程。完成标准：脚本的 find 命令未报告任何 [DEBUG] 语句，且项目的语法检查通过。
敏感值绝不能出现在注入的日志中，包括密码、令牌、API 密钥、PII 和会话标识符。此要求适用于添加日志的任何场景，包括尚未加载第 3 步时在调查过程中途添加日志。
反模式：症状打地鼠
在多个位置修复同一症状，说明存在架构问题，而非局部 bug。对于症状仍然存在的每份第 4 步报告，都以 Attempt N of 3 结尾，并在提出另一次修复方案前读出该数字。尝试三次后停止修复：第四步是向用户进行架构评估，说明尝试过什么以及失败原因、问题是否属于系统性问题（抽象错误、缺少层级、假设有误），以及能够解决问题的架构变更。若根因不断变化、每次尝试的变更规模不断扩大，或置信度评分逐次降低，则应更早停止并重新评估。