Agent Skills 工程化实践 05：调试不要靠猜，架构也要能被验证

先建立一个会变红的信号

diagnosing-bugs 最有价值的约束是：没有 tight、deterministic、fast、agent-runnable 的 feedback loop，就不要先开始猜原因。

这个 loop 必须驱动真实 bug path，并断言用户描述的 exact symptom。一个只检查“命令没有报错”的脚本不够；它可能一路走了错误路径，却因为没有断言而显示绿色。

可用的 loop 可能是 failing test、curl script、CLI fixture、headless browser、captured trace replay，或者一个只启动系统最小子集的 throwaway harness。工具不是重点，重点是修复前它真的会 red，修复后它真的会 green。

六个阶段，避免把阅读当成诊断

完整的 diagnosis loop 可以压缩成：

建立 loop → reproduce → minimise → hypotheses
→ instrument → fix + regression test

先让 bug 稳定出现，再把输入、caller、config 或 data 一次删除一个，直到剩下的每个元素都是 load-bearing。最小 repro 会缩小 hypothesis space，也会成为之后的 regression test。

在测试假设前，先列出 3–5 个 ranked、falsifiable hypotheses，并为每个 hypothesis 写 prediction。instrumentation 也必须服务于某个 prediction，使用唯一 prefix，结束时清理。这样 debugging 不会退化为“把所有东西都 log 出来再 grep”。

什么时候该先做 prototype

有些问题不是 bug，而是我们还不知道某个 state model、business logic 或 UI shape 是否成立。这时直接实现 production code 会把未经验证的设计变成长期负担。

prototype 用 throwaway code 回答一个 design question：logic/state 使用单个可分享 HTML，UI 使用多个可以切换的 variation。它应该 trivial to run、不做 persistence、不追求 polish，并在每次 action 后完整展示 state。

prototype 的完成标准不是“看起来像产品”，而是让团队做出一个具体判断。验证后的 decision 回到真实 code；throwaway implementation 本身不要悄悄升级成 production foundation。

架构健康：从一次 bug 反推 seam

如果 bug 需要多个 caller 才能复现，但现有测试只能触碰某个很浅的 unit，问题不一定是“测试写得不够多”，也可能是 codebase 没有正确的 seam。

codebase-design 提供了一组共同词汇：让 interface 变小、implementation 变深，用 seam 隔离 variation，并用 deletion test 检查 complexity 是被集中还是仅仅被移动。它帮助我们讨论 module shape，而不是用含糊的 component/service/API 代替设计。

improve-codebase-architecture 则负责 survey：扫描近期 hot spots，寻找可以 deepening 的 candidate，生成带 Before/After diagram 的 report，再等待用户选择要探索的方向。它不是自动 rescue，也不应该在用户选择前预先设计新 interface。

调试后的复盘

修复宣布完成前，至少重新运行 original repro、regression test 和完整的 feedback loop；检查所有 debug prefix 已清理；记录正确 hypothesis。最后再问一个更难的问题：什么架构变化本可以让这个 bug 更早被捕获？

这个问题的答案不一定要立刻变成重构 ticket，但它能把一次修 bug 的经验转化为下一次更好的 seam。Agent 越快地改代码，这种 post-mortem 越值得保留。

来源与版本

• 诊断流程：diagnosing-bugs
• 可运行验证：prototype
• 模块设计：codebase-design
• 架构巡检：improve-codebase-architecture
• 参考分支：main · 核验 commit：022fcc3 · 核验日期：2026-08-12