AGENTS.md 实战手册

核心概念

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

AGENTS.md 就是 Codex 的记忆系统——你在对话开始前写好的项目说明书。Codex 开始工作之前会先读取 AGENTS.md 的内容，把它自动带入到新的对话中，作为它的上下文。

没有项目规则时，Codex 每次都要从仓库里推断：用哪个包管理器、如何运行测试、哪些目录是生成物、哪些文件不能改、提交前要跑哪些检查。把这些规则显式写下来，可以大幅减少重复解释和误操作。

作用域与层级

AGENTS.md 的作用域是从它所在的目录开始，向下覆盖所有子目录。换句话说，放在项目根目录的 AGENTS.md 会覆盖整个项目。

如果在子目录下也创建了 AGENTS.md，那么更深一层的 AGENTS.md 会覆盖上层的同名指令（在它自己的范围内）。这一点非常重要——你可以用这个机制为不同模块写不同的规则。

层级优先级（从高到低）：

当前目录及其子目录中的 AGENTS.md（最深的优先）
上层目录中的 AGENTS.md
项目根目录中的 AGENTS.md
全局 AGENTS.md（Codex 桌面 App 设置中的「自定义指令」）

如果出现冲突：更深层的 AGENTS.md 指令优先；系统/开发者直接指令（prompt 中的）优先于 AGENTS.md。

项目级 vs 全局级

维度	项目级 AGENTS.md	全局级（桌面 App 自定义指令）
放在哪	项目根目录或子目录	Codex 桌面 App > 设置 > 个性化 > 自定义指令
谁能看到	团队所有成员（提交到仓库）	只有你自己的所有项目
适合写什么	项目命令、代码规范、目录说明、禁止事项、验证要求	个人偏好、通用习惯、模型选择、语言风格
不适合写什么	个人密钥、token、私有服务地址	项目特定的命令和目录说明

原则：项目共同规则写进 AGENTS.md 进仓库；个人偏好留在本机全局配置。

与 config.toml 的分工

放在哪	适合放什么
AGENTS.md（进仓库）	推荐测试命令、代码风格和目录说明、PR 模板、文档截图规范、禁止事项
config.toml（留在本机）	默认模型偏好、本地路径、凭证、密钥、私有服务地址、个人 MCP 服务、私有 automation 配置

简单说：共享的项目规范放 AGENTS.md，个人的 CLI 偏好放 config.toml。

写作原则

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

完整模板（适合中型项目）

# AGENTS.md

## 项目概览

- 项目类型：Web 应用
- 主要语言：TypeScript
- 包管理器：pnpm
- 关键目录：
  - src/：业务代码
  - src/components/：UI 组件
  - src/utils/：工具函数
  - tests/：测试文件
  - docs/：文档

## 常用命令

- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 构建：pnpm build
- 运行测试：pnpm test
- 运行单个测试文件：pnpm test -- tests/parser.test.ts
- 类型检查：pnpm tsc --noEmit
- 格式化：pnpm format
- Lint：pnpm lint

## 代码规范

- 遵循现有代码风格，不混用多种风格。
- 不做无关重构，除非任务明确要求。
- 新增功能必须补充或更新测试。
- 组件使用 PascalCase，工具函数使用 camelCase。
- 文件名使用 kebab-case。

## 目录说明

- src/components/ 下的文件是一一对应的组件和测试。
- tests/ 下是集成测试。
- docs/ 下的改动需要运行 pnpm build 验证。
- dist/ 和 node_modules/ 是生成物，不要手动修改。
- .env 和 .env.local 包含敏感配置，不要读取或提交。

## 改动规则

- 修改前先阅读相关文件和测试。
- 保持现有代码风格和目录结构。
- 不引入新的外部依赖，除非任务明确要求。
- 不修改数据库 schema 或迁移文件，除非任务明确要求。

## 安全边界

- 不读取或提交 .env、密钥、token 或任何私有凭证。
- 不执行删除生产数据的命令。
- 不执行发布、部署、数据库迁移命令，除非我明确认。
- 修改认证、权限、支付逻辑前先说明影响。

## 验证要求

- 文档改动运行：pnpm build
- 代码改动运行相关测试。
- 提交前确认没有新增 lint 错误。

## 交付要求

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

最小模板（适合小项目或刚上手）

# AGENTS.md

## 项目命令

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

## 改动规则

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

## 安全边界

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

Monorepo 写法

如果是 monorepo，建议在根目录的 AGENTS.md 写全局规则，然后在每个包下放自己的 AGENTS.md 写包级规则。

根目录 AGENTS.md：

# AGENTS.md

## 项目概览

- 这是一个 pnpm monorepo，包含以下包：
  - packages/core：核心逻辑
  - packages/ui：UI 组件库
  - apps/web：Web 应用
  - apps/admin：管理后台

## 全局命令

- 安装依赖：pnpm install（根目录执行）
- 构建所有包：pnpm build
- 运行所有测试：pnpm test
- 清理构建产物：pnpm clean

## 全局规则

- 不要在包之间引入循环依赖。
- 修改 packages/core 后，检查 apps/web 和 apps/admin 是否受影响。
- 不修改 pnpm-lock.yaml，除非你确定需要。

## 安全边界

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

packages/core/AGENTS.md：

# packages/core AGENTS.md

## 这个包做什么

核心业务逻辑，被 apps/web 和 apps/admin 依赖。

## 常用命令

- 测试：pnpm --filter @myapp/core test
- 类型检查：pnpm --filter @myapp/core tsc --noEmit

## 改动规则

- 这个包是共享的，修改后必须确保所有消费方的测试通过。
- 不要在这个包里引入 UI 相关的依赖。

排障清单

现象	检查
AGENTS.md 没生效	文件名是否正确（大小写）、文件编码是否 UTF-8、是否在正确目录下
Codex 忽略了某条规则	规则是否太模糊、是否与更深层的 AGENTS.md 冲突
不同模块需要不同规则	在子目录下放一个局部 AGENTS.md 覆盖上层规则
团队成员行为不一致	把项目共同规则写进 AGENTS.md 并提交到仓库
个人偏好影响了团队	把个人偏好移到全局自定义指令，不要放在项目 AGENTS.md 里

📎 📒 返回笔记索引

AGENTS.md实战手册

AGENTS.md 实战手册 ​

核心概念 ​

作用域与层级 ​

项目级 vs 全局级 ​

与 config.toml 的分工 ​

写作原则 ​

完整模板（适合中型项目） ​

最小模板（适合小项目或刚上手） ​

Monorepo 写法 ​

排障清单 ​