如何写一篇方便 AI 查阅与更新的文档

罪魁祸首往往不是 AI 不努力，而是它在写文档时，为了表述某些信息所使用的【文本组织方式】，只考虑了如何便于人类阅读，而不在乎AI是否读得有效率。

1. 问题出在哪？

AI 写文档有个默认习惯——照顾人类视觉。

它会使用一些花里胡哨的【文本组织方式】去表述一些信息，比如画 ASCII tree、画 TUI 流程图、写 Mermaid 源代码。这些人类看起来「一目了然」。

但 AI 自己读起来反而累：

• 盒字符 ┌─┐│└┘▼ 是 0 语义的装饰，token 烧了却什么都没说
• ASCII tree 的缩进需要心算层级，注意力被分散
• Mermaid 源文本要在脑子里「渲染一遍」才能读

更糟的是：你让 AI改它自己写的文档时，关键信息往往藏在这些装饰里，AI 容易漏掉。

短文档问题不大。文档一长就出问题——尤其是「读完之后还要更新」的场景。

2. 五种【文本组织方式】：用一个例子看完

我们用不同的【文本组织方式】，描述同一个流程：张三买高铁票，北京 → 郑州。

来看看哪一种【文本组织方式】是方便AI阅读的。注意，这或许并不意味着人类看着就舒服。

2.1 线性块结构叙述 ← 推荐

[登录 12306 §1]前提：账号已注册 + 实名操作：输账号、密码、验证码成功：→ §2[填 北京→郑州 + 出发日 §2]前提：§1 登录成功操作：填出发地、目的地、日期下一步：→ §3[选车次 §3]前提：§2 搜出来的车次列表分支： A. 有票 → §4 B. 无票 → 留在 §3，换个车次[选乘车人 §4]前提：§3 选好的车次分支： A. 已在名单里 → §5 B. 没在名单里 → 先填身份证 + 姓名 → §5[付钱 §5]前提：§4 选好的乘车人退出条件：扣款成功分支： A. 成功 → §6 B. 失败 → 留在 §5 重试[出票 §6]前提：§5 扣款成功输出：电子票（二维码）下一步：结束

每个块用 [名字 §X.Y] 开头，下面写前提 / 操作 / 顺序 / 分支 / 下一步——AI 从头读到尾就是顺序，分支有 A/B/C 显式标签。跨段跳转用 → §4 这种锚点引用。

2.2 表格

行 = 步骤，列 = 维度。表格适合属性对照（API 参数、配置项、术语表）——不适合流程。分支只能塞进单元格，读起来费劲。

2.3 ASCII tree（文档结构图）

买高铁票（北京→郑州）├─ §1 登录 12306│ └─ 前提：账号已实名├─ §2 填出发地+目的地+日期├─ §3 选车次│ ├─ 有票 → §4│ └─ 无票 → 留在 §3 换车次├─ §4 选乘车人│ ├─ 已加 → §5│ └─ 未加 → 先填身份证├─ §5 付钱│ ├─ 成功 → §6│ └─ 失败 → 留在 §5 重试└─ §6 出票 → 拿到电子票，结束

├─ └─ 画层级。人看着舒服，AI 看着累——分支靠缩进，没有 A/B/C 显式标签。

2.4 Mermaid 源文本

flowchart TD A[§1 登录 12306] --> B[§2 填 北京→郑州 + 日期] B --> C[§3 选车次] C -->|有票| D[§4 选乘车人] C -->|无票| C D -->|已添加| E[§5 付钱] D -->|未添加| F[填身份证+姓名] --> E E -->|成功| G[§6 出票] E -->|失败| E G --> H[结束]

人类看渲染图直观，但AI 拿到的是源代码——它要在脑子里「画一遍」才能判断分支走向，注意力开销翻倍。

2.5 TUI 流程图

┌────────────────┐│ §1 登录 12306 │└───────┬────────┘ ▼┌────────────────┐│ §2 填 北京→郑州 + 日期 │└───────┬────────┘ ▼┌────────────────┐ 无票│ §3 选车次 │ ──────────┐└───────┬────────┘ │ ▼ │ ┌───┴───┐ │ ▼ ▼ │┌───────┐ ┌───────┐ ││§4 已加│ │§4 未加│ ││乘车人 │ │→ 加人 │ │└───┬───┘ └───┬───┘ │ └────┬────┘ │ ▼ │ ┌──────────────────┐ │ │ §5 付钱 │◀────┘ (无票) └───┬──────────┬───┘ ▼ 失败 ▼ 成功 [留在 §5] ┌────────┐ │ §6 出票 │ └────┬───┘ ▼ [结束]

盒字符 + 箭头拼 2D 图。一半 token 烧在装饰上——AI 必须 2D 心算，看到底哪个盒连哪个盒。节点超过 5 个就开始乱。

3. 一句话排行

核心结论：

写给 AI 看的文档，默认走线性块结构 + 表格（属性对照时）。其他三种格式（TUI / ASCII tree / Mermaid 源文本）在 AI 文档里全局禁用。

为什么：

线性块结构把”流程”用「自定位 + 显式条件 + 显式分支 + 零装饰」写出来——LLM 读起来不需要心算父节点、不需要渲染图、不需要数缩进、不需要特外推理隐含条件，每条信息都非常明确。本质上，LLM模型擅长的是处理显式结构化的信息序列，而线性块结构这种【文本组织方式】，其所呈现的信息最接近前者。

4. 决策树（一段话搞定）

AI 是主要读者？├─ 是 → 流程 / SOP / 工作流 → 线性块结构│ 属性 / 配置 / API 参数 → 表格（列数 ≤6）│ 单点说明 / 注释 → 线性块结构│ 目录 / 分类 → 线性块结构 + Markdown 子项列表│└─ 否 → 人类看的视觉成品 → Mermaid 渲染图 / TUI（仅限 README 截图、PPT、海报）

两种格式就够：线性块 + 表格。

6. 写在最后

AI 写文档时照顾人类视觉，是一种「看似周到实则自伤」的做法——人类阅读时省下来的那点视觉直观，AI 阅读时全部还回去了：token 烧了，注意力被分散，关键信息漏掉。

如果你想让 AI 写的文档：

• AI 自己能轻松读懂
• AI 自己能稳定更新
• 你和 AI 协作时不出岔子

那就在 prompt 里加一句：

「流程 / SOP 用线性块结构叙述；属性对照用表格；不要 TUI / ASCII tree / Mermaid 源文本。」