官方原文索引： Prompting – Codex / Codex Prompting Guide / Best Practices
1. 核心架构与原理解析
Codex 的 Prompt 处理遵循**"意图识别 → 上下文加载 → 任务规划 → 执行"**四阶段。优质的 Prompt 能显著降低 Token 消耗和提升结果准确率。
Prompt 信息熵优化原则：
| 低效写法 | 高效写法 | 原因 |
|---|---|---|
| "优化一下代码" | "将 src/legacy/auth.js 的回调地狱重构为 async/await，保持接口不变" | 范围 + 目标 + 约束 |
| "写个测试" | "为 calculateTax 函数补充单元测试：覆盖正数、零、负数、非数字输入" | 具体场景枚举 |
| "修复 Bug" | "用户反馈上传 >10MB 文件返回 500。定位错误处理路径，修复并补充测试" | 上下文 + 验证方式 |
2. 工程落地与代码示例
RICE 任务描述模板
## Range（范围）
- 修改范围：`src/payment/` 目录
- 禁止修改：`src/payment/gateway/`（第三方集成，风险高）
## Intent（意图）
- 为所有支付相关函数添加统一的幂等性校验（idempotency key）
## Constraints（约束）
- 保持现有数据库 schema 不变
- 兼容现有 API 响应格式
- 使用 `neverthrow` 的 `Result<T, E>` 模式处理错误
## Evidence（验证）
- 修改后运行 `npm run test:payment`
- 所有现有测试必须继续通过
- 新增测试覆盖幂等性场景上下文管理技巧
# 技巧 1：用 @ 引用替代粘贴
> 检查 @src/auth.ts 第 45-60 行的 JWT 校验逻辑
# 技巧 2：管道输入外部上下文
git log --oneline -20 | codex exec "分析最近的提交模式，是否有重复修同一 Bug 的情况"
# 技巧 3：分阶段交付（降低上下文膨胀）
> /plan "重构用户模块"
# 确认方案后...
> 按方案第一步执行：提取 Repository 层
# 完成后...
> 继续执行第二步：重写 Service 层角色扮演模式
# 让 Codex 扮演特定角色，提升输出质量
> 扮演一名资深安全审计员，审查 @src/auth.ts：
> 1. 找出所有 OWASP Top 10 相关风险
> 2. 按 CVSS 评分排序
> 3. 给出具体修复代码片段
# 扮演架构师做技术选型
> 扮演一名系统架构师，比较 Kafka 和 RabbitMQ 在我们的场景下的优劣：
> - 日均消息量：100万条
> - 要求：至少一次投递，可容忍秒级延迟
> - 输出：选型建议 + 部署拓扑图 + 风险点Few-shot 示例驱动
# 给 Codex 看示例，让它模仿风格
> 按照下面的风格为所有 API 错误添加统一处理：
>
> 示例：
> ```typescript
> // Before
> throw new Error('user not found')
>
> // After
> return err(new UserNotFoundError({ userId, traceId: req.traceId }))
> ```
>
> 请修改 src/routes/ 下的所有路由处理器，统一使用这种错误处理方式。3. 场景深入：不同任务的 Prompt 设计模式
模式 A：Bug 修复（精确制导）
示例：
Bug：用户登出后仍能通过旧 Token 访问 API
复现：
1. 登录获取 Token
2. 调用 /api/logout
3. 立即用同一 Token 调用 /api/profile
4. 预期 401，实际 200
相关文件：src/auth/middleware.ts, src/auth/tokenStore.ts
要求：
- 修复 logout 时 Token 未失效的问题
- 补充测试覆盖此场景
- 运行 npm test 验证
模式 B：功能开发（需求分解）
需求：添加用户邀请功能
业务规则：
- 每个用户每月最多邀请 5 人
- 被邀请人注册后，邀请双方各得 10 积分
- 邀请链接 7 天有效
- 已注册用户不能再次被邀请
技术要求：
- 新增 invite 表（user_id, email, code, expires_at, status）
- 修改 user 表添加 invited_by 字段
- 在注册流程中校验邀请码
- 发送邀请邮件（使用现有 emailService）
验收标准：
- 单元测试覆盖所有业务规则
- 集成测试覆盖完整邀请流程
- 所有现有测试继续通过
模式 C：代码审查（结构化输出）
请审查 @src/payment/ 目录，按以下格式输出：
## 安全 🔒
- [ ] 无硬编码密钥
- [ ] 输入已校验
- [ ] SQL 已参数化
## 正确性 ✅
- [ ] 边界条件处理
- [ ] 错误路径覆盖
- [ ] 并发安全
## 可维护性 📝
- [ ] 命名清晰
- [ ] 函数长度 < 50 行
- [ ] 有必要的注释
如有未达标项，给出具体文件位置和改进建议。
4. 💡 核心避坑与最佳实践 (Takeaways)
- 避免开放式指令："看看有没有问题" → "找出 3 个最严重的性能瓶颈"
- 用
/plan做复杂任务：先出方案再执行，避免方向性错误导致大量 Token 浪费 - 上下文压缩策略：长会话定期
/compact，或主动拆分任务到多个会话 - 验证指令必须明确：不说"测试一下"，而说"运行
npm test并报告失败用例" - 给示例比给规则更有效：Few-shot 示例驱动的准确率比抽象描述高 40%+
- 分阶段交付降低风险：大任务拆成 3-5 个小步骤，每步确认后再继续