给AI看的文档怎么写

给 AI 看的文档，不能照着给人看的写

做 AI 取数，会踩到一个很典型的坑。

一开始的想法很朴素：公司里本来就有一大堆指标文档、数据字典、规范手册，直接丢给 AI 读不就行了？

丢进去之后发现，AI 是读了，但取出来的数还是不对。 有时候是答非所问，有时候是引用了一份早就过时的文档，有时候明明文档里写了，它就是没检索到。

排查了一阵才明白：那些文档是写给“人”看的。人看文档，可以跳着读，可以结合上下文猜，可以拿不准了去问同事。AI 不行。它只能读检索回来的那几个片段，读不到的，对它来说就不存在。

所以给 AI 看的文档，得换个写法。下面这几条，都是踩过坑才定下来的。

先搞清楚：AI 是怎么“读”文档的

很多人以为 AI 是把整个知识库都读一遍。其实不是。

大致是这样：你提一个问题，系统先去知识库里检索，挑出最相关的几个片段，再把这几个片段交给模型，让它基于这些片段回答。

这意味着三件事：

1. 文档会被切成片段。 一个片段脱离了前后文，还能不能看懂？

2. 检索靠的是语义相似。 你的文档标题和开头，能不能让检索把它挑出来？

3. 模型只看到检索回来的那几段。 没被挑中的内容，哪怕写得再好也没用。

后面所有的写法，都是围绕这三件事。

原则一：一个文件只讲一件事

这是改动最大、效果也最明显的一条。

最开始的指标文档往往是“大而全”的：一份文档里塞了十几个指标。人看着方便，一个文件什么都有。

但 AI 检索的时候，这种文档会出问题：

·问“逾期率怎么算”，检索回来的片段里夹着一堆别的指标的内容，互相干扰；

·文档太长被切成好几段，关键的定义和计算方式落在了不同片段里，模型只拿到一半。

后来改成：每个指标一个文件，每个维度一个文件。 文件主题单一，检索命中的就是那一份，内容也完整。

具体怎么落地：

·指标放一个目录，维度放一个目录，表的知识单独维护；

·文件名带统一的前缀，一看就知道是什么类型；

·不同业务线的内容放到各自独立的知识库里，文件里不用再重复写业务线。

原则二：文件头放结构化信息，正文用大白话

每个文件开头，放一段简短的结构化头部，大概包括：

·名称、编码；

·类型（指标还是维度）；

·计算公式；

·依赖的其他指标；

·所属模块。

示意一下：

name: 到期逾期率code: due_overdue_ratetype: 复合指标formula: 逾期订单数 / 已到期订单数depends_on: [逾期订单数, 已到期订单数]module: 贷后

头部之后，正文用自然语言把事情讲清楚：

·这个指标衡量什么；

·分子、分母各是什么；

·必须加哪些过滤条件；

·按哪个时间字段归属；

·一段可以直接拿来改的取数 SQL 示例。

为什么要两层？结构化的头部方便检索和程序处理；自然语言的正文，是让模型理解“为什么这么算”。光有字段没有解释，模型会机械地套公式；光有解释没有结构，检索又不容易命中。

原则三：只写规律，不写容易过时的东西

这条最反直觉，也是吃过亏之后才定下来的。

一开始很容易想把知识库做“全”：字段明细、枚举值对照表、表清单，统统放进去，觉得越全越好。

后来发现，这类内容没人持续维护。 表加了字段、枚举多了新值，文档却没人改。时间一长，知识库里写的和实际对不上，AI 照着旧文档写 SQL，反而写错。

你以为你在帮它，其实你在给它错误答案。

现在的做法是：

至于具体的库表结构、字段是否存在，让 AI 取数时实时去数据库里查，以当下的实际状态为准。

一句话：规律写进文档，事实交给实时查询。

原则四：每个文件要“自带上下文”

文档会被切片，所以每个片段最好能独立看懂。

几个小习惯：

·别用“上文”“如前所述”“见上表”。 片段单拎出来，这些指代就失效了。

·专有名词第一次出现时给出全称。 不要假设读者已经知道缩写。

·标题写具体。 “注意事项”这种标题检索不到任何东西；“到期逾期率：分母为什么要限制已到期”才能被挑中。

·关键结论放在前面。 一段话里最重要的那句话，放开头。

再补四条硬要求

除了上面几条，知识库写作规范里还值得写死四条，因为文档的第一读者是 AI，第二读者才是人：

陷阱的写法也有格式：用一个醒目的 ⚠️，写清“禁止用什么、原因是什么”。两张表关联时，还要写出匹配率。AI 看到匹配率很低，就知道要主动换一条备选路径，而不是对着一堆空值硬算。

还有一个小技巧：给每个文件写“别名”或“关键词”。业务口头叫“通过率”，系统里叫“审核通过比例”，英文又是另一个说法。把这些叫法都列在文件头，检索才命中得上。

原则五：目录和命名要“可推断”

知识库大了以后，怎么找成了问题。几个做法：

·首页放导航。 一个 README，说明这个知识库是干嘛的、目录怎么分、每类文档的命名规则、遇到什么问题该看哪个文件。

·文件名带前缀。 比如指标类统一一种前缀，规范类统一另一种，一看名字就知道类型。

·前缀要有书面定义。 哪个前缀代表什么，写在导航里。

另外有个体会：每个空间的命名规范可以不同，但每个空间内部必须一致。 批量检查的时候，不要拿一套规则硬套所有空间。

原则六：写完要测，不能凭感觉

文档写得好不好，不是你说了算，是 AI 取出来的数说了算。

最小的测试办法：

1. 挑 20~30 个典型问题，每个问题有一个已知的标准答案（或标准数）；

2. 每次改完文档，把这批问题重新问一遍；

3. 记录：检索到的是不是对的文档？答案和标准数对不对？

没有这套测试，你永远不知道一次文档改动是让 AI 变聪明了，还是变糊涂了。

起步不用贪多，10 题就够，按类型配比：数字查询、维度拆解、趋势分析、异常归因（占大头，要覆盖多种异常模式）、边界场景（专门放已知的陷阱字段）。题目固定，才好跨轮对比；问法模拟真实用户，比如“需要我关注吗”，而不是“请分析某某指标”。评分按“数字准确、过滤条件、字段选择、结构规范”拆开打，一轮一轮对着看。评测集具体怎么建，之前专门写过一篇，这里不展开。

还要有人维护

最后一点，容易被忽略：知识库不是写完就结束了。

·口径变了，文档要同步改；

·发现 AI 答错了，要回头看是文档缺了、写得不清楚，还是检索没命中；

·每份文档最好有负责人和最近更新日期；

·一份没人维护的知识库，三个月后就会变成“误导 AI 的来源”。

落到做法上，至少有三条：

·每份文档末尾都有变更记录（日期、版本、改了什么、谁改的）。改文档不写记录，等于没改；

·口径冲突有固定的优先级：报表上的数字 > 知识库文档 > 其他记录 > 口头约定。文档和报表对不上，一定是文档错了；

·评测失分了，倒查三类原因：信息根本没写（要补文档）、写了但 AI 没取到（要改检索路径或提示词）、取到了但分析逻辑有缺陷。分清了，才知道改哪里。

不要轻易整份删除旧文档，倾向于“更新、标注”。需要删除的时候，先确认再删。

几个容易踩的坑

1. 把给人看的手册原样丢进去。 大而全、靠上下文、满是“见上文”，AI 读起来会很吃力。

2. 知识库里放了大量静态信息。 越全越容易过时，过时比缺失更危险。

3. 多个主题写在一个文件里。 检索时互相干扰，片段被切开后各说各的。

4. 标题写得很空。 “说明”“注意事项”这类标题，检索几乎不会命中。

5. 写完不测试。 凭感觉觉得“应该没问题”。

6. 没人维护。 知识库的寿命，取决于有没有人在维护。

小结

给 AI 看的文档，和给人看的文档，目标不一样：

·给人看的，要读得顺；

·给 AI 看的，要检索得到、切开了也看得懂、内容不会过时。

核心就是这几句话：

·一个文件讲一件事；

·头部放结构，正文说大白话；

·规律写进去，事实实时查；

·每个片段自带上下文；

·写完要测，写完要有人管。

做这件事的过程中有个感受：为了让 AI 读得懂而把口径写清楚，其实是在补数据治理的课。 这些文档对新人、对跨部门沟通同样有用。

你们团队有没有把文档喂给 AI 的经历？效果怎么样？欢迎在评论区聊聊。