Codex 提示词最佳实践

掌握提示词技巧，让 Codex 更准确地理解你的意图并高效完成任务。

---

提示词基本结构

一个好的提示词包含以下要素：

基本要素

要素	说明	示例
任务描述	你想做什么	"实现用户登录功能"
上下文	相关背景信息	"使用现有的 auth 模块"
约束条件	限制和要求	"必须兼容现有 API"
期望结果	具体产出	"返回 JWT token"

结构化提示词

完整提示词示例

# 任务描述
实现一个用户登录 API 端点
# 上下文
- 项目使用 FastAPI 框架
- 已有 auth 模块处理认证逻辑
- 数据库使用 PostgreSQL
# 约束条件
- 使用现有的 JWT 工具生成 token
- 密码使用 bcrypt 验证
- 需要添加请求日志
# 期望结果
- 路径：POST /api/auth/login
- 请求体：{"email": "...", "password": "..."}
- 成功响应：{"token": "...", "user": {...}}
- 失败响应：{"error": "..."}

---

任务拆解原则

复杂任务应该拆解成小步骤，逐步完成。

拆解原则

• 每个步骤有明确目标
• 步骤之间依赖关系清晰
• 每步完成后验证结果
• 遇到问题可以回退

拆解示例

任务拆解

# 大任务
"实现完整的用户认证系统"
# 拆解成小任务
步骤 1："设计认证系统的数据结构，包括用户表和 token 表"
步骤 2："实现用户注册功能，包括密码加密和验证"
步骤 3："实现用户登录功能，生成 JWT token"
步骤 4："实现 token 验证中间件"
步骤 5："实现用户登出功能"
步骤 6："编写认证系统的测试"
步骤 7："更新 API 文档"

使用 /plan 模式可以帮助 Codex 自动拆解复杂任务。

---

提供上下文信息

充分的上下文让 Codex 更准确理解项目状态。

关键上下文

类型	说明	何时提供
技术栈	框架、语言、库版本	首次任务或新模块
项目结构	模块位置、命名规范	涉及多文件修改
现有代码	相关函数、类、模块	需要兼容或扩展
约束条件	兼容性、性能要求	有特殊限制

上下文提供方式

提供上下文

# 直接描述
"项目使用 Django 4.2，数据库是 PostgreSQL 15"
# 引用现有代码
"参考 src/utils/validator.py 的验证逻辑"
# 指定文件
"修改 src/api/users.py，保持与其他 API 一致的风格"
# AGENTS.md 自动提供
创建 AGENTS.md 文件，Codex 会自动读取项目规范

---

错误信息处理

Codex 可以根据错误信息快速定位问题。

提供完整错误信息

错误处理

# 提供完整错误
"运行测试时出现错误：
AssertionError: Expected status 200 but got 500
  at test_login.py:45
  in test_successful_login
  Full traceback:
  ...
分析原因并修复"
# 截图辅助
附加错误截图，Codex 可以直接查看

错误信息要素

• 错误类型和消息
• 完整堆栈跟踪
• 触发条件（做了什么操作）
• 期望结果 vs 实际结果

---

图片输入

Codex 支持图片输入，适合视觉信息传递。

适用场景

场景	说明
错误截图	截图显示错误界面或日志
设计稿	UI 设计稿转换为代码
架构图	解释架构图并实现
数据图表	分析图表数据

图片输入方式

使用图片

# CLI
codex -i screenshot.png
codex --image design.png "根据设计稿实现页面"
# App/IDE
直接粘贴或拖拽图片到对话区域
# 多张图片
codex -i img1.png -i img2.png "对比这两张设计稿的差异"

---

迭代优化

通过迭代逐步优化代码质量。

迭代流程

1. Codex 完成初步实现
2. 检查结果，提出改进点
3. Codex 根据反馈调整
4. 验证改进效果
5. 重复直到满意

迭代优化

# 初步实现
"实现用户列表 API，支持分页"
# 检查后提出改进
"添加排序功能，支持按创建时间排序"
# 继续优化
"添加搜索功能，支持按用户名搜索"
# 性能优化
"优化查询性能，添加索引"

---

避免歧义

明确的提示词减少误解和返工。

歧义示例

避免歧义

# 模糊的提示词（不好）
"修改那个函数"
# 明确的提示词（好）
"修改 src/utils/helper.py 中的 format_date 函数"
# 模糊的提示词（不好）
"让它更快"
# 明确的提示词（好）
"优化 query_users 函数，查询时间从 500ms 降低到 100ms 以内"
# 模糊的提示词（不好）
"加个功能"
# 明确的提示词（好）
"在用户 API 中添加批量删除功能，接收用户 ID 列表"

---

使用参考示例

提供参考代码或文档，帮助 Codex 理解期望风格。

提供参考

# 参考现有代码风格
"参考 src/api/products.py 的风格，实现用户 API"
# 参考文档
"按照 OpenAPI 规范文档 docs/api-spec.yaml 实现"
# 参考示例
"按照这个格式返回响应：
{
  'success': true,
  'data': {...},
  'message': '...'
}"

---

常见提示词模板

功能开发模板

功能开发

在 [模块路径] 添加 [功能名称] 功能
要求：
- 使用 [技术/库]
- 兼容 [现有系统]
- 包含 [边界处理]
- 返回 [响应格式]
参考：[现有类似功能路径]

Bug 修复模板

Bug 修复

问题描述：[Bug 表现]
触发条件：[什么情况下出现]
错误信息：
[完整错误堆栈]
期望行为：[正确结果应该是什么]
请分析原因并修复，不要影响其他功能。

代码审查模板

代码审查

/review [范围] for [重点]
# 示例
/review src/auth/ for security issues
/review HEAD~5..HEAD for performance regressions

---

最佳实践总结

核心原则

• 明确具体，避免模糊表述
• 提供充分上下文
• 复杂任务拆解执行
• 迭代优化，逐步完善
• 验证结果，确保正确

效率技巧

• 使用 AGENTS.md 减少重复说明
• 利用 Skills 封装常用提示词
• 使用图片传递视觉信息
• 提供错误信息时要完整

---

常见问题

Q: Codex 理解错了怎么办？

提供更明确的描述，补充上下文，或使用参考示例。

Q: 如何让 Codex 遵循项目规范？

创建 AGENTS.md 文件定义规范，Codex 会自动遵循。

Q: 复杂任务如何处理？

使用 /plan 模式制定计划，分步执行并验证。

Q: 图片输入有什么限制？

支持 PNG、JPG、WebP 格式，建议分辨率适中（不要太小或太大）。