debugging

用途

“debugging”是一个系统化调试技能，用于识别缺陷的根因，而不是只处理表面症状。根据资料，它适合以下情况：缺陷没有明显原因，或者曾被“修复”但再次出现；错误信息不清楚或具有误导性；已经尝试多次修复但都失败；问题可能影响代码库中的多个位置；理解根因对正确解决至关重要。

资料同时指出，以下情况可以跳过该技能：修复方式明显的简单语法错误；琐碎的拼写错误或缺失导入；已有清晰解决方案、隔离良好的已知缺陷。

主要能力

该技能包含一套名为 UNDERSTAND 的十步检查清单，涵盖：捕获精确复现、范围与近期改动；隔离组件或文件并追踪故障路径；检索确切错误并查阅相关文档；与代码库中已知正常的模式对比；使用顺序思考与 5 Whys 分析根因；写出可证伪的假设及其预测；通过日志或测试确认机制；按既定模式施加针对根因的最小修复，并覆盖所有出现位置；记录洞察、警告与决策；按需更新注释、文档或测试。

它还列出需要明确避免的反模式，包括：循环推理（在未理解上次失败原因的情况下重复提出同一修复）、过早宣布胜利、模式遗忘、上下文过载（上下文达到 50% 时重启对话）、只追症状、在理解之前先行实现。

在工具使用方面，技能给出工具决策树：知道精确文本或符号时使用 grep；需要概念或语义定位时使用 codebase_search；需要完整文件上下文时使用 read_file；遇到不熟悉的错误或行为时先使用 Context7:get-library-docs，再使用 WebSearch 与 Parallel Search；需要复杂多假设分析时使用 SequentialThinking:process_thought。

使用方式

资料给出的快速开始流程为：捕获精确复现、范围与近期改动；隔离组件或文件并追踪到故障的路径；研究确切错误并查阅官方文档；对比失败模式与正常工作模式，形成可测试的假设；用最小测试验证，施加最小修复并覆盖所有实例，然后验证。

该技能要求用 TodoWrite 跟踪调试进度：开始时为每个适用步骤创建待办项，包括捕获精确复现与范围、隔离失败组件、研究错误信息、与正常模式对比、根因分析（5 Whys）、写出可证伪假设、用最小测试验证、在所有出现位置应用修复、记录洞察、更新文档与测试。调试过程中将步骤从 in_progress 标记为 completed；卡住时，TodoWrite 可以让被阻塞的步骤可见，帮助判断是否跳过了步骤或陷入循环。只有缺陷足够简单、清单显得多余时，才可跳过步骤。

技能还规定上下文管理方式：在上下文使用约 50% 时重启对话，以避免推理质量下降。重启前应先总结事实、假设、已排除项与下一步，然后用该摘要开始新对话继续。

决策框架

资料提供的决策框架包括：如果同一修复被提出两次，应停止并使用 SequentialThinking:process_thought；如果错误不清楚，通过 WebSearch 与 Parallel Search 检索并用文档验证；如果区域不熟悉，用 codebase_search 探索而不是猜测；如果修复看起来过于简单，确认它针对的是根因而非症状；如果上下文混乱，在 50% 时用摘要重启；如果存在多个假设，明确评估支持与反对的证据；如果类似代码正常，找到并通过 codebase_search 或 read_file 对比差异；如果宣布成功，展示更改的行并做修复前失败、修复后通过的测试；如果修复跨多个文件，搜索并修补所有出现位置；如果对库行为有假设，检查 Context7:get-library-docs。

完成前的质量检查

在宣布缺陷已修复之前，需要验证：根因已识别并记录；修复针对原因而非症状；所有出现位置都已修复（全项目搜索）；遵循既有代码模式；原始症状消除；未引入回归；在相关条件下有测试或日志验证；文档与测试已更新（注释、文档、回归测试）。

参考资料

资料列出两个参考文件：reference/root-cause-framework.md 和 reference/antipatterns.md。

限制

资料未提供该技能的收费、价格、平台支持范围或安装命令等信息，这些事实暂未提供。