别再给 AI 写文档了,让它自己维护项目地图

上一篇说，AI 在企业项目里翻车，是因为模型和项目之间缺一层。

这一篇讲这一层的第一块：.llm-wiki。

01 从个人知识库到项目

Karpathy 提过一个思路：与其每次提问都临时检索文档，不如让 AI 持续维护一份知识库，让知识像复利一样积累。

我先在个人笔记上落地了一版，用了一个多月，效果不错。

但搬进软件项目时，必须做减法。

个人知识库可以什么都记。项目知识库如果也什么都记，很快就会变成又一个没人维护的文档仓库。

02 一条契约，五句话

.llm-wiki 的设计浓缩成五句话：

1. 不替代 PRD、设计、代码、测试和配置

2. 索引页不堆放长篇原文

3. 只存索引、摘要、关系、状态和缺口

4. 和代码冲突时，代码优先

5. 在初始化、摄入、开发、完成、评审时更新

它更像一张项目地图，而不是项目本身。

地图上标着：资料在哪、讲了什么、和哪个模块有关、哪些已确认、还缺什么。

03 谁来维护？

任何知识库最大的敌人都是维护成本。

所以分工很明确：

人负责原始资料，PRD、设计、会议纪要都留在原来的地方。

AI 负责索引层，在干活的过程中顺手写入摘要、关系和状态。

研发不用手工填表。说一句“代码和验证完成，同步一下 wiki”，剩下的交给 AI。

04 模块知识和任务知识分开放

.llm-wiki 里有两种上下文。

模块上下文：这个模块长期稳定的知识。职责边界、关键入口、内部架构、特有规则、怎么验证。

任务上下文：只服务于一次需求或修复。这次能改哪些模块，哪些只能参考，哪些不准碰。

为什么分开？

一个需求常常跨好几个模块。任务信息写进模块，模块知识会被一次次污染；模块知识写进任务，下次又得重新整理。

历史项目的 .llm-wiki 目录示例，可见 modules 与 working-context 两类入口。基于原截图经 AI 裁取整理，目录条目已核对；不同版本的目录可能不同。 点击图片可查看大图。

05 最重要的一条：Wiki 不是真相

AI 用 Wiki 时，顺序是固定的：

先查 Wiki 找线索 → 再看源码、配置和测试 → 确认不了的写“待确认”。

比如 Wiki 写着某个接口由用户中心提供，但接口三个月前已经迁走了。这时 AI 必须以源码为准，并指出 Wiki 可能过期。

Wiki 的价值是帮 AI 找对地方，不是替源码做判断。

那 Wiki 过期了会不会反过来误导 AI？这个问题，第四篇专门讲。

06 三个常见问题

要一次性导入所有资料吗？不用。从高频模块和正在做的需求开始，逐步积累。

要提交到 Git 吗？要，它跟代码一起演进。只有记录本机路径的配置文件不提交。

老项目已经有 docs 目录怎么办？原文档不动，登记进 Wiki 就行。

写在最后

一句话总结：.llm-wiki 告诉 AI 去哪里找，以及找到的东西可信到什么程度。

下一篇聊老项目最现实的问题：已有的文档和聊天记录，怎么接进来，又不把 Wiki 变成垃圾堆。

项目已开源，地址：

https://github.com/huajiexiewenfeng/role-copilot-skills/tree/main/project-agent-copilot/project-develop-copilot

你的团队现在把项目知识放在哪里？欢迎留言。