文档即可执行资产：当 Agent 逐字消费你的规格

系列：Idea-to-Production · 实践篇。同系列还有《人不在环内：一个 AI 自主交付组织的概念契约》《十三个阶段与它们的工件》。

人类文档靠读者的常识补全歧义；Agent 文档没有这层缓冲。这篇讲一个我们被迫接受的设定——文档是可执行资产：它有类型化接口、会藏 bug，而且真有人在生产环境 24/7 运行它。以及由此推导出的五条写作纪律。

为什么值得看

这是 Agent 工程里最被低估的一层：模型能力再强，你的系统质量上限等于交接文档的无歧义程度。本文不讲提示词技巧，讲更上游的东西——如何让"写文档"这件事本身工程化。五条纪律全部来自真实翻车后的复盘，读完可以直接拿自己的仓库对照检查。

你将学到三点

1. 把每份交付文档当公开 API 评审
   ：它的输入假设、输出契约、术语定义，都值得像函数签名一样过一遍。
2. 交付文档里的 TODO 是会跑的废代码
   ：人类会绕开占位符，Agent 会执行它。
3. 复述即分叉
   ：同一条原则写进第二份文档的那一刻，你就拥有了两条会各自漂移的真相。

文档如何被"运行"：两条路径

在这个系统里，文档不是参考资料，它有两条真实的执行路径。

路径一：工件链。 阶段之间以具名文档交接——requirement.md、solution.md、tech_design.md、plan.md……下游 Agent 逐份深读并据此产出。一份有歧义的架构文档，会被下一个环节按字面实现。

路径二：运行时装配。 工作实例拿到任务后，把知识层资源装配成一份结构化上下文提示，交给 AI CLI——固定八段，顺序不变：

1 通用守则      2 项目上下文     3 角色守则     4 工作流 5 知识资源      6 可用工具       7 技能         8 任务定义 

八段里只有"任务定义永远在场"；通用守则一旦绑定就永不缺席（宁可渲染空段，也不静默消失）；其余段落随实例绑定的资源出现或省略。换句话说：你在知识层写的每一个字，都会以这段文字的样子进入模型上下文，被当作操作指令执行。 文档写作从此不是辅助工作，是编程工作。

五类"文档 bug"，各配一条纪律

一、模糊规格 → 幻觉子系统

一句"加个基础鉴权"，人类同事会默认团队惯例，Agent 会还你一个自由发挥的登录宇宙。多数"Agent 幻觉"其实发生在此刻：模型只是执行了你的歧义。

→ 纪律：文档先行。 规格先于兑现它的实现而变化；写到"另一个角色不需要提问就能执行"的精度，是阶段交接的最低标准。文档与代码不一致，按 bug 排入队列，不按杂务搁置。

二、占位符 → 会跑的废代码

草稿习惯把没想清楚的地方留成 TODO。在人的世界里它躺得很安静；在 Agent 的世界里，下游会把"TODO: 补充限流策略"当成需求去实现，或者更糟——照着空着的部分产出"无"。

→ 纪律：交付文档零占位。 没想清楚的环节就不该进入交付；宁可少发一份文档，不发一份带洞的文档。

三、原则复述 → 双真相分叉

为了"方便阅读"把同一条规则抄进两份文档，是所有的开始。三个月后两份副本各自被改过一轮，两个 Agent 各引用一份，行为分裂，而没有任何一处报错。

→ 纪律：单一真源，链接代替复述。 原则只在一处定义；其他位置只允许出现指向它的链接。这条纪律便宜在执行、昂贵在破坏。

四、术语漂移 → 静默路由失效

角色 ID、阶段字母、任务类型词汇，在内容层与运行时各有一套拼写。改了 A 处忘了 B 处，症状是"某类任务神秘地再也没人执行"——没有异常，只有积压。

→ 纪律：术语一次定死，改名走跨仓库清扫。 把命名空间当公共 API 对待（详见《九个角色如何分掉一家公司：一张不会漂移的 Agent 组织图》）。

五、文档缺位 → 执行退化

流程规定每阶段有对应工作流文件。缺了它，Agent 会"发挥"：用通用常识代替项目约定，每次都会、每次都不同。方差就是这么进来的。

→ 纪律：执行面必须有文档承载，每阶段一份单页作业指导，按需加载——宁可十三份精准的小文档，不要一本没人读完的大部头。

自检清单

把你仓库里的关键交接文档拉出来，逐条问：

• ☐ 它的输入假设写明了吗（依赖哪几份上游文件、缺了会怎样）？
• ☐ 它的"完成定义"是可判定的吗，还是"设计合理"这种只有人能圆场的表述？
• ☐ 全文搜索 TODO / TBD / 占位符——交付物里有吗？
• ☐ 本文引用的原则，在别处有没有第二份"翻译版"？
• ☐ 术语在两个系统里的拼写一致吗，有没有映射表守护？

五条里任何一条答不上来，那份文档就带着一个未修复的 bug 在生产环境里跑。

总结

1. "文档是可执行的"不是比喻
   ：要么在工件链里被逐字实现，要么在八段上下文里被原样注入——你的文档已经在运行了，区别只在于运行它的是人还是 Agent。
2. 五条纪律的共同本质是把软件工程请进写作
   ：接口要定义、占位不许发版、真相只有一个、命名当 API 管、执行必有文档承载。
3. 从最小的动作开始
   ：挑你最重要的一份交接文档，按上面的自检清单修一轮，然后观察下一轮执行里方差是否变小——这是本系列里成本最低、反馈最快的一次实验。

你手里最重要的一份交接文档，敢拿它过一遍自检清单吗？欢迎在评论区聊聊你的结果。