执行驱动交付（四）：活文档——为什么 TR 文档从执行里长出来，比开工前写完准？

执行驱动交付（EDD）：AI 项目交付方法论 · 4/8

📖 摘要：EDD 把 TR 文档从「评审关卡」改成「活文档 + 执行产物固化」——四个活文档贯穿全程：边界卡（不能做什么）、TR2 约束真相源（生成时用什么）、跑通记录（执行时的账）、TR3 用例集（执行后的账）。核心机制：骨架前置 + 内容后置——字段表开工前建好（生成要用），约束内容从执行里长出来（推演写不准）。

📌 本文要解决的核心痛点

• 开工前写完的设计文档，开发时没人看，验收时对不上？

• 字段名每轮生成都改一遍，DSL 导入一次错一次？

• 用例集基线化前没确认，验收时测试漂移，谁改的都不知道？

• 本文讲四个活文档 + TR2 真相源 + TR3 自验证闭环——文档从执行里长出来，而不是开工前拍脑袋。

场景

传统项目的文档是「评审关卡」：开工前写设计文档，评审通过，开发照做。AI 项目里这套有两个死穴：

第一，开工前写不完。字段名、接口形状、约束规则——这些只有跑起来才知道。开工前写完的「详细设计」，一半是脑内推演，写的时候信誓旦旦，跑起来全对不上。

第二，评审通过 ≠ 文档有效。评审时看的是「文档写得好不好」，不是「文档和现实对不对得上」。AI 项目的现实在变（模型行为、平台行为、客户反馈），静态文档跟不上的速度。

我们踩过的典型：TR2 字段表里写了 item_count，执行循环生成 DSL 时用的却是 total_count——字段漂移。DSL 导入一次错一次，查半天才发现是文档和代码各说各话。文档不是写出来的，是养出来的。

结论

TR 文档从执行里长出来，不是开工前写出来——四个活文档贯穿全程：边界卡管「不能做什么」，TR2 约束真相源管「生成时用什么」，跑通记录管「执行时的账」，TR3 用例集管「执行后的账」。骨架前置，内容后置。

推导链：为什么「骨架前置 + 内容后置」是唯一正确的分工

骨架必须前置——因为第一轮执行就要用。字段表（变量名/字段名/Mock Schema）是第一轮生成 DSL 的输入，不可能等执行完再补。骨架建好即固定，防字段漂移。

内容必须后置——因为内容写不准。TR2 的约束规则（「这个场景这个客户」的约束）只有执行循环每轮回填才准——跑通记录里「留下了什么约束」是内容主源。经验再好，也给不出「这个客户这个场景」的约束。

TR2 的内容来源三分：

1. 骨架（字段表）——经验定：TR1 选型 + 平台层经验 + 边界卡。经验决定骨架长什么样

2. 内容（约束规则）——执行定：执行循环每轮回填，带来源标注（客户/实测/推测待验证）。凭经验写 = 脑内推演 = 文档后置要戒掉的动作

3. 字段准确值——实测定：平台字段名/参数名以实测为准（查源码优先），经验给方向，实测定准确值

一句话：TR2 = 经验开个头（骨架）+ 执行喂大（内容）+ 实测校准（字段）。

正例实证：字段表前置，一次生成通过

网络设备故障诊断助手，第一轮执行前 TR2 骨架就建好了：意图分类的输出字段（intent 枚举值）、检索节点的入参（query/top_k/score_threshold）、回答链路的出参（answer/source_chapter）。骨架固定后，每一轮生成 DSL 都用同一份字段表——字段漂移一次没发生过。

内容怎么长的：执行循环里发现「口语问法『认证』命中不了『验证』」——这条约束回填 TR2（检索词需要归一化处理），带来源标注「实测」。这个约束是开工前不可能写出来的，它是执行暴露的。

反例实证：字段漂移与脑内推演文档

反例 1：字段漂移。 内部实验项目，TR2 骨架没在建好时固定——执行中想改就改。三轮之后，文档里的字段名和已生成的 DSL 对不上了，第四轮生成直接导入失败，排查花了半天。修复：TR2 加变更记录（改字段 = 记录原因 + 影响范围 + 是否影响已生成 DSL），版本可逆，谁改的、为什么改、影响哪，全链条可查。

反例 2：脑内推演的 TR2。 另一个实验，TR2 内容不是从跑通记录提炼的，是开工前「参考别的项目」写的。跑起来发现：客户的实际字段格式和 TR2 写的不一样——文档是抄来的，约束是猜的。废掉重写，从跑通记录重新提炼。参考别的项目 = 内容搬移；跑通记录提炼 = 约束固化。前者是脑内推演，后者才是真相源。

实践动作：TR3 自验证闭环（用例从错误清单长出来）

TR3 是开发阶段的自验证（不是验收，验收是 TR4）。用例三个来源通道：

用例来源三通道：

① 错误清单 → 回归用例（修过几个错就有几条）

② 成功标准 → 端到端用例（每条成功标准至少一条）

③ 边界禁区 → 负向用例（测 AI 不会越界）

三个通道汇成一条自验证闭环：

TR3 与业界评测驱动开发（Evaluation-Driven Development）同源——评测集（Eval dataset）本质是 Agent 的可执行行为规格：持续收集 badcase、自动诊断、回归验证，推动 Agent 在受控边界内演进。本体系的对应关系是：

• 硬断言 = Tests（确定性断言，pass/fail）：字段一致性、禁区触发、工具调用顺序

• 软断言 = Evaluations（概率性评估，score over dataset）：语义相似度、关键信息覆盖率

• 黄金集 = Eval dataset（带 Source 标注的回归基线）：跨客户复用前跑回归，100% 通过才交付

差异化在于：评测集从执行循环的错误清单里「长出来」，不是开工前预设——修过几个错就有几条回归用例，评测集随项目生长，天然覆盖真实踩坑。

硬断言 / 软断言分层：

• 硬断言（规则校验，机器可执行）：字段名与 TR2 一致性、禁区触发、工具调用顺序。示例：contains_key("order_id") / len(tool_calls)<=3 / text!=""——通过率不达标不进 TR4

• 软断言（语义质量）：语义相似度 >0.9、关键信息覆盖率 100%

• 风险优先级：用例不平均用力，先覆盖会造成损失的场景（越权/错数据/重复扣费/错误发送/错误删除/错误审批）

归因三分（TR3 发现问题先归因再动手）：应用缺陷 → 修应用（改工作流/提示词，不反馈 TR2）；约束缺陷 → 反馈 TR2 更新约束 → 重新生成 DSL → 重跑；边界缺陷 → 更新边界卡 → 可能联动 TR2 → 重跑；用例缺陷 → 只修用例标识，不修改应用（基线后）；环境问题 → 排除后重跑。

基线化纪律：用例集全部输出 → 人确认基线化 → 严格执行，中途不改用例（防测试漂移）。基线后用例缺陷只标识不修改应用——把用例缺陷当应用缺陷修，是验收里最常见的自欺：应用本来是对的，因为用例断言错了报 FAIL，然后团队去「修应用」，越修越错。

边界与版本

• 冒烟 vs TR3：冒烟是每轮的小测验（这轮算没算完成）；TR3 是收敛后的期末大考（正式验证）——生成/导入/冒烟属于执行循环，TR3 验证的是导入后的应用

• 档位差异：一档 TR2 极简（一页字段表，可和跑通记录合一）、TR3 10-20 条用例；三档完整（13 节 + 变更记录 + 边界对照表 + 全量双层用例）

• 黄金集：从 TR3 用例挑 10-20 条核心集，带 Source 标注，作跨客户复用前的回归门槛（100% 通过才交付新客户）——第七篇展开

• TR2 是纯文档环节，零执行动作，不依赖环境；它的消费方是执行循环的 DSL 生成

收尾

活文档的实质：文档的职责从「评审关卡」变成「执行产物的固化」。评审关卡问「文档写得好不好」，活文档问「文档和现实对不对得上」——后者才是 AI 项目里文档唯一有用的形态。骨架前置保证能用，内容后置保证准，变更机制保证可追溯。

下一篇：错误放大坑——为什么一条推测会变成 N 个项目的毒资产？

下一篇：执行驱动交付（五）：错误放大坑——为什么一条推测会变成毒资产？

💬 讨论区：你遇到过字段漂移吗？文档和代码各说各话，排查半天才发现？你的项目里文档是「评审关卡」还是「活文档」？评论区聊聊。

本文基于真实项目交付经验撰写（2026-08，1 个真实交付项目与内部实战实验）。文中数据均来自实测记录，方法论部分以「已验证 / 推断待验证」标注边界。