Codex AGENTS.md 配置实战指南：让 AI 编程助手准确理解你的项目

引言

当你让 Codex 帮你写一段代码，它怎么知道你的项目是 Vue 还是 React？怎么知道你的数据库是 MySQL 还是 PostgreSQL？怎么知道你的团队缩进用 2 个空格还是 4 个 Tab？答案就是 AGENTS.md——Codex 的项目级指令文件。它就像给 AI 编程助手的一份"项目说明书"，让它在正确的上下文中做出正确的决策。

本文将从零开始，深入讲解如何编写和优化 AGENTS.md，帮你在实际项目中充分发挥 Codex 的上下文感知能力。

什么是 AGENTS.md？

AGENTS.md 是一个放在项目根目录下的 Markdown 文件，Codex 在启动时会自动读取它。它的作用是为 AI 代理提供项目级别的上下文信息，包括但不限于：

• 项目简介和架构概述
• 技术栈说明
• 代码规范和风格指南
• 目录结构约定
• 依赖管理方式
• 测试策略与命令
• 特有的业务规则

可以把它理解为 Codex 的"项目级系统提示词"——它不会直接生成代码，但会影响 Codex 生成代码时的每一个决策。

基础用法：创建你的第一个 AGENTS.md

1. 在项目根目录创建文件

touch AGENTS.md

Codex 会从项目根目录递归向上查找 AGENTS.md 文件，直到找到一个或到达文件系统根目录。这意味着你可以在单体仓库（monorepo）的子目录中放置独立的 AGENTS.md。

2. 编写基础内容

一个最小可用的 AGENTS.md 大概长这样：

# 项目概述

这是一个基于 Laravel 10 的电商后端 API 项目，使用 MySQL 作为主数据库，Redis 作为缓存。

## 技术栈

- PHP 8.2
- Laravel 10.x
- MySQL 8.0
- Redis 7.x
- Docker Compose 用于本地开发环境

## 代码规范

- 使用 PSR-12 代码风格
- 数据库迁移文件命名遵循 `yyyy_mm_dd_hhmmss_描述.sql` 格式
- 所有 API 响应统一使用 `ApiResponse` 类包装
- 控制器方法不超过 7 行，业务逻辑放在 Service 层

## 测试

- 使用 PHPUnit
- 运行测试命令：`php artisan test`
- 功能测试放在 `tests/Feature/` 目录
- 确保新功能有对应的测试覆盖

保存后，当你在这个项目中与 Codex 交互，它就会自动遵循这些约定。

AGENTS.md 的文件结构设计

一个好的 AGENTS.md 应该层次分明、信息密度高。推荐以下结构：

# [项目名称]

简短的项目描述（1-2 句话）。

## 技术栈

列出主要技术栈，帮助 Codex 确定语言、框架、数据库等上下文。

## 项目结构

说明关键目录的作用，帮助 Codex 理解代码组织方式。

## 编码规范

团队约定的代码风格、命名规范、注释规范等。

## 工作流程

开发、构建、测试、部署的命令和流程。

## 注意事项

特殊的业务逻辑、已知的坑、性能注意事项等。

一个真实的 Laravel 项目示例

# ShopAPI - 电商后端服务

为移动端和 Web 端提供 RESTful API 的电商系统。

## 技术栈

- PHP 8.2 + Laravel 10
- MySQL 8.0（主库）+ Redis（缓存 / 队列）
- 队列驱动：Redis（通过 Laravel Horizon 管理）
- 全文搜索：Meilisearch
- 对象存储：AWS S3（通过 Flysystem 抽象）
- API 文档：Scribe（自动生成）

## 项目结构

- `app/Models/` — Eloquent 模型
- `app/Services/` — 业务逻辑层，所有复杂逻辑放这里
- `app/Http/Controllers/` — 控制器，仅做参数验证和响应封装
- `app/Http/Requests/` — 表单验证类，每个请求独立一个类
- `app/Jobs/` — 异步任务
- `app/Enums/` — PHP 8.1 枚举类
- `database/migrations/` — 数据库迁移

## 编码规范

- 严格遵循 PSR-12
- 类名使用帕斯卡命名（PascalCase），方法名使用驼峰命名（camelCase）
- 数据库字段使用蛇形命名（snake_case）
- 每个 Service 方法必须声明返回类型
- 使用 Repository 模式封装数据库操作
- 禁止在控制器中直接写 SQL 查询

## 关键命令

本地开发

./vendor/bin/sail up -d

运行测试

./vendor/bin/sail test

代码格式化

./vendor/bin/pint

静态分析

./vendor/bin/phpstan analyse

生成 API 文档

php artisan scribe:generate

队列处理

php artisan horizon

## API 约定

- 所有响应格式为 `{ "code": 0, "message": "success", "data": {} }`
- 错误码定义在 `app/Enums/ErrorCode.php`
- 分页参数统一使用 `page` 和 `per_page`
- 需要用户认证的接口通过 `auth:sanctum` 中间件保护

进阶技巧

1. 指定不被修改的文件

如果你有一些自动生成的文件或敏感的配置文件不希望 Codex 改动，可以在 AGENTS.md 中明确说明：

## 禁止修改的文件

- `config/services.php` — 包含生产环境密钥，通过环境变量注入
- `routes/api.php` — 路由文件通过 OpenAPI 规范自动生成，请勿手改
- `public/build/` — 前端构建产物，由 CI 自动生成

2. 指定项目依赖来源

Codex 在生成代码时可能会引入第三方包。提前声明包管理偏好可以避免"自己发明轮子"：

## 依赖管理偏好

- HTTP 客户端：优先使用 Laravel HTTP Client，避免直接用 Guzzle
- Excel 处理：使用 `maatwebsite/excel`
- 权限管理：使用 `spatie/laravel-permission`
- 图片处理：使用 `intervention/image`
- 日期处理：优先使用 Carbon

3. 数据库迁移约定

明确的迁移规范能避免 Codex 生成不合规的迁移代码：

## 数据库约定

- 所有表名使用复数形式（`users`, `orders`, `products`）
- 外键命名格式：`{表名}_{字段名}_foreign`
- 索引命名格式：`{表名}_{字段名}_index`
- 时间戳字段统一使用 `$table->timestamps()` 和 `$table->softDeletes()`
- 金额字段使用 `decimal(10, 2)`，单位为人民幣「元」

4. 多语言 / 国际化

如果你的项目支持多语言，告诉 Codex 可以避免硬编码字符串：

## 国际化（i18n）

- 所有用户可见的文本必须通过 `__()` 或 `@lang()` 函数输出
- 翻译文件位置：`lang/{locale}/messages.php`
- 默认语言：zh_CN
- 支持语言：zh_CN, en, ja

你的 AGENTS.md 实际是如何被使用的？

当你运行 codex 并开始一段对话时，Codex 会执行以下步骤：

发现阶段：从当前工作目录向上遍历，查找 AGENTS.md 文件

加载阶段：将 AGENTS.md 的内容作为上下文注入到 AI 模型的系统提示中

交互阶段：在你的每一次追问中，AGENTS.md 的内容都会作为"背景知识"持续生效

这意味着 AGENTS.md 不是一次性的——它会影响整个会话中 Codex 的所有行为。

验证 AGENTS.md 是否生效

你可以用一句话来验证 AGENTS.md 是否被正确加载：

codex "根据项目规范，我应该用什么命令来运行测试？"

如果 Codex 能准确回答你在 AGENTS.md 中定义的测试命令（比如 php artisan test），那就说明配置生效了。

最佳实践

1. 保持简洁

AGENTS.md 不是项目文档，不需要长篇大论。每个模块用 2-3 句话说明即可。大模型的上下文窗口虽然很大，但信息密度越高，AI 越容易抓住重点。

2. 定期更新

项目在演进，AGENTS.md 也要跟上。建议把 AGENTS.md 的更新纳入 Code Review 流程——每当你引入新的技术栈或修改了编码规范，同步更新 AGENTS.md。

3. 按团队规模分层

• 个人项目：一份全局的 AGENTS.md 就够用，放在仓库根目录
• 小团队项目：根目录一份主 AGENTS.md，各服务目录根据需要补充
• 大型单体仓库：每个子项目都应该有自己的 AGENTS.md

4. 不要写显而易见的事情

不需要写"使用 Git 进行版本控制"或"代码要写注释"这种废话。把宝贵的上下文留给真正关键的信息。

5. 善用代码块

命令行、配置示例、代码片段都应该放在代码块里，方便 AI 精确解析：

## 构建与部署

安装依赖

composer install --no-dev

编译前端资源

npm run build

优化自动加载

composer dump-autoload --optimize

缓存配置

php artisan config:cache
php artisan route:cache
php artisan view:cache

常见问题

Q: 我可以在 AGENTS.md 中放敏感信息吗？

绝对不要！AGENTS.md 是纯文本文件，通常会被提交到 Git 仓库中。任何 API 密钥、数据库密码、内部 IP 地址等敏感信息都应通过环境变量管理。

Q: Codex 没有按照我的 AGENTS.md 执行怎么办？

首先检查文件是否在正确的位置（项目根目录或父目录）。其次，检查你的指令是否足够明确和具体。模糊的指令（如"写好代码"）AI 无法执行；具体的指令（如"使用 PSR-12 标准，每个方法不超过 30 行"）效果更好。

如果问题仍然存在，可以尝试在对话中明确引用你的 AGENTS.md：

请仔细阅读 AGENTS.md 中的编码规范，然后帮我实现这个功能。

Q: AGENTS.md 支持继承吗？

Codex 会从当前目录向上查找 AGENTS.md，最接近当前目录的文件优先级最高。但 Codex 不会自动合并多个 AGENTS.md——它使用的是找到的第一个文件。

总结

AGENTS.md 是连接你的项目现实和 AI 编程能力之间的桥梁。一份精心编写的 AGENTS.md 能让 Codex 从一个"通用代码生成器"变成一个"懂你项目的专属程序员"。

写好 AGENTS.md 不需要复杂的技术，需要的是对你项目的深入理解和对 AI 行为的合理预期。建议你今天就在正在工作的项目中创建一个 AGENTS.md，从技术栈和关键命令开始，然后逐步丰富。

当你习惯了这种工作方式，你会发现 Codex 生成代码的质量和相关性会有质的飞跃——因为它终于"认识"你的项目了。