Codex中AGENTS.md文件编写与项目配置的完整指南
来源：互联网
时间：2026-08-11 07:13:08
你有没有过这样的体验——让 Codex 写代码，结果它抛出一套陌生的规范、迥异的风格，甚至完全陌生的命名逻辑？这真不是它能力不足，根本原因在于，你忘了告诉它
你的项目到底是怎么写的
AGENTS.md 就是干这个的：一份文件，告诉 Codex 你的项目规约，它照做。
一、为什么需要 AGENTS.md？
Codex 默认会用 OpenAI 的最佳实践来写代码。但你的项目有自己的规则：
- ：2 空格还是 4 空格？
缩进
- ：camelCase 还是 snake_case？
命名
- ：标准库→第三方→本地？
导入顺序
- ：pytest 还是 unittest？
测试框架
- ：SQLAlchemy 还是 Prisma？
数据库 ORM
不写 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/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，把外部上下文带到代码中。
七、最佳实践总结
- ——晚写不如早写，Codex 第一次接触项目时就对了
项目一开始就写好 AGENTS.md
- ——不说"写好代码"，说"每个函数写类型注解和 docstring"
具体优于抽象
- ——先写 80% 的规范，比追求 100% 完美但不写强
覆盖率比完美重要
- ——AGENTS.md 不是一次写完就不动的，项目加了新工具就更新
随项目进化
- ——AGENTS.md 管 Codex 的代码风格，lint-staged 管提交前的检查，双保险
和 husky/lint-staged 配合
