← 文章·AI

从 OpenAI 的一篇文章出发，聊聊我理解的仓库知识库搭建

Mon Apr 0610 min
前几天读到 OpenAI 关于 Harness Engineering 的文章，其中"我们将代码仓库设为记录系统"这一节对我很有启发。
以前我对 AI Coding 的理解，更多还是停留在"给它更好的提示词""让它多读代码""把任务说清楚"这几个层面。但看完那一节之后，我慢慢意识到，真正重要的可能不是单次 prompt 怎么写，而是：我们有没有把仓库整理成一个适合 AI 理解和工作的知识环境。
顺着这个方向，我最近也在想一个问题：
如果想在一个真实项目里逐步搭一套"仓库知识库"，到底应该怎么做？
我现在的理解还在不断迭代，但大概有几个点已经比较明确了。

仓库知识库，不是为了把代码再写一遍

一开始最容易走偏的地方，就是觉得"既然要做知识库，那是不是应该把项目里的东西尽量都补成文档"。
但实际想下来，我越来越觉得不是这样。
因为代码仓库本身已经是最完整、最准确的一手信息来源。
如果知识库只是把代码里的实现逻辑、类结构、函数调用关系再翻译一遍，那最后大概率只会得到一套：
  • 内容很多
  • 维护很累
  • 很快过期
  • 还会误导 AI
所以我现在更认同一种思路：
知识库不是源码的镜像，而是源码之外的高价值补充。
也就是说，真正值得沉淀下来的，应该是那些 AI 直接读代码也不容易稳定获得、但又会明显影响它做判断和做修改的知识。
比如：
  • 一个业务概念到底是什么意思
  • 哪些状态流转是业务上允许的
  • 哪些地方看起来能改，但其实改动影响很大
  • 某个设计为什么会是现在这样
  • 某类需求通常应该去哪些地方改
  • 哪些坑是团队反复踩过的
这些东西，代码里未必完全没有，但通常都不够显式、不够集中，也不够容易稳定恢复。
我觉得这才是知识库真正该承接的部分。

AGENTS.md、docs/、skills/，我现在倾向于把它们看成三层

如果要落到仓库结构上，我现在比较认同三层分工：

第一层：AGENTS.md

它更像一个总入口 / 地图。
它不应该很长，也不应该试图把所有东西都塞进去。
更合适的角色是：
  • 告诉 AI 这个仓库大概是干什么的
  • 告诉它重要文档在哪
  • 告诉它全局有哪些硬约束
  • 告诉它遇到某类任务时，应该优先看哪里
所以它更像"导航页"，而不是"知识全集"。

第二层：docs/

这是我理解里真正的知识沉淀层。
比较适合放在这里的，是一些偏"声明式"的内容：
  • 业务概念
  • 核心流程
  • 系统边界
  • 模块职责
  • 外部依赖
  • 不变量
  • 历史决策
这些内容的共同点是，它们回答的是：
  • 这是什么
  • 为什么是这样
  • 边界在哪里
  • 哪些约束不能破

第三层：skills/

这个我越来越觉得很重要。
因为有些内容，本质上并不是"知识说明"，而是"任务做法"。
比如：
  • 新需求怎么拆
  • 怎么拉取文案
  • PR 怎么 review
  • merge 前怎么判断要不要更新 docs
  • 某类线上问题怎么排查
这类东西如果硬塞进 docs，最后通常会越写越像操作手册，而且不够灵活。 放到 skill 里会更自然，因为它本来就是一种过程化能力。
所以我现在会更粗暴地这么区分：
  • 事实、定义、边界、约束 → docs/
  • 步骤、流程、检查单、做法 → skills/

docs 怎么拆，我现在最大的感受是：不是越细越好

这是我自己在实践里感受特别明显的一点。
直觉上会觉得，文档拆得越细越清晰；但从 AI 使用的角度看，事情没那么简单。
因为层级一旦太深，引用链一旦太长，就很容易出现一种情况：
AI 并没有真正感知到某篇文档的存在。
比如：
AGENTS.md -> A.md -> B.md
理论上结构很清楚，但实际上它可能只读到了入口，或者只读到了 A，没有继续意识到 B 是必须看的。
最后不是文档不够，而是文档存在，但没有被发现。
所以我现在会比较倾向于：
层级浅一点
  • 尽量不要把关键知识藏得太深。
  • 能两跳到的，就不要三跳。
每篇文档尽量自包含
  • 不要让一篇文档必须依赖三四篇前置文档才能看懂。
  • 最好它单独被读到时，也能传递出七成以上的信息。
按"问题域"拆，而不是按"目录美学"拆
  • 我现在更倾向于让每篇文档回答一个比较明确的问题，比如：
    • 订单系统有哪些关键不变量？
    • 搜索请求链路的核心边界是什么？
    • 改推荐排序时要注意哪些外部依赖？
而不是按"service A / service B / module C"平均铺开。
因为 AI 进入问题时，往往是带着任务语义来的，而不是带着代码目录来的。

旧仓库开始沉淀知识库时，我现在更在意的是"写什么"，而不是"写多少"

如果是新仓库，很多东西还可以在一开始就顺手建立起来。
但旧仓库做知识沉淀，最大的风险其实不是"写得不够"，而是很容易越写越多，最后把知识库做成另一个更难维护的仓库。
所以我现在越来越倾向于用一个很简单的判断标准来筛：
如果 AI 只读代码，也能低成本、低歧义地得出结论，那这部分内容就不一定值得进入知识库。
真正更值得沉淀下来的，往往是这些内容：
  • 代码里不容易直接表达的业务语义
  • 跨模块、跨系统的依赖关系
  • 历史设计决策和 trade-off
  • review 里反复被提醒的问题
  • AI 或新人最容易误判的边界
  • 团队已经重复踩过很多次的坑
反过来，像这些内容，我现在会更倾向于让 AI 自己去读代码：
  • 具体实现细节
  • 函数级调用关系
  • 参数透传逻辑
  • 某段 SQL、正则、序列化代码
  • 局部 helper 的实现方式
因为这些东西，本来就是代码最准确。
如果再额外抄进 docs，最后很容易得到一套内容很多、维护很累、而且比代码还更容易过期的说明书。
所以在我现在的理解里，知识库的目标不是让 AI 少读代码，而是让 AI 更容易读对那些仅靠代码读不出来的东西。

现阶段我更愿意怎么开始

如果真的要在一个旧仓库里开始搭知识库，我现在不会追求"全仓覆盖"，而会更在意先把最值得沉淀的那部分内容写下来。
对我来说，知识库的价值，不在于覆盖率有多高，而在于它能不能抓住那些高频影响判断、但又最难从代码中恢复出来的知识。
所以比起平均给每个目录补一篇说明，我会更愿意先从几个高杠杆区域开始：
  • 新人最难接手的模块
  • 最容易误改的边界
  • 事故最多的链路
  • review 里反复出现的问题
  • AI 最容易判断失误的地方
这些地方哪怕只沉淀少量内容，通常也比"把文档补全"更有价值。
所以这件事对我来说，难点从来不是"怎么多写一点"，而是：
怎么把真正值得写的那一部分，稳定地留下来。

docs 的维护，最好不要靠"有空再补"

如果知识库真的有用，它的维护就不能靠"有空再补"，而应该进入研发流程本身。
比如在 merge 前，专门做一次检查：
  • 这次需求有没有改对外行为
  • 有没有引入新的概念或规则
  • 有没有改变模块边界
  • 有没有新增例外逻辑或排查方式
  • 有没有解决一个以后还会反复出现的问题
如果有，那就应该显式判断：
  • 要不要更新 docs/
  • 要不要补一个 skill
  • 要不要记一条 ADR
不一定每次都更新，但至少每次都应该被检查一次。
我觉得这样知识库才不容易慢慢失真。

写完 docs 之后，我现在更关心的是：它有没有真的被用到

写完 docs 之后，我现在更关心的是：它有没有真的被用到。
但在判断"有没有用"之前，还有一个更基础的问题：
AI 能不能稳定读到这段内容。
如果内容本身不可检索、没有被 AGENTS.md 正确引导，或者埋在一个不容易被引用的位置，那它对 AI 来说其实是不存在的。
所以在写完 docs 之后，我通常会先做一个很简单的检查：
  • 不显式提示路径，AI 是否能通过现有入口找到这段内容
  • 在真实任务上下文里，AI 是否会主动引用或依赖这段信息
  • 是否需要额外提示词，才能让 AI 注意到这段内容
如果需要"特意提醒"，那通常说明问题不在内容本身，而在它的暴露方式。
在确认"能被读到"之后，我才会再去判断它有没有价值。
对我来说，自测只回答一个问题：
这段内容如果不存在，会不会明显影响 AI 或新人把事情做对？
我现在主要用三种方式快速判断：
  • 用 AI 反向验证：不给 docs 看它怎么做，再给 docs，看行为有没有明显收敛
  • 用新人路径验证：是否知道从哪里开始、能不能找到关键约束、是否避免已知坑
  • 看过期风险：如果过期会不会误导，如果删掉有没有明显影响
如果"有无 docs 差别不大"，那这段内容大概率不值得沉淀。
对我来说，知识库的目标不是被阅读，而是改变行为。
自测本质上是在验证，这段知识有没有真的让决策变得更稳定。

现阶段我对"仓库知识库"的一个总结

如果用一句话总结我现在的理解，大概会是：
仓库知识库真正要解决的，不是信息量不够，而是让 AI 更稳定地读到那些代码本身不容易直接表达的上下文。
所以最后形成的结构，大概会是：
  • AGENTS.md 负责导航
  • docs/ 负责沉淀高价值知识
  • skills/ 负责复用任务流程
而沉淀这件事本身，我现在最在意的，其实还是两点：不要追求全，也不要复制代码。
更重要的是，优先留下那些真正影响判断质量、又无法稳定从代码中直接恢复出来的知识。