debugging-and-error-recovery

调试与错误恢复

概览

用结构化 triage 进行系统化调试。当某样东西出错时，停止添加功能，保存证据，并按结构化流程找到并修复根因。猜测只会浪费时间。这份 triage checklist 适用于测试失败、构建错误、运行时 bug 和生产事故。

何时使用

• 代码改动后测试失败
• 构建中断
• 运行时行为不符合预期
• 收到 bug report
• 日志或 console 中出现错误
• 之前能正常工作的东西突然不能用了

Stop-the-Line 规则

当出现任何意外情况时：

1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes

不要带着失败测试或破损构建继续去做下一个功能。 错误会叠加。第 3 步中未修复的 bug 会让第 4-6 步全部出错。

Triage Checklist

按顺序完成这些步骤。不要跳步。

第 1 步：复现

让失败稳定地发生。如果无法复现，就无法有把握地修复。

Can you reproduce the failure?
├── YES → Proceed to Step 2
└── NO
    ├── Gather more context (logs, environment details)
    ├── Try reproducing in a minimal environment
    └── If truly non-reproducible, document conditions and monitor

当 bug 无法复现时：

Cannot reproduce on demand:
├── Timing-dependent?
│   ├── Add timestamps to logs around the suspected area
│   ├── Try with artificial delays (setTimeout, sleep) to widen race windows
│   └── Run under load or concurrency to increase collision probability
├── Environment-dependent?
│   ├── Compare Node/browser versions, OS, environment variables
│   ├── Check for differences in data (empty vs populated database)
│   └── Try reproducing in CI where the environment is clean
├── State-dependent?
│   ├── Check for leaked state between tests or requests
│   ├── Look for global variables, singletons, or shared caches
│   └── Run the failing scenario in isolation vs after other operations
└── Truly random?
    ├── Add defensive logging at the suspected location
    ├── Set up an alert for the specific error signature
    └── Document the conditions observed and revisit when it recurs

对于测试失败（示例用 npm，请替换成本仓库自己的测试命令，参见 test-driven-development skill 中 Discover the Stack First 一节）：

# Run the specific failing test
npm test -- --grep "test name"

# Run with verbose output
npm test -- --verbose

# Run in isolation (rules out test pollution)
npm test -- --testPathPattern="specific-file" --runInBand