规则、参考、工作流：团队知识该放在哪
2026 年我在推动今日头条客户端团队的 AI 知识库规范，要回答的问题只有一个：Agent 时代，团队知识怎么组织，才能被 AI 和人同时用好。
问题的起点很具体。团队知识散在各处：文档平台上的设计文档、群聊里的排障记录、老工程师脑子里的约定。人找起来已经费劲——新人入职时问的第一批问题，答案大多散落在没人能指路的地方；Agent 则完全用不上，它进入一个仓库时，除了代码什么都看不到。反过来，把所有文档一股脑塞给 Agent 也不行：上下文有限，绝大多数知识和当前任务无关。
反复整理后，我收敛出一个三分法。
三分法
按知识的性质分三类，各有各的去处：
| 知识类型 | 放置位置 |
|---|---|
| 必须无条件遵守的项目规则 | AGENTS.md（Agent 每次会话自动加载） |
| 背景、架构、领域知识、参考资料 | Wiki（按需检索） |
| 可重复执行的标准工作流 | Skill（按需加载执行） |
两个名词给一句上下文：AGENTS.md 是多数 Coding Agent 约定的项目说明文件，会话开始时自动读入；Skill 是 Claude Code、Codex、Cursor 等 Agent 支持的机制，把工作流写成文档，按需加载执行。
按载入时机看，三类其实是两种。规则型知识强制引入，每次都要在场：代码规范、提交约定、禁止事项，Agent 不知道就一定会犯。参考型知识按需引入，用到再查：某个模块的架构设计，只在改那个模块的时候才有用。
由此推出第一条纪律：AGENTS.md 必须保持短小。它是唯一无条件占用每次会话上下文的文件，把大段参考资料复制进去，等于让所有任务都为它付出上下文成本。参考资料放 Wiki，AGENTS.md 里只放规则和入口。
Skill 按触发方式再分两种：AI 能可靠判断触发条件的工作流，做成自动触发；涉及敏感操作、或需要用户做选择的，做成手动触发。
这样，一个项目的知识加载就分成三层：AGENTS.md 的自动规则，按需检索的 Wiki，按需加载的 Skill 工作流。一次典型的任务流转是：Agent 带着 AGENTS.md 里的规则开工，改到不熟悉的模块时检索 Wiki 补背景，碰到发版这类标准操作时加载对应的 Skill 照流程执行。三层各管一段，互不越界。
Wiki 用 Diátaxis 组织
Wiki 内部采用 Diátaxis 框架，分教程、操作指南、解释、参考四类：教程带新人完整走一遍，操作指南解决一个具体任务，解释讲背景和设计决策，参考是精确的事实清单。选它就为一件事：让「怎么做」和「为什么」不混在同一篇文档里。混写的文档人读着累，Agent 检索时也拿不准该引用哪一段——查操作步骤的任务用不上历史背景，查设计决策的任务用不上命令清单。
Skill 控制在 20 个以内
团队 Skill 的数量设了上限：20 个。理由是认知负荷。Skill 列表本身会进入 Agent 的上下文，也会进入维护者的头脑；超过一定数量之后，「找到对的那个」比「新写一个」更贵，接下来就会出现两个高度重复的 Skill，连维护者自己都说不清差别。数量顶到上限时，先合并、删除，再考虑新增。20 这个数字本身谈不上精确，重要的是存在上限：它逼着每次新增之前先回答一个问题——这件事能不能并进已有的 Skill。
先读文档，再看代码
工作流层面有一条关键约定：Agent 进入任务时先查知识库，再翻代码。这条不立，Agent 的默认行为是直接读代码推断一切——推断得往往还不错，于是团队知识永远没有被引用的机会，写了等于白写。知识库的价值和这条工作流约定绑在一起，要推就一起推。
一处权威，别处引用
更新知识之前先判断：这件事是否已经有唯一权威来源？有，就链接过去，不复制正文。复制出来的第二套会漂移，过几个月两边说法不一致，读者不知道该信谁。全局知识库尽量只保存入口和稳定摘要，正文留在它的权威位置。判断的成本很低，检索一次而已；不判断的代价是库里渐渐出现几篇标题相似、内容各自演化的文档，后来的维护者只能靠猜。
检索靠默认能力
知识库的检索，默认依赖 Agent 原生的文件检索能力（比如 rg），加上清楚的内容结构：目录名达意、标题准确、正文里出现该出现的关键词，模型就找得到。没有真实的能力缺口时，不额外维护一套搜索脚本或索引服务——我在个人 Skill 库上为这个结论付过一次学费。
同样的判断放大一层，就是「要不要上 RAG」。我的立场是 agentic search 优于 RAG 同步文档库：把文档拉到本地用 Git 管理，让 AI 直接检索文件，也让 AI 参与优化知识结构。文档进了 Git，知识的每次变更就有了和代码一样的历史与评审。一句话概括：RAG 解决怎么找资料，知识编译解决怎么炼知识。向量检索能把相关段落捞出来，但改不动文档本身；本地化的知识库，AI 发现两篇文档冲突可以直接改，发现结构不合理可以重组。知识库要可被 AI 优化、可迭代，而不只是可检索。
顺带一句：评测集也是知识。一个问题加上它验证过的解答，本身就是团队知识的一部分，值得和文档放在一起管理。评测怎么建，单独写在《评测的尺子》里。
配套机制
三分法要运转起来，还差两个配套机制。
一是 wiki-lookup 和 wiki-update 这对工作流。前者让 Agent 按需查找和引用团队知识，后者让它把任务中新确认的知识写回知识库。写回的时机很自然：一次排障收尾、一个方案定稿，Agent 手里正握着刚验证过的结论，这时候顺手更新知识库，成本最低。只查不写，知识库会停在建库那天的状态。
二是 Skill 的统一分发。团队成员用的 Agent 各不相同，Claude Code、Codex、Cursor 都有，各家读取 Skill 的目录还不一样。分发工具的做法是维护单一的 Skill 源仓库，用软链接把它安装进各个 Agent 的目录——写一份，处处可用，改动只发生在一处。
这套规范目前的状态：两类知识的职责边界和 Skill 统一架构已经定稿，组织核心业务方评审过一轮，正在试点接入。推进到现在，我最大的体会是：三分法本身不难想，难守的是配套纪律——AGENTS.md 保持短小、Skill 数量设上限、先读文档再看代码。结构一天就能定下来，纪律要靠一次次评审守住。等试点跑出足够的使用数据，才能回答下一个问题：知识库被 Agent 引用的频率，到底有没有高到值得这套投入。