Codex中AGENTS.md文件编写与项目配置的完整指南

你有没有过这样的体验——让 Codex 写代码，结果它抛出一套陌生的规范、迥异的风格，甚至完全陌生的命名逻辑？这真不是它能力不足，根本原因在于，你忘了告诉它

。

AGENTS.md 就是干这个的：一份文件，告诉 Codex 你的项目规约，它照做。

一、为什么需要 AGENTS.md？

Codex 默认会用 OpenAI 的最佳实践来写代码。但你的项目有自己的规则：

• 缩进
  ：2 空格还是 4 空格？

• 命名
  ：camelCase 还是 snake_case？

• 导入顺序
  ：标准库→第三方→本地？

• 测试框架
  ：pytest 还是 unittest？

• 数据库 ORM
  ：SQLAlchemy 还是 Prisma？

不写 AGENTS.md，Codex 每次都要猜。有时候猜对了，有时候猜错了——体验不稳定。

写了之后：

二、AGENTS.md 的存放位置

Codex 支持两种配置文件：

方式 A：AGENTS.md（推荐，跨工具通用）

放在项目根目录。Aider、Cursor 也读这个格式。

cd /path/to/your/project
touch AGENTS.md

方式 B：codex.md（Codex 专属）

也是项目根目录。

touch codex.md

——不仅 Codex 用，其他 AI 编程工具也能识别，换工具不用重新写。

全局配置：~/.codex/config.yaml

model: o4-mini
approval-policy: on-failure
sandbox-mode: workspace-write

全局配置对所有项目生效，项目级配置覆盖全局配置。

三、AGENTS.md 应该写什么

必须写的

# AGENTS.md
## 项目信息
项目名称：my-api
项目描述：电商后台 API 服务
技术栈：Python FastAPI + PostgreSQL + Redis
## 代码规范
- Python 版本：3.12
- 缩进：4 空格
- 字符串：双引号
- 类型注解：所有公共函数必须写
- 命名：snake_case（变量/函数），PascalCase（类）
- 导入顺序：标准库 → 第三方 → 本地模块（每组空一行）
## 测试
- 框架：pytest
- 覆盖率：不低于 80%
- 测试文件命名：test_*.py
- 每个 API 端点必须有集成测试
## 数据库
- ORM：SQLAlchemy 2.0（异步模式）
- 迁移：Alembic
- 所有模型类放在 models/ 目录
- 查询优先用 select()，避免 query() 旧风格

推荐写的

## 关键命令
- `make dev` — 启动开发服务器
- `make test` — 跑全部测试
- `make lint` — ruff 检查
- `make db-migrate` — 数据库迁移
## 架构约定
- API 路由放在 routers/ 目录
- 业务逻辑放在 services/ 目录
- 数据模型放在 models/ 目录
- Schema 定义放在 schemas/ 目录
## 错误处理
- 所有 API 返回统一格式：{"code": int, "message": str, "data": any}
- 业务异常继承 AppException 基类
- 全局异常捕获中间件处理已知异常
## 日志
- 使用 structlog，不直接 print
- 关键操作记录 audit 日志
- 错误日志包含 trace_id 用于链路追踪

可以写的

## 编码偏好
- 列表推导优先于 map/filter
- 异常处理：精准捕获，不裸用 except:
- 配置管理：Pydantic Settings
- API 文档：自动生成（FastAPI 自带）
## 项目结构
project/
├── app/
│   ├── api/          # 路由层
│   ├── core/         # 核心配置
│   ├── models/       # 数据模型
│   ├── schemas/      # Pydantic Schema
│   ├── services/     # 业务逻辑
│   └── main.py       # 入口
├── tests/
├── alembic/
├── AGENTS.md
└── pyproject.toml

四、实际效果对比

没有 AGENTS.md

你：帮我加一个用户注册接口
Codex：import Flask  # ？？？我用的是 FastAPI
        def register_user():  # 路由呢？装饰器呢？
        # 写了 SQLAlchemy 同步代码
        # 测试用了 unittest

有 AGENTS.md

你：帮我加一个用户注册接口
Codex：（读取了 AGENTS.md 后）
        from fastapi import APIRouter, Depends
        from sqlalchemy import select
        from app.schemas.user import UserCreate, UserResponse
        router = APIRouter(prefix="/users", tags=["users"])
        @router.post("/register", response_model=UserResponse)
        async def register_user(data: UserCreate, db: AsyncSession = Depends(get_db)):
            """用户注册"""
            # 业务逻辑...
            # 测试用了 pytest + httpx

从"猜你要什么"变成了"按你的规矩来"。

五、进阶：条件规则

AGENTS.md 还支持条件写法：

## 如果是前端开发
- 使用 TypeScript strict 模式
- React 函数组件 + Hooks
- Tailwind CSS 优先
- 不用 class 组件
## 如果是后端开发
- 使用 Python 3.12+
- FastAPI + Pydantic v2
- 异步优先
- SQLAlchemy 2.0 select() 模式
## 如果是数据库变更
- 必须写 Alembic migration
- 向下兼容：不删已有列
- 大表变更走迁移脚本回滚方案

六、多 MCP 服务器配置（config.toml）

如果你需要 Codex 访问外部系统，在项目根目录创建 config.toml：

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }

这样 Codex 可以直接查数据库、读 GitHub Issues，把外部上下文带到代码中。

七、最佳实践总结

1. 项目一开始就写好 AGENTS.md
   ——晚写不如早写，Codex 第一次接触项目时就对了

2. 具体优于抽象
   ——不说"写好代码"，说"每个函数写类型注解和 docstring"

3. 覆盖率比完美重要
   ——先写 80% 的规范，比追求 100% 完美但不写强

4. 随项目进化
   ——AGENTS.md 不是一次写完就不动的，项目加了新工具就更新

5. 和 husky/lint-staged 配合
   ——AGENTS.md 管 Codex 的代码风格，lint-staged 管提交前的检查，双保险

八、一句话总结

你不主动定义规则，它只能靠猜；但只要你把指令写清楚，它就能精准执行。实践证明，一份仅需 50 行的配置文件，足以削减高达 80% 的无效沟通与反复修改成本。