AGENTS.md 是 Codex 读取的项目指令文件，适合写“这个仓库怎样工作”的稳定规则：目录约定、安装和测试命令、代码风格、提交前检查和不能触碰的文件。它不是提示词仓库，也不是存放密钥的配置文件。可以在 ChatGPT 桌面端运行 /init 生成起始模板，再按真实项目修订。
官方参考：OpenAI Codex AGENTS.md 指南 · OpenAI Codex 仓库说明 · Codex 官方使用说明
AGENTS.md 解决什么问题？
每次让 Codex 修改项目时，用户都可能重复解释“用什么命令测试”“不要改生成文件”“API 路由在哪里”。AGENTS.md 把这些稳定约定放到仓库上下文里，让代理在开始任务前看到统一的项目背景。好的文件让任务更快、更可复现，也减少因默认假设造成的返工。
| 适合写入 | 示例 | 不适合写入 |
|---|---|---|
| 项目结构 | src/ 是源码，dist/ 由构建生成 | 一段只适用于今天的临时需求 |
| 验证命令 | npm test、npm run lint、部署前检查 | “永远不要测试”这类与项目目标冲突的口号 |
| 边界与风险 | 不要修改迁移文件；生产操作先请求确认 | 密码、API Key、Cookie、私钥 |
| 交付约定 | PR 需要说明变更、测试和已知限制 | 完整复制外部文档或超长教程 |
Codex 如何发现和合并规则？
官方 Codex prompting guide 说明，Codex CLI 会从 ~/.codex 以及仓库根目录到当前工作目录查找这些文件，并按从全局到局部的顺序注入上下文。越靠近当前目录的指令可以覆盖更上层的通用规则；因此，根目录写团队共识，子目录写特定服务的命令，通常比把所有内容堆进一个大文件更清晰。
实际工作中可以这样分层：
- 全局层：只放个人通用偏好，例如输出语言或通用安全要求。
- 仓库根目录：放安装、测试、目录结构、提交前检查和通用禁区。
- 子目录：放前端、后端或文档目录独有的命令和验收标准。
文件名和覆盖规则以当前 Codex 版本文档为准。若代理表现与预期不一致，先在任务里明确要求它读取并复述相关 AGENTS.md，再检查当前目录、文件名和是否被更深层规则覆盖。
用 /init 生成第一版
在 ChatGPT 桌面端使用 Codex 时，在当前项目中运行：
/init官方帮助中心将它描述为为当前项目生成 AGENTS.md scaffold 的初始化流程，CLI 使用同一工作流。生成后不要直接当成最终规范，应该人工检查命令、目录和安全边界：
- 确认项目根目录正确，避免把规则写到上级目录。
- 删除猜测出来的命令、旧框架和不存在的目录。
- 补充“完成前必须运行什么检查”，并说明失败时如何报告。
- 把可公开的项目规则提交到版本库，敏感配置留在环境变量或密钥管理器。
一个可直接改写的模板
# AGENTS.md
## 项目概览
- 这是一个 Node.js + TypeScript 服务。
- 源码在 src/，测试在 tests/，生成文件不要手改。
## 开发命令
- 安装依赖：npm ci
- 本地开发：npm run dev
- 检查：npm run lint && npm test
## 修改规则
- 保持现有 API 响应格式，不要无关重构。
- 修改数据库结构前先说明迁移影响。
- 不要提交 .env、Token、Cookie 或私钥。
## 交付前
- 汇总修改文件、验证命令和未解决问题。
- 测试失败时保留原始错误，不要声称已通过。
模板的价值在于告诉代理“如何判断完成”，而不是把每一步都写死。命令名应以你仓库的 package.json、Makefile 或 CI 配置为准；不存在的命令会让代理形成错误反馈回路。
为什么 AGENTS.md 看起来没有生效？
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| Codex 没遵守测试命令 | 当前工作目录、文件名、规则是否写得明确 | 让 Codex 先列出已加载的规则，再检查命令是否真实存在 |
| 子项目规则被忽略 | 子目录是否在当前任务路径下，是否有覆盖文件 | 从仓库根目录进入目标目录，缩小任务范围 |
| 规则互相冲突 | 全局、根目录和子目录的同名要求 | 删除重复规则，把更具体的要求放在更近的目录 |
| 写了密钥仍担心泄露 | 是否已经提交或出现在会话上下文 | 立即轮换凭证，加入 .gitignore，并从文件中移除 |
AGENTS.md、Skills 和 MCP 怎么配合？
三者解决的层次不同。AGENTS.md 是项目级“长期约定”；Skills 是按任务加载的专业工作流；MCP 是连接外部工具或数据的接口。可以在 AGENTS.md 中写“什么时候使用某个 Skill 或 MCP、完成后要做哪些验证”，但不要把密钥、OAuth Token 或完整外部系统权限写进去。需要了解 Codex 的工具入口，可以继续看 MCP、Skills 与 Plugins、Codex CLI 使用教程和API 与 Credits 区别。
安全检查清单
- 只写项目规则，不写任何可认证的秘密。
- 把破坏性命令、生产环境和数据迁移列为需要确认的边界。
- 规则短而具体，优先写可执行的命令和验收条件。
- 规则变更和代码变更一起评审，避免过期命令长期误导代理。
- 如果使用第三方充值或代办服务，绝不提供 ChatGPT 密码、验证码、Session 或完整 API Key。
常见问题
AGENTS.md 是 Codex 必须的文件吗？
不是。它是可选的项目指令文件；没有它 Codex 仍可工作，但项目约定、测试命令和安全边界需要在每次任务中重复说明。
Codex 怎么生成 AGENTS.md？
在 ChatGPT 桌面端使用 Codex 时运行 /init，可为当前项目生成 AGENTS.md scaffold；CLI 也使用同一初始化工作流。
AGENTS.md 放在哪里最有效？
可以放在 ~/.codex、仓库根目录和更深的项目目录。Codex 会按从全局到仓库根目录再到当前目录的顺序合并，越靠近当前目录的规则优先。
AGENTS.md 和 Skills 有什么区别？
AGENTS.md 适合项目长期规则、命令和边界；Skills 适合按任务按需加载的工作流。两者可以配合，不要把全部操作步骤都塞进一个文件。
AGENTS.md 可以放 API Key 吗？
不可以。不要把 API Key、密码、Cookie、私钥或生产凭证写进 AGENTS.md；规则文件会被注入给代理，也可能进入版本库。
想把 Codex 项目规则落地？
GPT Pro AI 提供 Codex、ChatGPT Plus/Pro 相关的第三方使用咨询，不代表 OpenAI 官方授权。安装、登录、模型与功能可用性以官方文档和账号页面为准。