005 codex.yaml 项目管理
用 codex.yaml 统一团队编码标准，让 Codex 精准适配你的每个项目。
学习目标
完成本课程后，你将能够：
一、什么是 codex.yaml
`codex.yaml` 是 Codex CLI 的项目配置文件，功能类似于 Claude Code 的 CLAUDE.md 文件或 Cursor 的 `.cursorrules`。它告诉 Codex：
- 这个项目是什么技术栈
- 遵循什么编码规范
- 使用什么默认模型
- 有哪些自定义指令
Codex 启动时会**自动读取**当前目录及父级目录中的 `codex.yaml`，并据此调整行为。
二、配置层级与优先级
Codex 支持三级配置，优先级从高到低：
1. 项目级 codex.yaml （最高优先级）
2. 父目录级 codex.yaml （中优先级，向上查找）
3. 全局级 ~/.codex/codex.yaml （最低优先级，兜底配置）配置加载逻辑
当你在 `/home/user/projects/my-app/src/components/` 目录下启动 Codex，它会依次查找：
- `./codex.yaml`（当前目录）
- `../codex.yaml`（父目录，项目根目录）
- `../../codex.yaml`（继续向上，直到文件系统根）
- `~/.codex/codex.yaml`（全局兜底）
就近的配置会**覆盖**远处配置中的同名字段。
三、完整配置示例
项目级 codex.yaml（推荐配置）
# ============================================================
# codex.yaml — 项目级配置
# 位置：项目根目录
# ============================================================
# —— 基础设置 ——
model: o4-mini # 默认模型：GPT-4o | o4-mini
language: zh-CN # 交互语言：zh-CN | en-US
# —— 项目信息 ——
project:
name: trustcargo-platform
type: web # web | cli | library | mobile | desktop
framework: next.js # 主框架名称
version: "14.2"
language: typescript
package_manager: pnpm # npm | yarn | pnpm | bun
# —— 编码风格 ——
style:
indent: 2 # 缩进空格数
quotes: single # single | double
semi: true # 是否使用分号
trailing_comma: es5 # none | es5 | all
max_line_length: 100
# —— 命名规范 ——
naming:
files: kebab-case # kebab-case | camelCase | PascalCase | snake_case
components: PascalCase
functions: camelCase
constants: UPPER_SNAKE_CASE
types: PascalCase
# —— 技术栈约束 ——
constraints:
no_any_type: true # 禁止使用 TypeScript any 类型
prefer_async_await: true # 优先使用 async/await
require_error_handling: true # 必须处理异常
max_function_lines: 80 # 单个函数最大行数
max_file_lines: 400 # 单个文件最大行数
# —— 自定义指令 ——
instructions: |
你是一名熟悉跨境物流业务的全栈工程师。
本项目使用以下技术栈：
- 前端：Next.js 14 + TypeScript + Tailwind CSS + Zustand
- 后端：Next.js API Routes + Prisma ORM + PostgreSQL
- 测试：Vitest + Playwright
- 部署：Vercel + Docker
编码时请遵循以下规则：
1. 所有 API 路由使用 Server Components 优先策略
2. 数据库查询使用 Prisma，不要写原始 SQL
3. 组件拆分粒度：每个组件只做一件事
4. 优先复用 src/components/ui/ 下的已有组件
5. 修改数据库 schema 后必须生成新的 migration
6. 金额单位统一为"分"（避免浮点数精度问题）
# —— MCP 服务器 ——
mcp:
enabled: true
servers:
- name: database
command: npx
args: ["-y", "@codex/mcp-server-postgres"]
env:
DATABASE_URL: "${DATABASE_URL}"
# —— Hooks ——
hooks:
pre_commit:
- command: "pnpm lint"
description: "提交前运行 lint"
- command: "pnpm typecheck"
description: "提交前检查类型"全局级配置（~/.codex/codex.yaml）
# 全局默认配置，应用于所有项目
model: o4-mini
language: zh-CN
style:
indent: 2
quotes: single
semi: true
# 全局约束（可被项目级覆盖）
constraints:
no_any_type: true
prefer_async_await: true四、自定义指令最佳实践
`instructions` 字段是 codex.yaml 中最强大的部分。它相当于给 Codex 写了一份"入职手册"。
应该写什么
| 类别 | 示例内容 |
|---|---|
| 业务领域知识 | "支付状态包括：pending, paid, refunded, partial_refund" |
| 架构决策 | "API 路由统一返回 { code, data, message } 格式" |
| 命名约定 | "React Hook 必须以 use 开头，事件处理器以 handle 开头" |
| 禁止事项 | "不要引入超过 50KB 的 npm 包" |
| 文件组织 | "API 路由文件放 src/app/api/，业务逻辑放 src/services/" |
| 测试规范 | "每个 service 函数必须有对应的 .test.ts 文件" |
指令编写技巧
- **具体，不用抽象**：不说"写出好代码"，而是"每个函数必须有 JSDoc 注释"
- **可验证**：每条规则 Codex 都应该能自行检查
- **按优先级排序**：最重要的规则放在前面
- **迭代更新**：每次发现 Codex 犯了重复错误，就加一条规则
五、多项目管理
策略一：全局兜底 + 项目覆盖
~/.codex/codex.yaml ← 通用规则（缩进、分号、禁止 any）
~/projects/project-a/codex.yaml ← 项目 A 特有规则（Vue 生态、Element Plus）
~/projects/project-b/codex.yaml ← 项目 B 特有规则（React 生态、Ant Design）策略二：Monorepo 场景
~/monorepo/codex.yaml ← 大仓通用规则
~/monorepo/apps/web/codex.yaml ← Web 应用特有规则
~/monorepo/apps/mobile/codex.yaml ← 移动端特有规则
~/monorepo/packages/shared/codex.yaml ← 共享包特有规则策略三：模板复用
# 创建项目模板
mkdir -p ~/templates/codex
# 为不同类型项目准备模板
~/templates/codex/nextjs.yaml # Next.js 项目模板
~/templates/codex/express.yaml # Express 项目模板
~/templates/codex/cli.yaml # CLI 工具模板
# 新建项目时复制
cp ~/templates/codex/nextjs.yaml ./codex.yaml六、本课总结
**核心要点：**
- codex.yaml 是 Codex 的"项目入职手册"，启动时自动读取
- 三级配置：项目级 > 父目录级 > 全局级，就近覆盖
- `instructions` 字段是配置灵魂——将团队规范写成可执行规则
- 多项目用"全局兜底 + 项目覆盖"策略管理
- 每次发现 Codex 重复犯同一个错误，就更新 codex.yaml
**下一步：** 最后一课将进入实战，用 Codex 从零搭建一个 Next.js 项目开发环境，并完成第一个编码任务。