---

name: debug description: 系统化调试方法论。当用户遇到 Bug、代码错误、程序异常、需要排查问题时触发。提供三阶段调试法（精准定位→辅助排查→清洗代码）。即使不确定也要反问用户，不能卡住。

Debug Skill

系统化的代码调试方法论。信息完整后自主分析，只在关键节点汇报。

⚠️ 核心原则

1. 信息不全时反问：缺少关键信息才问，不要每步都问
2. 信息完整后自主分析：收集到 5 项信息后，自主执行三阶段流程
3. 只在关键节点汇报：定位到根源后、需要用户决策时、每次代码改动后必须调用 zhi

---

第一阶段：精准定位（向 AI 提供核心信息）

1. 收集 Bug 描述

必须向用户确认以下 5 项信息（缺一不可）：

如果用户没有提供完整信息，必须反问：

Copy我需要更多信息来定位问题：
1. 复现步骤：你是如何触发这个 Bug 的？
2. 当前表现：程序现在的反应是什么？
3. 预期表现：你期望它应该怎样？
4. 错误信息：Console 有报错吗？
5. 环境信息：在什么设备/浏览器上？

---

第二阶段：辅助排查（当 AI 找不到原因时）

2. 使用 Debug Log

如果第一阶段无法定位问题，必须植入调试日志：

Step 1: 植入详细调试日志

Copy请在您认为最有可能导致错误的重点代码段中添加详细的 Debug Log。
目的：收集执行到该位置时，程序内部的关键信息和数据流。

Step 2: 自主分析日志细节

获取日志后，主动分析而非简单列出：

• 执行流程：跟踪代码实际运行路径
• 变量状态：关注输入参数、循环计数器、条件判断结果在执行前后的数值变化

Step 3: 定位并确认根源

利用日志细节明确指出：

• 哪个具体代码行或逻辑块是错误根源
• 为什么该代码会导致错误（基于变量状态或流程跳转的异常）

多假设验证法

当问题复杂时：

1. 反思 5-7 个可能的问题来源
2. 筛选出 1-2 个最可能的来源
3. 添加日志验证假设
4. 确认后再实施修复

⚠️ 意外情况检查

有时操作根本和后台无关，所以后台才会没有反应。需要检查：

• 前端事件是否正确绑定？
• 请求是否真的发出了？
• 是不是完全不同的代码路径？

---

第三阶段：清洗代码（防止代码质量劣化）

3. 处理重复修改导致的质量下降

如果 AI 反复修改仍不对，代码质量会下降。此时必须：

1. 总结问题根源：让 AI 总结找到的问题根源及修改方法
2. 保存总结：记录到 .cunzhi-knowledge/problems.md
3. 回退修改：回到最初始状态
4. 重新开始：开启新对话，直接给出问题根源和修改方法，一次性改对

代码嵌套问题

当多次迭代导致结构复杂时，使用以下提示词：

Copy在这个问题上我们已经修改多次，仍然没有效果。
我怀疑是因为该部分的代码因为多次迭代导致了结构复杂，产生了不必要的嵌套，导致你的更新无法生效。
我建议你完全删除这部分的逻辑，根据我们讨论的实际需求重新写代码，这样可以避免你的更新被原有逻辑影响。

---

语言专用指南

• JavaScript: 见 references/javascript.md - 结构化 console 调试规范

---

调试失败处理

如果多次尝试仍未解决：

1. 记录问题到 .cunzhi-knowledge/problems.md（状态：open）
2. 总结已尝试的方法和排除的可能性
3. 调用 zhi 告知用户，询问是否：
   • 暂时搁置，后续再处理
   • 尝试第三阶段的"清洗代码"方法
   • 寻求外部帮助

---

流程图

Copy用户报告 Bug
     ↓
检查 5 项信息是否完整
     ↓ (不完整？反问用户)
     ↓ (完整？自主执行 ↓)
第一阶段：精准定位
     ↓ (找不到？自动进入 ↓)
第二阶段：植入 Debug Log → 分析 → 定位
     ↓ (多次失败？自动进入 ↓)
第三阶段：清洗代码
     ↓
【关键节点】调用 zhi 汇报结果

何时调用 zhi？