name: 调试 description: 系统性调试，旨在识别根本原因而非治标。使用顺序思考进行复杂分析，网络搜索进行研究，结构化调查以避免循环推理和治标不治本的修复。

调试

快速入门

捕获准确的复现步骤、范围和近期更改
隔离组件/文件；追踪失败路径
研究具体错误；检查官方文档
比较失败与正常工作模式；形成可测试的假设
用最小化测试验证；在所有实例中应用最小化修复；验证效果

使用此技能的时机

在以下情况下使用调试技能：

漏洞无明确原因或已被“修复”但再次出现
错误消息模糊或误导
多次尝试修复失败
问题可能影响代码库中的多个位置
理解根本原因对正确解决至关重要

在以下情况下跳过此技能：

具有明显修复的简单语法错误
轻微拼写错误或缺失导入
理解清晰、隔离的漏洞，具有明确解决方案

核心应避免的反模式

基于AI调试中记录的失败案例，明确避免：

循环推理：永远不要提出两次相同的修复，而不了解它为何失败
过早胜利：始终验证修复已实际实施并有效
模式遗忘：在整个会话中保持对现有代码模式的认知
上下文过载：使用50%规则——当上下文使用达到50%时重新开始对话
症状追逐：拒绝仅根据错误消息进行修复，而不理解根本原因
理解前实施：在检查现有模式之前，绝不跳到代码更改

理解（10步检查清单）

理解：捕获准确的复现步骤、范围和近期更改
缩小：隔离组件/文件；追踪失败路径
发现：研究具体错误（WebSearch → Parallel Search，Context7:get-library-docs）
检查：与代码库中已知良好模式进行比较
推理：使用SequentialThinking:process_thought和5个为什么方法达到根本原因
合成：编写可证伪的假设并进行预测
测试：添加日志/测试以确认机制
应用：针对根本原因应用最小化修复，在所有出现处遵循模式
记录：记录见解、警告、决策
文档：根据需要更新注释/文档/测试

使用TodoWrite进行进度跟踪

使用TodoWrite通过理解检查清单跟踪调试进度：

开始时：为每个适用步骤创建待办事项：

☐ U - 捕获准确的复现步骤和范围
☐ N - 隔离故障组件
☐ D - 研究错误消息
☐ E - 与工作模式进行比较
☐ R - 根本原因分析（5个为什么）
☐ S - 编写可证伪的假设
☐ T - 用最小化测试验证
☐ A - 在所有出现处应用修复
☐ N - 记录见解
☐ D - 更新文档/测试

调试期间：标记步骤为进行中 → 完成，按工作进展
遇到阻碍时：TodoWrite可视化显示哪个步骤被阻塞——有助于识别是否跳过步骤或陷入循环
仅跳过步骤如果：漏洞足够简单，检查清单是多余的（参见“跳过此技能的时机”以上）

工具决策树

知道确切的文本/符号？ → grep
需要概念/语义位置？ → codebase_search
需要完整文件上下文？ → read_file
不熟悉的错误/行为？ → Context7:get-library-docs，然后WebSearch → Parallel Search
复杂的多假设分析？ → SequentialThinking:process_thought

上下文管理

当上下文使用达到约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