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

时间：2026-08-12 | 作者：星河游者 | 阅读：0

你有没有过这样的体验——让 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

推荐用 AGENTS.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() 旧风格

可以写的

## 编码偏好
- 列表推导优先于 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，把外部上下文带到代码中。