夜雨聆风事情是这样的。
我最近在做一个 AI agent 的实验项目，设计文档写了三天，逻辑完整，ADR 齐全，模块拆解清晰。状态标的是「设计已确认」，我自己读了十遍觉得没问题。
然后我让 AI 来审。
13 轮追问，逼出 4 个洞。
不是那种措辞瑕疵或者格式问题，是那种「到写代码时才会发现整个方案跑不通」的结构性矛盾。每一个单独看都合理，组合起来就打架。
我当时就愣住了。
因为这 4 个洞，有 3 个我确实没意识到，还有 1 个我隐约觉得有点别扭但说不清哪里不对。AI 把它们一条条摆出来的时候，我脑子里的第一反应是，卧槽，如果这些矛盾留到写代码时才发现，我得返工多少天。
这件事让我重新思考了一个问题，设计文档到底在防什么。
我们写设计文档，潜意识里是在防「逻辑不自洽」。但真正危险的不是单点逻辑错误，是不同章节之间的隐含假设冲突。人审文档的时候，倾向于逐段验证「这段对不对」，很少交叉验证「这段和那段打不打架」。
AI 不一样。
它没有「逐段阅读」的惯性，它可以把整份文档当成一张关系网，每条规则都是一个节点，然后去找哪些节点之间有逻辑张力。这种交叉验证的能力，恰好是人类阅读习惯的盲区。
下面我把这 4 个洞具体展开讲讲。每一个都是真实踩坑，每一个都有点意思。
我在设计文档里给 agent 设了一套防幻觉机制，核心思路是，agent 每输出一条结论，都必须挂一个代码片段作为证据。如果挂不上，这条结论就不能写进报告。
听着很严谨对吧。
AI 问了我一句，需求理解阶段呢？
我愣了一下。
需求理解是 agent 工作流的第一步，它要根据用户输入的需求描述，理解用户到底想要什么。这一步输出的是「需求列表」，还没开始分析代码，当然挂不上代码片段。
但问题在于，如果需求理解这一步没有证据约束，agent 完全可以脑补一条文档里根本没有的需求。然后到后面代码分析阶段，发现代码里没有对应实现，诊断成「缺失」。
这就是从源头制造假缺口。
我当时设计的时候，脑子里想的是「分析结论要有证据」，但需求理解本身也是一种分析，它的「证据」应该是需求文档的原文引用。我把防线只设在了后半段，前半段漏了。
两条防线只锁一侧，等于没锁。
这个洞要是留到实现阶段才发现，我得回过头改整个证据链的设计。在设计阶段被逼出来，省了至少两天返工。
第二个洞，两条核心规则自相矛盾
我的文档 §5.1.2 写的是「严格两阶段，推理时禁止回补取证」。意思是 agent 先做推理，推理完了再统一取证，推理过程中不能边推理边取证。
§5.1.4 写的是「校验失败退回重新取证」。意思是如果证据校验没过，就退回去重新找证据。
AI 直接把这两条并排贴出来，问我，这俩能共存吗。
我看了半天。
如果允许退回取证，两阶段名存实亡，因为推理和取证又混在一起了。
如果不允许退回，第二条规则就是废话，因为校验失败了也没法补救。
选一个。
我当时写这两条的时候，脑子里想的是两个不同的场景。§5.1.2 针对的是「推理过程的纯净性」，§5.1.4 针对的是「最终输出的完整性」。单独看都合理，但它们在逻辑上确实打架。
这两条分散在不同章节，间隔了好几页。我逐段审的时候，每条单独看都没问题，但 AI 把它们拎出来放在一起，矛盾立刻就浮现了。
最后我的解决方案是，改成「允许一次退回，但必须标记为补证轮次」。既保留了两阶段的主体结构，又给了一个有限的补救机制。
但如果这个矛盾留到代码写完才发现，我得重构整个推理引擎的状态机。
第三个洞，实验设计在考闭卷学生用开卷答案
我的项目要做 A/B 对照实验，A 组是黑盒 agent，B 组是我设计的显式编排 agent。实验要测的是「显式编排是不是真的比黑盒强」。
我设计了一份「金标准答案」，用来给两组 agent 的输出打分。答案里列出了每个需求的正确诊断结果，哪些是缺失，哪些是偏差，哪些是符合预期。
AI 读完那份金标准答案后，问了我一句，这份答案是怎么来的。
我说，我根据需求文档和代码库，结合业务方的口头澄清，整理出来的。
AI 说，业务方口头澄清的信息，被测的 agent 能接触到吗。
我说，不能，agent 只能看到需求文档和代码。
AI 说，那你拿这份答案考 agent，不就是拿开卷答案考闭卷学生吗。
我当时脑子嗡了一下。
金标准答案里确实有几条诊断，是我根据业务方的口头澄清才确认下来的。但 agent 根本接触不到业务方，它只能从需求文档和代码里推。如果需求文档本身写得模糊，agent 推不出来也很正常，但我用包含了额外信息的答案去评判它，这就不是在测能力差异，是在测信息不对称。
实验白做。
这个洞要是留到实验跑完才发现，我得重新设计整套评估标准，甚至得重跑实验。
第四个洞，选的 SDK 直接毁掉项目论点
我的项目论点是「黑盒编排不如显式编排」。A 组用的是 Claude 的默认 agent 模式，B 组我打算用 Claude Agent SDK 来做显式编排。
AI 问我，Claude Agent SDK 是什么架构。
我说，它是一个编排框架，提供了 agent 循环、工具调用、状态管理这些能力。
AI 说，那它本身是黑盒还是显式。
我愣了。
Claude Agent SDK 本身就是一个黑盒编排器。虽然它暴露了一些 API 让你控制流程，但核心的 agent 循环逻辑还是封装在 SDK 里的，你看不到它内部怎么决策。
如果我用它来实现 B 组，B 组在架构上就退化成了 A 组的变体。我测的不是「显式 vs 黑盒」，是「一个黑盒 vs 另一个黑盒」。
工具选型和实验假设之间的逻辑冲突，通常要到实现中期才暴露。我可能写到一半才发现，诶不对，我这个 B 组好像也没比 A 组显式到哪去。到那时候再换技术栈，成本就大了。
在设计阶段被逼出来，我可以提前换方案，比如用更底层的 Anthropic API 自己搭编排逻辑，或者换一个真正显式的编排框架。
省了几天弯路。
这 4 个洞的共同特征
我后来复盘了一下，这 4 个洞有一个共同特征。
它们都不是单点错误，是组合矛盾。
单独看每条设计都合理，矛盾只在它们交叉组合的时候才出现：
• 第一个洞：防幻觉机制本身没问题，需求理解流程本身也没问题，但两者的边界没对齐 • 第二个洞：两阶段规则没问题，校验补救机制也没问题，但它们在逻辑上互斥 • 第三个洞：金标准答案没问题，闭卷实验设计也没问题，但答案的信息来源超出了被测对象的视野 • 第四个洞：显式编排论点没问题，选一个成熟的 SDK 也没问题，但这个 SDK 的架构恰好违背了论点
人审文档的时候，倾向于逐段验证「这段对不对」。每段单独看都对，就觉得整体应该也对。但设计文档不是线性文本，是一张关系网。不同章节之间有隐含的依赖关系、前置假设、逻辑约束。这些关系只有在交叉对照时才会浮现。
AI 的优势就在这。
它可以把整份文档拆成一堆命题，然后去找哪些命题之间有张力。它不会像人一样，读到第 5 页的时候已经忘了第 2 页写的什么。它可以同时把所有相关条款调出来，并排摆着看。
这种交叉验证的能力，恰好是人类阅读习惯的盲区。
我是怎么用的
我用的是 Claude Code 的 grill-with-docs skill。
操作很简单，写完设计文档后，在 Claude Code 里输入 /grill-with-docs，然后把文档路径丢给它。它会启动一个对话式审查流程，专门逼你文档里的隐含假设和内在矛盾。
它不会直接告诉你「这里错了」，而是用提问的方式，让你自己意识到哪里不对。
比如第二个洞，它不是说「你这两条规则矛盾了」，而是问「如果校验失败退回取证，两阶段还成立吗」。这种提问方式逼你主动思考，比直接指错效果好。
13 轮追问听着多，实际上每轮都很快，整个过程大概 1 小时。
我当时是边答边改文档，有些矛盾当场就能改掉，有些需要回去重新设计。但不管怎样，这 1 小时比写代码时花 3 天踩坑再重构，便宜太多了。
有一个细节我觉得挺重要。
它追问的时候，不是按章节顺序来的，而是按逻辑依赖来的。比如它会先问「你的核心论点是什么」，然后跳到工具选型那一节，问「这个工具支持你的论点吗」。这种跳跃式的追问，恰好能击穿那些分散在不同章节的隐含矛盾。
设计文档的本质困境
聊到这我突然想起一个事。
写代码的时候，我们有编译器。编译器会告诉你哪里类型不匹配，哪里引用未定义，哪里逻辑分支不完整。但写设计文档的时候，我们没有「设计编译器」。
设计文档是自然语言写的，逻辑约束是隐含的，矛盾是延迟暴露的。
你可以写出一份读起来很顺的文档，每段话都正确，但整体在逻辑上打架。这种矛盾不会像编译错误一样立刻报出来，它会潜伏到实现阶段，在你写到一半的时候突然冒出来。
那时候你已经投入了大量时间，沉没成本很高，你会倾向于打补丁而不是推倒重来。结果就是，设计越改越歪，代码越写越别扭。
如果有一个工具，能在设计阶段就把这些矛盾逼出来，就相当于给设计文档装了一个「逻辑编译器」。
AI 现在能做到的，就是这个。
它不能替你做设计决策，但它可以帮你发现设计决策之间的冲突。这种能力在过去只能靠「多人 review」或者「踩坑后复盘」来获得，现在可以前置到设计阶段。
成本极低，收益极高。
一点建议
如果你最近在写设计文档，或者已经写完了准备动手，我建议加这一步。
不是说人审就不行，人审当然有价值。但人审和 AI 审的盲区不一样，两者可以互补。
人审擅长判断「这个设计在业务上合不合理」「这个方案在工程上可不可行」。AI 审擅长找「这条规则和那条规则打不打架」「这个假设和那个约束兼不兼容」。
设计阶段多花 1 小时，实现阶段省几天。
这笔账，怎么算都划算。
我自己现在养成了一个习惯，设计文档写完之后，先扔给 AI 审一遍，改完了再找人审。这样人审的时候，大家可以把精力放在更高层的架构判断上，而不是纠结「咦这两条好像有点矛盾」。
反正试一次又不花钱。
最后说一句。
这件事让我重新理解了「设计」这个词。
设计不只是「想清楚要做什么」，还包括「确认这些想法之间不打架」。前者是创造，后者是验证。
人擅长创造，AI 擅长验证。
两者配合，效率能翻倍。