Codex 提示词最佳实践
掌握提示词技巧，让 Codex 更准确地理解你的意图并高效完成任务。
提示词基本结构
一个好的提示词包含以下要素：
基本要素
| 要素 | 说明 | 示例 |
|---|---|---|
| 任务描述 | 你想做什么 | "实现用户登录功能" |
| 上下文 | 相关背景信息 | "使用现有的 auth 模块" |
| 约束条件 | 限制和要求 | "必须兼容现有 API" |
| 期望结果 | 具体产出 | "返回 JWT token" |
结构化提示词
完整提示词示例
# 任务描述
实现一个用户登录 API 端点
# 上下文
- 项目使用 FastAPI 框架
- 已有 auth 模块处理认证逻辑
- 数据库使用 PostgreSQL
# 约束条件
- 使用现有的 JWT 工具生成 token
- 密码使用 bcrypt 验证
- 需要添加请求日志
# 期望结果
- 路径：POST /api/auth/login
- 请求体：{"email": "...", "password": "..."}
- 成功响应：{"token": "...", "user": {...}}
- 失败响应：{"error": "..."}
实现一个用户登录 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 文档"
"实现完整的用户认证系统"
# 拆解成小任务
步骤 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 会自动读取项目规范
"项目使用 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 可以直接查看
"运行测试时出现错误：
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 "对比这两张设计稿的差异"
codex -i screenshot.png
codex --image design.png "根据设计稿实现页面"
# App/IDE
直接粘贴或拖拽图片到对话区域
# 多张图片
codex -i img1.png -i img2.png "对比这两张设计稿的差异"
迭代优化
通过迭代逐步优化代码质量。
迭代流程
- Codex 完成初步实现
- 检查结果，提出改进点
- Codex 根据反馈调整
- 验证改进效果
- 重复直到满意
迭代优化
# 初步实现
"实现用户列表 API，支持分页"
# 检查后提出改进
"添加排序功能，支持按创建时间排序"
# 继续优化
"添加搜索功能，支持按用户名搜索"
# 性能优化
"优化查询性能，添加索引"
"实现用户列表 API，支持分页"
# 检查后提出改进
"添加排序功能，支持按创建时间排序"
# 继续优化
"添加搜索功能，支持按用户名搜索"
# 性能优化
"优化查询性能，添加索引"
避免歧义
明确的提示词减少误解和返工。
歧义示例
避免歧义
# 模糊的提示词（不好）
"修改那个函数"
# 明确的提示词（好）
"修改 src/utils/helper.py 中的 format_date 函数"
# 模糊的提示词（不好）
"让它更快"
# 明确的提示词（好）
"优化 query_users 函数，查询时间从 500ms 降低到 100ms 以内"
# 模糊的提示词（不好）
"加个功能"
# 明确的提示词（好）
"在用户 API 中添加批量删除功能，接收用户 ID 列表"
"修改那个函数"
# 明确的提示词（好）
"修改 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': '...'
}"
"参考 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
# 示例
/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 格式，建议分辨率适中（不要太小或太大）。
点我分享笔记