AGENTS.md 项目规则

对于 Codex 而言，我们每开启一个新的对话窗口，它都会进入一个全新的上下文。它不记得之前发生了什么，对于整个项目的记忆都是空白的。

所以 Codex 提供了记忆系统来解决这样的问题

AGENTS.md 是给 Codex 这类编码代理看的项目说明文件。它可以描述项目结构、开发命令、测试要求、代码风格和协作边界。

最后核对

AGENTS.md 机制请以 Codex AGENTS.md 官方文档 和 openai/codex GitHub repository 为准。最后核对日期：2026-05-04。

AGENTS.md

没有项目规则时，Codex 需要从仓库里推断很多事情：

• 用哪个包管理器。
• 如何运行测试。
• 哪些目录是生成物。
• 哪些文件不能改。
• 提交前要跑哪些检查。

AGENTS.md 能把这些规则显式写下来，减少反复解释。

建议放在仓库哪里

针对于我们打开的项目，我们可以在项目根目录下创建一个 agents.md 的文件。

它是 Codex 的记忆文件，Codex 在开始工作之前会先读取 agents.md 的内容。我们可以测试一下：

1. 在 agents.md 文件里面写入一些内容。

1. 回到 Codex 对话窗口问它：“这是一个什么样的系统？”

从这里可以看出，Codex 会读取 agents.md 文件，把里面的内容自动带入到新的对话，作为它们的上下文。

当然，在当前目录根目录下创建 agents.md 只对当前文件夹生效，并不是全局生效的。

如果想要全局生效，有以下两种方式：

1. 在系统的全局 Codex 文件夹里面找到 agents.md。
2. 在 Codex App 里面打开设置，找到“个性化”，在其中填写“自定义指令”。这里面设置的就是全局的 agents.md 文件。

设置全局文件后，对于所有的项目都会生效。所以它们的作用域和作用范围是不一样的，这一点大家需要了解一下。

推荐模板

# AGENTS.md

## 项目概览

- 项目类型：
- 主要语言：
- 关键目录：

## 常用命令

- 安装依赖：`...`
- 本地开发：`...`
- 运行测试：`...`
- 类型检查：`...`
- 格式化：`...`

## 代码规范

- 遵循现有代码风格。
- 不做无关重构。
- 新增功能必须补充或更新测试。

## 安全边界

- 不读取或提交 `.env`、密钥和私有凭据。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响。

## 交付要求

- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。

写作建议

• 越具体越好。运行测试：pnpm test 比“记得测试”有用。
• 把生成目录、构建产物、锁文件策略写清楚。
• 如果是 monorepo，请说明每个包的边界。
• 如果有特殊 lint、格式化或代码生成流程，写在命令区。
• 对安全敏感项目，单独写“禁止事项”。

最小可用版本

# AGENTS.md

## 项目命令

- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 构建：`pnpm build`

## 改动规则

- 修改前先阅读相关文件。
- 保持现有代码风格。
- 不提交构建产物和环境变量文件。

## 验证要求

- 文档改动运行：`pnpm build`
- 代码改动运行相关测试。

## 安全边界

- 不读取 `.env` 或任何私有凭据。
- 不执行发布、部署、数据库迁移和删除数据命令。