第 28 章 | 调试与故障排查

第 28 章：调试与故障排查

学习目标

知道哪里看 + 怎么修，独立解决 90% 的常见问题。

三大排查工具

flowchart TB
    Issue["遇到问题"] --> T1["工具 1
openspec status
(看工件状态)"]
    Issue --> T2["工具 2
git diff / git log
(看改了什么)"]
    Issue --> T3["工具 3
review/N.md
test-reports/N.md
STUCK.md
(谁说了什么)"]

    style Issue fill:#fff9c4

核心原则：文件状态 trump agent 自述

agent 说: "组 3 完成"
你: 验证！
  → cat openspec/changes/<active>/tasks.md | grep "## 3\." -A 10
  → 真的全部勾选了吗?
  → review/3.md 真的 APPROVED 吗?
  → test-reports/3.md 真的 PASS 吗?

只要文件不一致，就当 agent 没完成。

5 个常见症状的诊断流

症状 1：agent 声称完成但状态不对

现象: stdout 写"DONE"
       但 tasks.md 没勾、或 commit 没有
原因: 可能 agent 改了内存忘 commit；或 Edit 失败但它没意识到
对策: 让 main Claude 重读文件，按文件状态决定下一步

症状 2：死循环不停 dispatch

现象: dispatch 5 次以上还在推进
原因: 阈值没生效 / 状态读取不准
对策:
  1. /dev status 看真实状态
  2. 检查 review/N.md 的 **Reviewer Round** 字段
  3. 必要时手动加 STUCK.md 强制停手

症状 3：reviewer 反复拒同一处

现象: round 1, 2, 3 每次都拒同一行代码
原因: 
  - sonnet developer 不理解 reviewer 意图
  - 或 reviewer 钻牛角尖
对策:
  - 阈值 3 自动升 developer-deep
  - deep 会"质疑前提"，找出真正问题
  - 还失败 → architect 诊断

症状 4：测试通过但代码不对

现象: tester PASS，但用户跑发现 bug
原因: tester 写了"自证测试"——只测了 happy path
对策:
  - reviewer 应当检查测试是否针对 Scenario
  - tester.md 加约束："不为通过而通过"
  - 严重情况升 tester-deep

症状 5：hook 阻塞合法操作

现象: 完全合理的命令被 BLOCKED
原因: guard-bash 误判
对策:
  1. 单独测 hook：echo '{"tool_name":"Bash",...}' | hook
  2. 看 stderr 哪条规则触发
  3. 改 hook 加例外，或调宽匹配

调试决策树

flowchart TD
    P["问题"] --> Q1{什么类型?}
    Q1 -->|状态不一致| Read["重读文件
按文件为准"]
    Q1 -->|死循环| Check["openspec status + 阈值检查"]
    Q1 -->|代码错| Diff["git diff 看具体改动"]
    Q1 -->|测试错| Trans["看 Scenario → test 翻译
是否符合契约"]
    Q1 -->|hook 卡住| Trace["echo JSON 重现"]
    Q1 -->|不知道| Reset["/dev status
从头梳理"]

    style P fill:#ffcdd2
    style Read fill:#c8e6c9
    style Check fill:#c8e6c9
    style Diff fill:#c8e6c9
    style Trans fill:#c8e6c9
    style Trace fill:#c8e6c9
    style Reset fill:#fff9c4

重置策略（极端情况）

如果整个状态机乱了：

# 1. 备份当前
cp -r openspec/changes/<active> /tmp/backup-active

# 2. 清状态
rm -rf openspec/changes/<active>/review/
rm -rf openspec/changes/<active>/test-reports/
rm openspec/changes/<active>/STUCK.md 2>/dev/null

# 3. 把 tasks.md 的 [x] 改回 [ ]（只改要重做的组）
# 手工编辑

# 4. 重跑
/dev <N>

→ 这是核选项。日常不该用。

永远不该做的事

❌ 直接改 review/N.md 让它 APPROVED
   → 假阳性，跳过质量门
   
❌ 删 tasks.md 的某条 task 让它"完成"
   → spec 还要求那个能力，等于自欺

❌ 关掉 hook 让 agent 跑
   → 关闭安全网，迟早翻车

❌ /clear 后忘了重读 CLAUDE.md
   → main Claude 不知道项目规则

反模式

❌ 信 agent stdout 不看文件
❌ 状态不一致就靠人脑修
❌ 频繁 git reset 而不是修问题
❌ 修 bug 不更新 spec → 下次还会重蹈覆辙

你现在能做什么

• 用三大工具定位问题
• 区分"真完成"和"假完成"
• 知道什么情况该用核选项

下一章讨论沙盒——什么时候该上 Docker。