AI 编程真正缺的，不是提示词，是上下文系统

这不是一个纯理论判断。

最近我在维护一个项目，粗略统计了一下，光主要代码文件就已经有 11 万行左右。

真正麻烦的不是代码多。

而是当我反复让 Coding Agent 介入维护时，发现它最容易出错的地方，并不是不会写函数、不会补类型、不会改接口。

它真正容易翻车的地方，是不知道哪份文档该信，哪个路径已经迁移，哪段 fallback 只是兜底，改完以后到底应该跑哪组验证。

也就是说，代码量一上来，AI 编程的问题就从“会不会写”，变成了“能不能在正确上下文里写”。

我最近越来越觉得，AI 编程里最容易被低估的，不是模型能力，也不是提示词技巧。

而是上下文。

更准确地说，不是“给 AI 塞更多上下文”，而是项目里有没有一套可信的上下文系统。

这两个东西差别很大。

很多人一遇到 Coding Agent 写错代码，就会下意识想：是不是我给的信息不够？是不是 prompt 不够详细？是不是应该把更多文档、更多需求、更多历史记录都塞进去？

但真实情况经常相反。

AI 不是没看到信息。

它是看到了太多真假混在一起的信息。

有的文档是旧项目名，有的路径已经迁移，有的 feature 文档写得很完整但早就不是当前真源，有的 demo、mock、fallback 混在成功路径里，有的聊天总结看起来像架构事实，但其实只是当时的一段临时推理。

你给它更多，它不一定更聪明。

有时候只是更有信心地猜错。

所以今天这篇，我想讲一个更底层的判断：AI 编程要想提高代码质量和稳定性，不能只靠提示词，也不能靠无限扩张的知识库。

它需要的是一套高信噪比的上下文文档系统。

先说结论：

代码给事实，测试给证明，文档给边界，ADR 给原因，工作台给长任务交接。

这五件事分清楚，AI 才不容易乱猜。

文档不是让 AI 少看代码

很多人对工程文档有一个误解。

以为文档越完整，AI 就越不用看代码。

我觉得刚好反过来。

好的文档不是替代代码，而是告诉 AI：你应该先看哪里，什么才是 source of truth，哪些边界不能碰，改完以后应该怎么验证。

代码、测试、日志、配置、运行结果，永远是事实层。

文档不是事实本身。

文档是导航，是边界，是索引，是约束。

如果一个文档没有指向真实代码入口，没有说清验证命令，没有说明 owns 和 does not own，它写得再长，也只是给 AI 增加噪音。

这也是为什么很多项目“文档很多”，但 AI 还是会改错。

不是因为文档不够多。

而是因为它不知道哪份文档该信。

第一层：项目入口层

AI 进入一个项目，最怕的不是信息少，而是第一步就走错。

所以需要一个很清楚的项目入口层。

比如 AGENTS.md、docs/README.md，或者必要时的根目录 README。

这层文档不需要写得很深。

它只做几件事：

第一，告诉 AI 项目的主命名和主形态。

第二，告诉它目录职责和禁区。

第三，列出常用运行、测试、构建命令。

第四，写清项目特有纪律。

比如某些 refs 目录只是参考材料，不是当前运行真源；临时输出不能写到仓库根目录；某些旧路径只用于兼容读取，不代表现在应该继续扩散。

入口层最重要的不是“全面”，而是“别带偏”。

它应该像门口的路牌。

不是一本厚厚的城市历史书。

第二层：架构事实层

入口层解决“先看哪里”。

架构事实层解决“该信什么”。

这一层通常放在 docs/systems 或 docs/architecture 里。

它应该回答几个非常硬的问题：

这个系统的 source of truth 是什么？

它 owns 什么？

它 does not own 什么？

生命周期是什么？

失败模式是什么？

关键代码入口在哪里？

验证命令是什么？

你会发现，这些问题一点都不华丽。

但它们对 AI 编程特别关键。

因为 AI 最容易犯的错，就是看见一个相似实现，就以为它可以复用；看见一个旧路径，就以为它还是当前路径；看见一个 fallback，就以为那是主流程。

架构事实层的价值，就是把这些边界压缩清楚。

它不需要记录每一次小 diff。

它需要记录稳定事实。

第三层：决策记录层

有些东西，光知道“现在是什么”还不够。

你还得知道“为什么当初要这么做”。

这就是 ADR 的价值。

ADR 不应该变成实现文档。

它保存的是决策原因。

比如：为什么这个模块不直接调用另一个 runtime service？为什么这里保留一个兼容路径？为什么拒绝一个看起来更简单但风险更高的方案？为什么 source of truth 从 A 移到了 B？

这些东西如果不记录，AI 在后面的会话里很容易把它们当成“可以优化掉的复杂度”。

但很多复杂度不是偶然出现的。

它背后可能是边界、兼容、权限、运行时约束，或者之前踩过的坑。

什么时候值得写 ADR？

改变系统边界。

改变 source of truth。

改变 session、memory、workflow、tool、backup、sync 这类核心语义。

引入或删除重要兼容路径。

或者拒绝了一个看似合理但风险更高的方案。

ADR 的重点不是多写，而是把关键原因留住。

第四层：验证层

AI 编程最危险的一句话，是“已经完成”。

因为它经常意味着：看起来完成了。

但工程里真正重要的是：有没有被验证。

所以上下文系统里必须有验证层。

小改动，应该跑窄测试。

触及共享边界，应该跑更宽的测试。

文档结构变化，至少跑 architecture check。

可见 UI 或运行时入口变化，要补最小 smoke。

如果无法验证，就明确写出剩余风险。

这一步很重要。

因为 AI 的表达能力太强了，它可以把一个没有验证过的结果，说得像已经闭环了一样。

验证层就是把“说完成”变成“有证据”。

没有这层，代码质量会变得很玄学。

第五层：工作流层

长任务是 AI 编程里另一个高风险场景。

今天做到一半，明天换一个会话继续。

如果没有交接，下一轮 AI 很容易从头猜。

所以需要工作流层。

它可以是任务工作台、审计文档、TODO、CHANGELOG，或者某个长任务的临时交接记录。

它应该记录当前目标、非目标、证据快照、模块队列、已验证事实、未解决风险、下一轮从哪里继续。

但这里有一个边界特别重要：工作台不是稳定架构真源。

它只是任务现场。

任务结束后，稳定事实要回写到系统文档或架构文档；可执行待办回写 TODO；已经落地的历史回写 CHANGELOG。

否则临时工作台会慢慢变成另一个“看起来很重要但不知道该不该信”的噪音源。

真正的日常循环

如果把这套上下文系统用到日常 AI 编程里，大概是这样的。

开发前，AI 先建立事实上下文。

读项目入口。

找到相关系统文档。

确认 source of truth。

搜索已有实现和测试。

明确修改范围、边界和验证计划。

开发中，每个关键判断都要来自真实证据。

代码搜索、调用链、配置、日志、测试、最小运行验证。

不要因为“常见项目一般这样”，就直接改当前项目。

每个项目都有自己的 helper、类型、store、runtime service、tool executor、path policy、quality event。

AI 应该优先复用和收敛，而不是凭经验另起一套。

开发后，做三件事。

跑验证。

更新必要测试。

只更新有长期价值的文档。

这个“只”字很关键。

不是所有改动都值得写进文档。

普通 bugfix、局部变量改名、一次失败尝试、聊天里的临时推理，如果没有改变长期事实，就不要硬沉淀。

否则文档会膨胀，可信度会下降。

判断一条文档值不值得写

我很喜欢一个判断标准。

三个月后的维护者，会不会因为这条文档：

少读一轮无关代码？

少跑错一个命令？

少误判一个 source of truth？

少踩一个已经被验证过的坑？

如果答案是否定的，就别写。

AI 编程文档应该短、硬、可验证。

多写当前事实、稳定边界、source of truth、禁止事项、验证命令、已知缺口、退出条件。

少写愿景口号、泛泛原则、过期计划、没有命令或代码入口支撑的判断。

文档不是越多越专业。

文档越多，AI 越可能被噪音带偏。

关键是每一层都知道自己在干什么。

最小执行清单

如果你想立刻把这套方法用起来，可以先从这张清单开始。

每次让 AI 做工程改动前，问它九个问题：

第一，当前项目主命名和入口确认了吗？

第二，相关系统的 source of truth 确认了吗？

第三，现有实现和测试搜过了吗？

第四，这次改动属于哪个职责层？

第五，有没有旧命名、旧路径或兼容 fallback 需要收敛？

第六，成功路径是否混入 demo、mock 或 fallback？

第七，最小验证命令是什么？

第八，这次变化是否值得更新 docs 或 ADR？

第九，如果是长任务，交接点写在哪里？

这九个问题不复杂。

但它们能拦住很多 AI 编程里最常见的错误。

因为它们会不断提醒你：不要让 AI 猜。

最后

我不觉得 AI 编程的未来，是每个人都背一套更复杂的提示词。

真正重要的是，我们能不能把 AI 放进一个清楚的工程环境里。

让它知道先看哪里。

知道该信什么。

知道哪些边界不能猜。

知道改完以后怎么证明自己没乱改。

知道任务中断后，下一轮从哪里继续。

这就是上下文文档系统的价值。

它不是为了让文档变多。

而是为了让每一轮 AI 编程，都能在清楚边界、真实证据和可执行验证中推进。

如果你想立刻开始，可以先给自己的项目写一份很短的 Agent 文档。

不需要复杂。

重点是把入口、边界、真源和验证说清楚。

下面是一个可以直接改的提示词示例：

请为当前项目生成一份 AGENTS.md 草案。

目标：帮助 Coding Agent 在新会话中快速建立正确上下文，减少猜测和误改。

请先阅读项目根目录、README、主要配置文件、核心源码入口和已有测试，再输出文档。

AGENTS.md 必须包含：
1. 项目主命名和一句话说明
2. 主要目录职责
3. 当前 source of truth：代码、配置、文档分别以哪里为准
4. 明确禁止误用的旧路径、demo、mock、fallback 或临时文件
5. 常用开发、测试、构建、检查命令
6. 修改代码前必须先确认的边界
7. 修改完成后的最小验证要求
8. 长任务中断时应该写在哪里交接

要求：
- 只写已经能从代码、配置、测试或现有文档验证的事实
- 不要编造不存在的架构规则
- 不要把临时 TODO 写成稳定事实
- 如果证据不足，用“待确认”标出，并说明需要查看什么文件或运行什么命令
- 文档保持短、硬、可验证

更好的上下文，不是更多文字。

是更少猜测。