使用 AGENTS.md 为 Codex 编写项目规则#

AGENTS.md 是放在代码库中的长期项目指令。它适合记录每次任务都需要遵守的事实，例如如何构建、如何测试、目录由谁负责，以及哪些生成文件不能手改。相比在每条提示词中重复，这种方式更稳定，也能随代码一起审查。

适合写什么#

一份有用的 AGENTS.md 应帮助新的开发者或编程代理快速进入项目：

• 项目的语言、框架和关键目录。
• 安装、开发、测试、lint、类型检查和构建命令。
• 必须沿用的本地组件或服务层模式。
• 修改数据库、API、生成代码时的特殊步骤。
• 验证不同类型改动需要运行的最小命令。
• 明确不能读取、修改或提交的敏感文件。

不要把整本架构文档复制进去。链接到已有文档，并保留 Codex 执行任务真正需要的信息。

一个简洁示例#

# Repository guidelines

## Structure
- `src/server`: API and business logic
- `src/web`: Vue frontend
- `tests`: integration tests

## Commands
- Install: `npm ci`
- Unit tests: `npm test`
- Type check: `npm run typecheck`
- Build: `npm run build`

## Rules
- Reuse components from `src/web/components`.
- Do not edit files under `src/generated` manually.
- Never commit `.env` or credentials.
- API behavior changes require an integration test.

指令可以使用中文。命令、路径和配置键保持原样，避免翻译后无法执行。

分层规则如何工作#

Codex 会从项目根目录向当前工作目录查找项目指令。更靠近目标文件的 AGENTS.md 可以为其子目录提供更具体的规则。例如：

AGENTS.md
packages/
  web/
    AGENTS.md
  server/
    AGENTS.md

根文件描述整个仓库的共同规则，packages/web/AGENTS.md 只补充前端构建和 UI 约束。这样可以避免根文件充满互不相关的细节。

写成可执行的规则#

“保持高质量”没有可操作性；“修改 TypeScript 后运行 npm run typecheck”可以验证。“遵守现有风格”也比较模糊，最好指向格式化命令、参考目录或公共组件。

对高风险事项，用明确语言：

• 不运行生产数据库迁移。
• 不修改 vendor/ 和自动生成的客户端。
• 未经明确要求，不安装新的运行时依赖。
• 需要网络下载时先说明用途。

不应该放什么#

不要在 AGENTS.md 中放 API Key、密码、内部令牌或个人路径。也不要放只对一次任务有效的需求，或者强迫 Codex 永远使用某个可能过时的模型名。个人模型提供商配置属于用户级 ~/.codex/config.toml，特别是 APIBest 自定义 API 的地址和鉴权设置，不应由项目仓库覆盖。

如何验证规则有效#

新增或修改后，可以让 Codex 先复述它读取到的项目规则，并说明某个文件受到哪些层级指令影响。再用一个小任务检查它是否选择正确命令、避开禁止目录，并在完成时报告验证结果。

规则发生冲突时应尽快清理。长期维护中，把不再适用的命令和路径从 AGENTS.md 删除，比不断追加例外更重要。官方说明可参考 Codex 的 AGENTS.md 指南。