Back to Details

debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging

调试

Quickstart

快速入门

  1. Capture exact repro, scope, and recent changes
  2. Isolate components/files; trace path to failure
  3. Research exact error; check official docs
  4. Compare failing vs working patterns; form a testable hypothesis
  5. Verify with minimal test; apply minimal fix across all instances; validate
  1. 记录可精确复现的步骤、问题范围以及近期的代码变更
  2. 隔离故障组件/文件；追踪故障产生的路径
  3. 调研具体错误信息；查阅官方文档
  4. 对比故障场景与正常场景的模式；形成可验证的假设
  5. 通过最小化测试验证假设；在所有相关实例中应用最小化修复方案；确认修复效果

When to Use This Skill

何时使用该方法

Use debugging when:
  • A bug has no obvious cause or has been "fixed" before but returned
  • Error messages are unclear or misleading
  • Multiple attempted fixes have failed
  • The issue might affect multiple locations in the codebase
  • Understanding the root cause is critical for proper resolution
Skip this skill for:
  • Simple syntax errors with obvious fixes
  • Trivial typos or missing imports
  • Well-understood, isolated bugs with clear solutions
在以下场景使用本调试方法：
  • 故障原因不明确，或之前的“修复”后问题再次出现
  • 错误信息模糊或具有误导性
  • 多次尝试修复均失败
  • 问题可能影响代码库中的多个位置
  • 理解根本原因对彻底解决问题至关重要
在以下场景可跳过本方法：
  • 具有明显修复方案的简单语法错误
  • 无关紧要的拼写错误或缺失的导入
  • 原因明确、影响范围孤立且有清晰解决方案的故障

Core Anti-Patterns to Avoid

需要避免的核心反模式

Based on documented failures in AI debugging, explicitly avoid:
  1. Circular Reasoning: Never propose the same fix twice without learning why it failed
  2. Premature Victory: Always verify fixes were actually implemented and work
  3. Pattern Amnesia: Maintain awareness of established code patterns throughout the session
  4. Context Overload: Use the 50% rule - restart conversation when context reaches 50%
  5. Symptom Chasing: Resist fixing error messages without understanding root causes
  6. Implementation Before Understanding: Never jump to code changes before examining existing patterns
基于AI调试中的已记录失败案例，需明确避免以下情况：
  1. 循环推理：在未明确之前修复失败原因的情况下，绝不能重复提出相同的修复方案
  2. 过早宣告成功：务必确认修复方案已实际部署并生效
  3. 模式遗忘：在整个调试过程中始终牢记已确立的代码模式
  4. 上下文过载：遵循50%规则——当上下文占用率达到50%时重启对话
  5. 追逐表面症状：在未理解根本原因的情况下，不要仅针对错误信息进行修复
  6. 未理解先实现：在未分析现有代码模式之前，绝不要直接进行代码修改

UNDERSTAND (10-step checklist)

UNDERSTAND（10步检查清单）

  • Understand: capture exact repro, scope, and recent changes
  • Narrow: isolate components/files; trace path to failure
  • Discover: research exact error (WebSearch → Parallel Search, Context7:get-library-docs)
  • Examine: compare against known-good patterns in the codebase
  • Reason: use SequentialThinking:process_thought and 5 Whys to reach root cause
  • Synthesize: write a falsifiable hypothesis with predictions
  • Test: add logs/tests to confirm the mechanism
  • Apply: minimal fix for root cause, across all occurrences, following patterns
  • Note: record insights, warnings, decisions
  • Document: update comments/docs/tests as needed
  • Understand：记录可精确复现的步骤、问题范围以及近期的代码变更
  • Narrow：隔离故障组件/文件；追踪故障产生的路径
  • Discover：调研具体错误信息（WebSearch → Parallel Search, Context7:get-library-docs）
  • Examine：与代码库中已知的正常模式进行对比
  • Reason：使用SequentialThinking:process_thought和5Why法定位根本原因
  • Synthesize：撰写可证伪的假设及预测
  • Test：添加日志/测试以验证故障机制
  • Apply：针对根本原因实施最小化修复，并覆盖所有相关场景，遵循现有代码模式
  • Note：记录洞察、警示与决策
  • Document：根据需要更新注释/文档/测试

Progress Tracking with TodoWrite

使用TodoWrite跟踪进度

Use TodoWrite to track debugging progress through the UNDERSTAND checklist:
  1. At start: Create todos for each applicable step:
    ☐ 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. During debugging: Mark steps in_progress → completed as you work through them
  3. When stuck: TodoWrite makes it visible which step is blocked - helps identify if you're skipping steps or going in circles
  4. Skip steps only if: Bug is simple enough that checklist is overkill (see "Skip this skill for" above)
借助TodoWrite，通过UNDERSTAND检查清单跟踪调试进度：
  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. 调试过程中：随着工作推进，将步骤标记为进行中→已完成
  3. 遇到瓶颈时：TodoWrite会清晰显示哪个步骤被阻塞——有助于识别是否跳过了步骤或陷入循环
  4. 仅在以下情况可跳过步骤：故障足够简单，使用检查清单属于过度设计（详见上方“可跳过本方法的场景”）

Tool Decision Tree

工具决策树

  • Know exact text/symbol? → grep
  • Need conceptual/semantic location? → codebase_search
  • Need full file context? → read_file
  • Unfamiliar error/behavior? → Context7:get-library-docs, then WebSearch → Parallel Search
  • Complex multi-hypothesis analysis? → SequentialThinking:process_thought
  • 知道具体文本/符号？→ 使用grep
  • 需要概念/语义层面的定位？→ 使用codebase_search
  • 需要完整文件上下文？→ 使用read_file
  • 遇到不熟悉的错误/行为？→ 先使用Context7:get-library-docs，再通过WebSearch → Parallel Search调研
  • 复杂多假设分析？→ 使用SequentialThinking:process_thought

Context Management

上下文管理

  • Restart at ~50% context usage to avoid degraded reasoning
  • Before restart: summarize facts, hypothesis, ruled-outs, next step
  • Start a fresh chat with just that summary; continue
  • 当上下文占用率达到约50%时重启对话，以避免推理能力下降
  • 重启前：总结已知事实、假设、已排除的可能性以及下一步计划
  • 仅携带该总结开启新对话，继续调试

Decision Framework

决策框架

IF same fix proposed twice → Stop; use SequentialThinking:process_thought IF error is unclear → Research via WebSearch → Parallel Search; verify with docs IF area is unfamiliar → Explore with codebase_search; don't guess IF fix seems too easy → Confirm it addresses root cause (not symptom) IF context is cluttered → Restart at 50% with summary IF multiple hypotheses exist → Evaluate explicitly (evidence for/against) IF similar code works → Find and diff via codebase_search/read_file IF declaring success → Show changed lines; test fail-before/pass-after IF fix spans multiple files → Search and patch all occurrences IF library behavior assumed → Check Context7:get-library-docs
如果重复提出相同的修复方案→ 停止；使用SequentialThinking:process_thought 如果错误信息模糊→ 通过WebSearch → Parallel Search调研；结合文档验证 如果对相关领域不熟悉→ 使用codebase_search探索；不要猜测 如果修复方案看似过于简单→ 确认它针对的是根本原因而非表面症状 如果上下文杂乱→ 当占用率达50%时，携带总结重启对话 如果存在多个假设→ 明确评估（支持/反对的证据） 如果类似代码可正常运行→ 通过codebase_search/read_file查找并对比差异 如果宣告问题解决→ 展示修改的代码行；提供修复前失败/修复后成功的测试结果 如果修复涉及多个文件→ 搜索并修补所有相关实例 如果假设了库的行为→ 检查Context7:get-library-docs

Quality Checks Before Finishing

完成前的质量检查

Before declaring a bug fixed, verify:
  • Root cause identified and documented
  • Fix addresses cause, not symptom
  • All occurrences fixed (searched project-wide)
  • Follows existing code patterns
  • Original symptom eliminated
  • No regressions introduced
  • Tests/logs verify under relevant conditions
  • Docs/tests updated (comments, docs, regression tests)
在宣告故障已修复前，需验证以下内容：
  • 已定位并记录根本原因
  • 修复方案针对的是根本原因而非表面症状
  • 已修复所有相关实例（已在项目范围内搜索）
  • 遵循现有代码模式
  • 原始症状已消除
  • 未引入新的回归问题
  • 测试/日志已在相关场景下验证修复效果
  • 已更新文档/测试（注释、文档、回归测试）

References

参考资料

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