Codex 最佳实践
Codex 的价值不在于一次性替人完成所有工作，而在于把明确的工程任务变成可审查、可验证、可提交的改动。高质量 Codex 协作通常包含四件事：稳定上下文、清晰边界、可运行验证、持续反馈。
1. 先给项目规则，再给具体任务
Codex 会优先使用仓库中的项目说明。新项目建议先补齐：
text
AGENTS.md
README.md
docs/project/requirements.md
docs/project/acceptance.md
docs/project/architecture.md
docs/project/test-strategy.md其中 AGENTS.md 是 Codex 最重要的项目级说明文件。它应该写清：
- 项目目标和当前版本范围。
- 技术栈和禁止新增的技术。
- 常用命令。
- 哪些目录不能改。
- 什么算完成。
- 安全、测试和 Git 规则。
2. 把任务写成可验证改动
不推荐：
text
帮我做一个后台管理系统。推荐：
text
请实现任务列表的筛选功能。
范围：
- 只修改 src/features/tasks 和相关测试。
- 支持按 status、owner、priority 筛选。
- 不新增后端接口。
验收：
- 筛选条件可以组合。
- 空结果显示明确提示。
- npm run test 和 npm run build 通过。清晰任务能减少无关文件改动，也方便人类审查。
3. 复杂任务先分析，不立刻改代码
当任务涉及架构、权限、数据结构或多目录改动时，先让 Codex 分析：
text
请先阅读 AGENTS.md、README.md 和 docs/project/*.md。
只分析，不改文件。
请输出：
1. 你理解的目标
2. 可能修改的文件
3. 风险点
4. 验证命令
5. 分步计划确认计划后再进入实现：
text
按计划实现第 1 步。完成后运行相关验证，并说明结果。4. 保持小步提交
适合 Codex 的节奏是“小目标、小 diff、小验证”：
| 任务类型 | 建议粒度 | 验证方式 |
|---|---|---|
| 文档 | 一个主题或一个栏目 | npm run docs:build |
| UI | 一个页面或一个交互 | 浏览器 smoke test + build |
| API | 一个 endpoint 或一个 service | 单元测试 + 集成测试 |
| 重构 | 一个模块边界 | 原测试 + 类型检查 |
| 安全 | 一个风险面 | 负向用例 + review |
5. 让 Codex 报告证据
最终回复应包含：
- 修改了哪些文件。
- 运行了哪些命令。
- 命令是否通过。
- 有哪些没有验证的风险。
- 是否还有未提交或未处理的工作。
可以直接要求：
text
完成后请用中文说明变更、验证结果、剩余风险，并提交 Git。6. 用沙箱和权限约束降低风险
Codex 运行时可能受沙箱、网络、文件系统权限影响。项目规则应说明：
- 是否允许安装依赖。
- 是否允许访问网络。
- 是否允许写入构建产物。
- 是否允许执行数据库迁移。
- 哪些命令需要先征求确认。
对生产环境、密钥、数据库、支付、权限系统的改动，要把验收标准写得更严格。
7. Code review 优先看风险
要求 Codex 审查时，不要只让它总结“改了什么”，而要让它先找问题：
text
请按代码审查模式检查当前 diff。
优先指出 bug、行为回归、安全风险、缺失测试和部署风险。
findings 在前，摘要在后。课堂实践
- 先打开 AGENTS.md 初始化示例。
- 把示例复制到演示项目根目录。
- 创建
docs/project/requirements.md和docs/project/acceptance.md。 - 让 Codex 只分析，不改文件。
- 确认计划后再让 Codex 实现最小可用版本。