ARTICLE · 981702
文档即操作系统:L0~L3 四层金字塔模型
文档即操作系统：L0~L3 四层金字塔模型
"
“合抱之木，生于毫末；九层之台，起于累土。” — 《老子》
系列：《面向软件工程的 AI 编程范式》第 4 篇
关键词：文档分层、L0 契约、L1 需求、L2 设计、L3 指南、编号体系、上下文工程
上一篇留下的问题
上一篇我们提出了核心命题：AI 生成代码的质量上限，等于它拿到的上下文质量。并介绍了上下文工程的五条主张——文档 > 对话、分层 > 全量、编号 > 描述、门禁 > 自觉、生长 > 一次性。
但问题来了——72 份文档，AI 不可能一次全读。就算能读，它也分不清哪些该先读、哪些可以跳过、哪些是"宪法"级不可违反、哪些只是"建议"。
如果所有文档都是平等的，那文档就不是基础设施，而是噪音。
我们需要一个操作系统——让文档有层级、有优先级、有引用关系、有生命周期。就像计算机的操作系统管理内存和磁盘一样，文档操作系统管理 AI 的上下文。
这就是上下文工程第二条主张（分层 > 全量）的具体实现。
L0~L3：四层金字塔
在矿山底座平台的实践中，文档被分为四层。每一层有不同的"法律效力"和加载频率：
| L0 | 宪法 | |||
| L1 | 法律 | |||
| L2 | 法规 | |||
| L3 | 标准 |
为什么要分四层？因为 AI 的上下文窗口是有限的。你不能每次对话都把 72 份文档全塞进去——那只会让 AI 迷失在信息海洋里。
分层的核心价值是按需加载：
写一个认证服务的接口？加载 L0 契约（CT-02）+ L2 设计（详设 §5.1）即可 做一个新功能的验收？加载 L1 PRD（对应 AC）+ L0 契约（对应 CT）即可 做一次架构决策？加载 L2 架构（已有 ADR）+ L3 规约（决策模板）即可
分层不是割裂，而是让 AI 在正确的时机拿到正确的上下文。
底座平台的 72 份文档怎么分层
让我们用底座平台的真实文档来具体说明每一层长什么样。
L0 契约层：17 条 CT 条款
底座平台的契约文档（10-data-contract.md，386 行）定义了 17 种数据流的接口协议：
每一条 CT 条款都包含：字段清单与类型 / 质量语义 / 时标版本语义 / 消息格式 / 错误码。
契约的"宪法"地位体现在：详细设计 862 行代码里的每一个端点、每一个字段、每一个错误码，都标注了对应的 CT 条款。评审时的核心检查点就是"声称-字段一致性"——设计文档里声称的能力，必须在契约里有字段承载。
L1 需求层：PRD v0.15 + 14 份评审报告
PRD 文档（01-prd.md，134 行）定义了：
- 7 个能力域
（F1~F7）：统一认证/无感聚合/应用通信/统一 UI/Agent 运行时/公共能力/外部 API - 27 条验收标准
（AC-01~AC-27）：每条都可测试 - 6 条非功能验收
（NFR-01~NFR-06）：性能/隔离/驻留/兼容/License - 3 个里程碑
（M1 MVP/M2 增强/M3 管控）
PRD 不是孤立存在的。它的头部声明了完整的上游依据和关联文档：
上游依据：总体架构 v1.7（强制依赖）
关联文档：契约 v0.9 · 架构 ADR-01~09 · 概要设计 v0.8 · 评审报告 14 份这些"链接"把 PRD 锚定在整个文档网络中——AI 读 PRD 时，立刻知道该去哪里找契约、找架构决策、找评审报告。
L2 设计层：从架构到类级设计
L2 是底座平台文档体系中最庞大的一层，包含：
L2 的关键特征是每条 ADR 都有四要素：结论 / 理由 / 被否决的方案 / 适用边界。AI 在做设计决策时，先查已有 ADR——如果决策已有记录，禁止重新论证。
L3 指南层：规约 + 开发计划 + 任务卡
任务卡是指南层最直接的"AI 上下文入口"。一张典型的任务卡（如 T-1A01 认证服务）只有 33 行，但包含了 AI 编码需要的一切：
三段式追溯：T-1A01 / ADR-06 / CT-02
验收：AC-01（登录底座一次，接入应用免登录访问）
依据：契约 CT-02 · ADR-06 · 详设 §5.1/§6
DoD：编码完成 / 单测通过 / 验收场景通过 / CHANGELOG 登记AI 拿到这张卡，再加载 CT-02 和 ADR-06，就能开始编码了。不需要读 72 份文档——只需要 3 份。
编号体系：文档之间的"外键"
四层文档能形成网络而不是孤岛，靠的是编号体系。编号是文档之间的"外键"——就像数据库里表与表通过外键关联一样，文档通过编号形成可追溯的网络。
底座平台的核心编号体系：
这些编号在文档之间形成引用链：
任务卡 T-1A01
→ 依据 ADR-06（为什么继承迁移认证）
→ 约束 CT-02（SSO 会话与嵌入令牌的字段/格式/错误码）
→ 验收 AC-01（登录底座一次，全部应用免登）
→ 承载 F1（统一认证与授权能力域）当 AI 在编码时需要理解"为什么嵌入令牌默认 10 分钟"，它沿着 T-1A01 → CT-02 → ADR-06 追溯，在 ADR-06 里找到"继承建模认证，密钥迁移期不变"的决策依据。不需要重新论证——决策已经记录在案。
文档头部：每一份文档的"身份证"
底座平台的每一份文档，头部都有一段标准化的元数据声明。这不是格式癖好——这是 AI 的"导航地图"。
以详细设计为例：
版本：v0.10 | 日期：2026-08-21 | 状态：草案
文档层级：L2 设计层
上游依据：概要设计 v0.8 · 架构 v0.14（ADR-01~09）· PRD v0.15 · 契约 v0.9
· 主题包落地方案 v0.2 · 权限设计方案 v0.4 · 总体架构 v1.7
任务编号：T-1A01 起贯穿这段头部告诉 AI：
- 版本号
：该文档当前是什么版本，是否最新 - 文档层级
：这是 L2 设计层，不是 L0 契约 - 上游依据
：该文档的设计依据来自哪些文档、什么版本 - 关联任务
：该文档服务于哪些任务编号
当上游文档升级时（比如架构从 v0.13 升到 v0.14），AI 可以通过 grep 全仓搜索"架构 v0.13"来发现哪些文档的头部引用了旧版本，需要同步更新。这就是"版本引用同步"——评审的核心检查点之一。
文档生态全景
把四层文档和它们的引用关系画出来，底座平台的文档生态是这样的：
总体架构设计 v1.7（L0 总体架构，强制依赖）
│
┌──────┴──────┐
│ ADR-01 继承 │
└──────┬──────┘
│
┌──────────────────┼──────────────────┐
│ │ │
PRD v0.15 架构 v0.14 契约 v0.9
(L1, 27AC) (L2, 9 ADR) (L0, 17 CT)
│ │ │
│ ┌───────────┼───────────┐ │
│ │ │ │ │
│ 概要 v0.8 UI v0.5 接入规范 │
│ (L2) (L2) (L2) │
│ │ │
│ 详设 v0.10 │
│ (L2, 862行) │
│ │ │
│ ├─ 权限方案 v0.4 │
│ ├─ 主题包方案 v0.2 │
│ └─ 网关规范 v0.5 │
│ │
评审报告 ×14 ──驱动──→ 各文档版本演进 │
│ │
开发计划 v0.7 ──→ 25张任务卡（T-1A01~T-1C02）这不是一棵静态的树。它是活的——评审报告驱动版本升级，版本升级触发引用同步，引用同步引发新一轮评审。72 份文档在这个循环中持续"生长"。
为什么这比"写一堆文档"强
有人可能会说：这不就是写了一堆文档吗？我以前也写文档啊。
区别在三个地方：
第一，分层加载。你以前的文档可能是平铺的——所有文档同等重要，AI 不知道先读哪个。四层模型让 AI 知道：L0 是宪法不可违反，L1 是法律决定范围，L2 是法规指导设计，L3 是标准统一风格。按需加载，而不是全量投喂。
第二，编号互联。你以前的文档可能是孤立的——PRD 是 PRD，设计是设计，契约是契约。编号体系把它们粘成一张网：AC-01 ↔ CT-02 ↔ ADR-06 ↔ T-1A01，任何一条代码都能追溯到需求、决策和约束。
第三，头部导航。你以前的文档可能没有版本和依赖声明——AI 不知道手里的文档是最新的还是过期的。头部元数据让每份文档自带"导航坐标"，AI 能自动检测版本滞后和引用断裂。
这三个特征加在一起，文档就不再是一堆 Markdown 文件的集合——它是一个操作系统，管理着 AI 的全部上下文。
小结
L0~L3 四层模型解决的问题是：怎么让 AI 在正确的时机拿到正确的上下文。
L0 契约是宪法——代码可以不写，但契约必须先有 L1 需求是法律——做什么、不做什么、做到什么程度 L2 设计是法规——怎么定、为什么这么定、被否决的方案是什么 L3 指南是标准——让所有产出"长一个样子"
编号体系是文档之间的"外键"，文档头部是每份文档的"导航坐标"，评审报告是文档演进的"驱动力"。
这三者加在一起，72 份文档就不再是噪音，而是一个有序生长的操作系统。
面向软件工程的 AI 编程范式 · 系列文章