📌 本文是「AI 时代的编码新范式」系列的第 6 篇。全系列共 9 篇，基于 43 篇行业文献、学术论文与一线实践报告，探讨 Spec-Driven Development 如何在 AI Agent 时代从边缘实践变为工程的基础设施。每篇可独立阅读。前五篇讲了 spec 为什么重要、怎么写、怎么用。本篇讲一个你可能不想听到的事实：spec 也会失效。失效不是因为你写错了，是因为 spec 有它的系统性边界——学术界已经把四条边界摸清楚了。
你的团队写了一份 spec。不是敷衍的三行字——是按第 5 篇的五要素认认真真写的。目标清楚，约束明确，验收标准可测试，边界条件覆盖到位。你把它交给 Agent，Agent 读完，开始写代码。
然后 Agent 调用了一个不存在的 API。
不是拼写错误。Agent 确信这个 API 存在——它甚至给出了参数类型和返回值结构。但你在代码库里搜了一遍，没有。文档里也没有。Agent 从训练数据里「记住」了一个看起来合理但实际不存在的接口签名，然后围绕这个幻觉构建了整个功能。
你检查了 spec——spec 里没写「只能使用以下 API」。你检查了 CLAUDE.md——里面只有技术栈和通用约束。Agent 没有违反任何一条 spec 条款。它只是不知道当前代码库里到底有哪些接口。
这不是你的 spec 写得不够好。这是一个 spec 本身解决不了的问题。
第一个边界：Agent 是「上下文盲人」
Spec Kit Agents 论文给这个问题起了个名字：context blindness。
论文的描述很精确：「Agent 的中间产物可以在内部逻辑自洽的同时，与仓库的实际状态不兼容。」什么意思？Agent 写出来的 spec、plan、task breakdown，单看每一步都合理——逻辑通顺，设计清晰。但它引用的 API 不存在，它提到的文件路径是编的，它假设的依赖关系在当前版本里已经变了。Agent 不是在偷懒，也不是在乱猜——它在用它训练数据里的「一般情况」填补当前仓库的「具体情况」，而两者之间的差距它自己看不出来。
这篇论文做了一件有用的事：它不只是诊断问题，还给了解法。研究团队在 GitHub Spec Kit 的四阶段流程（Specify → Plan → Tasks → Implement）中，每个阶段都加了一层 context-grounding hooks——让 Agent 在生成产物之前，先做一轮只读探查：检索相关文件、确认依赖版本、检查现有 API、扫描代码风格惯例。生成产物之后，再加一层 validation hooks——用项目实际环境验证 Agent 的中间产物，跑测试、跑 linter，看它有没有引用不存在的东西。
实验覆盖了 5 个仓库、32 个功能、128 次运行。结果：加了 grounding hooks 之后，Agent 产出质量提升了 0.15 分（1-5 分制），同时保持了 99.7% 到 100% 的仓库级测试兼容性。提升幅度看起来不大——但论文指出，真正的好处不是平均分跳了多少，而是减少了多步工作流中上下文错误的累积放大。一个不存在的 API 在第一步被引入，如果到第四步才发现，Agent 需要回溯整个链条。grounding hooks 把这个发现在第一步就截住了。
结论很直接：spec 本身不够。你还需要一套 grounding 机制，让 Agent 在每次生成之前先回答一个问题——「这个仓库里到底有什么」。spec 告诉 Agent 该做什么，grounding 告诉 Agent 在什么环境下做。
第二个边界：Spec 会跟代码「静默漂移」
Spec Growth Engine 论文识别出了第二个系统性问题。它有两个名字，第一个叫 context explosion——Agent 需要同时理解整个仓库，上下文窗口越塞越满，输出质量随之下降。论文引用了一组数据：一个强模型在长上下文编程基准上，当窗口从 32K 增长到 256K token 时，表现从 29% 暴跌到 3%。
但更危险的是第二个名字：silent spec-code drift。
论文对它的描述几乎是文学性的：「代码在演化，规范没有跟上。分歧变得不可见，直到修复成本已经很高。」这不是新问题——论文引用了 1990 年代软件架构研究的「architectural erosion」概念。但 AI 时代赋予了它一个新的危险维度：当一个 Agent 每分钟生成几百行代码，而 spec 停留在上个月的版本，损害积累的速度远远超过传统开发。
论文说了一段让人后背发凉的话：「这种失败模式尤其阴险，因为它始终不可见。Linter 不会标记它。CI 不会标记它。系统带着漂移发布出去。」就像一架带着裂缝起飞的飞机——没有人知道，直到它出事。
你在第 4 篇里读过 Agent 的外部记忆系统——进度文件、功能清单、git log。这些文件解决了 Agent「跨会话失忆」的问题。但它们解决不了漂移——因为漂移不是「忘记」，是「记错了」。Agent 读了上个月的 spec，spec 说 API 返回三个字段，但代码上周改成了四个。Agent 基于过时的 spec 生成了代码，代码跑得通——因为 Agent 还顺便修了调用方。但那个第四个字段携带的安全校验逻辑，被 Agent 当成冗余删掉了。没有人发现，因为测试没覆盖到，CI 没报错，spec 没更新。
Spec Growth Engine 的解法是把漂移检测变成合并阻断条件——不是「建议你更新 spec」，是 spec 和代码不一致时，PR 不能合并。drift gate。硬门禁。跟 linting 报错一样不可绕过。论文把这个机制叫「code-coupled」——spec 和代码在同一个 commit 里演化，改代码必须同时改 spec，否则你过不了门禁。
这意味着 spec 的维护方式必须改变。它不再是「有空了更新一下文档」的软约束，而是和测试一样的 CI 硬门禁。
