夜雨聆风摘要： AI 开发的文档不是说明书，而是给模型构造上下文、状态、约束和评估器。
标签： AI编程、上下文工程、需求文档、设计文档、AI协作
最近在 vibecoding 时，我反复碰到一个问题。
不是 AI 不会写代码。
也不是我完全没有写需求。
恰恰相反，很多时候需求文档有了，设计方案有了，执行计划也有了。AI 也确实一直在干活，文件在改，命令在跑，页面能打开，接口能返回。
但最后验收时，结果就是不对。
这种“不对”最难受。
它不是语法错误，不是明显跑不起来，而是局部看着都合理，整体却偏了：目标缩水了，边界扩大了，概念混了，验收断了，代码规范知道但没执行。
我一开始以为这是提示词问题。
后来发现不完全是。
这更像是文档形态的问题。我们过去写文档，默认读者是一个人。人有长期记忆，有业务经验，有组织习惯，有工程直觉，还会根据上下文补全很多没写出来的东西。
但模型不是这种读者。
模型看到的是当前上下文窗口里的 token。它不是把一份需求读完以后，在脑子里形成一个稳定、完整、可持续维护的项目理解，再像人一样带着这个理解去做事。它是在每一步生成时，根据当前上下文、注意力分布、训练中学到的模式、工具返回的信息，预测下一步最合理的动作。
所以，AI 开发的文档不能再只是“给人看的说明书”。
它必须变成模型的外部运行环境：
帮模型知道当前任务是什么。 帮模型知道哪些信息重要。 帮模型知道什么是对的。 帮模型知道当前做到哪一步。 帮模型知道是否偏离预期。 帮模型在偏离时能回到正确轨道。
这篇文章不想再泛泛说“需求要写清楚”。
我想从模型运行原理出发，重新推导一遍：需求文档、设计文档、执行计划、代码规范到底应该长什么样，才更适合 AI 稳定输出。
一、先把模型当成什么都不是
要写给 AI 用的文档，第一步是先放下几个错觉。
第一个错觉：模型看过，就等于理解了。
第二个错觉：模型理解了，就等于会一直记得。
第三个错觉：模型知道规范，就等于执行时会遵守。
第四个错觉：模型说完成，就等于真的可验收。
这些错觉，本质上都是把模型当成了一个稳定的人。
但从运行机制看，大语言模型更像一个“上下文驱动的生成系统”。它没有人类那种持续稳定的项目脑子。它在每一步都依赖当前能看到的信息，以及这些信息在当前生成目标下被激活的程度。
Transformer 架构的核心是注意力机制。注意力机制让模型在生成时可以关注上下文里的不同位置。但“能关注”不等于“一定关注”，更不等于“按人类认为的重要性关注”。
如果一份文档里同时出现了背景、愿景、功能列表、技术方案、例外情况、代码规范、验收标准，模型可能都看到了，但它未必知道哪个是硬约束，哪个只是解释，哪个是当前阶段必须执行，哪个只是未来规划。
这就是很多长文档失效的原因。
不是信息不够。
而是信息没有被组织成模型容易使用的形态。
对模型来说，一段自然语言里的“请注意代码质量”，和一条阶段门禁里的“后端实现结束前必须运行 pnpm test，并在交付报告中贴出通过结果”，约束力完全不一样。
前者是语义提示。
后者是执行结构。
AI 开发文档要解决的不是“让模型读懂中文”，而是让模型在生成、调用工具、修改代码、汇报结果的每一步，都被正确的信息结构牵引。
二、模型处理信息的几个关键特性
如果把模型原理压到工程实践里，我认为至少有六个特性必须重视。
1. 上下文窗口不是记忆，只是当前工作台
上下文窗口像一张临时工作台。
你把需求、代码片段、命令输出、用户反馈、规范都放上去，模型就能在这张工作台上处理它们。
但工作台不是长期记忆。
当上下文太长，旧信息会被压缩、截断、弱化；当新工具输出很多，模型注意力会被新信息吸走；当任务持续多轮，早期目标很容易变成模糊背景。
这解释了一个常见现象：一开始明明说过“不允许修改公共组件”，做到后面 AI 还是改了公共组件。
不是它故意违背。
而是这条约束没有在执行过程中反复进入“当前工作台”的高优先级位置。
所以文档不能只在开始喂一次。关键约束必须在任务简报、阶段检查、交付报告里反复出现。
2. 注意力不是优先级系统
注意力机制会计算上下文中不同 token 对当前生成的影响，但它不等于项目管理里的优先级。
人类看到“P0”“必须”“禁止”“验收不通过”会自然提高警惕。模型能理解这些词，但在长上下文、多目标、多约束下，它不一定稳定把它们当成最高优先级。
这就要求文档不要只靠形容词表达重要性。
不要只写：
“必须保证权限安全。”
要写成可执行规则：
规则 SEC-001：任何列表查询必须复用系统租户与数据权限机制。
- 禁止：在业务 SQL 中手写临时租户过滤。
- 验收：使用普通用户和管理员各查询一次，确认数据范围不同。
- 交付报告必须说明：本次查询权限由哪个既有机制生效。
这种写法的重点不是更啰嗦，而是把“重要”变成了“规则编号 + 禁止方案 + 验收方式 + 汇报字段”。
模型更容易执行这种结构。
3. 模型擅长补全，但补全会引入默认世界
大模型很擅长根据上下文补全缺失信息。
这是能力，也是风险。
当需求里没有说清楚“任务归档后是否允许修改”，模型可能按常见后台系统经验补一个默认逻辑。当设计里没有说“必须复用现有搜索区组件”，它可能重新写一个看起来也不错的搜索区。当计划里没有说“没有真实验收证据不能宣布完成”，它可能在代码写完后自然地说“已完成”。
模型的补全来自训练语料中的常见模式，不一定来自你的业务现实。
所以，面向 AI 的文档必须写“反默认值”。
什么叫反默认值？
就是那些人类团队里大家心照不宣，但模型很容易按通用经验走错的地方：
不要做 demo，要做真实业务闭环。 不要用 mock 数据假装验收。 不要为了修页面改公共组件。 不要把配置数据和运行数据混在一起。 不要把“代码能跑”当成“业务可用”。
这些内容必须显式写进“禁止事项”和“反例”。
4. 模型没有天然状态表
开发任务不是一次生成，而是多步执行。
多步执行最怕状态丢失。
例如当前到底是：
需求确认阶段？ 设计阶段？ 后端实现阶段？ 前端联调阶段？ 验收阶段？ 发布阶段？
哪些文件已经改了？
哪些命令只是跑过，哪些是真的通过？
哪些结果是模型推测，哪些是工具验证？
人类开发者会在脑子里维护这些状态。模型如果没有外部状态表，就容易把“我准备做”“我已经做”“我以为做了”“工具证明做了”混在一起。
所以执行计划不能只是 todo list。
它必须是状态机。
每个阶段都要有进入条件、退出条件、证据和失败处理。
5. 模型需要外部知识，但外部知识必须结构化
RAG 的核心启发是：模型参数里的知识不够，很多任务需要外部知识。企业项目更是这样。项目规范、业务规则、接口文档、数据库结构、历史踩坑，都不在模型参数里。
但把外部知识塞进上下文，不等于模型就能稳定使用。
如果知识是一大坨自然语言，模型仍然要自己解析关系、判断优先级、提取规则。这一步会出错。
所以知识要拆成可以检索、可以引用、可以评估的块。
例如不要只写：
“客户有渠道，渠道下有客户经理，客户经理可以报单。”
应该写成：
实体：Channel
- 含义：业务渠道
- 关系：Channel 1:N CustomerManager
- 可执行动作：创建客户、提交报单、查看本渠道订单
- 权限边界：只能查看所属渠道数据
实体：CustomerManager
- 含义：渠道客户经理
- 关系：属于一个 Channel
- 禁止：跨渠道查看订单
这就是把自然语言知识变成实体、关系、动作、边界。
如果再进一步，就接近知识图谱或 GraphRAG 的思路：知识不是一堆段落，而是实体与关系的网络。
6. 模型不会自动知道什么是“对”，需要评估器
这是最关键的一点。
AI 开发的核心不是“告诉模型做什么”，而是“告诉模型如何判断自己做得对不对”。
人类需求文档经常停在“要做什么”。但模型更需要“做到什么状态算对”。
例如“支持审批”不是一个可执行标准。
可执行标准应该是：
申请人提交后生成审批任务。 审批人待办列表出现该任务。 审批通过后业务单据状态变为已通过。 审批拒绝后业务单据状态变为已驳回。 每次审批动作生成审计日志。 用普通用户直接调用审批接口会失败。
这才是评估器。
没有评估器，模型会用自己的默认标准判断完成。
而模型的默认标准，经常是“动作完成”，不是“业务正确”。
三、从模型原理推导文档原则
既然模型有这些特性，文档就不能按传统方式写。
我现在会把面向 AI 的文档原则总结成八条。
原则一：每条重要信息都要有位置
不要把重要信息藏在一段长话里。
目标放目标区。
边界放边界区。
规则放规则区。
状态放状态区。
验收放验收区。
反例放反例区。
这样做不是为了好看，而是为了让模型、检索系统、人类复盘都能快速定位。
原则二：每个抽象词都要落到证据
“完成”“支持”“优化”“可用”“安全”“稳定”“符合规范”，这些词对人有意义，但对模型执行不够。
它们必须落到证据。
完成的证据是什么？
可用的证据是什么？
安全的证据是什么？
符合规范的证据是什么？
如果没有证据，模型就会用语言完成替代工程完成。
原则三：每个业务对象都要定义生命周期
业务系统里最怕概念混。
订单、申请、任务、审批、日志、配置、模板、实例，这些词只要边界不清，AI 会很快写出一套看起来完整但根基错误的代码。
所以核心对象必须写：
定义是什么。 谁创建。 什么时候创建。 状态怎么变化。 谁能操作。 什么时候结束。 与其他对象是什么关系。
模型不是不会写 CRUD，而是会在概念没清楚时替你发明 CRUD。
原则四：每个阶段都要有门禁
AI 容易跳步。
需求没确认就设计。
设计没确认就编码。
接口没验证就写页面。
页面能打开就宣布完成。
所以执行计划必须带门禁。
门禁不是“建议检查”，而是“没有证据不能进入下一阶段”。
原则五：规范要分层进入上下文
代码规范不能一次性贴一万字。
模型会被淹没。
规范应该分四层：
长期原则：放 AGENTS.md、项目说明、系统规则。 任务摘录：本次任务相关的 5 到 10 条。 阶段自检：每个阶段结束必须回答。 自动门禁：lint、typecheck、test、e2e、截图检查。
规范不是一份文档，而是一套进入执行循环的机制。
原则六：反例和禁止事项必须显式写
只写正确做法不够。
模型会自动补全“看起来也合理”的做法。
所以要写：
不允许什么。 容易误解什么。 看起来合理但不采用什么。 如果遇到某种情况必须停下来问什么。
反例是把人的工程经验外化。
原则七：状态必须外置
不要相信模型会稳定记住当前状态。
执行计划里要有状态记录：
当前阶段。 已完成。 未完成。 已验证事实。 未验证假设。 风险。 下一步。
这就是给模型一张外部工作记忆表。
原则八：反馈必须沉淀成规则
AI 做错一次，如果只在对话里说“你错了”，下一次还会错。
有效反馈必须沉淀成规则：
错误行为是什么。 为什么错。 正确做法是什么。 下次如何判断。 是否加入需求模板、设计模板、执行计划或代码规范。
这才是上下文工程的持续进化。
四、需求文档：它不是愿望清单，而是目标函数
从模型原理看，需求文档承担的角色不是“告诉 AI 有哪些功能”。
它更像目标函数。
它要定义：什么结果更接近正确，什么结果偏离正确。
所以需求文档必须解决四类问题：
模型要优化的目标是什么。 模型不能越过的边界是什么。 模型需要理解的业务世界是什么。 模型如何判断结果是否达到预期。
下面是我认为更适合 AI 的需求文档模板。
需求文档模板
## 0. 给模型的读取说明
- 本文档用途：定义目标、业务对象、规则、边界和验收标准。
- 执行要求：编码前必须先复述第 1、2、4、6、9 节。
- 禁止：未确认核心对象和状态机前直接写代码。
## 1. 目标函数
### 1.1 一句话目标
为了让【用户角色】在【业务场景】中完成【关键任务】，系统需要提供【能力】，最终达到【可验证结果】。
### 1.2 成功状态
| 成功状态 | 可观察证据 | 验收方式 |
|---|---|---|
### 1.3 失败状态
| 失败状态 | 为什么失败 | 如何发现 |
|---|---|---|
## 2. 范围边界
### 2.1 本次必须做
-
### 2.2 本次明确不做
-
### 2.3 如果模型想扩大范围
- 必须先说明原因、影响文件、风险和替代方案。
- 未经确认，不允许修改范围外模块。
## 3. 用户与场景
| 用户角色 | 使用场景 | 触发条件 | 期望结果 | 权限边界 |
|---|---|---|---|---|
## 4. 业务对象模型
| 对象 | 定义 | 谁创建 | 生命周期 | 与其他对象关系 | 易混淆对象 |
|---|---|---|---|---|---|
## 5. 业务规则
| 编号 | 规则 | 规则类型 | 适用对象 | 反例 | 验收方式 |
|---|---|---|---|---|---|
| R-001 | | 硬规则/默认规则/提示规则 | | | |
## 6. 状态机
### 6.1 状态定义
| 状态 | 含义 | 进入条件 | 退出条件 | 可执行动作 |
|---|---|---|---|---|
### 6.2 状态迁移
| 当前状态 | 动作 | 下一状态 | 前置条件 | 失败处理 | 审计要求 |
|---|---|---|---|---|---|
## 7. 输入输出
| 功能点 | 输入 | 处理 | 输出 | 持久化数据 | 外部依赖 |
|---|---|---|---|---|---|
## 8. 页面与交互
| 页面 | 菜单路径 | 用户动作 | 系统反馈 | 复用页面/组件 | 禁止事项 |
|---|---|---|---|---|---|
## 9. 验收用例
| 用例 | 前置数据 | 操作步骤 | 预期结果 | 必须提供的证据 |
|---|---|---|---|---|
## 10. 反例库
| 错误做法 | 为什么错 | 正确做法 |
|---|---|---|
## 11. 完成定义
- 业务完成：
- 代码完成：
- 页面完成：
- 数据完成：
- 权限完成：
- 测试完成：
- 交付完成：
这个模板里的字段，不是随便加的。
它们分别对应模型运行中的问题：
需求文档写到这个程度，才不是“我想要什么”，而是“模型应该朝哪个目标收敛”。
五、设计文档：它不是技术说明，而是决策边界
需求文档定义目标函数。
设计文档定义搜索空间。
模型写代码，本质上是在一个很大的可能空间里寻找实现路径。设计文档要做的，是把这个空间缩小到工程上可接受的范围内。
人类设计文档经常写“采用 Spring Boot + MyBatis-Plus + Vue”，但这对 AI 还不够。
AI 真正需要知道的是：
哪些现有机制必须复用。 哪些方案看起来可行但不能用。 哪些层负责哪些逻辑。 遇到冲突时优先级是什么。 哪些决策已经做完，不允许重新发明。
设计文档模板
## 0. 给模型的读取说明
- 本文档用途：约束实现路径，避免模型自行发明架构。
- 编码前必须确认：第 2、3、4、6、8 节。
- 如果实现与本文档冲突，必须停下来说明冲突，不允许直接改。
## 1. 设计结论
- 推荐方案：
- 核心取舍：
- 不采用方案：
- 最大风险：
## 2. 架构边界
| 层级 | 职责 | 可修改 | 不可修改 | 必须复用 |
|---|---|---|---|---|
| 前端 | | | | |
| 后端接口 | | | | |
| 业务服务 | | | | |
| 数据访问 | | | | |
| 公共组件 | | | | |
## 3. 决策表
| 场景 | 判断条件 | 正确方案 | 禁止方案 | 原因 | 如有例外怎么办 |
|---|---|---|---|---|---|
## 4. 概念模型
| 概念 | 定义 | 所属层 | 生命周期 | 关系 | 禁止混用 |
|---|---|---|---|---|---|
## 5. 数据设计
### 5.1 表与字段
| 表 | 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|---|
### 5.2 数据分类
| 数据 | 类型 | 配置/运行/审计/临时 | 谁写入 | 谁读取 | 保留策略 |
|---|---|---|---|---|---|
## 6. 接口设计
| 接口 | 方法 | 入参 | 出参 | 权限 | 幂等 | 错误处理 | 验收 |
|---|---|---|---|---|---|---|---|
## 7. 前端设计
| 页面 | 参考页面 | 复用组件 | 区域结构 | 数据来源 | 禁止自造交互 |
|---|---|---|---|---|---|
## 8. 非功能与工程约束
| 约束 | 正确做法 | 检查方式 |
|---|---|---|
| 权限 | | |
| 租户 | | |
| 日志 | | |
| 审计 | | |
| 性能 | | |
| 可观测性 | | |
## 9. 设计反例
| 反例 | 为什么看起来合理 | 为什么不能用 | 替代方案 |
|---|---|---|---|
## 10. 验证设计是否落地
| 设计点 | 验证方法 | 证据 |
|---|---|---|
这里最重要的是“决策表”。
因为 AI 最容易出错的地方，不是已经写清楚的地方，而是文档没写、但实现时必须做选择的地方。
例如：
| 场景 | 判断条件 | 正确方案 | 禁止方案 | 原因 |
|---|---|---|---|---|
| 页面布局不一致 | 只影响当前页面 | 当前页面内修复 | 修改公共组件 | 避免影响全局 |
| 权限校验 | 需要限制数据范围 | 复用系统数据权限 | 前端隐藏按钮代替后端权限 | 前端限制不可信 |
| 分页查询 | 列表数据较多 | 使用项目分页组件和后端分页 | 前端一次性加载后分页 | 性能和权限风险 |
| 临时演示 | 需要尽快看到页面 | 使用真实接口和测试数据 | hardcode mock 数据进入正式代码 | 防止假完成 |
这张表就是把人的工程判断翻译给模型。
设计文档不是为了证明架构师想过，而是为了限制模型不要乱想。
六、执行计划：它不是待办清单，而是外部状态机
执行计划是 AI 开发里最应该重写的东西。
传统计划喜欢列步骤：
建表。 写接口。 写页面。 测试。
这对模型不够。
因为它没有说明：
什么条件下能开始建表？ 建表完成的证据是什么？ 接口没验证能不能写页面？ 页面能打开是否等于完成？ 测试失败应该回到哪一步？ 当前已验证事实有哪些？
AI 需要的是状态机。
执行计划模板
## 0. 任务运行规则
- 每个阶段开始前，必须确认进入条件。
- 每个阶段结束后，必须填写阶段报告。
- 没有证据，不允许标记完成。
- 如果发现范围外问题，只记录，不直接扩大修改范围。
## 1. 当前任务摘要
- 原始目标：
- 本轮目标：
- 本轮不做：
- 修改半径：
- 成功标准：
- 风险：
## 2. 前置状态检查
| 检查项 | 方法 | 预期 | 实际 | 是否通过 |
|---|---|---|---|---|
| 工作区 | git status | 干净或已提交 | | |
| 依赖 | | 可安装/已安装 | | |
| 服务 | | 可启动 | | |
| 测试基线 | | 当前可运行 | | |
## 3. 阶段状态机
| 阶段 | 进入条件 | 主要动作 | 完成条件 | 必须证据 | 失败回退 |
|---|---|---|---|---|---|
| S1 需求复述 | 需求文档存在 | 复述目标/边界/对象/验收 | 用户或文档确认 | 复述记录 | 回到需求澄清 |
| S2 概念建模 | S1 通过 | 梳理对象/关系/状态机 | 概念无冲突 | 对象表/状态表 | 回到 S1 |
| S3 设计确认 | S2 通过 | 确认架构边界/决策表 | 设计约束明确 | 设计摘录 | 回到 S2 |
| S4 后端实现 | S3 通过 | 数据/接口/服务/权限 | 接口测试通过 | 测试日志 | 回到 S3/S4 |
| S5 前端实现 | 后端接口可用 | 页面/交互/联调 | 真实页面可用 | 截图/路径 | 回到 S4/S5 |
| S6 验收闭环 | S5 通过 | 真实数据跑主流程 | 用例全部通过 | 地址/数据/截图/日志 | 记录缺陷并回退 |
| S7 收尾提交 | S6 通过 | 提交/报告/风险说明 | 工作区干净 | commit/status | 回到对应阶段 |
## 4. 阶段报告模板
- 当前阶段：
- 进入条件是否满足：
- 实际完成：
- 未完成：
- 已验证事实：
- 未验证假设：
- 是否扩大范围：
- 是否违反规范：
- 证据：
- 下一阶段是否允许进入：
## 5. 偏差记录
| 偏差 | 发现阶段 | 原因 | 处理 | 是否沉淀为规则 |
|---|---|---|---|---|
## 6. 交付报告
- 原始目标：
- 实际完成：
- 未完成/延期：
- 修改文件：
- 运行环境：
- 验收地址：
- 测试数据：
- 操作步骤：
- 预期结果：
- 实际结果：
- 测试命令：
- 证据：
- 风险：
- 下一步：
这套执行计划的核心是把模型从“自由推进”拉回“状态推进”。
每一步都要回答：
我现在在哪？
我凭什么能进入下一步？
我凭什么说这一步完成？
这三个问题，是 AI 开发稳定性的底座。
七、代码规范：它不是知识，而是运行时约束
代码规范最容易被误用。
很多人把规范写成一本手册，然后在任务开始时贴给模型。
效果通常不稳定。
原因很简单：规范太多，任务太长，上下文会漂移，报错会抢注意力，模型会为了当前局部目标牺牲长期规范。
所以代码规范不要只当知识库，要当运行时约束。
我建议分成四种形态。
1. 长期规范：放在固定上下文
例如 AGENTS.md、项目根目录说明、团队默认规则。
内容要少，但要硬：
- 修改前必须阅读同类实现。
- 不允许扩大修改范围。
- 不允许引入 mock/fake/临时代码作为正式交付。
- 不允许绕过权限、租户、审计机制。
- 完成后必须提供真实验收证据。
2. 任务规范：每次只摘相关规则
后端任务：
本任务后端规范：
- 列表查询必须使用项目既有分页机制。
- 权限必须复用既有权限和数据权限机制。
- 不允许使用裸 JDBC 绕过仓储层。
- 不允许 hardcode 租户、用户、角色。
- 接口必须提供成功和失败用例验证。
前端任务：
本任务前端规范：
- 页面结构必须参考同业务域已有页面。
- 搜索区、表格区、操作区不要自造布局。
- 字典值显示中文，不显示 code。
- 不允许使用假数据替代真实接口。
- 完成后必须提供页面路径和截图。
3. 阶段规范：每阶段结束重新检查
例如后端阶段结束：
后端阶段自检：
- 是否复用权限机制？
- 是否复用租户机制？
- 是否没有临时代码？
- 是否没有裸 SQL 绕路？
- 是否有接口测试证据？
这一步的作用，是把规范从“开始时看过”变成“结束时必须判断”。
4. 自动规范：交给工具
能自动化的，绝不要只靠模型自觉。
lint typecheck unit test integration test e2e test forbidden pattern scan screenshot check SQL migration check
模型很适合根据工具反馈修复，但前提是工具真的跑了。
所以执行计划里必须写清测试命令和通过证据。
代码规范的稳定形式应该是：
长期原则 -> 任务摘录 -> 阶段自检 -> 自动门禁 -> 反馈沉淀
这才是规范进入模型执行循环的方式。
八、把文档做成知识结构，而不是文章
如果从知识类数据结构看，AI 文档最好不要是一篇顺滑的文章。
文章适合人读。
模型更需要结构。
我认为至少要有五类知识块。
1. 实体块
实体：GuaranteeApplication
- 中文名：保函申请
- 含义：客户发起的一次保函办理请求。
- 创建者：渠道客户经理/内部商务。
- 生命周期：草稿 -> 已提交 -> 风控审核 -> 出函中 -> 已出函/已拒绝。
- 关系：
- 属于一个 Customer。
- 可关联多个 Attachment。
- 会产生多个 AuditLog。
- 禁止混淆：
- 不是保函文件本身。
- 不是银行出函记录。
2. 关系块
关系：GuaranteeApplication -> Attachment
- 类型：1:N
- 含义：一个保函申请可以包含多个资料附件。
- 约束：附件必须属于当前申请，不能跨申请复用。
- 验收：查询申请详情时能看到该申请下附件列表。
3. 规则块
规则 R-003：已出函申请不可修改核心信息
- 适用对象：GuaranteeApplication
- 触发条件：status = ISSUED
- 正确行为：隐藏编辑入口，后端拒绝更新。
- 禁止行为：只在前端隐藏按钮，后端仍可更新。
- 验收：直接调用更新接口应失败，数据库核心字段不变。
4. 决策块
决策 D-002：附件存储方式
- 场景：上传保函资料。
- 选择：使用系统既有文件服务。
- 不选择：业务表中存 base64。
- 原因：避免数据库膨胀，复用权限和预览能力。
- 例外：无。
5. 验收块
验收 A-005：提交申请
- 前置数据：存在客户、渠道、保函类型。
- 操作步骤：
1. 新建申请。
2. 上传资料。
3. 点击提交。
- 预期结果：
- 状态变为已提交。
- 生成提交日志。
- 风控待办出现该申请。
- 证据：
- 页面截图。
- 数据库记录。
- 接口返回。
这五类知识块，比一篇连续自然语言更适合 AI。
因为它们有稳定边界、稳定字段、稳定引用方式。
当模型需要判断“能不能修改已出函申请”时，它应该检索到规则 R-003，而不是在一篇长文里自己猜。
九、一次真实任务应该怎样喂给模型
有了这些文档以后，真正喂给模型时也不能一股脑全塞。
要分层。
第一层：任务简报
每次任务开始，先给一屏以内的简报：
你要完成：{功能名称}
请先阅读：
- 00-task-brief.md
- 01-requirements.md
- 02-design.md
- 03-plan.md
- 04-standards.md
开始前不要写代码。先输出：
1. 原始目标
2. 本轮不做
3. 核心业务对象
4. 状态机
5. 修改半径
6. 阶段计划
7. 不确定问题
第二层：按阶段给上下文
概念建模阶段，只给需求、对象、状态、规则。
设计阶段，给架构边界、决策表、反例。
编码阶段，给当前模块代码、任务规范、相关接口。
验收阶段，给验收用例、真实数据、操作路径。
不要把所有东西一直堆在上下文里。
上下文不是越多越好，而是当前阶段需要什么，就给什么。
第三层：每阶段强制回填状态
每阶段结束都让模型填：
- 当前阶段：
- 已完成：
- 未完成：
- 已验证事实：
- 未验证假设：
- 是否偏离目标：
- 是否扩大范围：
- 证据：
- 下一步：
这能减少模型把推测当事实。
第四层：错了以后更新规则
如果 AI 做错，不要只说“不对”。
要补一条反馈：
反馈 F-007：AI 将页面能打开误判为验收完成
- 错误行为：未使用真实数据走主流程，只提供页面地址。
- 为什么错：页面可访问不等于业务可用。
- 正确做法：必须提供测试数据、操作步骤、预期结果、实际结果和截图。
- 加入位置：03-plan.md 的 S6 验收闭环阶段。
这才会让文档系统进化。
十、我的结论：文档是模型的外部脑子
现在回头看，我之前那种“需求写了、设计写了、计划写了，为什么还是不行”的困惑，答案大概是：
文档虽然写了，但它们还不是模型可运行的结构。
人类文档强调表达。
AI 文档强调运行。
人类文档可以省略共识。
AI 文档必须外化共识。
人类文档可以靠经验补全。
AI 文档必须写出边界、反例和证据。
人类开发者会维护脑中的状态。
AI 需要外部状态机。
人类知道什么是完成。
AI 需要验收器。
所以，面向 AI 的需求文档、设计文档、执行计划，不是传统文档的小修小补，而是文档范式变化。
它们应该共同构成一个系统：
需求文档 = 目标函数
设计文档 = 搜索空间和决策边界
执行计划 = 外部状态机
代码规范 = 运行时约束
验收清单 = 评估器
反馈记录 = 自我进化机制
这套东西做起来会比普通文档累。
但如果不做，AI 开发就会一直停留在“看起来很快，验收很累”的状态。
真正的 AI 开发能力，不是写一句神奇提示词。
而是持续构建一个能让模型知道当前在哪、什么是对、偏了怎么回来、完成如何证明的上下文系统。
我现在越来越觉得，所谓 AI 开发的本质，就是把人的隐性判断，变成模型可读取、可执行、可评估、可沉淀的信息结构。
谁能把这件事做好，谁就能把 AI 从一个聪明但不稳定的助手，逐渐变成一个可校准的工程执行系统。
参考资料：
Vaswani et al., Attention Is All You Need: https://arxiv.org/abs/1706.03762 Lewis et al., Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks: https://arxiv.org/abs/2005.11401 Microsoft Research, GraphRAG: https://www.microsoft.com/en-us/research/project/graphrag/ LangChain, Context Engineering for Agents: https://www.langchain.com/blog/context-engineering-for-agents
