最近在使用 GPT-6.1 Sol 配合 grill-with-docs 和 to-spec 时，我注意到一个变化：它会直接在 docs/design/ 下生成两类文档——需求共识 和 实现规格。
过去使用旧模型时，需求共识 通常只在会话中完成确认；即使需求比较复杂，也大多只是先生成到临时目录供人工检查。实现规格 也类似，通常先生成临时文档，随后再将内容整理并发布为 issue，不会长期保留在仓库中。
现在经过权衡，我决定改变这一做法：保留这些设计文档，并直接提交到 Git。
这样做的好处是，需求形成过程、设计思路和实现规格都能留下完整记录。以后回顾某项功能为什么这样设计时，相比只保留 issue 或最终代码，会有更完整的上下文。
但这也带来了另一个问题：历史设计文档很容易被 AI 误认为项目当前状态。
最近我就遇到过类似情况：AI 将 docs/research/ 中的一份研究文档误认为已经落地的方案，并据此判断当前实现。实际上，这类文档记录的只是某个时间点的调研、候选方案和结论，并不意味着其中的内容已经被采用。
因此，我最终在 AGENTS.md 中增加了下面这组规则，明确不同文档的可信边界：
现状与已定设计以当前代码、
CONTEXT.md和docs/adr/为准。仅CONTEXT.md和docs/adr/持续维护为最新状态；判断当前实现时，以当前代码为事实依据。将设计文档或研究报告作为实现依据前，应先在代码中核实相关描述。
docs/design/记录对应任务执行时的需求、设计与规格，仅作为历史参考，不代表最新代码现状。
docs/research/收录研究报告。各文档记录写作时点对上游能力、候选方案与结论的调研，不描述项目当前状态，也不代表相关设计已经被采纳。
我现在更倾向于把这些内容看成不同层级的信息来源：
代码 是当前事实，CONTEXT.md 和 docs/adr/ 是持续维护的项目认知与已定决策，而 docs/design/ 和 docs/research/ 则是带有明确时间属性的历史上下文。
从这个角度看，“文档是否应该进入 Git”其实只是表层问题。更核心的问题，是如何给不同上下文定义清晰的可信度和时效性。
对于 AI Agent 来说，保留更多上下文本身并不是问题。真正重要的是让它知道：哪些内容可以直接当作当前事实，哪些内容只是历史记录、设计过程或尚未落地的研究结论。
这实际上也是我现在越来越重视的一类 Agent 工程问题：除了给模型提供更多上下文，还需要给这些上下文本身建立明确的语义边界。