很多人第一次使用 Codex 时，会把所有要求都写进聊天框：项目使用什么技术栈、代码应该放在哪里、修改后运行哪些测试、哪些目录不能碰、接口错误应该怎样返回。当前任务可能因此顺利完成，但换一个会话、换一个开发者，或者几天后重新打开仓库，这些背景又需要解释一遍。
AGENTS.md 就是为了解决这个问题而存在的。它不是业务代码，也不是应用运行时配置，而是一份跟随仓库保存、专门提供给编码 Agent 阅读的长期工程说明。Codex 在开始工作前会自动加载适用的指令，让每次任务从相对一致的仓库认知出发。
📷 [图片 token=JplCbO9cioQ2QRxF61ScLQswnyj（未能下载，见飞书原文）]
[!SUCCESS] 可以把
AGENTS.md理解为“面向 AI 编码助手的仓库 README”。README 主要告诉人怎样理解和运行项目，AGENTS.md 则进一步告诉 Codex 应该怎样阅读、修改、验证和交付这个项目。
为什么仅靠提示词还不够
提示词适合描述当前任务，例如“修复登录过期后页面没有跳转的问题”。但仓库里还有大量不会随着这次任务改变的长期事实：后端使用什么包管理器、数据访问必须经过哪一层、API 契约放在哪里、是否允许新增环境变量、什么情况必须创建数据库迁移，以及怎样才算真正完成。
如果这些信息只存在于某一次对话中，就会出现三个常见问题。首先是重复沟通，每次都要重新解释目录和命令；其次是行为漂移，不同会话对同一仓库采用不同做法；最后是隐性风险，Codex 可能在没有意识到安全边界的情况下写入凭据、绕过租户过滤，或者把测试替身的结果描述成真实联调成功。
📷 [图片 token=YxxDb8T9Tojet4xHFmvcE4OpnEt（未能下载，见飞书原文）]
AGENTS.md 把这些长期规则放进版本库，让它们与代码一起演进。它不会替你完成架构设计，也不能代替测试和代码审查，但它能够在 Agent 动手之前，把“这个仓库认为什么是正确做法”放入上下文。
📷 [图片 token=PkDBbo5sLoGj5KxWrKtcpatAnVb（未能下载，见飞书原文）]
AGENTS.md 到底是什么
从 Codex 的角度看，AGENTS.md 是一种开放格式的持久指令文件。文件内容就是普通 Markdown，不要求固定模板，也不会被应用打包或部署。它只在 Codex 等支持该约定的 Agent 读取仓库时发挥作用。
它最适合保存四类信息：稳定的仓库事实、反复使用的工作流程、可以执行的验证命令，以及必须长期遵守的安全和工程边界。一次性的需求、某个临时 Bug 的细节和只对当前会话有效的偏好，仍然应该放在本次提示词或对应的 OpenSpec 变更里。
📷 [图片 token=XLC3bgWHwojhrOxdm1Jc6nMHnxh（未能下载，见飞书原文）]
需要特别区分：AGENTS.md 描述的是“在这个仓库里应该怎样工作”，不是“本次具体要开发什么功能”。后者应该由当前需求和 OpenSpec 负责。
📷 [图片 token=A5NMb73GUo2euDxJS9fcLIxjnGf（未能下载，见飞书原文）]
Codex 怎样发现并应用这些规则
根据 Codex 官方说明，指令发现会在一次运行开始时构建。Codex 先读取全局规则，再从项目根目录沿着目录层级走向当前工作目录，逐层收集可用的指令文件。越接近当前目录的文件越晚加入上下文，因此在规则冲突时拥有更高优先级。
📷 [图片 token=YUWLbOaCWouSkNx2NPOc0Qgwngb（未能下载，见飞书原文）]
| 作用范围 | 典型位置 | 适合保存的内容 |
|---|---|---|
| 个人全局规则 | ~/.codex/AGENTS.md | 个人长期偏好，例如沟通语言、常用审查方式和跨仓库工作习惯 |
| 仓库公共规则 | 仓库根目录的 AGENTS.md | 项目结构、技术栈、通用工作流、验证命令和安全边界 |
| 子目录规则 | apps/backend/AGENTS.md 等 | 只适用于该子树的语言规范、测试命令或团队约束 |
📷 [图片 token=ZqKPbAK7po3eFgxqB5acSmy8n0g（未能下载，见飞书原文）]
在同一个目录中，Codex 会优先检查 AGENTS.override.md，找不到时再检查 AGENTS.md。同一目录最多选择一个指令文件。全局层和项目层都可以使用 override，但它会遮盖同层的普通文件，应当只在确实需要替代规则时使用。
📷 [图片 token=Ywkzb0rIrosFEoxGznBcTefRn9g（未能下载，见飞书原文）]
Codex 会跳过空文件。所有被发现文件的合并内容还受到 project_doc_max_bytes 限制，官方当前默认值为 32 KiB。文件过大时，与其不断提高上限，更好的做法通常是保留精炼的根规则，把只适用于某个区域的内容下沉到对应子目录，或者引用独立的架构与审查文档。
指令链通常在一次 Codex 运行或 TUI 会话开始时生成。如果刚修改了 AGENTS.md，却发现当前会话仍在执行旧规则，可以新开一次运行或重启当前会话，让 Codex 重新发现指令。
📷 [图片 token=Us6Kbvv16odP7Exv7AZcCr2RnJb（未能下载，见飞书原文）]
一份有效的 AGENTS.md 应该包含什么
没有唯一模板，但内容应该帮助 Codex 在行动前回答几个问题：这是一个什么项目，事实应该去哪里查，代码分别位于哪里，什么流程必须遵守，哪些命令能够验证结果，以及有哪些绝对不能越过的边界。
适用范围和项目定位。 说明当前文件影响整个仓库还是某个子目录，并用准确、克制的语言描述项目。这样可以避免 Codex 把完整项目当成空白脚手架，也能防止它引入不属于当前系统的产品定位和技术栈。
事实来源和阅读顺序。 指出主规格、活动变更、共享契约、实现和测试分别承担什么角色。发生冲突时，应说明以什么为准，历史归档是否仍允许继续修改。
仓库结构。 列出真正重要的目录及职责，不需要复制整棵文件树。目录说明应该帮助 Agent 快速定位前端、后端、共享包、基础设施、脚本、规格和文档。
标准开发流程。 说明修改前需要检查什么，什么类型的变更必须先创建 OpenSpec change，怎样拆分纵向功能，何时同步契约、迁移、测试和文档，以及交付前应检查哪些差异。
📷 [图片 token=HOmNbrliMo6NDsxhLlOcK3HSnVh（未能下载，见飞书原文）]
构建与验证命令。 提供可以直接运行的安装、格式检查、类型检查、测试和构建命令，并注明正确工作目录。不要只写“运行相关测试”，因为不同 Agent 对“相关”的理解可能不同。
语言与架构约定。 例如 Python 导入方式、前端状态管理模式、路由和服务的职责边界、数据库访问路径，以及能否引入新的包管理器或传输层。
安全与数据边界。 明确凭据如何管理、日志必须怎样脱敏、用户和 tenant 数据怎样隔离、真实工具结果能否伪造、失败状态应该如何呈现。这类规则越具体，越能在代码生成早期阻止高风险偏差。
📷 [图片 token=FnhHbWUX3obpokxkh6scSGUgnue（未能下载，见飞书原文）]
完成定义和交付要求。 规定什么情况下必须运行后端测试、前端测试、契约检查、迁移或文档构建，以及只能报告真实执行过的验证结果。必要时还可以规定提交信息和 PR 描述格式。
📷 [图片 token=M4uHbq53noOUJ0xZXEIciHqwnaf（未能下载，见飞书原文）]
哪些内容不适合写进去
AGENTS.md 并不是越长越好。把所有知识都塞进去，会占用上下文，也会让真正重要的规则被淹没。
不要写 API key、密码、访问令牌、真实连接地址或其他敏感信息。
不要复制整份产品需求、数据库字典或架构文档；应写清事实来源并链接到对应文档。
不要放只针对一次任务的临时要求，它们应该留在本次提示词或 OpenSpec change 中。
不要写“保持高质量”“充分测试”“遵循最佳实践”这类无法执行和验收的空话。
不要保留已经失效的命令、目录和技术栈。错误的长期指令比没有指令更危险。
不要把无法自动验证的偏好伪装成强制规则，也不要让文字规则替代权限控制、测试和静态检查。
📷 [图片 token=VhnabRi4foQf4qxzH1Kc1nr3nRc（未能下载，见飞书原文）]
OncallAgent 仓库中的真实做法
当前 OncallAgent 仓库在根目录维护了一份 AGENTS.md，且暂时没有更深层的同名文件，因此它对整个仓库生效。文件不是泛泛介绍产品，而是围绕 Codex 实际开发时最容易出错的地方组织内容。
首先，它定义了项目事实来源：已经生效的行为查看 openspec/specs/，正在推进的变更查看 openspec/changes/[change]/，HTTP 与 SSE 协议查看 packages/api-contracts/，最后再由实现和测试确认当前真实行为。归档目录只用于追溯，不继续在历史变更上开发。
📷 [图片 token=Ux4Mbn6rDoGsmoxbKObczIzrnc5（未能下载，见飞书原文）]
其次，它说明了真实仓库结构和技术边界。例如前端采用 Vue 3、Vite、TypeScript、Pinia 与 Vue Router；后端采用 FastAPI、LangChain/LangGraph、SQLAlchemy/Alembic 和 uv；后端源码使用 src layout，内部 Python 包名是 super_ai，导入时不能写成 src.super_ai。
📷 [图片 token=MnVebzy1WoNbr3xR8s1cOXOHn6c（未能下载，见飞书原文）]
更重要的是，它把容易造成严重错误的约束写成了明确规则：共享契约是前后端协议的唯一事实来源；所有用户数据都必须携带 owner 或 tenant 范围；Milvus 只能保存知识 chunk 向量；MCP 只能装配真实发现且已启用的用户工具；诊断证据不足时必须说明不确定性，不能虚构日志、根因或执行成功状态。
📷 [图片 token=NkjVbooUGokzJyx6lZ9cnh59nGf（未能下载，见飞书原文）]
最后，它给出了可以运行的质量门禁，例如共享契约类型检查、前端类型检查和测试、后端 Ruff、Pyright、Pytest、Alembic 升级验证、OpenSpec 全量校验以及文档构建。Codex 因此不仅知道“要测试”，还知道不同改动应该运行哪一组命令。
📷 [图片 token=GE4qbPzInoAIiFx00BBcBBi9nAc（未能下载，见飞书原文）]
有了 AGENTS.md 后应该怎样使用
创建初始文件。 可以在 Codex CLI 中使用 /init 生成一个起步版本，也可以手动在仓库根目录创建。自动生成的内容只是骨架，必须根据真实代码、命令和团队规则调整，不能未经核对直接提交。
从仓库根目录启动 Codex。 这样 Codex 能识别正确的项目根和根级规则。如果只在某个子目录启动，也应确认向上查找后得到的是预期仓库，而不是另一个父目录。
正常描述本次任务。 不需要在每条消息里再次粘贴技术栈和测试命令。提示词重点描述本次目标、背景和特殊限制，长期规则由 AGENTS.md 提供。
让 Codex 先核对事实。 对非平凡任务，可以直接要求它说明当前适用的指令、相关 OpenSpec、可能影响的模块和准备运行的验证，再开始写代码。
根据重复错误持续更新。 如果 Codex 多次采用错误包管理器、漏掉租户过滤或遗漏某类测试，就把经过团队确认的纠正写进最接近适用范围的 AGENTS.md。一次偶发误解不必立刻增加规则，重复出现的问题才值得长期固化。
把文件纳入代码审查。 AGENTS.md 会影响以后所有 Agent 任务，因此它的修改应像构建脚本和工程配置一样接受审查。新增规则要说明它解决了什么反复发生的问题，删除规则要确认仓库行为已经变化。
📷 [图片 token=FRdybXYkqoEvTKxGy6fcfD4QnTb（未能下载，见飞书原文）]
可以使用以下命令检查 Codex 是否读取了预期规则：
codex --ask-for-approval never "Summarize the current instructions."
如果仓库未来新增了后端专用规则，还可以从子目录验证：
codex --cd apps/backend --ask-for-approval never "Show which instruction files are active."
这里的 apps/backend/AGENTS.md 只是说明分层方式的假设示例。当前 OncallAgent 仓库只有根目录文件，不应把尚未创建的子目录规则描述成现有实现。
📷 [图片 token=NkmWbdd8Yoaqexxn75QcOTnFnbh（未能下载，见飞书原文）]
AGENTS.md 与 OpenSpec 怎样分工
| 载体 | 主要回答的问题 | 适合保存的内容 | 生命周期 |
|---|---|---|---|
| 当前提示词 | 这一次希望完成什么 | 当前目标、背景、特殊限制和期望输出 | 一次任务或一次会话 |
AGENTS.md | 在这个仓库里应该怎样工作 | 工程规则、目录路由、命令、安全边界和完成定义 | 长期存在，随仓库演进 |
| OpenSpec | 某个功能为什么改、要怎样变化 | Proposal、Design、Tasks、规格增量和验收场景 | 从变更提出到归档，并沉淀进主规格 |
| 契约、实现与测试 | 系统实际上怎样运行 | 可执行代码、协议定义、迁移和验证证据 | 与产品实现持续同步 |
📷 [图片 token=HW3qbdOyCoU5LFx7uVVcGy5lnme（未能下载，见飞书原文）]
一个典型流程是：Codex 先通过 AGENTS.md 理解长期规则，再根据用户需求读取或创建相关 OpenSpec change，然后按照 Tasks 修改契约、实现和测试，最后运行 AGENTS.md 中规定的质量门禁并验证规格一致性。
两者不能相互替代。如果只写 OpenSpec 而没有仓库规则，Codex 知道要做什么，却可能使用错误的实现方式；如果只有 AGENTS.md 而没有变更规格，Codex 知道怎样写代码，却仍然不清楚这次功能的边界和验收条件。
它能带来哪些实际好处
减少重复上下文。 开发者不必在每个任务中重新粘贴目录、命令和基础约束，可以把注意力放在本次需求真正特殊的地方。
让不同会话更一致。 团队成员、本地 Codex 和后续会话共享同一套仓库规则，减少因为个人提示词差异造成的实现分叉。
更早阻止错误方向。 当包管理器、导入方式、契约来源和数据边界在行动前已经明确，Agent 更不容易先生成大量错误代码，再通过返工纠正。
提升验证可信度。 明确命令和完成定义后，Codex 更容易报告真实运行过的测试，也更难把“看起来正确”误写成“已经验证通过”。
沉淀团队反馈。 反复出现的代码审查意见可以转化为长期规则，使同类问题在下一次任务开始前就进入上下文。
形成安全护栏。 凭据、日志脱敏、tenant 隔离、真实工具调用和证据不足处理等约束，可以贯穿多个功能变更，而不依赖开发者每次临时提醒。
📷 [图片 token=Znqab2bNTo22w7xxuN5cz2QSn0g（未能下载，见飞书原文）]
这些收益不应被包装成无法验证的效率百分比。AGENTS.md 提供的是更稳定的执行边界，真正的质量仍然需要代码审查、测试、类型检查、权限机制和运行时验证共同保证。
📷 [图片 token=Bn8PbIF4go2Swvx0sKOcSyUrnBK（未能下载，见飞书原文）]
怎样维护才不会逐渐失效
维护 AGENTS.md 的关键不是一次写得很长，而是持续保持准确。仓库目录、依赖管理、启动方式或测试命令变化时，应同步更新；团队重复留下同一种 PR 反馈时，可以评估是否固化；某条规则已经被 lint、hook 或权限系统可靠执行后，可以把文件中的文字压缩为验证入口。
每隔一段时间可以做一次小型审计：命令是否还能运行，路径是否真实存在，禁止项是否仍符合架构，OpenSpec 和共享契约的事实来源是否改变，是否出现互相冲突的规则，以及文件是否接近加载大小上限。
根文件应尽量保存全仓库共同规则。只有当某个子目录确实拥有不同语言、命令或风险边界时，才增加嵌套文件。规则下沉得太细会提高维护成本，也可能让开发者难以判断当前到底应用了哪一层。
📷 [图片 token=NlQpbOqMnoVxiIxl99wcqgvmnre（未能下载，见飞书原文）]
可以直接修改使用的基础模板
下面的模板强调结构而不是篇幅。使用时应删除不适用的章节，并把所有示例命令替换成项目中真实可运行的命令。
# 项目仓库指南
## 适用范围
本文件适用于整个仓库。
若子目录存在更具体的 AGENTS.md，以离目标文件最近的规则为准。
用一段话说明项目定位、当前状态和修改时最重要的前提。
## 事实来源
- 产品与工程主规格：specs/
- 活动变更：changes/
- 共享契约：packages/contracts/
- 当前行为：实现与测试
说明发生冲突时的判断顺序，以及历史归档是否允许继续修改。
## 仓库结构
- apps/backend：后端应用及测试
- apps/frontend：前端应用及测试
- packages：共享包与协议
- docs：用户文档和工程文档
只保留能帮助 Agent 正确定位代码的重要目录。
## 标准工作流
1. 修改前检查工作区、相关规格、实现和测试。
2. 明确影响范围，避免顺手修改无关文件。
3. 行为变化先更新规格或创建变更记录。
4. 同步实现、契约、迁移、测试和文档。
5. 运行与影响范围匹配的验证。
6. 交付前检查 diff 和工作区状态。
## 常用命令
安装：
- 项目真实安装命令
检查：
- 格式检查命令
- 类型检查命令
- 单元测试命令
- 构建命令
注明每条命令应该在哪个目录运行。
## 代码约定
- 语言版本和包管理器
- 模块导入与目录边界
- API、服务、Repository 的职责
- 前端状态和传输层约定
- 数据库迁移要求
## 配置与安全
- 配置文件入口和覆盖顺序
- 凭据与本地配置的禁止提交规则
- 日志和错误脱敏要求
- 权限、用户和 tenant 数据边界
- 外部工具调用的真实性要求
## 测试与交付
- 不同变更类型必须运行哪些检查
- 什么情况需要迁移、截图或联调
- 只能报告真实执行并通过的验证
- 提交信息和 PR 说明要求
📷 [图片 token=Y8pIbxcjWoWSiRxmay2c86Wnn9e（未能下载，见飞书原文）]
AGENTS.md 最有价值的地方，不是让提示词变得更长，而是让那些已经验证有效的工程经验不再依赖某个人记住。它把仓库结构、开发纪律和安全边界变成 Codex 每次开始工作前都能获得的共同上下文；OpenSpec 再在这套长期规则之上，描述每一次具体变更。两者配合后，AI Coding 才从一次性的对话技巧，逐渐变成可以复用、检查和维护的工程流程。
📷 [图片 token=IhYAbSQcpoF3v3xzSgjcqx8Un2g（未能下载，见飞书原文）]