Codex AGENTS.md 怎么写：读取规则与三个完整示例

以下信息核对于 2026 年 10 月 24 日，Codex 的功能可能随官方更新而变化

一份有用的 Codex AGENTS.md，要让它进项目后知道去哪里改、怎样验证、做到哪一步停。 文件名写对只是开始；里面的路径和命令要是真的，规则之间也要能同时成立。

如果你每次都在重复“这里用 npm”“只改源文件”“先做预览”，这些稳定要求就适合写进去。当天要修哪个问题、这次要改哪张页面，仍放在当前任务里，别把每次聊天都追加成永久规则。

AGENTS.md 是什么，和 README 分别写什么

AGENTS.md 是给编码助手的项目工作说明。Codex 会按官方约定寻找它，并把找到的内容作为任务上下文中的指令使用。官方说明：发现与合并规则。

README 常见的用途是向人介绍项目：解决什么问题、怎样安装、如何启动、有哪些主要功能。AGENTS.md 更适合回答执行时的问题：页面改哪个目录，生成文件能不能手动动，提交前运行哪些检查，遇到失败怎样报告。

两者可以互相引用。比如安装步骤已经在 README 维护，AGENTS.md 写清“依赖初始化按 README 的本地开发章节执行”，再补充本项目的测试要求，就比复制两套安装步骤好维护。

README 不在默认自动发现的文件名列表里。 这不等于 Codex 不能读它：你可以在任务中要求读取，也可以在 AGENTS.md 里指向具体章节。配置备用文件名是另一条路，但要明白你改变了项目指令的发现方式。

一个很常见的场景是：README 介绍的是整个产品，而你只让 Codex 改一个按钮。它真正需要的通常是前端目录、样式约定、这类改动的检查方式，不是产品从创立到现在的全部背景。

下面三个示例都是为说明写法设计的假设项目，不是现成仓库的审计结果。示例中的脚本都以相应项目确实提供该命令为前提，迁移前要核对自己的 package.json、目录和持续集成配置。

Codex 按什么顺序读取规则

按官方 AGENTS.md 专页，Codex 在运行开始时构建一次指令链；终端交互界面通常是在启动会话时构建。理解它的读取顺序，比反复给同一个文件加醒目标题更有用。

没有找到项目根目录时，官方说明是在当前目录查找。项目里的空文件会被跳过；存在一个文件名，并不等于它一定提供了有效规则。

同目录替换和下层覆盖，区别在哪里

假设仓库根目录的 AGENTS.md 写着“执行检查后，报告修改文件和验证结果”，apps/web/AGENTS.md 写着“前端样式使用现有 CSS 变量”。从 apps/web 启动时，这两条可以同时成立，没有理由丢掉根目录的汇报要求。

如果根目录写“测试用根目录统一脚本”，而当前子目录明确写“本目录使用独立测试入口”，后者会成为这部分工作的更具体要求。团队最好把这种例外写成“本目录覆盖根目录的哪一条”，让人和助手都能追踪原因。

同目录的 override 是另一回事。在 apps/web 同时放 AGENTS.override.md 和 AGENTS.md，Codex 优先选择前者；不是先读普通文件，再把 override 当成补丁。需要保留的本目录规则应在选中的文件中交代清楚。

从根目录启动，不代表所有子目录说明都读进来了

默认发现路径是项目根目录到当前工作目录。从仓库根目录启动时，不应假设 apps/web、apps/api、packages/ui 中的说明都已自动预载。

如果任务明确只做一个子项目，可以把启动目录放到相应目录，再检查指令来源。若已经从根目录开始处理跨目录任务，则在任务或根规则里明确要求修改前读取对应子目录说明，并核对执行结果。

不要把“这个文件就在仓库里”当作“本次会话已经读到了”。这也是为什么把当前目录写进诊断记录，比盲目增加规则重复次数更有效。

长度限制、备用文件名与重新加载

读取受 project_doc_max_bytes 限制，AGENTS.md 专页列出的默认值为 32 KiB，并按合并指令预算描述。它是字节限制，不能直接换算成固定汉字数量；关键操作规则应放在前面。

如果团队原来用 TEAM_GUIDE.md 之类的文件，官方支持通过 project_doc_fallback_filenames 配置备用名称。它们在默认文件名之后按配置顺序检查，并不会因为名字像说明文档就自动生效。相关配置。

修改配置或指令后，用新会话、新命令重新检查。已经打开的长会话里还保留旧规则时，继续追加“我刚改了，请再看一次”容易把新旧要求混在一起。

内容怎么取舍：写六类能执行的信息

先列项目结构，只保留会影响这次定位的目录。比如“路由在 src/routes，业务逻辑在 src/services，测试在 tests”，比逐行抄一遍完整文件树更有用；自动生成目录还要注明源头在哪。

再写构建和测试命令，包括从哪个目录执行、需要什么先决条件。命令失败时也要有下一步：保留错误、区分环境缺失和代码失败，不能把“没跑起来”写成“验证通过”。

代码风格优先指向已有工具和临近实现。项目已有格式化器，就写清对应命令；现有模块已经有错误处理方式，就要求沿用，并在确实需要改变时说明理由。单独写“代码优雅”没有验收标准。

禁止事项后面接可行替代路径。例如生成文件不手改，就说明应该改模板并重新构建；生产不能直接写，就说明先生成候选和差异，交给有权限的人执行既定入口。

发布部分要写真实流程和停止点。写清“本任务只做本地候选”或者“满足哪些检查后才交接”，比孤零零的“谨慎操作”更容易执行。这些文字是行为要求，技术上的访问限制还要靠沙箱、权限和审批。

最后写交付结果：改了哪些文件，执行了什么检查，哪些没完成。这里不需要长篇工作日志；审阅者要能据此判断改动是否满足任务，以及接手后还有什么要做。

示例一：Node 项目，把可执行命令写明白

假设这是一个使用 npm 的 TypeScript 服务，根目录的 package.json 已有 lint、typecheck、test 和 build 四个脚本。下面是一份完整的根目录 AGENTS.md；若你的脚本名称不同，应换成仓库真实入口。

# 项目工作说明

## 目录
- src/routes/：HTTP 路由与输入校验。
- src/services/：业务逻辑。
- tests/：自动化测试，测试用本地替身，不访问生产服务。
- dist/：构建产物；修改 src/ 后重新构建，不手工修改。

## 开始前
- 阅读 README 的本地开发章节和 package.json。
- 确认任务涉及的路由、服务和对应测试，再开始修改。
- 使用 npm；依赖变更同时维护 package-lock.json。

## 检查命令
- 从仓库根目录执行 npm run lint 和 npm run typecheck。
- 改动业务行为时执行 npm test，并说明覆盖了哪些相关情况。
- 交付前执行 npm run build。
- 检查失败时记录命令和关键错误；环境不满足时说明缺少什么。

## 实现约定
- 沿用相邻模块的返回格式与异常处理方式。
- 对外接口变化先说明调用方影响，再更新实现与相关测试。
- 与任务无关的格式调整不放进本次修改。

## 凭据与发布
- 文档只记录环境变量名，真实值由授权环境提供。
- 缺少凭据时报告缺项，不输出真实值，不写入仓库。
- 发布步骤见 docs/release.md；本地验证完成后提交交接说明。
- 本任务不执行生产发布。

## 交付
- 列出行为变化、修改文件、验证结果和仍未解决的问题。

目录段先把路由和业务逻辑分开，是为了让助手有定位依据。说明 dist 的生成关系，则是在告诉它正确修改入口；否则它可能修好了构建产物，下次构建又把改动覆盖掉。

检查段把命令和触发条件放在一起。改行为就解释测试覆盖，构建失败就保留错误，这样审阅者看到的不是笼统的“已经测试”，而是能复核的结果。

发布段只指向文档，不把部署命令顺手塞进普通开发任务。它同时明确当前停止点，适合开发者先完成修复、发布负责人再接手的工作方式。

示例二：静态网站，划清源文件和输出目录

假设网站用 Markdown 和模板生成静态 HTML，仓库提供构建、链接检查和本地预览命令。这个例子关心的是内容是否只改到授权页面，以及生成结果是否能正确打开。

# 静态站点工作说明

## 文件来源
- content/：文章 Markdown。
- templates/：页面模板。
- public/assets/：共享图片与样式源文件。
- out/：构建输出，只通过构建生成。
- 构建过程与页面元数据字段见 docs/content.md。

## 修改范围
- 写文章时只新增本次文章及明确要求变更的列表、站点地图条目。
- 未获任务授权，不改旧文章标题、正文和更新时间。
- 需要共享模板改动时，先说明受影响页面，再按确认范围处理。
- 图片使用本地已有或明确获准新增的素材，不编写用户评价。

## 验证
- 从仓库根目录执行 npm run build。
- 执行 npm run check:links，确认内部链接和页面锚点可达。
- 执行 npm run preview，在浏览器检查本次页面和共享组件。
- 记录浏览器错误及检查结果，不把错误隐藏后当作通过。

## 交接和发布
- 比较生成结果与指定基底，列出新增及修改文件。
- 保留正文、模板和生成文件的对应关系。
- 生产发布只按 docs/publishing.md 的公共入口执行。
- 当前任务只输出本地候选、差异和验证报告，到这里停止。

这个示例没有把“改一篇文章”解释成“顺手整理整个网站”。对于已有搜索流量的站点，标题、更新时间和列表顺序都是实际内容变化，应当出现在授权范围里。

链接检查与浏览器检查解决的问题也不同。一个路径能返回页面，仍可能有排版溢出、组件打不开或资源加载错误，所以写清两类验证各看什么，比一句“检查网站正常”更具体。

如果你的静态站点根本不用 Node，就把这些 npm 命令换成真实构建器入口。复制示例后保留不存在的脚本，会把“工作说明”变成第一次运行就报错的障碍。

示例三：多人协作，根目录管共用要求，子目录管差异

假设同一仓库有前端和接口两个子项目，团队已提供对应 npm workspace 脚本。根目录保存以下完整文件，前端目录再加一份范围更小的说明。

# 团队共用规则

## 结构和任务边界
- apps/web/：前端页面。
- apps/api/：接口服务。
- packages/contracts/：前后端共用接口定义。
- 修改某个目录前，读取该目录的工作说明。
- 开始时确认本次修改范围；交付前重新检查差异。

## 协作
- 工作区已有未提交改动时，先区分本次任务与他人的修改。
- 不覆盖他人的改动；发生同文件冲突时说明冲突位置并协调。
- 共用接口变化需要同时说明前端和接口服务的影响。
- 当前任务不擅自创建其他人的任务，也不替其他人提交改动。

## 共用验证
- 使用根目录锁文件和 npm workspace 命令。
- 接口服务改动执行 npm run test --workspace apps/api。
- 共用接口定义变化要检查两个调用侧。
- 子目录文件补充本目录专用检查，不免除共用接口检查。

## 发布与汇报
- 发布流程见 docs/release.md，当前任务只完成开发与交接。
- 交付列出修改范围、验证、冲突和后续依赖。

apps/web/AGENTS.md 的完整内容可以是：

# 前端补充说明

## 实现
- 页面入口在 src/pages/，公共组件在 src/components/。
- 使用现有设计变量和组件，新增交互先检查键盘操作。
- 不修改 apps/api/ 的内部实现；如有依赖，写入交接说明。

## 本目录检查
- 从仓库根目录执行 npm run lint --workspace apps/web。
- 执行 npm run test --workspace apps/web。
- 执行 npm run build --workspace apps/web。
- 界面变化还需检查桌面和窄屏显示，记录结果。

## 共用接口
- 如果修改 packages/contracts/，仍按根目录要求检查两个调用侧。

分层的目的，是让前端读到前端的检查入口，让接口服务读到自己的要求。把所有模块的长命令集中塞进根文件，往往更难判断本次究竟需要跑哪一组。

“不覆盖他人的修改”也需要配套动作：开始时看差异，结束时再核对。单写一句“注意多人协作”无法说明同一个文件已经有人编辑时该怎样处理。

这里的目录边界是团队约定，不是文件隔离机制。若需要让前端任务技术上无法写接口目录，应另外配置实际访问权限，不能只靠 AGENTS.md 的一句话。

常见错误：把含糊要求改成能检查的动作

一、把全部历史都塞进去

改写前：“项目先后经历过多次目录调整，旧脚本以前用于发布，现在可能还有几个地方保留；以前还讨论过另一套测试方案……”

改写后：“当前源文件在 content/，构建命令为 npm run build；旧版迁移记录见 docs/history.md，仅在处理兼容问题时查阅。”

历史并非没有价值，只是大部分日常任务不需要重复读。保留现状、入口和何时查历史，能减少过期说明与有效规则混在一起的机会。

二、两条规则给出相反命令

改写前：“统一使用 npm。前端一律使用 pnpm。”如果没有范围说明，处理前端时就得猜哪条仍有效。

改写后：“本仓库统一使用 npm workspace 和根目录锁文件；所有子项目命令从根目录执行。”如果项目确实有例外，就把例外目录、原因和锁文件位置单独写清。

冲突不该靠把其中一条加粗来解决。维护者应选定真实流程，删掉失效规则，再检查各层文件是否仍引用旧入口。

三、只说不能改，没说该去哪改

改写前：“不要修改 out，不要动生成文件，不要破坏页面。”这能表达担心，却没有提供完成任务的路径。

改写后：“文章修改 content/，布局修改 templates/，执行构建生成 out/；对照任务范围检查输出差异。”

同样是限制，后者给出了可执行方案。助手发现问题落在生成文件里时，就知道应追溯源文件，而不是在几条禁令之间反复停住。

四、把凭据复制进项目说明

改写前：“生产 API 密钥直接放在下面，遇到连接问题可以复制使用。”即便仓库暂时只有几个人能看，这种写法也扩大了凭据出现的位置。

改写后：“连接需要 SERVICE_API_TOKEN，由授权的密钥管理方式提供；缺失时报告缺项，文档、日志和提交中都不记录真实值。”

OpenAI 的安全文档以遥测令牌为例，要求通过批准的密钥管理器或进程环境提供令牌，并使真实值远离部署配置文件与源码管理。这里沿用的是这一处理原则，而不是要求所有项目使用同一种密钥产品。

五、把文字规则当成权限开关

改写前：“已经写了禁止生产发布，所以这个任务不可能访问生产。”这句话把行为要求误当成了技术保证。

改写后：“当前任务只交付本地候选；生产访问由实际权限、沙箱及审批控制，发布按既定入口完成。”

官方安全文档区分了沙箱能做什么，以及审批策略何时需要确认。AGENTS.md 可以描述流程，却不能替你建立这些控制，也不应让它推翻更高层的访问限制。

六、要求测试，却不给失败的出口

改写前：“所有检查必须通过才能结束。”如果环境缺少依赖，这条规则可能诱发不断重试，也容易让交付记录掩盖真正阻塞点。

改写后：“执行规定检查；失败时保留命令、错误和已尝试的相关修复。环境不满足时说明未验证项，交付时不得把它标为通过。”

对小改动，也应说明哪些检查与行为有关。目标是得到可审阅的证据，不是让每次修一个标点都机械执行同一套漫长流程。

写完怎样确认它真的生效

先检查文件名、存放位置和当前工作目录。有 override 时看选中的是哪份；使用备用文件名时，核对配置顺序。比起怀疑模型“突然不听话”，这些都是可以直接检查的原因。

接着从实际准备工作的目录启动新会话，让 Codex 列出读到的指令来源并概括适用规则。下面是检查思路，路径应换成你的真实仓库：

codex --cd /path/to/repo/apps/web "列出本次加载的项目指令来源，并概括测试和发布要求。先不要修改文件。"

官方文档提供了用提示词核对来源、通过 --cd 检查子目录规则的方式。回复是排查线索，还需要和磁盘上的文件内容对照，尤其是有多层覆盖和备用文件名的项目。

然后选一个小而真实的任务验收，比如仅改一条提示文案，观察它是否修改源文件、执行相关检查、避免无关格式调整，并在预定位置停止。这样的试跑比单问“你理解了吗”更能暴露规则缺口。

如果结果不对，改最接近问题的一条规则。读错目录就补目录映射，执行不存在的脚本就修命令，越过交接边界就明确停止点；别为一个问题再追加几十条重复提醒。

它为什么可能省额度，又不能保证省多少

假设任务是修前端校验。规则没写清，助手可能先去找后端实现，执行不存在的脚本，再回头确认项目用哪个包管理器；每一步都需要读取、判断和反馈。

把真实入口与检查方式写清，这些无效尝试就有机会减少。对经常重复处理同一仓库的团队，价值还在于少解释一次“我们这里一直怎样做”，让任务更早进入实际修改。

但代码理解、实现和验证本身仍有成本，AGENTS.md 也需要进入上下文。把所有文档整本拼进去，不等于效果更好；任务相关、没有重复、能执行的要求才有帮助。

你可以记录试跑中有没有找错路径、命令错误和无关改动，用这些现象判断规则是否变好。没有对照证据，就不要把额度下降归因于某一段提示词，更别给出固定节省比例。

需要看五小时窗口和每周重置，直接读Codex 额度重置说明；模型和推理强度的选择见Codex 模型参数解读。这两个问题和项目规则有关联，但分别有自己的判断依据。

如果你还在准备订阅，可以从 AIPlusGate 的ChatGPT Plus 开通说明了解办理步骤。已经能运行 Codex，就先用一个真实小任务检验这份 AGENTS.md：路径对不对、命令能不能跑、交付能不能复核，都比继续堆规则更有用。

核对来源

以下页面均于 2026-10-24 查看。示例目录、脚本和改写对比为本文设计，用于演示组织方法，不是官方规定的项目结构，也不是对真实项目测试成功的声明。

1. OpenAI：Custom instructions with AGENTS.md。对应全局与项目发现顺序、每目录至多一份、override 选择、路径合并、当前工作目录边界、32 KiB 默认预算、备用文件名和重新启动后的核对方法。README 不属于默认发现文件名的判断也依据该列表。
2. OpenAI：Codex prompting guide — Using agents.md。对应全局先于仓库、目录由浅到深，以及指令内容进入模型上下文；与发现专页交叉核对。
3. OpenAI：Advanced configuration。对应 project_doc_max_bytes 和 project_doc_fallback_filenames 配置项。读取链和合并预算的具体解释按 AGENTS.md 专页；不要把字节预算理解成固定字数。
4. OpenAI：Sandbox and approvals。对应技术访问限制与审批策略的区别，支持“指令文件不能替代实际权限控制”的边界说明。
5. OpenAI：Security cookbook — Monitor Codex activity。对应通过批准的密钥管理方式提供令牌、避免把真实值写入部署配置及源码管理的原则；文中的项目变量名只是示意。