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 RequestReviewer可以检查文档与代码是否一致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 GardeningDoc 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领域文档SkillCI规则。第四周增加自动维护建立文档链接检查、元数据检查和周期性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能推理多深仓库知识决定它从什么事实开始推理。