mcpField
D
debugging

debugging

github.com/ratacat开发5845 次安装37 周前更新
代码仓库

关于 debugging

面向编码 Agent 的调试技能，适用于原因不明、反复出现或影响多处代码的问题。它强调定位根因、提出可验证假设，并通过测试确认最小修复有效。

主要功能

  1. 01记录复现步骤与范围
  2. 02隔离故障路径
  3. 03分析根本原因
  4. 04基于假设进行测试
  5. 05验证修复与回归

适用场景

  1. 01调查反复出现的 Bug
  2. 02追踪含糊的错误信息
  3. 03检查多个文件中的修复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ratacat/claude-skills --skill debugging

安装后在 Claude Code 中输入/debugging确认已加载。

附带文件reference/antipatterns.mdreference/root-cause-framework.md

详细介绍

调试

快速入门

  1. 记录精确的复现步骤、影响范围和近期更改
  2. 隔离组件/文件；追踪导致故障的路径
  3. 搜索确切的错误信息；查阅官方文档
  4. 对比失败与正常的模式；提出可测试的假设
  5. 通过最小化测试验证；在所有实例中应用最小修复；进行验证

何时使用此技能

在以下情况下使用调试：

  • Bug 没有明显原因，或之前“修复”过但又复发
  • 错误信息不清楚或具有误导性
  • 多次尝试修复均告失败
  • 问题可能影响代码库中的多个位置
  • 了解根本原因对妥善解决问题至关重要

以下情况可跳过此技能：

  • 有明显修复方法的简单语法错误
  • 无关紧要的拼写错误或缺少导入
  • 已充分了解、范围明确且解决方案清晰的 Bug

需要避免的核心反模式

根据有记录的 AI 调试失败案例，明确避免：

  1. 循环推理：不要在未弄清失败原因前重复提出同一修复方案
  2. 过早宣告成功：始终验证修复是否确实已实施并且有效
  3. 模式遗忘：整个会话中都要留意已确立的代码模式
  4. 上下文过载：遵循 50% 规则——上下文达到 50% 时重新开始对话
  5. 追逐症状：不要在未了解根本原因时只修复错误信息
  6. 未理解就实施：检查现有模式之前，绝不要直接修改代码

理解（10 步检查清单）

  • 理解：记录精确的复现步骤、影响范围和近期更改
  • 缩小范围：隔离组件/文件；追踪导致故障的路径
  • 探查：搜索确切的错误信息（WebSearch → Parallel Search，Context7:get-library-docs）
  • 检查：与代码库中已知正常的模式进行比较
  • 推理：使用 SequentialThinking:process_thought 和 5 Whys 找出根本原因
  • 综合：编写可证伪的假设，并列出预测
  • 测试：添加日志/测试以确认问题机制
  • 应用：遵循现有模式，针对根本原因实施最小修复，并覆盖所有出现位置
  • 记录：记录见解、警告和决策
  • 编写文档：按需更新注释/文档/测试

使用 TodoWrite 跟踪进度

使用 TodoWrite 跟踪调试进度，逐项完成“理解”检查清单：

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

    ☐ U - Capture exact repro and scope
☐ N - Isolate failing component
☐ D - Research error message
☐ E - Compare with working patterns
☐ R - Root cause analysis (5 Whys)
☐ S - Write falsifiable hypothesis
☐ T - Verify with minimal test
☐ A - Apply fix across all occurrences
☐ N - Record insights
☐ D - Update docs/tests

  2. 调试期间：随着工作的推进，将步骤标记为 in_progress → completed

  3. 遇到阻碍时：TodoWrite 会显示受阻的步骤，帮助判断你是否跳过了步骤或陷入循环

  4. 仅在以下情况下跳过步骤：Bug 足够简单，检查清单显得过于繁琐（见上文“以下情况可跳过此技能”）

工具决策树

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

上下文管理

  • 上下文使用量达到约 50% 时重新开始，以避免推理质量下降
  • 重新开始前：总结事实、假设、已排除的可能性和下一步
  • 使用仅包含该摘要的新聊天；继续处理

决策框架

IF 同一修复方案被提出两次 → 停下；使用 SequentialThinking:process_thought IF 错误不清楚 → 通过 WebSearch → Parallel Search 进行调查；使用文档验证 IF 对该领域不熟悉 → 使用 codebase_search 探索；不要猜测 IF 修复看起来过于简单 → 确认它解决的是根本原因，而非症状 IF 上下文杂乱 → 在达到 50% 时附上摘要重新开始 IF 存在多个假设 → 明确评估每个假设（支持/反对的证据） IF 类似代码运行正常 → 通过 codebase_search/read_file 查找并进行差异比较 IF 宣布成功 → 展示更改的代码行；测试修复前失败/修复后通过 IF 修复涉及多个文件 → 搜索并修补所有出现位置 IF 假定了库的行为 → 查阅 Context7:get-library-docs

完成前的质量检查

在宣布 bug 已修复前，请确认：

  • 已确定并记录根本原因
  • 修复针对原因，而非症状
  • 已修复所有出现的位置（已在整个项目中搜索）
  • 符合现有代码模式
  • 原始症状已消除
  • 未引入回归问题
  • 测试/日志已在相关条件下验证
  • 文档/测试已更新（注释、文档、回归测试）

参考资料

  • reference/root-cause-framework.md
  • reference/antipatterns.md

评论

支持 Markdown