名称: 调试描述: 系统化调试，识别根本原因而非治疗症状。使用顺序思维进行复杂分析，网络搜索进行研究，以及结构化调查，以避免循环推理和打地鼠式修复。

调试

快速入门

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

何时使用此技能

在以下情况下使用调试：

错误没有明显原因或之前被“修复”但返回
错误消息不清晰或误导性
多次尝试修复失败
问题可能影响代码库中的多个位置
理解根本原因对正确解决至关重要

跳过此技能用于：

具有明显修复的简单语法错误
琐碎的拼写错误或缺失导入
理解清楚、孤立且有明确解决方案的错误

核心反模式避免

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

循环推理：不要在未了解失败原因的情况下两次提出相同修复
过早胜利：始终验证修复是否实际实施并工作
模式遗忘：在整个会话中保持对已建立代码模式的意识
上下文过载：使用50%规则 - 当上下文达到50%时重新开始对话
症状追逐：抵制在不理解根本原因的情况下修复错误消息
理解前实施：在检查现有模式之前不要跳转到代码更改

UNDERSTAND（10步检查清单）

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

使用TodoWrite进行进度跟踪

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

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

☐ 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

名称: 调试 描述: 系统化调试，识别根本原因而非治疗症状。使用顺序思维进行复杂分析，网络搜索进行研究，以及结构化调查，以避免循环推理和打地鼠式修复。

调试