diagnosing-bugs

1# 诊断缺陷
2 
3面向棘手 bugs 的纪律。只有在明确说明理由时才跳过阶段。
4 
5探索 codebase 时，先读取 `GLOSSARY.md`（如果存在），建立相关 modules 的清晰 mental model，并检查你将触碰区域的 ADRs。
6 
7## 脱敏
8 
9这个 skill 会要求你展示 commands、outputs 和捕获的 artifacts。**先 redact 掉每个 secret**：用 `<REDACTED>` 替换。Build loops 要针对 env vars 进行，让 credential 留在 environment 里而不是你展示的内容中。捕获的 artifacts 带有 auth headers：只引用携带 signal 的那些行。
10 
11如果 redact 后的 output 不足以诊断 bug，就说明情况并询问用户。
12 
13## Phase 1 - 构建 feedback loop
14 
15**这就是这个 skill 的核心。** 其他所有内容都是机械步骤。如果你拥有一个针对该 bug 的 **tight** pass/fail signal，即它会在 _这个_ bug 上变红，你就能找到原因；bisection、hypothesis-testing 和 instrumentation 都只是消费这个 signal。没有它，盯着代码看多久都救不了你。
16 
17在这里投入不成比例的精力。**要强硬、要有创造力、拒绝放弃。**
18 
19### 构建 loop 的方式 - 大致按以下顺序尝试
20 
211. **Failing test**，放在能触达 bug 的 seam 上：unit、integration、e2e 都可以。
222. **Curl / HTTP script**，打到运行中的 dev server。
233. **CLI invocation**，使用 fixture input，并把 stdout 与 known-good snapshot diff。
244. **Headless browser script**（Playwright / Puppeteer），驱动 UI，并断言 DOM/console/network。
255. **Replay a captured trace.** 把真实 network request / payload / event log 保存到磁盘，并在隔离环境中 replay 到代码路径。
266. **Throwaway harness.** 启动系统的最小子集（一个 service、mocked deps），用一次 function call 触发 bug code path。
277. **Property / fuzz loop.** 如果 bug 是 "sometimes wrong output"，运行 1000 个 random inputs 并寻找 failure mode。
288. **Bisection harness.** 如果 bug 出现在两个已知状态之间（commit、dataset、version），自动化 "boot at state X, check, repeat"，这样可以 `git bisect run`。
299. **Differential loop.** 用同一 input 跑 old-version vs new-version（或两个 configs），然后 diff outputs。
30…