debug

调试

黄金法则

不要猜测。先收集信息。

错误做法：出问题 → 随便尝试修复 → 不管用 → 再试一个 → 试了 5 次还是没修好。

正确做法：出问题 → 重现问题 → 收集诊断信息 → 找出根本原因 → 修复问题（通常第一次就能成功）。

先诊断，再修复。

---

根据工具进行调试

调试方式取决于你使用的工具。

Claude Code（你可以直接访问）

Claude Code 可以自行收集诊断信息。在向创始人索要截图或日志之前，先自动执行以下操作：

Auto-debug steps (do these yourself):
1. Check git history: git log --oneline -10 and git diff HEAD~3
2. Search for the error: Grep for error text across the codebase
3. Read the failing file: Read the file + surrounding context
4. Run the app/tests: Bash to run dev server, test suite, or reproduce
5. Check logs: Read server logs, build output, or error logs
6. Check environment: Verify .env.example vs actual config

只向创始人询问你无法自行获取的信息：他们在浏览器中看到的内容、点击了什么，以及视觉问题的截图。

Lovable / Replit（创始人粘贴到聊天中）

创始人需要手动收集信息并粘贴。使用 DEBUG-PROMPTS.md 中的“告诉 AI：”提示词——它们是结构化模板，可确保提供完整的上下文。

生产环境问题（先检查监控）

调试生产环境问题之前，先检查监控和错误跟踪：

1. Error tracker (Sentry, LogRocket): exact error + stack trace + user context
2. Server logs: filter by timestamp of report
3. Hosting dashboard: any deployment or outage at that time?
4. Database: any failed migrations or connection issues?

有关设置监控的信息，请参阅 /monitor 技能。有关回滚流程，请参阅 /deploy 技能。

---

工作流

Debug process:
- [ ] Reproduce bug consistently
- [ ] Gather diagnostic info (auto in Claude Code, manual elsewhere)
- [ ] Check what changed recently
- [ ] Diagnose root cause before proposing fixes
- [ ] Fix the root cause
- [ ] Test fix works
- [ ] Verify didn't break anything else
- [ ] Ask: how do we prevent this?

---

重现问题

修复之前，先重现问题：

Can you reproduce it?
- [ ] Exact steps to trigger bug
- [ ] Happens every time or intermittently?
- [ ] Specific browser/device?
- [ ] Specific data or user?

If can't reproduce:
- Ask user for exact steps or screen recording
- Try different browser/device/account
- Try with different data
- Clear cache and retry
- Check if timing-dependent

告诉 AI：

Bug: [description]

Steps to reproduce:
1. [Step]
2. [Step]
3. [Bug happens]

Happens: [Always / Sometimes / Once]
Browser: [Chrome 120 on Mac]
Screenshot: [attach]

---

收集错误信息

浏览器控制台

1. 右键点击页面 → 检查 → 控制台标签页
2. 查找红色错误
3. 截取完整错误的屏幕截图，包括堆栈跟踪

告诉 AI：

Console error: [paste full error message]
When it happens: [what you were doing]

网络标签页

1. 打开 DevTools → 网络标签页 → 重现问题
2. 查找失败的请求（红色、4xx、5xx）
3. 点击失败的请求 → 检查响应标签页

告诉 AI：

API call failing:
URL: /api/endpoint
Method: [GET/POST]
Status: [status code]
Response: [paste error response]
This happens when: [action]

视觉问题

截取预期效果与实际显示效果的对比图，并注明设备和浏览器。

---

常见问题类型

“点击后没有任何反应”

检查：控制台是否有错误？网络请求是否失败？元素是否确实可点击（是否被其他元素遮挡）？

“页面无法加载”

检查：是否有网络错误？是否有 JavaScript 错误？是否发生无限重定向？是否缺少环境变量？

“显示的数据不正确”

检查：API 是否返回了错误数据（网络标签页）？是否存在缓存问题？状态是否未更新？用户上下文是否错误？

“表单无法提交”

检查：是否显示了验证错误？控制台是否有错误？是否触发了网络请求？

“开发环境正常，生产环境出问题”

检查：是否设置了环境变量？数据库是否不同？构建步骤是否移除了某些内容？是否为生产域名配置了 CORS？

“Chrome 中正常，Safari 中出问题”

检查：CSS / JS 兼容性？Safari 特有的默认设置？日期解析差异？

---

升级处理规范

修复失败 1 次后

重新评估。我们是否误诊了？是否还需要收集更多信息？

Fix didn't work. Here's what happened after applying it: [new info].
Are we fixing the right thing?

修复失败 2 次后

**停止尝试修复。**诊断很可能有误。

2 fixes failed.
Fix 1: [tried] → [result]
Fix 2: [tried] → [result]

Are we fixing the wrong thing? Should we rethink the approach entirely?

修复失败 3 次后

不要尝试第 4 次。改变策略：

1. 用更简单的方法重建该功能
2. 请人工开发者检查（参见 /hiring）
3. 先发布临时解决方案，之后再彻底修复

---

深入调查：找到真正的根本原因

大多数调试失败都是因为你停留在第一个看似合理的原因，而没有找到真正的根本原因。使用“不断追问为什么”的方法：

Problem: Server crashed
  Why? → Out of memory
  Why? → Memory leak in the auth service          ← Most people stop here and "add more RAM"
  Why? → Database connections not being released
  Why? → Error handler doesn't close connections
  Why? → No cleanup in the finally block           ← THIS is the fix

如何判断你是否找到了真正的根本原因：

• 它是你确实可以更改的内容（代码、配置、流程）
• 修复它可以防止问题再次发生
• 再问一次“为什么？”也不会导向可采取行动的答案

**常见错误：止步于“AI 把它弄坏了”。**这只是归咎，不是原因。应该改问：什么流程本可以发现这个问题？是否缺少测试？缺少验证？没有代码审查？

当问题有多个原因时

有时，问题需要两个条件同时出错才会发生。如果显而易见的原因无法完全解释问题，请继续寻找第二条原因链：

Problem: Deployment failed
  Why? → Database migration timed out
    Branch A: Why was the migration slow?
      → Table lock from a long-running query → Missing index
    Branch B: Why is the timeout so short?
      → Using default timeout → No deployment-specific config

两条原因链都需要修复，否则问题会在略有不同的条件下再次出现。

验证你的诊断

实施修复之前，沿着因果链反向追溯：“如果我修复了 X，是否就能避免 Y，进而避免 Z，最终解决原始问题？”如果因果链中断，说明你找错了根本原因。

---

间歇性 Bug

“有时正常，有时出错”——很可能是竞态条件、缓存问题或外部 API 不稳定。

告诉 AI：

Bug is intermittent.
Works: [X] out of 10 times
Fails: [Y] out of 10 times

Pattern: Fails more when [condition]. Never fails when [condition].

Add logging to capture state when it fails.

---

边界情况测试

当修复对主要情况有效时，也要测试以下情况：

• 空状态：没有数据、空列表、缺少字段
• 数据量：1 项、100 项、10,000 项
• 时序：慢速连接（在 DevTools 中启用 3G 限速）、快速双击、会话过期、多个标签页
• 边界值：超长文本、特殊字符、零值、负数

---

生产环境中的 Bug

优先级 1：用户能否绕过问题继续工作？

• 能 → 在下一次部署时修复
• 不能 → 需要紧急修复

紧急修复：

Production bug blocking users.
Bug: [description]
Impact: [how many users affected]

Need the simplest fix that unblocks users. Can improve later.

---

同时出现多个 Bug

看起来像一个 Bug 的症状可能实际由多个 Bug 引起；多个症状也可能有同一个根本原因。

List all symptoms:
1. [Symptom]
2. [Symptom]
3. [Symptom]

Are these separate bugs or one root cause?

**按优先级修复：**阻塞性（无法使用应用）→ 严重（主要功能失效）→ 重大 → 轻微。严重 Bug 尚未修复时，不要先修复轻微 Bug。

---

添加调试日志

当 Bug 难以诊断时，添加有针对性的日志：

Add logging at:
- Function entry with input values
- Before/after API calls with request/response
- State changes with before/after values
- Error handlers with full context
- Decision points (which branch was taken)

Format: [TIMESTAMP] [LEVEL] [CONTEXT] Message
Example: [2025-01-13 10:30:45] [ERROR] [UserAuth] Login failed for [email protected] - Reason: Invalid password - Attempts: 3

修复 Bug 后，删除或减少日志。

---

预防

每次修复后，从三个层面进行思考：

1. 立即修复——你已经完成了这一步（Bug 已消失）
2. 预防措施——怎样才能彻底避免这种情况再次发生？（验证、测试、类型检查）
3. 检测机制——如果预防措施失效，怎样才能及早发现？（监控告警、错误跟踪）

Bug is fixed. Now:
- What validation or test would prevent this from recurring?
- What monitoring or alert would catch it early if it does recur? (see /monitor)
- Is this a pattern? Could the same type of bug exist elsewhere in the codebase?

---

何时寻求帮助

遇到以下情况时，考虑聘请开发者：

• 按照整个流程操作后仍然无法解决
• 无法查明原因的严重生产环境 Bug
• 修复后同一个 Bug 仍反复出现
• 复杂的第三方集成中出现 Bug
• 存在安全问题或数据损坏风险

对于大多数 Bug，配合 AI 工具使用此流程就足够了。

---

常见错误

错误	修正方法
未收集信息就尝试修复	先收集诊断信息
“它无法运行”（含糊不清）	具体说明：究竟哪里无法运行？
没先复现问题	找到能稳定触发 Bug 的步骤
让 AI 随机尝试修复	先诊断根本原因
忽略控制台或网络错误	始终检查这两个标签页
修复后不测试	确认修复有效，且没有影响其他功能
严重 Bug 尚未解决就修复轻微 Bug	根据对用户的影响确定优先级
接受第一个看似合理的原因	持续追问“为什么？”，直到找到真正可以修复的问题
“是 AI 把它弄坏的”（责怪，而非诊断）	试着问：怎样的流程才能及时发现这个问题？