Codex 提示词教程:让代码任务少返工、可验证
很多人觉得 Codex “有时很好用、有时又会乱改”,通常不是因为提示词要写得很长,而是任务缺少范围、约束和验收方式。高质量的 Codex 提示词,应该让代理知道:要解决什么问题、可以看哪些文件、哪些内容不能动、完成后怎样证明结果有效。
一条好用的 Codex 提示词公式
可以按下面五个字段组织任务:
背景:项目是什么,当前遇到什么问题。
目标:这一次只要完成什么结果。
范围:允许查看和修改哪些目录或文件。
约束:不能改变哪些接口、依赖、数据和行为。
验收:需要运行什么测试、构建或检查命令。例如,不要只写:
帮我优化这个页面。可以改成:
背景:这是一个 VitePress 中文文档站,首页在 768px 宽度下出现横向滚动。
目标:修复移动端横向溢出,保持桌面端布局和现有链接不变。
范围:只检查首页组件和主题 CSS,不修改文章内容。
约束:不要引入新依赖,不要改变颜色变量和导航结构。
验收:运行 npm run build,并说明用什么方式检查了移动端溢出。第二个版本更容易检查,也更容易在发现问题时回滚。
广告|中文提示词与代码辅助入口
如果你正在整理需求、解释报错或比较不同模型的代码回答,可以先查看以下第三方入口。它们不是 OpenAI 官方 Codex 客户端,涉及本地仓库、密钥和敏感代码时请先确认平台的数据规则。
复杂任务要分几轮?
推荐使用“读、计划、改、测、审”五步循环:
1. 读:先确认事实
请先阅读 README、项目配置、相关入口文件和测试目录。
只输出你确认的事实、可能相关的文件和仍然缺少的信息,不要修改文件。2. 计划:给出最小方案
基于刚才看到的内容,给出一个最小修改计划。
每一步写出目标文件、预期变化和验证方法。
如果有两种方案,先比较风险,不要直接执行。3. 改:限制变更边界
按已确认的方案实施,只修改列出的文件。
遇到需要扩大范围、添加依赖或改变公开接口的情况先停下来说明。4. 测:让测试成为任务的一部分
运行与本次改动直接相关的测试、lint 和构建命令。
不要把“命令返回成功”替换成“功能一定正确”;请列出仍未覆盖的情况。5. 审:最后看 diff 和风险
请检查当前 git diff。
重点寻找:边界条件、错误处理、权限变化、性能回归、未更新文档和无关文件修改。
按严重程度列出问题;没有问题也要说明检查范围。这套流程比一次性要求 Codex 输出完整项目更适合真实仓库,尤其是改动涉及多个模块时。
AGENTS.md 是什么?
AGENTS.md 可以理解为给 Codex 和其他代码代理阅读的项目说明文件。它适合放稳定、反复适用的规则,例如:
- 项目目录和关键入口。
- 安装、开发、测试、lint 和构建命令。
- 代码风格、命名约定和提交要求。
- 哪些目录或文件不能修改。
- 完成任务前必须执行的验证步骤。
在 Codex CLI 中可以用 /init 生成起始文件,再根据真实项目修改。官方最佳实践建议把个人默认配置、仓库规则和更具体目录的规则分层维护;离当前工作目录更近的规则可以补充或覆盖更上层的说明。
一个简短的示例:
# Project instructions
## Commands
- Install: `npm install`
- Dev: `npm run dev`
- Build: `npm run build`
## Rules
- Use the existing VitePress structure.
- Keep public URLs and front matter stable unless the task asks for a change.
- Run `npm run build` after editing content or configuration.
- Never commit secrets or real customer data.
## Done means
- The requested pages exist.
- Internal links resolve.
- The production build passes.
- The final response lists changed files and validation.不要把一次性任务细节全部塞进 AGENTS.md。只写长期有效的项目规则,临时需求仍然放在当前提示词中。
常见任务的提示词模板
修复 Bug
请定位这个问题:{现象}。
环境:{系统、运行时、版本}。
报错:{完整错误堆栈}。
请先列出最可能的原因,再检查相关代码。
只采用能被现有代码和日志支持的结论。
修复后补充回归测试,运行测试并报告结果。新增功能
请为 {用户/角色} 增加 {功能}。
已有入口:{文件或路由}。
必须保留:{接口、数据结构、兼容行为}。
请先给出实现计划和验收清单;确认范围后再修改。代码审查
请审查当前 diff,不要直接修改。
优先检查正确性、权限、异常处理、性能、兼容性和测试缺口。
每条问题给出文件位置、影响和建议;没有足够证据的内容标记为待确认。文档更新
请根据现有实现更新文档。
先核对命令、配置字段、路径和示例是否真实存在。
不要为了让文章更完整而发明尚未实现的功能。
完成后运行站点构建,并检查内部链接。让 Codex 的结果更稳定的 6 个细节
- 给出真实文件名和命令,不要只说“前端部分”。
- 把完整报错和复现步骤放在提示词里。
- 明确“只读调查”还是“可以修改”。
- 说明哪些内容必须保持不变。
- 要求测试、构建或人工检查方式。
- 让 Codex 最后列出未解决问题,而不是只输出成功结论。
常见问题
提示词越长越好吗?
不是。稳定、可执行的约束比堆砌背景更有用。长期规则放到 AGENTS.md,当前任务只保留与本次结果有关的事实和验收条件。
什么时候应该使用 /review?
当功能已经完成、准备提交或改动跨越多个文件时使用。它适合发现遗漏和风险,不能替代真实测试或人工业务验收。
Codex 总是修改太多文件怎么办?
先让它只读分析,再给出允许修改的文件列表;明确“超出范围先停下来询问”。同时检查 AGENTS.md 是否写了过于宽泛的规则。
如何防止它虚构测试结果?
要求输出实际运行的命令和退出结果,必要时让它先运行命令再总结;最终自己查看终端输出和 Git diff。
更多配置可以参考 Codex 最佳实践 和 Codex 配置基础。