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

佚名 2026-08-11 11:46:56

你有没有这样的经历——让 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/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() 旧风格

可以写的

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