Codex 高级使用说明（实战版）

目标：让 Codex 更稳定地产出“可运行、可维护、少返工”的代码。

1. 一句话原则

• 你给得越具体，输出越可控。
• 先约束“目标和边界”，再让 Codex 写代码。
• 每次只做一件事：需求、实现、验证、评审分阶段推进。

---

2. 高质量提问框架（推荐模板）

直接复制下面模板改一改即可：

你是我的结对工程师，请按以下要求执行：

【任务目标】
- 要做什么：
- 成功标准（可验收）：

【技术上下文】
- 项目/语言/框架：
- 关键文件路径：
- 现有行为：

【硬约束】
- 不允许改动：
- 必须兼容：
- 代码风格/规范：
- 性能/安全要求：

【输出要求】
1. 先给实现方案（3-6条，简短）
2. 再直接修改代码
3. 列出改动文件与关键差异
4. 提供验证步骤和命令
5. 给出潜在风险与回滚方案

---

3. 话术编排技巧（核心）

3.1 先定“验收标准”，不要只说“帮我优化下”

差的说法：

帮我优化这个接口代码。

好的说法：

请把 `src/api/order.ts` 的 `createOrder` 重构为：
1. 参数校验失败返回 400（含字段名）
2. 数据库失败返回 503（不泄漏 SQL 错误）
3. 新增单元测试覆盖 4 个分支
4. 保持现有接口签名不变

3.2 用“禁止项”减少跑偏

不要改动：
- 路由定义文件
- 数据库表结构
- UI 文案

3.3 把“完成定义（DoD）”写清楚

完成标准：
- `npm test` 全通过
- `npm run lint` 无新增告警
- 核心函数圈复杂度不高于 10

---

4. 让代码质量明显提升的 8 个指令习惯

1. 先读后改
   先阅读相关文件，输出你的理解，再开始改动。

2. 先方案后实现
   先给最小可行方案，再编码；不要一次大改。

3. 限制改动范围
   仅允许改动以下文件：...

4. 显式要求测试
   必须补充单元测试，并说明覆盖了哪些分支。

5. 要求兼容性说明
   列出对现有 API/数据结构的兼容性影响。

6. 要求失败处理
   所有外部调用必须有超时、重试或降级策略。

7. 要求可观测性
   关键路径增加日志/埋点，避免输出敏感信息。

8. 要求自检清单
   提交前给出 checklist：功能、边界、异常、性能、安全。

---

5. 四步协作流程（推荐）

Step 1：探索

先不要写代码。请先：
1. 扫描相关模块
2. 找出风险点
3. 给我 2 个可行实现方案（含取舍）

Step 2：落地

按方案 B 实现，要求最小改动。
每改完一个文件，说明改动目的。

Step 3：验证

请运行测试/静态检查（或给我可执行命令），
并按“通过/失败/原因/修复建议”格式汇报。

Step 4：评审

请做一次严格 code review：
- 先列严重问题
- 再列中低风险
- 最后给改进建议

---

6. 常用高阶 Prompt 模板（可直接复用）

模板 A：精准修 Bug

修复一个线上 bug：
- 现象：...
- 复现步骤：...
- 期望行为：...
- 影响范围：...
- 约束：不改接口签名，不改数据库

请输出：
1. 根因分析
2. 最小修复方案
3. 代码改动
4. 回归测试清单

模板 B：安全加固

请审查 `src/` 下与鉴权相关代码，重点检查：
- 鉴权绕过
- 注入风险
- 敏感信息泄漏

输出格式：
1. 风险等级（高/中/低）
2. 证据（文件+行）
3. 修复建议（含代码）

模板 C：重构但不改变行为

请重构 `xxx` 模块，目标是可读性和可测试性提升。
硬约束：外部行为 100% 不变（输入输出一致）。

请先给重构计划（分 3 步），每步可独立提交。

模板 D：生成新功能（防止“伪完成”）

实现新功能：...

必须交付：
- 功能代码
- 单元测试
- README 片段（使用方式）
- 错误处理策略
- 已知限制

---

7. 常见误区与修正

• 误区：“帮我写个登录”
  修正：补齐鉴权方式、token 生命周期、失败策略、风控要求。

• 误区：一次性要求“大重构 + 新功能 + 全量测试”
  修正：拆成多轮，小步快跑，每轮可验证。

• 误区：只看“能跑”不看“可维护”
  修正：强制要求测试、日志、异常处理、边界条件说明。

---

8. 你可以直接用的“万能开场白”

从现在开始你是我的高级工程师搭档。
请遵循：
1. 不确定的地方先标注假设，不要硬编
2. 先读代码再改代码
3. 优先最小改动，避免无关重构
4. 所有修改都解释“为什么”
5. 给出验证命令与预期结果

如果发现需求有歧义，先给 2 个可选方案及影响，再执行默认推荐方案。

---

9. 快速检查清单（发给 Codex 前先看）

• 我是否写清了目标和完成标准？
• 我是否给了文件路径和技术上下文？
• 我是否写了“不允许改动”的边界？
• 我是否要求了测试与验证方式？
• 我是否要求输出风险和回滚方案？

---

10. 推荐协作节奏（短）

1. 先让 Codex “读 + 方案”
2. 再让 Codex “小步实现”
3. 再让 Codex “测试 + review”
4. 最后你做业务验收

这套节奏通常比“上来就一把梭”更快、更稳、更少返工。