官方原文索引： Codex Quickstart / Best Practices / Use Cases
1. 核心架构与原理解析
Codex 的 Agentic Workflow 遵循**"理解 → 规划 → 执行 → 验证"**四阶段循环。对于初学者，掌握如何描述任务边界比掌握命令更重要：
高效任务描述的 RICE 框架：
| 要素 | 说明 | 示例 |
|---|---|---|
| Range | 明确文件/目录范围 | "只在 src/auth/ 目录下修改" |
| Intent | 描述目标而非步骤 | "修复登录超时问题" 而非 "把 timeout 改成 5000" |
| Constraints | 列出限制条件 | "不要修改接口返回结构" |
| Evidence | 指定验证方式 | "修改后运行 npm test" |
2. 工程落地与代码示例
任务 1：理解项目结构（只读）
codex --sandbox read-only
> 请阅读当前项目结构，告诉我：
> 1. 主要技术栈和架构模式
> 2. 入口文件在哪里
> 3. 测试目录结构
> 不要修改任何文件。预期输出：
## 项目分析
**技术栈：** Node.js + Express + TypeScript + Prisma
**架构模式：** MVC（Model-View-Controller）
**关键文件：**
- 入口：`src/server.ts`
- 路由：`src/routes/`
- 模型：`src/models/`
- 测试：`tests/`（Jest）
**测试结构：**
- `tests/unit/` - 单元测试
- `tests/integration/` - 集成测试
- 覆盖率：约 65%（建议提升到 80%+）任务 2：修复具体 Bug（自动编辑）
codex --full-auto
> src/utils/validation.ts 中的 email 校验函数
> 没有处理包含 + 号的邮箱（如 [email protected]）。
> 要求：
> 1. 修复正则表达式
> 2. 在 tests/validation.spec.ts 补充对应测试用例
> 3. 运行测试确认通过预期执行流程：
任务 3：生成项目文档（安全模式）
codex --full-auto
> 基于当前项目结构，生成 README.md：
> 1. 项目简介
> 2. 本地启动步骤
> 3. 环境变量说明（参考 .env.example）
> 4. 目录结构说明
> 先给我看大纲，确认后再写入文件。任务 4：审查代码（Read Only）
codex --sandbox read-only
> 检查 src/payment/ 目录下的所有文件，找出：
> 1. 明显的安全隐患（如 SQL 注入、硬编码密钥）
> 2. 缺少错误处理的异步操作
> 3. 不符合 PEP8 的命名（如果是 Python）
> 输出格式：文件名 + 行号 + 问题描述 + 修复建议任务 5：依赖升级与验证
codex --full-auto
> 将 lodash 从 3.x 升级到 4.x：
> 1. 更新 package.json 中的版本号
> 2. 检查并修复已废弃的 API 调用
> 3. 运行完整测试套件确认无回归
> 4. 生成升级变更摘要3. 场景深入：新手常见任务模式
模式 A：探索式学习
模式 B：防御性修复
模式 C：增量改进
# 不要一次性大改，小步快跑
# 第 1 天
codex "为 utils/date.ts 添加单元测试"
# 第 2 天
codex "重构 auth.ts 的错误处理，使用统一格式"
# 第 3 天
codex "将重复的 API 调用提取到 apiClient.ts"4. 💡 核心避坑与最佳实践 (Takeaways)
- 从小任务开始磨合：不要一上来就"重构整个系统"，先修 Bug、补注释、写测试建立信任
- 限定范围比限定步骤更重要：告诉 Codex "改什么" 和 "不改什么"，比教它 "怎么改" 效果更好
- 要求验证形成闭环：每个修改任务末尾加上 "运行测试确认"，防止 Agent 改完不验证
- 先
/plan后执行：复杂任务先让 Codex 出方案，确认思路正确再允许写入 - 使用 RICE 框架描述任务：Range + Intent + Constraints + Evidence = 精准产出
- 保留中间检查点：每完成一个子任务就
git commit，便于回滚和审查