Codex AGENTS.md 怎么写
AGENTS.md 是给 Codex 读取的项目说明文件。它适合保存仓库结构、启动和测试命令、代码约定、提交要求和禁止事项，减少你在每次任务中重复说明。它不是把所有需求写进一份巨型提示词，而是记录团队长期有效、可以检查的规则。
文件放在哪里
官方说明支持全局和项目层级。全局文件可以放在 ~/.codex/AGENTS.md，项目根目录可以放一份，子目录还可以有更具体的文件。越靠近当前工作目录的规则优先级越高；如果存在 AGENTS.override.md，它可用于临时覆盖同层默认文件。具体发现顺序以当前版本文档为准。
使用 /init 可以在当前目录生成起始文件：
/init生成后务必人工编辑。自动生成的内容可能没有项目特有的测试、部署和安全约束。让 Codex 读取规则并复述它将遵守的重点，是验证文件已进入上下文的简单方法。
一份有用的文件写什么
# Project instructions
## Repository
- `apps/web` 是前端，`services/api` 是后端。
- 使用 pnpm，不要提交生成目录。
## Commands
- 安装：`pnpm install`
- 测试：`pnpm test`
- 构建：`pnpm build`
## Rules
- 保持现有 API 返回字段兼容。
- 不升级依赖，除非任务明确要求。
- 不修改 `.env` 和生产配置。
## Done
- 运行相关测试。
- 总结改动文件、测试结果和未验证内容。每条规则都尽量对应一个动作或检查。“代码要优雅”“注意性能”可以作为背景，但不能替代具体的验收方式。不要把密钥、个人账号、临时路径或只对一次任务成立的决定写进仓库规则。
如何组织层级
根目录文件写全仓库共用内容；前端或后端子目录写局部命令和约定。若同一条规则在多个层级出现，保持含义一致。更具体的文件可以补充，而不是随意推翻安全边界。修改规则后，开启新会话或确认当前客户端会重新加载，避免把旧上下文当成新规则。
常见失效原因
文件名拼错、放在当前目录的上级之外、项目不是受信任目录、规则只写在另一个分支，都会让结果与预期不一致。规则内容过长、重复、互相冲突，也会降低可用性。先用一条只读任务验证加载，再继续修改项目。
AGENTS.md 不会替你授予文件、网络或生产系统权限。权限由 Codex 配置、审批策略和运行环境决定。想了解两者区别，可看Codex 权限与沙箱。
把重复错误变成规则
如果 Codex 连续两次忘记先运行测试，就在规则中写明测试命令和交付要求；如果它总把生成文件提交进 Git，就增加目录约束。规则应来自真实摩擦，而不是把所有可能情况提前写成百科全书。每次补充后，检查文件是否仍让新成员容易读懂。
完整使用路径见Codex使用教程。
用一个验收任务检查规则是否清楚
准备一项容易检查的任务，例如给一个已有函数补充输入校验。先让 Codex 读取规则并说明打算采用的测试命令，然后观察它是否先找到了正确包、是否遵守禁止升级依赖的要求，以及最后有没有报告未运行的检查。只让模型复述文件，能够验证读取，但不能代替实际执行验证。
如果结果不符合约定，先检查规则本身是否明确。写着“按项目要求测试”，却没有给出命令和目录，新成员与工具都会猜。可以改为“前端改动在 apps/web 中运行已有测试；环境缺失时停止并报告缺少条件”。这句话提供了动作、作用范围和失败后的处理方式。
为不同目录写不同说明
假设仓库同时包含网站、API 和脚本。根目录文件说明共同的包管理器、分支规则和安全要求；网站目录记录构建与页面检查；API 目录记录接口兼容和数据库测试；脚本目录记录重复执行与数据输出。这样每份规则聚焦当前工作，不必让所有任务都读取整套操作手册。
分层不意味着可以随意互相覆盖。创建局部文件前，先检查根规则是否允许局部差异，特别是部署、凭证和生产数据相关限制。若局部说明与全局政策冲突，应该修正规则来源，而不是让工具自行猜哪份更重要。
OpenAI 的 AGENTS.md 指南说明了发现和作用范围。团队维护时还应明确哪个文件由谁负责，目录迁移后更新相关路径。一个指向已删除测试脚本的规则，看起来完整，实际会让每次任务都从同一个错误开始。
把命令写到可以直接核对
命令说明应包含执行目录和前置条件。例如“在仓库根目录运行 pnpm build”比“构建一下”清楚；“数据库相关测试需要本地测试实例，不允许连接生产库”把范围也交代了。不要把命令执行成功和业务验证成功混为一谈，构建、单元测试和实际复现承担不同作用。
环境并非每次都具备时，在规则中说明如何报告。例如“没有测试数据库时记录未运行，不创建线上替代连接”。这样任务交付可以如实描述检查状态，不会为了写一个全绿总结而尝试超出授权范围的操作。
项目换了包管理器或测试框架，就应在同一改动中更新规则。把规则文件当作代码库的一部分审查：命令存在吗，目录正确吗，是否引入新的外部服务，执行是否需要凭证？这些都是可以用事实检查的问题。
哪些内容适合规则，哪些留给任务
长期有效的信息适合 AGENTS.md：仓库结构、常用命令、代码约定和交付格式。一次性业务需求、还在讨论的设计、个人临时路径则更适合写在任务中。把未确定决定写成长期规则，下一次任务可能把它当成已经批准的约束。
例如“当前只修登录刷新问题，不改注册流程”属于一次任务范围；“对外接口变更必须保留向后兼容”可能是项目约定。区分这两类信息，能让规则保持稳定，也让每次任务有自己的验收条件。需要解释复杂设计时，可以链接到仓库里的设计文档，避免复制一份会很快过时的长文。
文件中还不适合存放真实密钥、个人 Token 和临时会话链接。即使仓库是私有的，也应通过环境或专用凭证系统提供。规则可以写“读取环境变量名”，不能把凭证值当作示例让成员照抄。
第三方模型的配置说明怎么写
如果团队通过 ClawSocket调用模型，可以在规则里说明如何核对当前 provider、模型和请求记录，但不要要求所有成员共享同一把 Key。配置模板、环境变量名和已验证能力可以保存在文档，真实凭证由对应账户提供。
项目规则不会把模型请求自动路由到 ClawSocket。路由需要另在 Codex 配置中设置 provider；模型元数据、Responses 和工具能力也要按服务端要求验收。写清这个边界，可以避免把 AGENTS.md 当作万能配置文件。接入步骤见第三方模型教程。
规则太多时怎么精简
先找重复条目和已经过时的要求，再检查哪些句子没有可执行含义。不要为了缩短文件删掉安全范围、兼容性和验证条件。把解释性背景移动到相关文档，规则只保留结论和链接；任务需要时再让工具读取原文。
精简后做一次对照：原来要求的独立事项是否保留，否定条件有没有丢失，允许和禁止有没有被改反。比如“未运行测试必须说明原因”不能压成“说明测试结果”，后者容易遗漏环境阻塞。表达自然的目标是让含义更清楚，不是追求字数更少。
文件变长往往来自每次失败都追加一条命令式提醒。新增前先判断失败是否由环境、任务描述或权限导致。如果问题在配置上，修配置；如果是一次性操作遗漏，完善该任务即可。只有反复出现、适用于后续工作的要求，才值得升级为长期规则。
多人修改和冲突处理
规则发生变更时，应把原因写进提交说明，说明之后的任务行为会有哪些不同。不要悄悄把测试要求改弱，或把发布从需确认改为自动执行。审查者需要看到这是行为边界变更，而不仅是文案更新。
两位成员同时增加局部规则时，合并后读一遍完整文件。语法冲突解决不等于语义一致：一段说必须运行全部测试，另一段说只运行相关检查，就需要明确适用条件。无法统一时标出待决问题，别让工具替团队作政策选择。
给任务交付设一份短格式
可以要求交付包含改动原因、涉及文件、已运行验证、未验证部分和需要用户处理的事。每一项都有实际用途，不必再加一长段空泛总结。若任务只修改文案，则对应的构建或页面检查即可；不必机械要求所有任务都新增测试。
这份格式还能帮助团队复核。没有运行的命令明确写“未运行”，运行失败保留原因，环境缺失与代码失败分开说明。出现模型自称完成但文件没有变化时，依照诊断树检查工具流程，再决定是否调整规则。
维护前后都保留验证记录
新增规则后，选一个小任务检查；升级客户端后，复核你依赖的加载与覆盖行为；目录重构后，检查命令和路径。无需为每一条自然语言规则编造测试，但应能指出它如何被实际检查。
想从项目规则继续学习，可以看CLI 命令了解如何启动和恢复任务，再看权限与沙箱区分指导与技术限制。回到Codex使用教程，按理解、修改和验证完成一轮任务，才能判断这些规则是否真的适合自己的项目。
规则的版本与阅读习惯
当规则引用外部服务文档时，保留来源和核对日期，尤其是模型、端点和命令参数。更新产品资料后，再检查规则是否仍符合本机版本。不要把一次搜索到的答案永久写成项目事实，后续成员可能已经换了环境。
新成员可以先手动阅读规则，再让 Codex 解释不清楚的部分。若人读起来都无法执行，智能体也很难稳定遵守。把缩写、隐藏前置条件和个人习惯展开成明确动作，是比堆积提示词更实用的维护方式。
规则需要撤销时，删除对应条目并检查引用，不必保留一串互相矛盾的历史命令。历史原因写在版本记录中，当前文件保持现行要求。这样每次任务拿到的都是可以实施的规则，而不是需要重新判断的讨论过程。
官方资料与核对范围
以下资料用于核对产品入口、命令和配置；练习与任务模板是本文提供的操作建议，不代表已在读者设备上运行。官方源码主分支会更新，安装时请再核对本机版本。