Codex AGENTS.md怎么写？项目规则、命令、目录边界与分层配置教程【2026年7月】

文章更新时间：2026年7月20日

Codex AGENTS.md可以理解为写给编码智能体的项目协作说明书，用来保存那些每次进入仓库都要重复交代的稳定约定，例如技术栈、常用命令、禁止修改目录、测试方式和交付前检查。本教程站只提供文字教程与写法参考，不提供与Codex对话、读取本地文件、代替执行命令或托管仓库的功能；涉及官方入口、下载、登录、模型和具体功能时，均应以当前官方页面或实际页面显示为准。

开发工具测试建议

zeogpt.com：适合先用脱敏的小任务做代码解释、只读分析和 Diff 审查。
zeoapi.com：适合开发者用公开或脱敏样本做多模型 API 原型测试。

以上均为第三方服务，不是 OpenAI 或 Anthropic 官方产品。不要提交 API Key、.env、生产日志、私有仓库或其他敏感数据。

AGENTS.md解决什么问题，以及什么内容不应该写进去

AGENTS.md的核心价值，是把稳定、可复用、与项目强相关的工作约定沉淀下来，让Codex进入仓库后先理解这个项目怎样构建、怎样测试、哪些地方不能碰、交付前必须确认什么。它适合解决反复沟通成本高的问题：同一个开发者每天都要解释包管理器、单元测试命令、数据库迁移限制、生成文件不可手改，团队成员之间也容易因为口头约定不一致而让智能体走偏。把这些规则写进文件后，后续任务可以围绕明确边界展开，减少临时提示遗漏。

但AGENTS.md不是万能知识库，也不应该成为项目所有文档的复制品。它不适合放业务长文、历史会议纪要、密钥、账号、一次性需求、未确认的实验命令、含糊的价值判断或只对某个人有效的偏好。更重要的是，不要把它当成绕过人工审查的许可文件；它只能提供规则和上下文，不能替代开发者判断。写得越长不一定越好，越具体、越可验证、越接近实际开发流程，才越容易被正确执行。

如果你的痛点是每次都要说这是pnpm项目、后端在server目录、不要改生成的schema文件、提交前要跑测试，那么这些正是适合放入AGENTS.md的内容。如果你的内容是本周临时活动文案、某次排查过程、尚未合并的个人想法，通常更适合放在任务提示、Issue或项目文档中。判断标准很简单：下个月新任务开始时仍然有效，并且影响Codex如何修改代码，就值得写进去。

写稳定规则，不写一次性需求
写可执行命令，不写无法验证的口号
写目录边界，不写密钥和账号
写交付检查，不替代人工审查
写项目差异，不复制整本文档

先收集技术栈、常用命令、目录结构和验收规则

开始编写AGENTS.md前，不建议直接凭记忆下笔，而应先收集项目中真正会影响修改行为的信息。第一类是技术栈，例如前端框架、后端语言、包管理器、测试框架、格式化工具、数据库迁移方式和运行环境约束。第二类是命令，例如安装依赖、启动开发服务、运行单测、运行集成测试、类型检查、构建、格式化和静态检查。第三类是目录结构，例如源码、测试、文档、脚本、配置、生成物、第三方拷贝文件分别放在哪里。

第四类是验收规则，它决定Codex完成修改后怎样证明工作可交付。验收规则不应只写改完请测试，而应写清楚在什么场景下跑哪些命令，若命令耗时或依赖外部服务，应该如何说明未执行原因。还要收集团队对变更范围的要求，例如是否允许顺手重构、是否必须保持公共API兼容、是否禁止修改锁文件、是否需要同步更新测试和文档。收集过程本身也能帮助团队发现命令过期、文档散乱、目录边界不清的问题。

一个实用做法是先让开发者列出过去十次让Codex进入仓库时反复补充的话，然后把其中稳定的部分归类。凡是出现三次以上、每次都影响执行结果的内容，优先进入AGENTS.md；只出现一次或高度依赖当前任务的内容，保留在临时提示中。这样写出来的文件不会像百科，也不会缺少关键约束。

确认包管理器和运行时版本要求
列出最常用且当前有效的验证命令
标注源码、测试、文档、脚本和生成物目录
记录修改后必须同步更新的文件类型
区分长期规则与一次性任务说明

项目级规则如何写得短、明确且可验证

项目级AGENTS.md最重要的写法原则是短、明确、可验证。短不是信息少，而是只保留会影响Codex行为的规则；明确是避免让模型猜测，例如不要写注意代码质量，而要写修改TypeScript后运行类型检查，修改接口后更新对应测试；可验证是让每条规则尽量能被命令、文件变化或审查动作确认。这样的规则对开发者和智能体都友好，出现问题时也容易定位是哪条约定失效。

推荐把内容分成项目概览、常用命令、目录边界、编码约定、测试要求、交付前检查几个小块。每一块保持句子直接，少用抽象口号。比如不要写遵循最佳实践，而写新增React组件时放入src/components并补充相邻测试；不要写不要破坏构建，而写提交前至少运行pnpm test和pnpm build，如因环境缺失无法运行，需要在回复中说明原因。规则越接近日常动作，越容易形成稳定执行。

项目级规则还应避免把所有例外都塞进去。例外过多会让文件变成难以维护的流程手册，也会增加误读概率。更好的方式是把高频、稳定、全仓库适用的内容放在根目录AGENTS.md，把局部目录的特殊约定放到更靠近代码的子目录AGENTS.md，把临时例外写在当前任务提示中。这样既能保留上下文，又不会让全局规则膨胀。

每条规则尽量对应一个动作或检查
用具体命令替代泛泛提醒
避免把README全文复制进来
只写长期有效的项目约定
把局部例外下沉到子目录规则

目录边界、敏感文件和禁止操作如何表达

目录边界要写得像权限说明，而不是模糊提醒。可以明确哪些目录是主要修改区域，哪些目录只读，哪些目录原则上禁止修改，哪些目录只有在任务明确要求时才能改。例如源码目录可以正常修改，迁移脚本需要谨慎追加，生成目录不可手工编辑，部署配置必须先征得确认。这样的表达能让Codex在跨文件修改时更稳妥，也能减少顺手改动配置、样式产物或历史迁移文件的风险。

敏感文件和禁止操作尤其需要直白。AGENTS.md中不应写入任何密钥、令牌、私有账号、内部地址或可复用凭据；如果需要提醒，可以写不要读取、打印、提交或修改.env、密钥文件、证书和本地配置。禁止操作还应覆盖数据库清空、生产脚本执行、删除迁移、重写提交历史、批量格式化全仓库、改动锁文件等高风险行为。注意，这些文字不是系统权限控制，开发者仍需通过代码审查、权限隔离和实际工具配置来配合。

表达目录边界时，建议同时说明原因和替代路径。例如dist为构建产物，不要直接修改，如需改变输出请修改src中的源文件；openapi生成文件不要手改，如需更新请修改接口定义并运行生成命令。带原因的规则更不容易被误判为任意禁令，也方便新人理解项目维护方式。

标明可改、谨慎改、禁止改的目录
不要在文件中保存任何敏感凭据
禁止执行破坏性数据库或部署操作
生成文件应说明来源和更新方式
高风险改动要求先得到明确确认

临时提示、AGENTS.md、项目配置和自动化规则对比表

很多开发者会把临时提示、AGENTS.md、项目配置和自动化规则混在一起，导致规则难维护。临时提示适合描述当前任务目标，例如修复某个按钮的异常状态；AGENTS.md适合保存跨任务复用的项目协作约定；项目配置适合被工具直接读取，例如测试框架、格式化器、构建器的配置；自动化规则适合在持续集成或提交钩子中强制执行。四者配合使用，才能既有上下文，又有真实校验。

一个判断方法是看这条信息由谁消费、是否需要机器强制、变化频率多高。如果信息主要给Codex理解，长期稳定，就放AGENTS.md；如果信息必须由工具准确执行，就放配置文件或脚本；如果信息只对本次需求有效，就放临时提示；如果信息属于交付门禁，就放自动化流程中。AGENTS.md不应承载所有责任，它更像协作说明，而不是构建系统、测试系统或权限系统。

对团队来说，最好的组合是AGENTS.md写清要做什么和不要做什么，package脚本或Makefile提供可运行入口，持续集成负责最终验证，代码审查处理业务判断。这样即使Codex没有完全执行某条建议，流程也能在后续环节发现问题。

类型	适合内容	不适合内容
临时提示	本次要修的缺陷、目标文件、特殊验收点	长期技术栈说明和全仓库固定规则
AGENTS.md	包管理器、测试命令、目录边界、交付检查	密钥、账号、一次性需求、冗长业务资料
项目配置	格式化、构建、测试、类型检查的工具参数	面向人阅读的协作背景和例外说明
自动化规则	持续集成门禁、提交前检查、可重复验证脚本	需要人工判断的产品取舍和临时讨论

临时提示解决当前任务上下文
AGENTS.md沉淀长期项目规则
项目配置交给工具直接读取
自动化规则负责强制验证
不要让单一文件承担全部流程

分层规则与子目录约定应如何避免冲突

大型仓库往往不是单一技术栈，根目录可能包含前端、后端、移动端、文档站和基础设施脚本。此时只写一个根目录AGENTS.md容易过宽，所有规则都堆在一起会产生冲突。更稳妥的做法是根目录写全仓库通用原则，例如禁止提交密钥、交付前说明验证情况、不要修改生成物；在frontend、server、docs等子目录中再写局部规则，例如各自的包管理器、测试命令、代码风格和目录边界。

分层规则的关键是职责清楚。根规则负责全局底线，子目录规则负责局部细节；子目录规则不应随意推翻根目录的安全要求，根目录也不应写过多只适用于某个模块的命令。若确实存在例外，应在子目录中清楚说明适用范围和原因，例如仅在docs目录允许修改生成的搜索索引，或仅在server目录的迁移文件中允许追加新版本脚本。避免冲突的本质，是让每条规则都有明确作用域。

维护分层配置时，要定期检查规则是否重复或矛盾。常见矛盾包括根目录要求使用npm，子目录实际使用pnpm；根目录要求全仓库格式化，子项目却有不同格式化标准；根目录禁止改锁文件，但子项目升级依赖必须更新锁文件。遇到这种情况，不要让Codex自行猜测，应由维护者统一改写为有条件的规则。

根目录写全仓库底线和通用流程
子目录写局部技术栈和命令
例外必须说明作用域和原因
安全规则不要被局部规则随意覆盖
定期清理重复和冲突条目

构建、测试、格式化和代码审查要求如何落地

验证要求写进AGENTS.md时，最常见的问题是只有愿望，没有落地动作。建议把构建、测试、格式化、静态检查和代码审查拆开描述，并说明在不同改动类型下应执行哪些命令。比如修改前端组件要运行对应测试和类型检查，修改公共工具函数要运行单元测试，修改构建配置要运行完整构建，修改API契约要同步更新调用方测试。这样Codex在完成任务时更容易选择合适的验证路径。

也要允许真实环境中的限制被透明说明。有些命令依赖数据库、容器、第三方服务或本地凭据，并不总能在当前环境运行。AGENTS.md可以要求如果验证无法执行，必须在最终回复中说明未执行的命令、失败原因和建议的人工验证步骤。这样不会假装已经完成检查，也能让开发者知道后续该补哪些环节。验证要求的目的不是制造形式，而是让变更结果可追踪。

代码审查要求同样可以写得具体。比如要求说明修改范围、列出测试结果、指出未覆盖风险、避免无关重构、不要把格式化变更混入业务修复。对于团队协作项目，还可以要求涉及公共接口、数据结构或迁移的变更必须提示审查重点。AGENTS.md中的审查规则不能替代审查人，但能让提交内容更容易被理解。

按改动类型匹配验证命令
无法运行验证时要说明原因
避免把无关格式化混入业务修改
公共接口变更要提示影响范围
最终交付应包含测试或未测说明

真实场景案例：为前后端混合仓库写一份最小AGENTS.md

假设一个仓库同时包含web前端和api后端，开发者每次让Codex进入仓库都要重复说明：前端使用pnpm，后端使用某种服务端框架，web目录不要修改构建产物，api目录不要删除历史迁移，改动后至少运行相关测试，无法运行时要说明原因。这个场景非常适合写最小AGENTS.md，因为规则稳定、跨任务复用、直接影响修改行为，而且不会涉及具体业务机密。

最小版本可以围绕五件事组织：项目概览写明web和api的职责；命令区列出安装、测试、构建和格式化入口；目录边界写明src可改、dist不可改、migrations只追加不重写；验证要求写明按改动范围运行相应命令；交付说明要求列出修改点、验证结果和未覆盖风险。它不需要解释每个业务模块，也不需要放长篇架构图，只要让Codex在开始工作前知道怎样安全地行动。

例如可以用自然语言写成：本仓库包含web与api两个主要模块；修改web下源代码后优先运行前端测试和类型检查；修改api接口后同步检查调用方和后端测试；不要手改生成目录、锁定的接口产物和本地环境文件；如需修改迁移、部署脚本或依赖锁文件，必须在任务中有明确要求。这样的最小文件通常已经能覆盖大部分重复说明。

先写仓库结构和模块职责
再写每个模块的常用验证命令
明确生成物、迁移和环境文件边界
要求交付时说明验证结果
把业务细节留给任务提示或正式文档

错误与避坑清单：写得太长、包含密钥、规则冲突和过期命令；风险提示：Codex行为与配置能力以当前官方文档和实际版本为准

最常见的错误是把AGENTS.md写成大而全的仓库百科，结果重要规则被淹没，维护者也不愿更新。第二个错误是写入敏感信息，哪怕只是为了提醒如何连接测试环境，也不应放入密钥、令牌、账号或私有凭据。第三个错误是规则冲突，例如同一文件中同时要求不要修改锁文件和升级依赖必须更新锁文件，却没有说明条件。第四个错误是命令过期，包管理器已经迁移，文件中仍保留旧命令，反而误导执行。

避坑方式是把AGENTS.md当作需要维护的工程资产。每当Codex反复犯同类错误，可以把稳定教训提炼成一条短规则；每当项目命令、目录或工具发生变化，应同步更新文件；每隔一段时间审查是否有过期命令、重复规则、含糊表达和不再适用的例外。规则不必追求一次写完，最好在真实任务中逐步修正，让它持续贴近项目现状。

还需要保留风险意识。Codex的读取方式、配置能力、命令执行行为、模型选择、登录状态、可用功能和客户端细节，可能随版本和实际环境变化；涉及这些内容时，应以当前官方页面或实际页面显示为准。AGENTS.md能提升协作一致性，但不是权限隔离、测试覆盖、代码审查和安全流程的替代品。重要仓库仍应配合版本控制、最小权限、持续集成和人工确认。

不要把文件写成冗长百科
不要写入密钥、令牌和账号
不要保留过期命令和旧目录
不要让规则相互矛盾
以当前官方页面或实际页面显示为准

官方参考

页面中的账号可见功能、模型、下载方式、验证步骤和服务规则可能变化，请以当前官方页面及实际页面显示为准。

Codex AGENTS.md怎么写？项目规则、命令、目录边界与分层配置教程【2026年7月】 ​

开发工具测试建议 ​

AGENTS.md解决什么问题，以及什么内容不应该写进去 ​

先收集技术栈、常用命令、目录结构和验收规则 ​

项目级规则如何写得短、明确且可验证 ​

目录边界、敏感文件和禁止操作如何表达 ​

临时提示、AGENTS.md、项目配置和自动化规则对比表 ​

分层规则与子目录约定应如何避免冲突 ​

构建、测试、格式化和代码审查要求如何落地 ​

真实场景案例：为前后端混合仓库写一份最小AGENTS.md ​

错误与避坑清单：写得太长、包含密钥、规则冲突和过期命令；风险提示：Codex行为与配置能力以当前官方文档和实际版本为准 ​

相关阅读 ​

官方参考 ​