先说结论
AI 写代码有两个致命问题：忘了自己要干啥，以及同样的坑反复踩。
我的解决方案是两步走：
- 文档编程——动手写代码之前，先让 AI 把方案、设计、影响面写成文档，相当于给 AI 一张”施工蓝图”
- 向量索引工作日志——用 Qdrant 把每天的工作记录变成可搜索的”经验库”，AI 执行时能自动翻出相关的历史踩坑记录
效果：返工明显减少，一晚上跑完代码只消耗不到 3% 的 Copilot 额度。
核心概念
什么是文档编程？
文档编程不是写文档，而是把”想清楚”这件事前置。
打个比方：盖房子之前要画施工图，不能让工人边盖边想。AI 写代码也是一样——如果你直接甩一句”帮我重构这个模块”，AI 大概率会走弯路。但如果先把方案、设计决策、影响范围、执行步骤都写清楚，AI 就像拿着导航开车，不会跑偏。
具体来说，文档编程包含：
- 方案文档：要做什么、为什么这样做
- 设计文档：技术选型、接口设计、数据结构
- 影响面分析：改动会波及哪些模块
- 执行流程：分几步走、每步验收标准是什么
什么是向量索引？
向量索引（Vector Index）是一种让计算机理解”语义相似度”的技术。
举个例子：传统搜索只能精确匹配关键词——你搜”登录报错”，只能找到包含这四个字的记录。但向量索引能理解语义，搜”登录报错”也能找到”用户认证失败”、“token 过期”这类相关内容。
我用的是 Qdrant（一个开源的向量数据库），把每天的工作日志——包括遇到的问题、解决方案、踩过的坑——全部转化为向量存储起来。
工作原理
整个流程像是给 AI 装了两个器官：大脑（文档） 和 记忆（向量索引）。
┌──────────────────────────────────────────┐
│ 开始新任务 │
│ ↓ │
│ 文档编程：明确目标、方案、步骤（大脑） │
│ ↓ │
│ AI 执行时，自动检索相关历史经验（记忆） │
│ ↓ │
│ 写代码 → 完成后记录本次经验 → 回到经验库 │
└──────────────────────────────────────────┘关键点在于：AI 在执行每一步时，都会根据当前正在做的事情，去向量数据库里搜索”最近一个月有没有类似的坑”。如果搜到了，它会先看看之前是怎么解决的，再动手写代码。
这套方案借鉴了 OpenClaw 的记忆设计和 OpenSpec 的最佳实践，核心思想是：经验不应该只存在人脑里，应该变成 AI 可检索的资产。
实际效果
返工减少
以前 AI 写代码经常出现”改了 A 又忘了 B”的情况。有了文档编程之后，AI 始终知道全局目标是什么，不会顾此失彼。
自动避坑
比如上周 AI 在处理一个并发问题时，向量检索自动拉出了两周前一条类似的踩坑日志——当时因为锁粒度太粗导致死锁。这次 AI 直接用了细粒度锁，一次通过。
成本极低
文档编程还有个意外收获：因为方案提前写好了，执行阶段可以交给 GitHub Copilot（按 Request 计费，不按 Token 计费）。一晚上自动跑完，才消耗不到 3% 的月度额度。
常见误区
误区一：“工作日志随便记记就行”
向量检索的质量完全取决于日志质量。如果日志只写了”修了个 bug”，AI 根本搜不到有用信息。好的日志应该包含：问题现象 + 根因分析 + 解决方案 + 教训总结。
误区二：“文档编程就是写 PRD”
文档编程的核心不是文档格式，而是让 AI 和你对齐认知。它不需要多正式，但一定要把”为什么这样做”和”边界在哪里”说清楚。
误区三：“向量索引能替代人的判断”
向量索引只是帮 AI 找到相关经验，但经验是否适用于当前场景，仍然需要设计合理的 prompt 来引导 AI 做判断。不能盲信历史方案。
总结
| 手段 | 解决的问题 | 类比 |
|---|---|---|
| 文档编程 | AI 执行中跑偏、忘记目标 | 施工蓝图 |
| 向量索引工作日志 | 重复踩坑、经验流失 | 老师傅的笔记本 |
| 两者结合 | 返工多、效率低 | 有地图 + 有经验的司机 |
核心思路就一句话：先让 AI 知道往哪走（文档），再让它记住路上哪里有坑（向量索引）。
FAQ
Q：Qdrant 部署复杂吗？
不复杂。Qdrant 支持 Docker 一键部署，本地跑一个实例就够了。数据量不大的情况下（几千条日志），单机完全能撑住。
Q：工作日志需要手动写吗？
前期需要手动记录，但可以逐步自动化——比如让 AI 在每次完成任务后自动生成一条结构化的经验总结，直接入库。
Q：这套方案适合小项目吗？
小项目（几百行代码的改动）不需要。这套方案主要解决的是大需求、大重构场景下的经验复用问题。小改动直接让 AI 写就行。
Q：除了 Qdrant，还能用什么？
任何支持向量检索的数据库都行，比如 Milvus、Pinecone、Weaviate，甚至用 SQLite + 向量扩展也可以。关键不是工具，而是持续沉淀高质量的经验日志。