debug-error

调试错误技能

自由度：混合。 根因判断 [HIGH freedom]；红色反馈循环和验证通过后的重新运行 [LOW freedom — run exactly]。

系统化调试错误和意外行为的方法。适用于任何项目。

推理方法

1. 观察 — 确切症状、堆栈、环境、首次出现时间
2. 解读 — 崩溃位置还是产生问题的位置；FE / BE / 集成 / 数据
3. 分类 — 空值访问 / 契约 / 环境 / 竞态 / 未知
4. 严重程度 — 影响全站的生产环境身份验证故障，优先级高于单个用户的边缘情况

示例

观察： 注册后访问 /account 时出现 TypeError: Cannot read property 'email' of undefined。 解读： 崩溃发生在个人资料卡片中；对于尚未完成入职流程的用户，API 返回 null。 分类： 数据错误 — 生产方返回 null，消费方却假设返回的是对象。 修复： 在生产方契约中处理入职流程未完成时的 null，并为 UI 添加空状态；不要只在崩溃位置使用 ?.。

报告前自我检查

• 先跑红色测试 — 假设形成前就有一条失败的命令
• 修根因，而非症状 — 不能只用 ?. 或吞掉异常作为修复
• 绿色循环 — 重新运行同一条命令并通过
• 找对负责人 — FE↔BE 不匹配 → debug-fe-be-integration；Sentry 待处理问题 → debug-sentry-monitor

调试前检查

开始调试前：

1. 阅读相关文档

README.md (project overview)
src/[domain]/@_[domain]-README.md (domain-specific behavior)
docs/ (system documentation)

2. 检查 Sentry 上下文（如果是生产环境错误）

如果错误来自生产环境且已配置 Sentry，获取完整上下文：

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "<error message or description>",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 5
}

然后获取匹配问题的详细信息：

sentry:get_sentry_resource
{
 "organizationSlug": "<ORG_SLUG>",
 "resourceType": "issue",
 "resourceId": "<ISSUE_ID>"
}

提取：堆栈跟踪、面包屑、标签（浏览器、OS、URL、版本）、事件频率。

3. 检查数据库状态（如果与数据有关）

如果涉及数据，请使用 Supabase MCP 或直接查询，核实预期是否符合实际情况。

4. 验证声明 — 确保诊断依据是你阅读和获取的信息

开始深入调试前，声明：

"Pre-debug check:
- README/docs read: [list]
- Sentry context: [YES with details / NO — not production / not configured]
- Database state verified: [YES/NO — findings]
- Backend API checked: [YES/NO — status]
- Error scope identified: [FE only / BE only / Integration / Data]"

---

调试流程

1. Reproduce → 2. Isolate → 3. Research → 4. Identify → 5. Fix → 6. Verify → 7. Prevent

---

阶段 1：复现

先构建紧密的反馈循环

这就是本技能的核心 — 后续步骤都是机械操作。 在阅读代码构建理论之前，先构造一条能针对此错误报红、修复后变绿的命令（改编自 mattpocock/skills，MIT）。按大致优先顺序：最近边界处的失败测试 → 针对开发服务器的 curl/HTTP 脚本 → 使用夹具输入的 CLI 调用 → 无头浏览器脚本 → 在隔离环境中通过代码路径重放捕获的跟踪记录/负载。

满足以下条件时，反馈循环才算完成：

• 能报红 — 断言用户的确切症状，而不是“运行时没有报错”
• 确定性 — 每次运行都得到相同结论（对于不稳定错误：循环触发，直到提高复现率、便于调试）
• 快速 — 只需几秒，而不是几分钟
• 已运行过一次 — 你可以贴出调用命令及其报红输出

如果你发现自己在命令构建好之前就开始形成假设，请停下来 — 这正是此阶段要避免的问题。如果确实无法构建反馈循环，请明确说明，列出尝试过的方法，并请求提供捕获的材料（HAR、日志转储、录屏），而不是盲目继续。

收集信息

Error Report:
- What happened: [description]
- Expected behavior: [what should happen]
- Steps to reproduce:
 1. [step]
 2. [step]
- Environment: [browser/OS/Node version]
- Error message: [exact message]
- Stack trace: [if available]
- First seen: [when — correlate with deploys]

确定范围的问题

• 能否稳定复现？
• 何时开始出现？（检查 git log 中的近期更改）
• 是所有用户都会遇到，还是只有特定用户？（检查 Sentry 标签分布）
• 是否只在特定环境中发生？（开发环境、预发布环境还是生产环境）

---

阶段 2：隔离

缩小问题范围

Works in: Fails in:
├─ Production? ├─ Production?
├─ Staging? ├─ Staging?
├─ Local? ├─ Local?
├─ All browsers? ├─ Specific browser?
├─ All users? ├─ Specific user?
└─ All data? └─ Specific data?

追踪数据流

对于与数据有关的错误，追踪完整流水线：

User Action → Frontend Handler → API Call → Backend Controller → Database → Response → State Update → Render

检查每个边界，确定数据从何处开始出错。

缩小复现范围

反馈循环变红后，将复现缩减到仍会变红的最小场景：每次只删减一项输入、调用方、配置或数据，并在每次删减后重新运行反馈循环。直到剩下的每个元素都不可或缺——移除任何一个，反馈循环都会变绿。最小复现可以缩小假设范围，并成为第 6 阶段的回归测试。

---

第 3 阶段：修复前先研究错误模式

对于非简单错误，在实施修复前先研究正确的修复方案。识别出框架或错误，并不代表了解其当前行为——搜索完整的错误字符串并阅读当前文档，即使你认为自己知道如何修复：

firecrawl:firecrawl_search
{
 "query": "<framework> <exact error message> fix best practice",
 "limit": 5,
 "sources": [{ "type": "web" }]
}

然后抓取最相关的结果：

firecrawl:firecrawl_scrape
{
 "url": "<best-result-url>",
 "formats": ["markdown"],
 "onlyMainContent": true
}

如果错误与某个库有关，也要通过 Context7 查看官方文档：

context7:resolve-library-id
{
 "libraryName": "<library>",
 "query": "<error description>"
}

可信度顺序：官方文档 > 维护者文章 > 工程博客 > Stack Overflow（当前年份、高票数）。

---

第 4 阶段：找出根本原因

根本原因表述

编写任何修复之前，先说明：

1. 发生了什么：导致错误的具体运行时状态
2. 为什么会发生：使该状态成为可能的上游原因
3. 应该在哪里修复：正确的层级——通常不是崩溃发生处

---

第 5 阶段：修复

反模式检查清单

不要仅用以下方式修复：

• 添加 ?. 来抑制 TypeError → 查明值为 null 的原因并修复
• 用 try/catch 包裹并吞掉错误 → 修复底层错误
• 添加 ?? [] 作为回退值 → 明确处理加载和错误状态
• 在使用方添加 if 守卫 → 修复生产方

修复原则

1. 在根本原因所在层级修复，而不是在崩溃发生处（除非两者相同）
2. 让无效状态无法表示
3. 遵循项目现有约定
4. 如果修复涉及共享函数，请检查所有调用方
5. 只修复此错误。发现的既有错误应作为后续事项写入报告，而不是纳入差异中。除非反馈循环脚本成为第 6 阶段的回归测试，且放在仓库已有的测试目录中，否则不要将其加入仓库。精准修改；不要重写文件。

---

第 6 阶段：验证

测试修复

• 重新运行第 1 阶段的反馈循环，现在结果为绿色（粘贴调用命令和输出）
• 将最小复现转换为正确边界处的回归测试——该测试应覆盖真实的错误模式；如果不存在合适的边界，则将其记录为架构发现，而不是编写会造成虚假信心的测试
• 在存在测试套件的情况下运行测试套件，并粘贴输出

回归检查

# Run tests
npm test
# Or framework-specific
pytest
cargo test
go test ./...

---

第 7 阶段：预防

添加监控

如果错误可能以其他形式再次发生，请添加监控：

• 为受影响的代码路径设置自定义 Sentry 上下文
• 为关键用户操作添加面包屑
• 为数据流检查点添加结构化日志

记录不明显的修复

如果错误由不明显的交互导致，请添加注释，解释其中的约束：

// Profile can be null for users who haven't completed onboarding.
// The API returns null (not 404) in this case. See: ISSUE-123.

---

调试检查清单

## Bug Investigation: [Title]

**Pre-Debug:**
- [ ] Docs/README read
- [ ] Sentry context fetched (if applicable)
- [ ] Database state checked (if data-related)
- [ ] Error scope identified

**Investigation:**
- [ ] Can reproduce locally (or have Sentry reproduction)
- [ ] Isolated to specific component/function/layer
- [ ] Research completed (Firecrawl/Context7)
- [ ] Root cause identified and stated

**Fix:**
- [ ] Fix addresses root cause (not symptoms)
- [ ] No anti-patterns used as sole fix
- [ ] Side effects checked (other callers)
- [ ] Tests pass

**Prevention:**
- [ ] Monitoring added (if applicable)
- [ ] Documentation updated (if non-obvious)