很多团队接入Codex之后，会遇到一个看起来很矛盾的问题：

团队明明已经写了大量文档，为什么Agent还是不了解项目？

架构方案在在线文档里，接口约定在聊天记录里，部署步骤由运维保存在个人笔记中，某个历史兼容逻辑只有两名老开发者知道。

人类开发者遇到问题时，可以在群里提问、翻找会议记录，或者直接询问熟悉项目的同事。Agent执行任务时，却未必能够访问这些信息。

在Agent看来，无法在当前工作环境中发现、读取和验证的知识，几乎等于不存在。

所以Agent时代的知识管理目标，不再只是“让团队有文档”，而是：

让代码、规则、架构、决策、运行手册和验证方法，共同存在于一个可搜索、可版本控制、可校验的仓库知识系统中。

这套系统应该成为项目的唯一事实源。

一、文档很多，为什么仍然不等于知识可用？

团队常见的知识分布大致是：

代码：Git仓库 产品需求：在线文档 架构讨论：聊天群 接口变化：会议记录 部署步骤：个人笔记 故障经验：值班复盘 测试规则：测试人员口头传递

这些内容对人类来说可能勉强可用，因为人会主动询问、补充和判断。

Agent没有这种组织关系。

它接到任务后，首先看到的通常是：

• 当前仓库；

• 当前目录；
  -任务提示词；

• 能够读取的规则文件；

• 被允许访问的外部工具。

如果一项关键决策只存在于三个月前的群聊中，Agent很可能重新做出另一种设计。

如果部署流程只保存在某位开发者的笔记中，Agent就无法判断修改完成后应该怎样验证。

所以问题不是“有没有写过”，而是：

这些知识是否位于Agent可以稳定发现的路径中？

二、什么叫仓库知识的唯一事实源？

唯一事实源并不意味着所有信息只能写在一个文件里。

它真正表达的是：

对于某一类工程问题，团队必须明确哪份仓库文件拥有最终解释权。

例如：

• 系统总体边界以ARCHITECTURE.md为准；

• 支付状态流转以docs/domains/payments/state-machine.md为准；

• 公共接口契约以OpenAPI文件为准；

• 测试命令以AGENTS.md和CI配置为准；

• 当前大型重构进度以执行计划为准；

• 生产故障处理以运行手册为准；

• 数据库结构以Schema和自动生成文档为准。

如果群聊里的说法与仓库文档冲突，应该修改仓库文档，而不是继续让两个版本长期并存。

唯一事实源的价值，是减少Agent必须自行判断的信息冲突。

三、为什么不能把全部知识塞进AGENTS.md？

很多团队第一次配置Codex时，会把所有规则都写入根目录的AGENTS.md。

文件逐渐包含：

• 项目介绍；

• 架构说明；

• 编码规范；

• 测试命令；

• 接口规则；

• 发布流程；

• 安全要求；

• 历史决策；

• 常见故障；

• 所有目录说明。

最后可能变成数百行甚至上千行的项目百科全书。

这种做法有四个问题。

第一，挤占任务上下文

Agent真正执行任务时，还需要读取代码、日志、测试结果和当前需求。

一个巨大的规则文件会让大量无关内容过早进入上下文。

第二，重要性无法区分

当每条规则都被标记为重要时，Agent反而无法判断当前任务最应该关注什么。

第三，内容非常容易过期

代码已经变化，文档中的目录、命令和接口却仍然停留在旧版本。

第四，难以自动检查

一份巨型文件很难判断每一条内容由谁维护、何时验证、是否仍然有效。

因此，AGENTS.md更适合成为仓库知识地图，而不是完整百科全书。

四、AGENTS.md应该写什么？

一个实用的根目录AGENTS.md只需要回答五个问题：

1. 这是一个什么项目？

2. 重要目录分别负责什么？

3. 开始任务前应该先读哪些文档？

4. 修改后必须运行哪些检查？

5. 哪些高风险操作必须暂停并请求确认？

示例：

# AGENTS.md ## Repository map - `apps/web/`：Web客户端 - `services/orders/`：订单服务 - `services/payments/`：支付服务 - `packages/sdk/`：公共SDK - `docs/`：项目知识库 ## Read before working - 架构边界：`docs/ARCHITECTURE.md` - 产品规则：`docs/product-specs/` - 服务说明：`docs/domains/` - 运行手册：`docs/runbooks/` - 大型任务计划：`docs/exec-plans/` ## Validation - 修改TypeScript后运行：`pnpm lint && pnpm test` - 修改接口后检查OpenAPI与SDK - 修改数据库后运行迁移测试 ## Guardrails - 不得删除测试来通过CI - 不得擅自新增生产依赖 - 公共接口变化必须说明兼容性 - 数据库和生产权限变化必须人工批准

它告诉Agent去哪里寻找答案，而不是试图提前回答所有问题。

五、仓库知识应该怎样分层？

推荐把知识分成六层。

第一层：入口导航

包括：

AGENTS.md README.md ARCHITECTURE.md

它们负责帮助Agent快速建立项目地图。

第二层：领域知识

例如：

docs/domains/orders/ docs/domains/payments/ docs/domains/users/

每个领域目录说明：

• 业务职责；

• 核心对象；

• 状态流转；

• 上下游依赖；

• 不允许破坏的规则；

• 常见验证方式。

第三层：产品与接口契约

包括：

• 产品规则；

• OpenAPI文件；

• 数据Schema；

• 事件格式；

• SDK类型；

• 兼容性说明。

这类内容应该尽量结构化，减少自然语言产生的歧义。

第四层：设计与决策

包括：

docs/design-docs/ docs/decisions/

记录为什么选择当前方案、放弃过哪些替代方案，以及未来什么情况下需要重新评估。

第五层：运行知识

包括：

docs/runbooks/ docs/reliability/ docs/security/

记录部署、监控、故障处理、回退和安全操作。

第六层：任务计划与技术债

包括：

docs/exec-plans/active/ docs/exec-plans/completed/ docs/tech-debt/

大型任务不能只存在于会话中，还应该把计划、进度、决策和未完成项提交到仓库。

六、怎样实现渐进式披露？

Agent不应该在每个任务开始时读取整个docs/目录。

更合理的方式是：

先读取小型入口，再根据任务逐层深入。

例如，任务是修复支付回调重复处理。

Agent首先读取：

AGENTS.md docs/ARCHITECTURE.md

根据导航，再读取：

docs/domains/payments/index.md docs/domains/payments/idempotency.md docs/runbooks/payment-callback.md

如果任务不涉及前端，就没有必要加载前端设计规范。

可以在领域目录中增加index.md：

# Payments knowledge index ## Core behavior - `state-machine.md`：支付状态流转 - `idempotency.md`：重复回调与幂等规则 - `refunds.md`：退款与撤销 ## Interfaces - `callback-contract.md` - `events.md` ## Operations - `../../runbooks/payment-callback.md` - `../../reliability/payment-alerts.md`

这相当于为Agent提供一套知识路由。

七、完整案例：支付服务怎样建立知识地图？

假设支付服务经常出现三种问题：

• Agent使用浮点数计算金额；

• 重复回调导致订单重复更新；

• 日志中输出了不应该出现的敏感字段。

如果只在提示词里反复提醒，每次新会话都需要重新说明。

更可靠的目录可以这样设计：

services/payments/ ├── AGENTS.md ├── src/ ├── tests/ └── docs/ ├── index.md ├── money.md ├── idempotency.md ├── state-machine.md └── security.md

支付目录的AGENTS.md只保留高优先级规则：

# Payment service rules 开始修改前，先阅读`docs/index.md`。 - 金额使用整数最小单位，禁止浮点运算。 - 回调处理必须保持幂等。 - 终态订单不得退回处理中状态。 - 禁止在日志中输出完整Token或支付凭证。 - 修改状态流转后运行`make test-payments`。

更详细的原因、示例和边界场景则放在对应文档。

例如idempotency.md记录：

• 幂等键来自哪里；

• 重复回调怎样识别；

• 哪些数据库操作必须位于同一事务；

• 当前失败重试策略；

• 典型测试数据；

• 已知例外情况。

当Codex进入支付目录工作时，能够先获得关键边界，再按需读取详细知识。

八、知识必须和代码一起版本化

将文档放进仓库的价值，不只是方便Agent读取。

它还意味着知识可以参与正常的软件工程流程：

• 修改可以进入Pull Request；

• Reviewer可以检查文档与代码是否一致；

• Git历史能够解释规则为何变化；

• 分支可以保留不同版本的知识；

• 回退代码时可以同时回退对应说明；

• 发布标签可以对应当时真实的架构和接口。

例如一次接口字段变更，PR中应该同时包含：

后端实现 OpenAPI定义 SDK类型 兼容性说明 迁移步骤 相关测试

如果代码已经变化，而知识文件没有变化，PR就不应该被视为完整交付。

九、怎样防止仓库知识过期？

知识库最大的风险不是缺少内容，而是内容看起来权威，实际已经失效。

因此，每份重要文档最好增加元数据：

--- owner: payments-team status: verified last_verified: 2026-08-05 source_of_truth: - services/payments/src/state-machine.ts - services/payments/tests/state-machine.test.ts ---

可以定义三种状态：

• verified：已与当前代码核对；

• needs-review：可能过期，使用前需要确认；

• historical：只用于解释历史，不代表当前规则。

Agent读取文档时，就不会把所有文件都当成同等可信。

十、什么是Doc Gardening？

Doc Gardening可以理解为周期性的知识维护。

它不是让Agent每天重写所有文档，而是定期寻找知识与代码之间的偏差。

检查内容可以包括：

• 文档中引用的文件是否仍然存在；

• 命令能否正常执行；

• 接口字段是否与Schema一致；

• 目录索引是否缺少新文件；

• 已完成的执行计划是否仍放在active目录；

• 文档负责人是否已经失效；

• 最近代码变更是否影响架构说明；

• 是否存在互相冲突的规则。

任务输出不应该直接大规模修改，而应该先生成报告：

过期文档： 疑似冲突： 缺少索引： 代码变化但文档未更新： 建议修复PR：

经过验证后，再由Agent提交小范围文档修复。

十一、怎样用CI自动检查知识库？

不是所有知识都能自动判断真假，但很多结构性问题可以机械检查。

例如CI可以检查：

链接有效性

所有Markdown内部链接指向的文件必须存在。

索引覆盖

docs/domains/下新增文件后，必须被对应index.md引用。

Schema同步

OpenAPI、SDK类型和生成文档必须保持一致。

文档元数据

重要文档必须包含Owner、状态和最近验证时间。

执行计划状态

完成任务后，计划必须从active/移动到completed/。

规则冲突

根目录与子目录规则如果存在明显冲突，应要求人工确认。

CI负责检查可以确定的规则，Agent负责识别需要语义判断的知识漂移。

十二、哪些内容应该做成Skill？

仓库知识回答的是：

项目当前是什么样，以及有哪些长期规则。

Skill回答的是：

某一类重复工作应该怎样完成。

例如以下流程适合做成Skill：

• 新增API后的同步检查；

• 数据库迁移审查；

• 发布前检查；

• 故障复盘整理；

• 文档过期扫描；

• Pull Request架构审查。

Skill中可以引用仓库知识：

先读取docs/ARCHITECTURE.md 再读取当前服务的docs/index.md 按照references/release-checklist.md执行 最后输出验证证据

这样可以形成稳定分工：

仓库知识保存事实；
AGENTS.md负责导航；
Skill负责复用流程；
CI负责强制检查；
Agent负责发现漂移和提交修复。

十三、团队怎样从零开始建设？

不建议一次重写全部文档。

可以先从最近最容易出现Agent错误的地方开始。

第一周：建立入口

创建：

AGENTS.md ARCHITECTURE.md docs/index.md

先让Agent知道项目结构和关键验证命令。

第二周：整理高风险领域

优先覆盖：

• 支付；

• 权限；

• 数据库；

• 公共接口；

• 发布与回退。

第三周：把重复反馈写入规则

整理最近的PR Review和Agent失败记录。

同一错误出现两次，就判断应该进入：

• AGENTS.md；

• 领域文档；

• Skill；

• CI规则。

第四周：增加自动维护

建立文档链接检查、元数据检查和周期性Doc Gardening任务。

不要追求文档数量。

真正重要的是：

每份知识都有明确位置、负责人、验证方式和更新触发条件。

仓库知识目录模板

repository/ ├── AGENTS.md ├── README.md ├── ARCHITECTURE.md ├── docs/ │ ├── index.md │ ├── design-docs/ │ │ ├── index.md │ │ └── core-principles.md │ ├── decisions/ │ │ └── ADR-0001-example.md │ ├── domains/ │ │ ├── orders/ │ │ │ ├── index.md │ │ │ └── state-machine.md │ │ └── payments/ │ │ ├── index.md │ │ └── idempotency.md │ ├── product-specs/ │ ├── runbooks/ │ ├── reliability/ │ ├── security/ │ ├── exec-plans/ │ │ ├── active/ │ │ └── completed/ │ └── generated/ └── .agents/ └── skills/

发布前检查清单

□ AGENTS.md是否保持简洁 □ 重要目录是否都有明确说明 □ 架构和领域文档是否有索引 □ 每类知识是否有唯一事实源 □ 文档是否与代码一起版本化 □ 高风险规则是否靠近对应目录 □ 重复流程是否已沉淀为Skill □ 可以自动检查的规则是否进入CI □ 文档是否包含Owner和验证状态 □ 是否存在周期性的知识漂移检查 □ 大型任务计划是否提交到仓库 □ 聊天中的重要决策是否已经回写

结语

Agent时代，项目知识不能只服务于熟悉系统的人。

它还必须服务于：

• 第一次进入项目的新开发者；

• 新启动的Codex会话；

• 并行工作的子Agent；

• 后台执行的自动化任务；

• 几个月后重新处理问题的团队成员。

真正可靠的仓库知识系统应该做到：

Agent能够发现；
人类能够阅读；
Git能够追踪；
CI能够检查；
负责人能够维护；
任务能够引用；
结果能够验证。

AGENTS.md不应该成为装满所有知识的巨大说明书。

它应该是一张地图，引导Agent找到真正的架构、契约、运行手册和执行计划。

当团队发现Codex总是重复提问、误解项目边界、忘记历史决策时，问题可能不是模型不够聪明，而是项目没有给Agent提供一个可靠、可发现并且持续更新的事实系统。

Agent能力越强，仓库知识越重要。

因为模型决定Agent能推理多深，仓库知识决定它从什么事实开始推理。