自学教程

Codex 提示词最佳实践

Codex 教程

提示词是人与 Codex 智能体交互的载体。清晰、结构化的提示词，可以降低理解偏差，减少反复沟通，让输出更贴合项目实际需求。Codex 不同于普通对话大模型，它可以读写文件、执行命令、修改项目代码，提示词不仅要描述“做什么”，还需要明确上下文、修改范围、约束条件、验收标准。本文介绍提示词基础组成、编写原则、上下文管理、任务拆解、各类场景模板、常见误区与配套斜杆命令使用技巧。

一、提示词四大基础要素

一份高质量工程类提示词，包含任务描述、上下文、约束条件、期望结果（验收标准）四个核心部分，缺一不可。

要素说明示例
任务描述清晰说明要完成的目标动作实现用户登录 API 端点
上下文项目背景、技术栈、现有模块、参考文件项目使用 FastAPI，已有 auth 认证模块
约束条件限定范围、禁止行为、技术限制、兼容性不能改动现有对外接口，密码使用 bcrypt 加密
期望结果产出格式、接口定义、验证方式，定义“怎样算完成”接口路径 POST /api/auth/login，需编写单元测试

结构化提示词完整示例

# 任务描述
实现一个用户登录 API 端点# 上下文
- 项目使用 FastAPI 框架
- 已有 auth 模块处理认证逻辑
- 数据库使用 PostgreSQL
# 约束条件
- 复用项目内部 JWT 工具生成令牌
- 密码使用 bcrypt 做校验
- 增加请求访问日志
- 禁止修改已有数据库表结构
# 期望结果
- 接口路径：POST /api/auth/login
- 请求体：{"email":"string","password":"string"}
- 成功响应：{"token":"xxx","user":{...}}
- 失败响应：{"error":"错误描述"}
- 补充对应的单元测试用例

二、核心编写原则

2.1 拒绝模糊表述，使用具体路径与名词

模糊指令极易产生歧义，尽量写明文件路径、函数名、模块名称。

❌ 不推荐：修改那个函数，让接口变快。
✅ 推荐：优化 src/api/user.py 的 query_users 函数，将查询耗时降低至100ms以内。

2.2 提供充足但不冗余的上下文

Codex 无法自动知晓全部项目背景，需要主动给出关键信息：技术栈版本、目录结构、参考代码、业务规则。
常用上下文传递方式：

  1. 直接文字描述项目环境；
  2. 指定参考文件路径：参考 src/utils/validator.py 的校验逻辑；
  3. 引用已有代码片段；
  4. 依靠项目根目录 AGENTS.md 固化长期项目规范，避免每次重复输入。

注意：不要一次性粘贴大量无关代码，只提供任务相关片段，避免上下文过载。

2.3 复杂任务优先拆解，不要一次性下发巨型需求

Codex 对中等粒度任务处理效果最好。超大需求应当拆分为多个小步骤，分步执行、分步验证。也可以使用斜杆命令 /plan，让 Codex 先生成执行方案，人工确认后再动手修改代码。

❌ 不推荐：直接实现完整用户认证全套系统。
✅ 推荐拆分为子步骤：

  1. 设计用户数据表结构；
  2. 实现用户注册接口，完成密码加密；
  3. 实现登录接口，签发 JWT；
  4. 编写鉴权中间件；
  5. 补充单元测试，更新接口文档。

2.4 明确输出格式与验收条件

告诉 Codex 输出形式：需要输出方案再改代码、输出diff、输出markdown报告、还是直接修改文件；同时写明如何验证任务是否完成。例如：“修改完成后运行 npm test，保证全部用例通过”。

2.5 遇到报错，提供完整错误信息

调试排错时，尽量提供完整报错堆栈、触发操作、预期行为，不要只贴一句简短报错。
示例：

运行测试发生报错：
AssertionError: Expected status 200 but got 500
文件位置 test_login.py 第45行
触发操作：使用正确账号密码调用登录接口
期望：返回200与token；实际返回500服务异常。请定位根因并修复，不要改动其他业务模块。

2.6 善用图片输入传递视觉信息

桌面端、CLI、IDE扩展支持图片输入，适合：报错截图、UI设计稿、架构示意图。

  • 桌面/IDE：直接拖拽粘贴图片；
  • CLI：codex --image screenshot.png "根据截图复现并修复问题"。

三、结合斜杆命令增强提示效果

提示词可以和 Codex 内置斜杆命令搭配使用，提升稳定性：

  1. /plan：复杂任务，先规划方案再执行；
  2. /review：做代码审查，限定审查范围与审查重点；
  3. /diff：查看本次会话全部变更；
  4. /compact：压缩会话上下文，清理冗余日志；
  5. /goal：设置持久目标，适合长周期多轮迭代任务。

示例组合：

/plan
实现用户登录接口，遵循项目auth模块规范，输出完成之后自动生成单元测试。

四、常用提示词模板

4.1 新增功能模板

# 新增功能
在【模块/文件路径】实现【功能名称】## 上下文
技术栈：xxx
参考现有文件：【参考文件路径】
## 约束
- 使用指定第三方库；
- 兼容现有接口，不破坏旧逻辑；
- 做好参数校验、异常捕获。
## 交付与验收
1. 实现业务逻辑；
2. 补充单元测试；
3. 运行测试命令【xxx】全部通过。

4.2 Bug修复模板

# Bug修复
问题描述：【bug现象】
触发条件：【什么操作会复现】
错误堆栈：
【粘贴完整报错信息】期望行为：【正确的结果】
约束：只修复本问题，不要改动无关业务逻辑。
完成后给出复现步骤与验证方法。

4.3 代码审查模板

/review src/auth/
重点检查：安全漏洞、参数校验、异常处理；输出问题清单与修改建议，不要直接自动修改代码。

4.4 重构模板

# 代码重构
重构【文件/函数】
约束：保持对外接口完全不变，不能改变业务行为；
要求：提升可读性，补充必要注释；
完成后保证原有单元测试全部通过。

五、迭代优化工作流程

很多场景无法一次写出完美提示词，适合迭代式工作流：

  1. 下发提示词，获取第一版输出；
  2. 人工审阅结果，指出不足、遗漏点；
  3. 补充新的提示，让 Codex 调整；
  4. 验证效果，循环直到满足预期。

不建议一次性把全部需求写死，适度迭代更符合真实开发节奏。

六、常见误区

  1. 只讲目标，不写边界：没有写明禁止修改的目录、接口，容易发生非预期改动。
  2. 任务过大，一步到位：一次性下发整个系统重构，容易出现遗漏、逻辑错乱。应当配合 /plan 拆分。
  3. 省略验收标准：只说“完成功能”，没有写清楚如何判断任务已经做完。
  4. 上下文过度膨胀：会话堆积大量无关日志、旧报错，导致 Codex 遗忘约束；适时使用 /compact 或新建会话。
  5. 完全信任输出：无论提示词多么完善，所有代码修改必须人工复核，不可直接合并上线。
  6. 忽略AGENTS.md：重复描述项目编码规范，没有沉淀为项目级配置文件。

七、最佳实践总结

  1. 提示词结构完整：任务 + 上下文 + 约束 + 验收标准。
  2. 路径、函数名尽量写明确，拒绝模糊的代词描述。
  3. 大型任务优先 /plan 做方案评审，再执行修改。
  4. 项目长期约束写入 AGENTS.md，减少重复输入。
  5. 调试排错带上完整报错堆栈，必要时附加截图。
  6. 善用迭代模式，不要追求一次提示词解决全部问题。
  7. 会话臃肿时压缩上下文或新建会话，减少模型遗忘需求。
  8. 输出结果必须人工审核，提示词优化不能替代代码评审。

八、常见问题

Q：Codex总是理解错我的意图怎么办？
优先补充上下文、写明文件路径，明确禁止行为；也可以要求Codex先输出执行方案，确认之后再修改代码。

Q：如何让Codex持续遵守项目编码规范？
在项目根目录创建AGENTS.md，统一写明编码风格、目录保护规则，桌面端、IDE、CLI都会自动读取。

Q：特别复杂的长任务如何处理？
使用 /plan 做任务拆解，结合 /goal 设置持久目标，分多轮分步执行，避免单轮任务过载。

标签：

0 条笔记