AI 工程的技术文档——怎么写让团队真正看
AI 工程的技术文档——怎么写让团队真正看
适读人群：AI 工程师、技术 Leader | 阅读时长：约11分钟 | 核心价值：建立轻量级 AI 工程文档体系，解决"写了没人看"的根本问题
去年我在做一个 RAG 项目，花了三周时间建了一套比较完整的文档体系：Prompt 版本记录、模型选型依据、评估报告、知识库更新规范……写得很认真，格式也好看。
结果呢？三个月后新来了个同事接手这个项目，他打开文档看了十分钟，然后关掉，直接来问我。
我问他为什么不看文档，他说："太长了，我不知道该看哪里，而且也不确定现在还不还是这样。"
这句话把我整个文档体系的问题说透了——文档不是写给自己看的，是写给"未来的接手人"看的。如果他不看，文档等于没写。
从那以后我开始认真想，AI 工程的文档到底应该怎么写。
AI 工程文档面临的特殊挑战
传统软件工程的文档已经够难写了，AI 工程还有几个额外的麻烦：
一、AI 系统的"决策"很多，但很难说清楚
为什么用 GPT-4 而不是 Claude？为什么 Chunk size 设成 512 而不是 256？这个 Prompt 模板经历了哪些迭代？每一个参数背后都有一个判断过程，但这个过程很难在代码里体现，只能靠文档。
问题是这种判断过程很难用标准格式写清楚，写浅了没用，写深了太长。
二、AI 系统变化快
模型供应商每隔几个月就更新一次，Prompt 一旦有效果就要迭代，评估指标也在不断调整。文档如果没有及时更新，很快就过时了。过时的文档比没有文档还麻烦，因为它会误导人。
三、效果难以客观描述
传统系统的文档可以写"这个接口响应时间 < 50ms"。AI 系统的评估往往是"准确率 78%，人工评估一致性 0.82"——这些数字背后有大量的评估方法论，脱离了上下文很难理解。
四、没人觉得写文档是自己的事
工程师觉得文档是产品的事，产品觉得技术细节是工程师的事，反正最后就是没人写。AI 工程尤其严重，因为大家都在追赶节奏，文档总是被推后。
我的轻量级文档体系
经过几次失败的尝试，我现在用的文档体系核心原则只有一条：最小可用，持续更新，代码旁边找得到。
具体分四类文档：
1. 决策记录（ADR）
Architecture Decision Record，这个概念在传统工程里有，但 AI 工程里更需要。
每一个关键技术决策，写一个简短的记录，格式固定：
## 决策：使用 BGE-M3 作为 Embedding 模型
**日期：** 2024-08-15
**状态：** 生效中
**背景：**
需要为中文知识库选择 Embedding 模型，候选：text-embedding-3-small, BGE-M3, m3e-base
**决策：**
选择 BGE-M3
**原因：**
- 中英文混合效果最好（我们的文档里大量中文夹英文术语）
- 在我们的 200 个测试问题上，召回率比 text-embedding-3-small 高 12%
- 可以自托管，规避数据出境合规风险
**代价：**
- 部署成本增加（需要 GPU 实例）
- embedding 速度比 API 调用慢约 3 倍
**重新考虑的触发条件：**
如果文档量增长到 100 万条以上，需要重新评估速度代价这个格式写起来不超过 15 分钟，但六个月后回头看，能立刻想起当时为什么这么选。
关键是"重新考虑的触发条件"这一栏——很多团队做了决策之后就忘了，等到情况变了还在用旧决策。有了这个触发条件，至少知道什么时候该重新评估。
2. Prompt 版本记录
这是 AI 工程特有的文档类型，也是最容易被忽视的。
Prompt 是系统行为的一部分，但它通常不在代码 commit 里，也不在任何版本控制里——就是一个字符串，散落在数据库或者配置文件里。
我推荐的最小化方案：把 Prompt 放进代码仓库，用 Git 管理，加上版本注释。
# prompts/rag_answer_v3.py
# 版本历史：
# v1: 初始版本，直接回答
# v2: 加入"如果无法回答请说不知道"的约束，减少幻觉
# v3: 加入分步骤思考的引导，在复杂问题上准确率提升约8%（2024-09-20 测试）
# 当前状态：生产使用中
RAG_ANSWER_PROMPT = """
你是一个专业的知识库助手。请根据以下检索到的相关文档回答用户问题。
要求：
1. 只根据提供的文档内容回答，不要使用你自己的知识补充
2. 如果文档中没有相关信息，请明确说"根据现有文档无法回答这个问题"
3. 对于复杂问题，先分析问题的关键点，再组织答案
4. 回答要简洁，避免重复文档内容
文档内容：
{context}
用户问题：{question}
"""这样做的好处是：Prompt 的变更历史和代码变更一起管理，任何人 clone 代码就能看到完整的 Prompt 演进过程。
3. 评估报告快照
每次做重大改动（换模型、改 Prompt、调参数），记录一个评估快照：
## 评估快照 2024-09-20
**改动：** RAG Prompt 从 v2 升级到 v3
**测试集：** 200 个标注问题（内部标注，标注者 2 人，一致性 0.85）
**主要指标对比：**
| 指标 | v2 | v3 | 变化 |
|------|-----|-----|------|
| 准确率（0/1） | 71% | 79% | +8% |
| 相关性得分（1-5） | 3.6 | 3.9 | +0.3 |
| 平均 token 消耗 | 850 | 1100 | +30% |
| 平均响应时间 | 2.1s | 2.8s | +33% |
**结论：**
准确率提升显著，代价是 token 成本和响应时间增加约 30%。
在当前产品定位下，准确率优先于速度，接受这个代价。
**注意事项：**
v3 在简单问题上有时候过度解析，会比 v2 啰嗦一些，需要持续观察用户反馈。这个不需要每天写，只在关键节点写。有了这些快照，几个月后回溯某个问题的根源，有据可查。
4. 运维手册（面向接手人）
这是真正会被人看的文档。当系统出了问题，或者新人接手，第一个打开的就是这个。
所以这个文档要写得极其实用，只写"出了问题怎么办"：
## RAG 系统常见问题处理
### 问题：召回结果为空
可能原因：
1. 查询问题（问题太短或太宽泛）→ 检查 query rewrite 模块日志
2. 向量库索引未更新 → 查看 qdrant 集合状态 `curl http://qdrant:6333/collections`
3. Embedding 服务挂了 → 检查 bge-m3 服务健康状态
### 问题：回答质量突然变差
可能原因：
1. 模型 API 版本切换 → 检查 OpenAI API 版本日志
2. Prompt 被误改 → git diff HEAD~1 查看 prompts/ 目录变化
3. 知识库内容过期 → 确认最后一次同步时间
### 系统重要参数速查
- Chunk size: 512（在 config/rag_config.yaml）
- Top-k: 5（可在管理后台调整）
- Embedding 模型: BGE-M3（更换需要重建索引，耗时约 4 小时）
- LLM: GPT-4o（备用 Claude 3.5 Sonnet，切换方式见 .env 说明）这种文档新人能用，出故障时候更能用，实用价值高，所以才会被真正看。
用 AI 辅助写文档
说了这么多文档类型，还有一个关键问题：写文档本身很费时间。
我现在的做法是：用 AI 帮我整理思路，不是 AI 全写。
具体场景：
场景一：写 ADR 的时候想不清楚
我会把背景和几个选项告诉 AI，让它帮我列出每个选项的 pros/cons。这不是让 AI 替我决策，是让 AI 帮我把考量维度显化出来，我自己做最后判断并填写"决策原因"。
场景二：从会议记录整理设计决策
开完技术讨论会，我把会议记录（可以是口语化的流水账）丢给 AI，让它帮我提炼出"做了什么决策，理由是什么，遗留什么问题"。整理一个 ADR 从 30 分钟缩短到 10 分钟。
场景三：生成评估报告的框架
给 AI 描述你的改动和测试数据，让它帮你生成报告结构，你只需要填入真实数字和主观判断。
但有一条原则必须坚守：结论必须是你自己写的。AI 可以帮你整理事实，但"这个改动值不值得上线"这个判断，必须是你来做。让 AI 写结论，文档就失去了它存在的意义。
让团队真正看的关键
最后说一个最实用的点：
文档写好了，还是没人看，问题往往不在文档本身，在于找不到。
我们现在的做法：每个项目有一个 README，README 里有且只有一件事——告诉你在哪里找各种文档。
# 项目文档导航
- 快速上手 → docs/quickstart.md
- 系统架构 → docs/architecture.md
- AI 相关决策记录 → docs/decisions/
- Prompt 版本 → prompts/（代码里，看注释）
- 评估报告 → docs/evaluations/
- 出了问题 → docs/runbook.md（先看这个）这个导航本身很轻，但它解决了"不知道该看哪个"的问题。
新人入职，我让他做的第一件事不是读所有文档，而是把 README 和 runbook 读一遍，其他的等到需要的时候再看。这个安排让文档的使用率高了很多，因为文档和需求对上了。
写文档这件事，在 AI 工程里特别容易被轻视。因为 AI 系统本身就变化快，写了感觉也会过时，干脆不写。
但这个逻辑是倒的。正因为 AI 系统变化快，才更需要记录每一次重要决策和变更——不然三个月后连你自己都不记得为什么这么设计。
轻量，但持续；够用，但真实——这是我对 AI 工程文档最终的判断。