开发与测试
debugging-and-error-recovery
指导系统化根因调试。当测试失败、构建中断、昨天还能用的东西今天坏了、行为不符合预期,或遇到任何意外错误时使用。当你需要搞清楚是什么坏了、为什么坏时使用:用系统化的方法找到并修复根因,而不是靠猜测。
vinvcn · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vinvcn/addyosmani-agent-skills-zh --skill debugging-and-error-recovery技能说明
name: debugging-and-error-recovery description: 指导系统化根因调试。当测试失败、构建中断、昨天还能用的东西今天坏了、行为不符合预期,或遇到任何意外错误时使用。当你需要搞清楚是什么坏了、为什么坏时使用:用系统化的方法找到并修复根因,而不是靠猜测。
调试与错误恢复
概览
用结构化 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
第 2 步:定位
缩小失败发生在哪里:
Which layer is failing?
├── UI/Frontend → Check console, DOM, network tab
├── API/Backend → Check server logs, request/response
├── Database → Check queries, schema, data integrity
├── Build tooling → Check config, dependencies, environment
├── External service → Check connectivity, API changes, rate limits
└── Test itself → Check if the test is correct (false negative)
对 regression bug 使用 bisection:
# Find which commit introduced the bug
git bisect start
git bisect bad # Current commit is broken
git bisect good <known-good-sha> # This commit worked
# Git will checkout midpoint commits; run your test at each
git bisect run npm test -- --grep "failing test" # substitute the repository's focused-test command
第 3 步:缩减
构造最小失败用例:
- 移除无关代码/配置,直到只剩 bug 本身
- 把输入简化为能触发失败的最小示例
- 把测试剥离到能复现问题的最小程度
最小复现能让根因显而易见,并防止只修症状而不修原因。
第 4 步:修复根因
修底层问题,而不是症状:
Symptom: "The user list shows duplicate entries"
Symptom fix (bad):
→ Deduplicate in the UI component: [...new Set(users)]
Root cause fix (good):
→ The API endpoint has a JOIN that produces duplicates
→ Fix the query, add a DISTINCT, or fix the data model
不断追问“为什么会这样?”,直到触及真正的原因,而不只是它显现的位置。
第 5 步:防止复发
写一个能抓住这个特定失败的测试:
// The bug: task titles with special characters broke the search
it('finds tasks with special characters in title', async () => {
await createTask({ title: 'Fix "quotes" & <brackets>' });
const results = await searchTasks('quotes');
expect(results).toHaveLength(1);
expect(results[0].title).toBe('Fix "quotes" & <brackets>');
});
这个测试能防止同一个 bug 复发。它应该在缺少修复时失败,在有修复时通过。
第 6 步:端到端验证
修复后,用本仓库自己的命令(示例用 npm)验证完整场景:
# Run the specific test
npm test -- --grep "specific test"
# Run the full test suite (check for regressions)
npm test
# Build the project (check for type/compilation errors)
npm run build
# Manual spot check if applicable
npm run dev # Verify in browser
各类错误的特定模式
测试失败 Triage
Test fails after code change:
├── Did you change code the test covers?
│ └── YES → Check if the test or the code is wrong
│ ├── Test is outdated → Update the test
│ └── Code has a bug → Fix the code
├── Did you change unrelated code?
│ └── YES → Likely a side effect → Check shared state, imports, globals
└── Test was already flaky?
└── Check for timing issues, order dependence, external dependencies
构建失败 Triage
Build fails:
├── Type error → Read the error, check the types at the cited location
├── Import error → Check the module exists, exports match, paths are correct
├── Config error → Check build config files for syntax/schema issues
├── Dependency error → Check package.json, run npm install
└── Environment error → Check Node version, OS compatibility
运行时错误 Triage
Runtime error:
├── TypeError: Cannot read property 'x' of undefined
│ └── Something is null/undefined that shouldn't be
│ → Check data flow: where does this value come from?
├── Network error / CORS
│ └── Check URLs, headers, server CORS config
├── Render error / White screen
│ └── Check error boundary, console, component tree
└── Unexpected behavior (no error)
└── Add logging at key points, verify data at each step
安全 Fallback 模式
时间紧张时,使用安全 fallback:
// Safe default + warning (instead of crashing)
function getConfig(key: string): string {
const value = process.env[key];
if (!value) {
console.warn(`Missing config: ${key}, using default`);
return DEFAULTS[key] ?? '';
}
return value;
}
// Graceful degradation (instead of broken feature)
function renderChart(data: Ch
阅读完整来源 ↗