AI 编程的真正瓶颈不是模型，是上下文

"

“Context is worth 80 IQ points.” — Alan Kay

系列：《面向软件工程的 AI 编程范式》第 1 篇

关键词：AI 编程、上下文工程、文档驱动、软件工程

一个让人不安的事实

AI  Coding的同学，大概率经历过这样的场景。

场景一：上下文丢失。对话进行到第 200 轮，AI 忘了你最早拍板的架构决策——"继承迁移，不推翻重建"变成了"要不我们重新搞一套认证服务吧"。你不得不翻聊天记录，证明它自己三小时前为什么反对这个方案。

场景二：决策漂移。“为什么用 wujie 不用 iframe？”这个问题没有写进文档，于是 AI 每轮迭代都在重新回答它——而且每次答案都不一样。你花了三天做的技术选型，AI 用三句话就给你推翻了。

场景三：文档过期。你终于写了设计文档，但代码演进比文档快。AI 虔诚地照着过期设计写代码——比没文档更糟，因为你连"它在犯错"都发现不了。

更隐蔽的问题是第四个：黑箱交付。代码是 AI 写的，人还没完全看懂，更没人写文档。技术债以一种隐形的方式累积——AI 的代码质量取决于上下文质量，而上下文正在逐轮衰减。

这四个问题，不是模型能力不够造成的。GPT也好，Claude 也好，它们的能力已经足够强。问题出在一个更根本的地方——

我们给 AI 的上下文，配不上我们对代码质量的期望。

核心命题：上下文质量决定代码质量

在开发矿山工业互联网平台的实践中，我们提炼出一个核心命题：

AI 生成代码的质量上限，等于它拿到的上下文质量。

AI 的上下文只有两个来源：对话（易失、无序、会漂移）与文档（持久、有序、可检索）。

打一个比方：对话是内存，文档是磁盘——内存会断电。

当你关掉浏览器、换个会话、隔一天再回来，对话里的一切就消失了。但文档还在。它忠实地记录着：当初为什么选了这个架构、接口契约长什么样、哪些方案被否决了、代码里的每一行对应哪个需求编号。

所以我们的解法不是"写更好的提示词"，而是把文档做成 AI 编程的基础设施。

一个彻底的实验：矿山一体化应用底座平台

矿山一体化应用底座平台，是普联矿山工业互联网平台的一个核心子平台，也是这套范式最彻底的一次实践。

这个平台的定位是"矿山应用聚合底座"——不是一个业务系统，而是承载各类矿山行业应用的运行基座：统一身份、统一 UI、应用互通、无感聚合。它不是一个人在几天内能搞定的项目——它有 7 个能力域、27 条验收标准、3 个里程碑、25 张任务卡。

我们来看看，当"文档纪律"被严格执行时，这个项目的文档体系长成了什么样子：

72 份文档不是"写文档耽误了写代码"。恰恰相反，文档是这个项目里 ROI 最高的投资。因为每一份文档都在为后续的 AI 编码积累"上下文资产"。

举一个具体的例子：底座平台的 PRD 不是一次写成的。它从 v0.1 的骨架开始，经过 14 个版本的迭代，最终长成 134 行、27 条验收标准、7 个能力域的完整需求文档。每一次版本升级，背后都有一份评审报告在驱动——评审发现问题 → PRD 修订 → 契约同步补全 → 设计文档对齐。这不是"写文档"，这是"文档在生长"。

而那个 17 条契约条款的数据契约文档，也不是数据模式定义——它是 17 种接口协议的精确描述：应用注册表的字段清单、SSO 会话的令牌类型、嵌入消息的信封结构、Agent 工具注册的 ID 格式……每一行代码的端点和字段，都能追溯到具体的 CT 条款。

四个问题，四条解法

回到开头的四个问题。在矿山工业互联网平台多个项目的实践中，我们逐步发展出一套系统性的解法，后来被整理为一份工程规约（17-ai-doc-driven-programming.md）。

这四条解法不是独立的技巧，而是一个相互咬合的体系。我们给它起了一个名字——基于文档的面向软件工程 AI 编程范式。

"面向软件工程"的意思是：它不只关心"AI 怎么生成代码"，更关心"代码怎么在长周期里保持可维护、可追溯、可审计"。

这不是提示词工程，是上下文工程

很多人把"AI 编程"等同于"写提示词让 AI 生成代码"。这是一种窄化。

提示词工程关心的是单次对话里怎么把需求说清楚。它的天花板是对话窗口的长度——再好的提示词，也扛不住 200 轮对话后的上下文衰减。

我们关心的是一种更持久的东西：怎么让 AI 在跨会话、跨迭代、跨版本的长周期里，始终保持一致的工程行为？

答案是：把工程决策固化进文档，让文档成为 AI 的稳定上下文。

这不是提示词工程。这是上下文工程（Context Engineering）。

上下文工程的核心主张是：

1. 文档 > 对话
   ：持久化 > 易失性
2. 分层 > 全量
   ：按需加载 > 一次全塞
3. 编号 > 描述
   ：AC-01、CT-05、ADR-07 这种编号是文档之间的"外键"，把散落的文档粘成一张可追溯的网络
4. 门禁 > 自觉
   ：强制机制 > 靠人记得
5. 生长 > 一次性
   ：文档是活的，随评审和迭代持续演进

矿山应用一体化底座平台的 72 份文档，就是这五条主张的活证据。它们不是一次写成的——它们从第一版 PRD 的骨架开始，经过调研、评审、决策、契约、设计、任务分解，一步步"长"出来的。

这个系列要讲什么

这个系列共 11 篇文章，将系统性地分享这套AI编程范式。它不是理论空想——每一条款都来自普联矿山工业互联网平台的真实实践，有数据、有案例、有踩坑。系列以底座平台为核心案例，因为它是这套范式最彻底的应用实践。

第一部分：问题与理念

第 1 篇（本文）：提出问题，定义核心命题——上下文质量决定代码质量。

第 2 篇：上下文工程。提示词工程关心“单次对话”，上下文工程关心“跨会话、跨迭代、跨版本”。从提示词到上下文工程的范式转变，是这套方法论的理论基础。

第 3 篇：软件工程映射。软件工程的经典实践（Schema / Code Review / CI/CD / ADR）如何适配到“AI 是主要编码者”的场景，以及每个映射对应哪份文档。

第二部分：结构设计

第 4 篇：文档即操作系统。介绍 L0~L3 四层模型，以及底座平台 72 份文档如何自组织成一个完整的“文档操作系统”。

第三部分：五条铁律

第 5 篇：调研驱动决策。底座平台独有的调研体系——4 个专题 12 篇笔记如何经过评审，沉淀为 ADR 决策，最终驱动 PRD 和契约的成稿。

第 6 篇：评审闭环。14 份评审报告如何驱动文档从 v0.1 生长到 v0.15。跨文档的连锁反应是怎么发生的。

第 7 篇：契约先行。17 条 CT 条款不是数据模式，而是接口协议。底座平台的契约形态与早期项目完全不同——展示了范式在不同场景的适配能力。

第 8 篇：ADR 的继承与进化。底座平台的 ADR-01 强制依赖总体架构设计，ADR-05 取代 ADR-04 的载体条款——决策是怎么跨项目传导、又怎么在事实面前进化的。

第 9 篇：对齐门禁与交付即沉淀。“实现赢但文档必须记录偏差”——文档不过期的铁律。以及三段式追溯（T/ADR/CT）如何让交付可审计。

第四部分：执行与落地

第 10 篇：迭代循环。以 T-1A01（认证服务）为例，完整展示任务卡、三段式追溯、波次排期、里程碑退出门禁。

第 11 篇：从理论到实践。1 小时启动一个新项目，按规模裁剪，以及这套范式在 4 个不同项目中的普适性验证。

写在最后

有人把 AI 编程理解为"让 AI 写代码"。我们的实践更接近另一句话：

AI 编程 = 把工程决策固化进文档，让 AI 的每一次生成都有据可依。

代码会重构，架构会演进，框架会换代。唯有文档——连同它背后的决策——是这个项目的常量。

平台的 72 份文档、14 次评审、9 条决策记录、17 条契约条款，不是某个人"有空时写的"。它们是这套范式的必然产出——当你把"文档纪律"做到位，这些东西会自然生长出来。

当 AI 越来越会写代码，"写什么、为什么这么写"的决定权，必须越来越重地落在人——以及人维护的文档——手里。

这，就是我们理解的面向软件工程的 AI 编程方式。

面向软件工程的 AI 编程范式 · 系列文章