Codex AGENTS.md 完全指南：用标准化指令文件精准操控 AI 编程助手

引言

代码库越来越大，团队成员越来越多，每个项目都有自己独特的构建命令、测试流程和编码规范。如果每次使用 AI 编程助手时，都需要口头解释这些约定，不仅效率低下，还容易遗漏关键细节。

Codex CLI 支持 AGENTS.md ——一种用于指导编码代理的标准化 Markdown 文件格式，目前已被超过 6 万个开源项目采用。本文将详细介绍 AGENTS.md 的设计理念、在 Codex 中的工作原理、编写技巧，以及如何利用嵌套文件和优先级机制在大型项目中构建多层次的指令体系。

AGENTS.md 的设计理念

为什么需要 AGENTS.md？

README.md 是给人看的——项目简介、快速开始、贡献指南。但人类和 AI 助手的阅读习惯不同。AI 需要更具体的上下文，比如：

  • 构建命令：pnpm build 还是 npm run build？
  • 测试命令：pnpm test 还是 pnpm vitest？
  • 编码风格：单引号还是双引号？是否使用分号？
  • 安全约束：哪些操作绝对不允许？

这些信息写在 README 里会显得冗长，不写又导致 AI 频繁犯错。AGENTS.md 专门存放面向 AI 助手的精确指令，两者各司其职。

开放标准，跨工具兼容

AGENTS.md 不是 Codex 的私有格式。它由 OpenAI、Google（Jules）、Cursor、Factory 和 Amp 联合推动，现由 Linux Foundation 旗下的 Agentic AI Foundation 托管。这意味着同一份 AGENTS.md 可以在 Codex、Cursor、VS Code Copilot、Gemini CLI、Devin、Windsurf 等数十个工具中通用。

在 Codex 中使用 AGENTS.md

基本用法

在项目根目录创建一个 AGENTS.md 文件：

# AGENTS.md

## 项目概述
这是一个电子商务平台后端，使用 Go 语言开发，PostgreSQL 数据库，
gRPC 微服务架构。

## 环境初始化
- 安装依赖：`go mod download`
- 启动数据库：`docker compose up -d postgres`
- 运行迁移：`go run cmd/migrate/main.go up`

## 构建与测试
- 构建：`go build ./...`
- 运行所有测试：`go test ./...`
- 运行单个包测试：`go test ./internal/service/order/...`
- 运行集成测试：`go test -tags=integration ./...`

## 代码风格
- 遵循 Effective Go 规范
- 所有导出函数必须有文档注释
- 错误处理不能使用 panic，必须返回 error
- 使用 context.Context 作为函数的第一个参数
- 数据库操作统一使用 sqlx 库

## PR 规范
- 标题格式：`[模块名] 简短描述`
- 提交前必须运行 `go vet ./...` 和 `golangci-lint run`
- 新增接口必须包含单元测试

创建文件后，无需任何额外配置——Codex 在启动时会自动加载项目根目录下的 AGENTS.md，并将其内容注入到上下文窗口中。你只需要正常输入提示词，Codex 就会遵循文件中定义的规则。

Codex 如何解析 AGENTS.md

Codex 对 AGENTS.md 的加载机制遵循以下规则：

自动发现：Codex 会自动扫描当前工作目录及父目录链，寻找 AGENTS.md 文件。

Markdown 原生格式：AGENTS.md 是纯 Markdown 文件，没有必填字段或特定 schema。你可以使用任意标题层级。

全文注入：Codex 将文件内容作为系统级指令注入模型的上下文窗口，影响后续所有交互。

实时生效：修改 AGENTS.md 后，下一次 codex 会话启动时自动加载最新版本。

下面用一个实际演示来验证：

# 创建一个空项目
mkdir demo-project && cd demo-project

# 创建 AGENTS.md
cat > AGENTS.md << 'EOF'
# AGENTS.md

## 重要规则
- 所有新创建的 Python 文件首行必须添加 `# -*- coding: utf-8 -*-`
- 函数命名使用 snake_case
- 类命名使用 PascalCase
EOF

# 启动 Codex 并提交一个编程任务
codex "创建一个名为 user_manager.py 的 Python 类，包含 add_user 和 remove_user 方法"

Codex 会自动读取 AGENTS.md 中的编码风格要求，生成符合约定的代码：

# -*- coding: utf-8 -*-
from typing import Dict, Optional


class UserManager:
    def __init__(self):
        self._users: Dict[str, dict] = {}

    def add_user(self, user_id: str, user_data: dict) -> bool:
        if user_id in self._users:
            return False
        self._users[user_id] = user_data
        return True

    def remove_user(self, user_id: str) -> Optional[dict]:
        return self._users.pop(user_id, None)

嵌套 AGENTS.md：多级指令体系

Monorepo 场景

对于大型 monorepo 项目，单一根目录的 AGENTS.md 往往不足以描述所有子项目的约定。Codex 支持嵌套 AGENTS.md——在子项目目录中放置独立的 AGENTS.md 文件。

my-monorepo/
├── AGENTS.md                  # 全局规则
├── packages/
│   ├── web/
│   │   └── AGENTS.md          # Web 前端规则
│   ├── api/
│   │   └── AGENTS.md          # API 服务规则
│   └── shared/
│       └── AGENTS.md          # 共享库规则

优先级规则

当存在多层 AGENTS.md 时，Codex 的优先级规则为：

最近优先：距离被编辑文件最近的 AGENTS.md 优先级最高

显式指令优先：用户在对话中直接给出的指令会覆盖所有 AGENTS.md

合并而非替换：根目录的 AGENTS.md 仍然生效，子目录的规则在全局规则之上叠加

以 openai/codex 仓库为例，该项目包含了 88 个 AGENTS.md 文件。根目录文件定义了 Rust 通用开发规范，而 codex-rs/tui/ 下的 AGENTS.md 则专门规定了 TUI 界面样式（Ratatui 组件风格、颜色使用约定等）。

实战示例：多层 AGENTS.md 配置

根目录 AGENTS.md（全局规则）：

# AGENTS.md

## 通用规范
- 提交信息格式：`<type>(<scope>): <description>`
- 禁止向仓库提交密钥、Token 等敏感信息
- PR 合并前必须通过 CI 流水线

## 开发环境
- Node.js >= 20.x
- 使用 pnpm 作为包管理器

packages/web/AGENTS.md（前端规则）：

## 前端开发规范

### 构建命令
- 开发环境：`pnpm dev`
- 生产构建：`pnpm build`
- 代码检查：`pnpm lint`

### 编码规范
- 使用 TypeScript 严格模式
- 组件文件使用 .tsx 后缀
- 使用 React Hooks 而非 class 组件
- 样式统一使用 Tailwind CSS
- 单引号，不使用分号

packages/api/AGENTS.md（后端规则）：

## API 服务开发规范

### 构建命令
- 运行服务：`go run cmd/server/main.go`
- 数据库迁移：`go run cmd/migrate/main.go`
- 生成 proto：`buf generate`

### 编码规范
- 所有 API 端点必须先定义 proto 文件
- 错误码使用统一的 errcode 包
- 数据库查询使用参数化，禁止拼接 SQL

当你在 packages/web/src/App.tsx 中工作时，Codex 会同时加载根目录和 packages/web/ 的 AGENTS.md，但不会加载 packages/api/ 的规则。

AGENTS.md 编写最佳实践

1. 结构清晰，按主题分节

推荐使用以下核心节：

# AGENTS.md

## 项目概述
## 环境初始化
## 构建与测试
## 代码风格
## 安全约束
## PR 规范

2. 命令要具体、可执行

不推荐（模糊描述）：

- 运行测试

推荐（具体命令）：

- 运行所有单元测试：`go test ./...`
- 运行特定包测试：`go test ./internal/service/user/...`
- 生成覆盖率报告：`go test -coverprofile=coverage.out ./...`

Codex 不仅会遵循这些指令，还会在执行任务时自动运行列出的测试命令，以确保代码变更不会破坏现有功能。

3. 使用断言式语言描述规则

AGENTS.md 中的指令应该是声明性的、不可协商的：

## 编码规范
- 函数命名使用 snake_case
- 禁止使用 any 类型，必须定义明确的 TypeScript 接口
- 所有 HTTP 请求必须设置 30 秒超时
- 数据库迁移文件只能追加，禁止修改已有迁移

避免使用"建议"、"尽可能"等模糊词汇。AI 会按字面理解，模糊指令等于没有指令。

4. 提供反例与边界说明

对于容易出错的地方，给出明确的反例：

## 文件操作规范
- 使用 os.ReadFile 读取文件 ✓
- 禁止使用 ioutil.ReadFile（Go 1.16 后已废弃）✗

## 错误处理规范
- 使用 fmt.Errorf("context: %w", err) 包装错误 ✓
- 禁止直接 return err（丢失上下文信息）✗

5. 安全约束放在显眼位置

将安全相关的硬性约束放在文件顶部或独立章节：

## 🔒 安全约束（最高优先级）
- 绝对禁止执行 `rm -rf /` 或任何删除根目录的命令
- 禁止修改 .git/ 目录下的任何文件
- 禁止向外部 URL 发送源代码内容
- 禁止生成含有默认密码的生产配置文件

6. 善用"提示词工程"技巧

AGENTS.md 本质上是系统级提示词的一部分，以下技巧能显著提升效果：

  • 角色定义：在文件开头说明 AI 的角色定位

```markdown
你是一个 Go 后端开发专家，擅长微服务架构和分布式系统设计。
```

  • 输出格式指定：

```markdown
代码注释使用中文，但代码标识符全部使用英文。
```

  • 工具使用偏好：

```markdown
当需要查询数据库 schema 时，优先使用 psql 而非 GUI 工具。
```

7. 面向团队协作的可维护性

AGENTS.md 是一份活的文档。项目约定变更时，同步更新 AGENTS.md：

# 将 AGENTS.md 视为与源代码同等重要的文件
git add AGENTS.md
git commit -m "docs: 更新 AGENTS.md 添加新的测试运行规则"

建议在 Code Review 流程中增加一个检查项：代码变更是否涉及了 AGENTS.md 中约定的规则变更？如果是，AGENTS.md 是否需要同步更新？

与 Codex 其他配置机制的协作

AGENTS.md 并非孤立存在，它需要与 Codex 的其他配置层配合：

config.toml vs AGENTS.md

| 维度 | config.toml | AGENTS.md |
|------|-------------|-----------|
| 用途 | 配置 Codex 工具本身的行为 | 定义项目的编码规范和 AI 行为准则 |
| 内容 | 模型选择、API 端点、执行策略 | 项目约定、命令、编码风格 |
| 格式 | TOML 配置键值对 | Markdown 自由文本 |
| 加载方式 | Codex 启动时读取 | 随上下文注入模型 |

简单来说：config.toml 告诉 Codex "怎么跑"，AGENTS.md 告诉 AI "怎么做"。

执行策略（Execution Policy）与 AGENTS.md

Execution Policy 控制的是 Codex 执行命令的权限边界（如禁止某些命令、禁止网络访问），而 AGENTS.md 关注的是任务的方法论（如怎么命名、怎么写测试）。两者互补：

# config.toml – 权限控制
[exec_policy]
deny_commands = ["rm", "git push --force"]
# AGENTS.md – 方法论指导
## Git 操作规范
- 推送前必须先运行 `git pull --rebase`
- 合并 commit 使用 `git merge --no-ff`

Skills 与 AGENTS.md

Codex 的 Skills 功能提供模块化的指令片段（如预置某个框架的代码模板），而 AGENTS.md 是项目级的全局指令。两者可以共存——AGENTS.md 定义"什么是对的"，Skills 提供"怎么做"的具体实现。

从 Codex 官方仓库学到的技巧

OpenAI 的 codex 仓库（github.com/openai/codex）本身使用了极度详细的 AGENTS.md，我们从中学到几个关键实践：

严格控制上下文窗口

### Model visible context

1. No history rewrite - the context must be built up incrementally.
2. No unbounded items - everything injected in the model context
   must have a bounded size and a hard cap.
3. No items larger than 10K tokens.

这份指令告诉 AI：你不能随便往上下文中塞东西，每个注入的片段必须有限制。这对于长期维护 AGENTS.md 至关重要——写得越长不等于越好，精确才重要。

变更大小管控

### Change size guidance (800 lines)

Unless the change is mechanical the total number of changed lines
should not exceed 800 lines.

通过 AGENTS.md 约束单次变更规模，避免 AI 产生无法审查的大型 diff。

Rust 项目特定约束

对于 Rust 项目，AGENTS.md 可以深入到编译器级别的细节：

- Use method references over closures when possible
- Always inline format! args when possible
- Discourage both `#[async_trait]` and `#[allow(async_fn_in_trait)]`

这种精确程度能极大减少 AI 生成代码后的手动修正工作。

常见问题

Q: AGENTS.md 必须是根目录吗？
A: 不一定。Codex 会沿目录树向上搜索，但推荐放在根目录以便全局生效。子目录可以放置额外的 AGENTS.md 覆盖特定子项目的规则。

Q: 多个 AGENTS.md 规则冲突时怎么办？
A: 距离被编辑文件最近的 AGENTS.md 优先。用户在对话框中的显式指令优先级最高。

Q: AGENTS.md 应该有多长？
A: 没有硬性限制，但建议控制在 500 行以内。过长的文件会占用宝贵的上下文窗口，反而降低 AI 表现。可以拆分为多个子目录级别的 AGENTS.md。

Q: 我已有 CLAUDE.md、CURSOR_RULES.md 等文件，需要迁移吗？
A: 建议迁移。AGENTS.md 是开放标准，兼容性最好。你可以保留旧文件作为符号链接：ln -s AGENTS.md CURSOR_RULES.md。

Q: Codex 会自动运行 AGENTS.md 中列出的命令吗？
A: 会的。如果你在 AGENTS.md 中列出了测试命令，Codex 会在完成任务后尝试执行这些命令来验证结果。

总结

AGENTS.md 是为 AI 编程时代设计的"项目说明书"。它解决了一个根本问题：如何让 AI 编程序助手在不丢失上下文的情况下，准确理解每个项目的独特性。

对于 Codex 用户，编写一份高质量的 AGENTS.md 应该是每个项目的起点——它比口头指令更持久，比 config.toml 更灵活，是连接人类意图和 AI 执行之间的关键桥梁。

随着 Agentic AI Foundation 的持续推动，AGENTS.md 正在成为编码代理领域的事实标准。现在花一小时写好它，未来将为你节省成百上千次的重复解释。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客