AI 友好型文档编写指南
在人工智能时代，文档不仅是给人类阅读的，也是给“机器”阅读的。一份 AI 友好型（AI-Friendly）文档可以显著提高大语言模型（LLM）在理解、摘要、检索和推理时的准确性。
1. 选择正确的格式
首选 Markdown (.md)
- 原因：Markdown 是 AI 的“母语”。它结构清晰，且在模型训练数据中占比极高。
- 优点：支持标题层级、代码块、表格和列表，能清晰传达语义权重。
次选 JSON/YAML
- 用途：适用于高度结构化的数据或配置说明。
2. 结构化布局 (Structure)
AI 通过结构来定位上下文，混乱的布局会导致模型“迷路”。
2.1 严格的标题层级
使用 # 到 ### 来定义文档结构。
#用于全局标题。##用于主要章节。###用于子话题。- 不要跳级：不要直接从
#跳到###。
2.2 使用元数据 (Metadata)
在文档开头添加 YAML 格式的元数据块，帮助 AI 快速建立索引。
---
title: "项目 A 开发规范"
version: "1.2.0"
author: "Tech Team"
tags: [开发, 规范, 接口]
last_updated: 2024-05-20
---
3. 内容编写原则 (Content)
3.1 消除歧义与代词
- 错误：它在运行这个操作时会报错。
- 正确：当 Python 脚本执行数据库连接操作时，SQLAlchemy 会抛出连接超时错误。
- 原则：尽量使用具体名词，减少使用“它”、“这个”、“其”等代词。
3.2 保持一致性
- 在整篇文档中，对同一个概念使用相同的术语。如果称之为“用户 ID”，就不要在后文改称“账号编号”。
3.3 提供上下文
- AI 没有“长期记忆”。在介绍复杂逻辑前，先用一句话说明背景。
- 示例：“以下代码块展示了如何在高性能分布式环境下处理缓存失效问题。”
4. 优化 RAG 检索 (Optimization for RAG)
如果你的文档是为了放入向量数据库，以下技巧能显著提升召回率：
4.1 逻辑分块 (Chunking-Friendly)
- 每个段落专注于一个核心观点。
- 过长的段落会干扰向量化（Embedding）的精度。建议单个段落控制在 200-400 字以内。
4.2 包含“关键词”
- 在章节开头自然地嵌入关键词，这有助于相似度计算。
5. 元素的使用规范
5.1 列表 (Lists)
- 有序列表：用于描述流程（Step 1, Step 2）。
- 无序列表：用于列举属性或并列项。
5.2 表格 (Tables)
- 表格对 AI 来说是非常高效的对比工具。
- 技巧：确保表头清晰，不要使用合并单元格，因为复杂的合并会导致 Markdown 解析错误。
5.3 代码块
- 必须指定语言：使用
- 添加注释：代码块内部的关键逻辑应有清晰的注释。
6. 自检清单 (Checklist)
- 文档是否使用了 Markdown 格式？
- 是否有明确的标题层级？
- 术语是否全篇统一？
- 所有的缩写是否在第一次出现时给出了全称？
- 复杂的逻辑是否提供了具体的示例（Input/Output）？
- 是否移除了文档中所有的“废话”和模糊表达？
总结
AI 友好 = 结构清晰 + 语义明确 + 逻辑解耦。 当你像对待一个极其聪明但完全没有背景知识的新同事一样写文档时，你就写出了最完美的 AI 友好型文档。
