ChatGPT、Codex方法论：为什么Agent时代必须把仓库知识变成唯一事实源？

很多团队接入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只需要回答五个问题：

示例：

# 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能推理多深，仓库知识决定它从什么事实开始推理。