Codex AGENTS.md 与项目规范配置：让 AI 从一开始就懂你的项目

Codex AGENTS.md 与项目规范配置：让 AI 从一开始就懂你的项目并不只看表面做法，关键还要理解相关条件、限制和后续影响。

---

一、为什么需要 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/projecttouch AGENTS.md

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

也是项目根目录。

touch codex.md

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

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

model: o4-miniapproval-policy: on-failuresandbox-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# ？？？我用的是 FastAPIdef register_user():# 路由呢？装饰器呢？# 写了 SQLAlchemy 同步代码# 测试用了 unittest

有 AGENTS.md

你：帮我加一个用户注册接口Codex：（读取了 AGENTS.md 后）from fastapi import APIRouter, Dependsfrom sqlalchemy import selectfrom app.schemas.user import UserCreate, UserResponserouter = 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，把外部上下文带到代码中。

---

七、最佳实践总结

项目一开始就写好 AGENTS.md——晚写不如早写，Codex 第一次接触项目时就对了具体优于抽象——不说"写好代码"，说"每个函数写类型注解和 docstring"覆盖率比完美重要——先写 80% 的规范，比追求 100% 完美但不写强随项目进化——AGENTS.md 不是一次写完就不动的，项目加了新工具就更新和 husky/lint-staged 配合——AGENTS.md 管 Codex 的代码风格，lint-staged 管提交前的检查，双保险

---

八、一句话总结