夜雨聆风有标题，有目录，有“背景、目标、方案、风险、总结”，每一段话也都很完整。读起来甚至有一点专业。
但你让同事照着做，他会问：“所以我现在到底要干什么？”
你把它丢给 agent，它会继续问：“这里的‘相关数据’是哪一份？‘正常情况’怎么定义？失败以后要不要重试？”
这就是很多 AI 文档的尴尬：人类看不懂，agent 也看不懂。
问题通常不在 AI 词汇量不够，也不在人的理解能力变差了，而在于这份东西从一开始就没有明确服务谁、帮助谁做什么决定。
它只是长得像文档。
不是写给人，还是写给 AI 的问题
前几天我重新想了一下“给人看的文档”和“给 AI 看的文档”到底差在哪里。
很多人的第一反应是：给人看的要自然一点，给 AI 看的要结构化一点，最好再改成 JSON、YAML 或表格。
这话只对了一半。
表格不一定比自然语言更清楚，JSON 也不会自动让一个错误的规则变得正确。
真正的区别，是两种读者要完成的动作不一样。
人读文档，通常是为了理解背景、形成判断，然后决定接下来怎么做。人会结合常识补全上下文，也会根据语气判断哪些是重点，哪些只是铺垫。
agent 读文档，通常是为了检索信息、选择分支、调用工具，或者生成下一步动作。它需要知道的不是“这件事大概是什么意思”，而是“在什么条件下，我应该执行哪一个动作”。
所以，给人看的文档，最先要降低理解成本；给 agent 看的文档，最先要降低歧义和执行错误。
这不是两种语言，而是两种责任。
人可以说：“我大概明白你的意思了。”
agent 不能靠“大概”扣动按钮、修改数据库或者给客户发消息。
AI最容易写出一种“假完整”
AI 写文档有一个很明显的倾向：它会把空白填满。
你只给它一个主题，它可以迅速补出背景、意义、方法、风险和展望。每一个部分看起来都没有问题，组合在一起却没有任何人能够据此行动。
因为“写得完整”和“定义得清楚”根本不是一回事。
比如下面这句话，人读了可能觉得没毛病：
系统会根据用户反馈，及时优化推荐策略，提升整体体验。
但如果要让一个团队或 agent 执行，它至少缺了几个关键问题：
什么算用户反馈？聊天记录、问卷，还是投诉工单？ 谁负责判断反馈是否有效？ 多久分析一次？达到什么数量才触发调整？ 哪个指标下降或上升，才算体验变好？ 谁能修改推荐策略？修改后需要谁审批？ 如果数据互相矛盾，应该暂停调整，还是继续执行？
这句话不是错，而是没有完成从“观点”到“规则”的转换。
AI 特别擅长把观点说得完整，却不会自动替你承担规则没有定义清楚的后果。
人类为什么也看不懂
很多人以为，只要 agent 能读懂文档，人的问题自然就解决了。
其实正好相反。
人类看不懂 AI 文档，往往有三个原因。
第一，文档只讲“我们要做什么”，不讲“为什么现在要做”。背景没有事实，只有正确但空泛的判断；目标没有可观察的结果，只有“提升效率”“优化体验”这类愿望。 第二，文档把事实、推测、决定和建议混在一起。读者不知道哪些已经发生，哪些只是作者猜的，也不知道哪些内容需要执行，哪些内容只是供讨论。 第三，文档的结构是按 AI 的生成习惯排的，不是按人的阅读路径排的。每个章节都有几段差不多长度的解释，却没有把读者最关心的东西提前说出来：结论是什么，谁负责，什么时候完成，什么情况算失败。
这类文档最浪费时间的地方，是它会让人产生“我已经看过了”的错觉。
真正的问题，往往要等到开会、交接或项目延期时才暴露出来。
agent为什么也看不懂
agent 的“看不懂”，和人的“看不懂”又不完全一样。
人读到“及时处理”，可能会结合团队习惯理解成今天；agent 只能面对一堆互相都说得通的可能性。
人读到“必要时升级”，可能知道去找直属负责人；agent 需要知道升级的触发条件、目标对象、通知渠道和超时时间。
人看到“订单异常”能继续往下问；agent 如果没有明确的异常类型，可能把支付失败、库存不足、地址错误都当成同一种问题。
agent 最怕的不是长文档，而是这些东西：
术语没有定义，同一个词在不同章节里意思不一样。 条件没有边界，使用“通常”“适当”“及时”“相关”等词代替规则。 流程没有状态，只有一串看起来顺滑的叙述。 没有反例，agent 不知道什么时候不能照常处理。 没有优先级，多个规则冲突时不知道听谁的。 没有来源和版本，不知道哪一条是最新生效的。
说到底，agent 不是缺少阅读能力，而是不能安全地替你猜。
一份好文档，得先把四件事分开
要让人和 agent 都能读懂，最有效的办法不是把句子改得更漂亮，而是把不同性质的信息拆开。
事实：已经发生了什么
事实要能够被追溯。
不要写“用户普遍反映流程复杂”，要写清楚数据来自哪里、统计周期是什么、样本有多少，和“复杂”是用什么指标衡量的。
如果还没有证据，就明确写成“待验证假设”，不要把推测包装成事实。
判断：我们认为这意味着什么
判断可以有立场，但必须和事实分开。
例如：
事实：近 30 天内，62% 的新用户在支付页面退出。
判断：支付页面可能存在信任成本或操作阻力，需要进一步拆分原因。
这样人知道作者的推理过程，agent 也知道哪些内容不能直接当作事实调用。
决策：现在决定做什么
决策必须包含对象、负责人和截止时间。
“优化支付页面”不是决策，只是一个方向。
“产品负责人在本周五前完成支付页面的两版改稿，并通过 10 名新用户测试”才接近可执行决策。
规则：什么情况下怎么处理
规则最好写成条件和动作：
如果支付失败且第三方返回可重试错误，系统最多自动重试 2 次；仍然失败则生成工单，不再继续扣款。
这句话人能读，agent 也能执行。它没有多高级，但边界完整。
把文档从“说明书”改成“工作接口”
很多文档的问题，是作者把它当成一篇文章在写。
但团队真正需要的，往往不是一篇文章，而是一个工作接口：任何新成员、自动化流程或 agent 接进来，都能知道当前状态、可用信息和下一步动作。
可以从下面几个问题开始改：
这份文档的读者是谁？他读完以后要做什么？ 文档里的核心名词，是否只有一个定义？ 哪些是事实，哪些是判断，哪些是尚未验证的假设？ 每一个动作的触发条件、输入、输出和负责人是什么？ 失败、超时、权限不足、数据冲突时怎么办？ 如果两条规则冲突，优先级怎么排？ 这份内容从哪里来，什么时候更新，谁有权修改？
尤其要补上反例。
正例告诉读者“应该怎么做”，反例才告诉读者“什么不能这么做”。对 agent 来说，后者经常更重要。
比如不要只写“客户投诉需要及时跟进”，还要写：
仅咨询类消息不进入投诉流程；涉及退款、隐私、产品安全或连续两次未解决的问题，才进入投诉流程。工作日 4 小时内未响应，自动升级给值班负责人。
这才是可以被人理解、被系统执行的内容。
不要为了 AI，把文档写得像机器
这里还有一个容易走偏的地方。
有些人听说 agent 喜欢结构化，就开始把所有文档改成字段、编号和大表格。最后人读起来像在填报表，agent 读起来也未必更准确。
结构化不是目的，减少误解才是目的。
背景、动机、取舍和风险，仍然需要用自然语言讲清楚；状态、字段、条件和接口，才适合用表格或结构化格式固定下来。
好的文档不是“人类版”和“AI版”各写一份，而是让解释层和执行层彼此对齐：
人先看摘要，快速知道结论和影响。 人再看背景，理解为什么这么决定。 人和 agent 共同查看定义、规则和边界。 agent 根据明确条件执行动作。 人在关键节点审批、复核和承担责任。
这比单独维护两套文档更可靠。因为两套文档迟早会出现一个更新了、另一个没更新的情况。
写完以后，用两个读者各测一遍
一份文档发布前，至少做两次测试。
第一次，把它交给一个不了解背景的人，只告诉他：“请按这份文档完成任务。”观察他会在哪些地方停下来提问。那些提问，通常就是文档的缺口。
第二次，把它交给 agent，让它输出三样东西：
它认为这份文档的核心规则是什么； 它准备执行的具体动作是什么； 它仍然无法确定的地方是什么。
如果 agent 总结出来的规则和作者原意不一样，不要急着怪模型。先回头检查文档里是不是混用了事实和判断，是不是把边界藏在了上下文里，是不是存在互相冲突的说法。
这相当于给文档做一次“编译”。能被读者稳定理解，才能进入团队协作；能被 agent 稳定解析，才能进入自动化流程。
别让 AI 替你制造文档幻觉
AI 可以帮你整理材料、补齐结构、发现遗漏，也可以把一堆散乱信息变成初稿。
但它最容易制造的，正是那种“看起来什么都有，真正做事什么都缺”的文档。
所以每次让 AI 写文档之前，先不要急着说“写得详细一点”。先告诉它：
谁会使用这份文档； 使用者要完成什么动作； 哪些内容是事实，哪些是推测； 哪些条件必须写死； 哪些地方不确定时必须停下来提问。
文档不是把字写满。
文档的价值，是让下一个人，或者下一个 agent，在没有作者陪同的情况下，仍然能够少猜一点，做对一点。
如果一份文档离开作者就失效，那它可能只是作者脑子里的想法被排版了一遍。
真正的文档，要经得起两种阅读：人读完知道该怎么判断，agent 读完知道该怎么行动。
