这页解决什么问题
“帮我改一下”“这个报错修一下”“加个功能”都像任务,实际上缺少 Codex 做出正确决定所需的信息。信息不完整时,代理会自行猜测文件、行为、技术方案和完成标准;即使最后能运行,也可能改错地方、扩大范围,或者遗漏边界条件。 这页提供一套可反复使用的提问方法:- 目标:任务完成后,用户或系统应该得到什么可观察的结果。
- 范围:允许检查和修改哪些文件、函数、接口或环境。
- 约束:哪些行为、依赖、接口、数据和权限必须保持不变。
- 验证:用什么命令、测试、请求、截图或人工步骤证明已经完成。
本页的命令、斜杠命令和配置行为以本机 Codex 版本为准。先运行 codex --help,需要时再查看对应子命令的帮助。本文不要求提交、推送或发布改动。
先看一个完整闭环
假设你发现订单详情页在接口返回空数组时显示“加载中”。不要直接输入“修一下订单页面”。可以先写成:01 模糊需求与高质量需求
模糊不等于简洁
短句只有在双方共享足够背景时才有效。同一个会话里刚刚讨论过文件、复现步骤和验收标准,后续说“按刚才方案继续”可能足够;新会话、陌生仓库或多人交接时,这句话就不够。 下面的左列缺少的是“决定空间”,不是字数:
高质量需求不要求你预先知道实现方式。你可以只规定“结果、边界和证据”,把实现方案交给 Codex;但不能把“结果是什么”也交出去。例如,“使用缓存优化”是方案,“重复请求相同参数时在 30 秒内复用结果”才是可验收的目标。
四个缺口分别会造成什么
提问前逐项问自己:
- 完成后谁能观察到什么变化?
- 它应该从哪里开始查,最多动到哪里?
- 哪些接口、目录、依赖、数据或行为不能改变?
- 哪条命令或哪组步骤能证明成功,失败时能定位到什么?
02 目标:把结果写成可观察行为
目标应描述“结束时世界有什么不同”,而不是描述代理要做的动作。优先写输入、条件、输出和不变项。目标的三种颗粒度
行为目标适合 bug 和功能:- “更优雅”
- “更健壮”
- “体验更好”
- “全面优化”
- “按最佳实践重写”
目标与方案分开
把方案写成不可更改的指令,会过早限制排查;把方案完全省略,又可能让代理选择不符合项目约定的实现。更稳妥的写法是区分“必须满足的结果”和“允许采用的方向”:03 范围:给出边界和探索路径
范围回答两个问题:Codex 可以读什么,最终可以改什么。两者不一定相同。排查一个接口可能需要阅读路由、配置、日志和调用方,但最终只应修改服务实现和测试。文件上下文怎么给
优先点名最相关的文件,并说明它们的关系:文件名、选区、日志和截图
不同材料适合不同的上下文方式:
日志不要只写“报了空指针”。应保留调用坐标和前后事件:
保护敏感上下文
提交上下文前先脱敏:
保留时间、状态码、错误类型、路由形状、请求 ID 的脱敏版本和数据结构。不要把
.env、SSH 私钥、完整客户记录、生产令牌或可直接访问的私有链接粘贴到提示词中。线上操作先规定“只读取证,不改生产状态”,需要改变权限、数据、计费、通知或部署时单独确认。
04 约束:写清楚不能变的东西
约束不是“请写得好一点”,而是实现必须服从的边界。常见约束包括:- 代码边界:只改指定目录,不改迁移、锁文件或生成文件。
- 接口边界:函数签名、HTTP 方法、状态码、字段名和排序保持不变。
- 依赖边界:只用已有依赖,或只能使用标准库。
- 兼容性边界:支持的运行时、数据库版本和旧客户端行为不变。
- 数据边界:不读取或写入生产数据,不修改历史记录,不记录敏感值。
- 流程边界:不提交、不推送、不发布;失败后停止扩大范围。
- 风格边界:沿用现有目录、命名、测试框架和错误处理方式。
05 验证:从“看起来完成”到证据
验证是四件套中最容易漏掉、却最能减少返工的一项。好的验证至少包含命令、对象和通过条件:分层验证
按风险从近到远排列验证,失败时更容易定位:- 语法或格式:格式化、lint、静态检查。
- 局部行为:目标函数或组件的单元测试。
- 模块行为:相关服务、页面或接口测试。
- 系统行为:构建、集成测试、启动后请求或浏览器操作。
- 回归审查:查看 diff、检查未预期文件、确认兼容性和安全边界。
验证必须覆盖负面路径
只验证成功路径不能证明修复有效。根据任务补齐至少一个失败或边界条件:空输入、重复请求、权限拒绝、超时、网络断开、旧格式、并发访问、窄屏布局或已有数据。让代理报告证据
要求交付摘要包含:git status 或 diff 证明。
06 什么时候先用 /plan
小任务可以直接执行:目标明确、影响范围单一、实现方式已有项目先例,且你能在一句话里描述预期 diff。比如“在现有函数入口增加空值判断,补一个单测,运行目标测试”。
以下情况先进入 /plan 或要求“只读并出方案”:
- 不熟悉的代码库或找不到真实入口。
- 跨多个模块、接口、数据库或部署配置。
- 迁移、重构、权限、并发、缓存、计费和数据修复。
- 需求仍有多个合理解释。
- 验证方式未知,或者失败成本很高。
- 需要并行拆分或新建工作树。
07 /goal 适合什么任务
当任务有明确、可持续检查的完成标准,可以使用 /goal 把目标和完成条件放在一起。一个好的目标能由命令、测试或明确的用户步骤判断为“是”或“否”:
/goal 让代码更优雅、/goal 全面提升性能,因为代理无法稳定判断是否达成。目标不清晰时,先 /plan,让它列出事实、问题和可测标准,再整理成目标。
/goal 的具体可用性取决于当前版本和账号配置。如果命令不显示,运行本地帮助或查看官方文档,不要凭旧教程修改未知配置。无论是否使用 /goal,仍需人工审查 diff、权限和敏感操作;长期任务也要定期检查进度和上下文,不要把“目标模式”理解成无需监督。
08 复杂任务拆分
复杂任务的最小单位不是“一个文件”,而是“一次可以独立验证的行为变化”。每个小步都要有目标、范围、约束和验证,并尽量让下一步建立在前一步已通过的结果上。一个认证迁移的拆法
不要直接说“把认证系统改成 OAuth”。可以拆成:
步骤 1 只是探索,不应顺手改代码;步骤 2 的结构先确认,再进入实现。每完成一步查看一次 diff,让变更保持可回退。
用依赖关系判断顺序
先做被多个后续步骤依赖的稳定合同,再做外围适配:类型和接口先于页面,复现测试先于修复,数据备份和迁移方案先于写入逻辑。把可以并行的只读工作分出去,例如一个任务梳理调用链,另一个任务整理测试缺口;两条线不要同时修改同一批文件。什么时候不要拆
改错别字、单个变量重命名、已知位置的一行日志和一个明确的边界判断,不需要铺设长计划。拆分本身也会产生沟通成本。判断标准是:你能否在开始前写出预期 diff、能否在几分钟内运行局部验证、失败是否容易撤回。三项都满足时直接执行即可。09 提速:减少猜测和返工
提速的主要来源不是让代理少思考,而是让它少走错误路径。按以下顺序优化:先减少往返
一次提供目标、相关文件、日志、约束和验收,比先发“帮我看看”再补五次信息更快。已知文件用@ 或路径点名,已知错误贴完整堆栈,已知期望给输入输出示例。
控制上下文
- 一个任务一个会话,相关讨论保留在同一线程。
- 不相关任务新开会话,不让旧需求污染判断。
- 对话很长时先查看状态,必要时使用本机支持的压缩命令。
- 只提供相关文件,不把整个仓库、无关日志和重复代码全部粘贴。
- 把持久规则放进项目约定文件,把一次性要求留在当前提示中。
按任务选择算力
改一处文案或补一个已知测试,使用较快、较低推理设置通常足够;跨模块调试、协议迁移和安全审查需要更多推理。模型、推理级别和快速模式的名称与计费会变化,先查看当前配置,不要把旧版本的模型名写死在团队规则里。并行但要隔离
并行适合独立的只读调查、测试运行、日志分析和文档整理。若两个任务都要修改代码,使用独立的 git worktree 或不同工作目录,并在合并前分别审查 diff。不要让两条会话同时写同一个配置、锁文件、迁移目录或生成文件。让代理自验,但保留人工闸门
提示末尾明确要求它运行测试、lint、构建或复现路径,并报告证据。人工仍需核对高风险动作:安装依赖、删除文件、访问网络、修改生产数据、写入密钥、提交、推送和发布。少一次无效返工,不等于取消边界检查。10 失败时怎么追问
失败追问的目标是缩小不确定性,不是重复“再试一次”。先保留错误输出和当前 diff,再按证据追问。验证命令失败
改错文件或范围扩大
结果与需求不符
环境或权限不足
反复失败
第三次失败后不要继续堆补丁。让代理总结失败轨迹、已尝试方案、排除的假设、未读的关键文件和最小复现;必要时回到/plan,重新确认目标和范围。反复失败通常说明目标、上下文、约束或验证中有一项写错或缺失。
11 案例一:修复 Python 空输入错误
这是一个可运行的最小示例,展示从模糊需求到四件套。先在临时目录执行:stats.py:
test_stats.py:
if”:
None 而不是 0,应以项目合同为准,先追问而不是照搬示例。
12 案例二:用日志和截图修复页面状态
准备一个前端页面问题时,不要只说“按钮错位”。同时提供视口、操作步骤、截图和相关入口:13 案例三:增加 CSV 导出而不改变数据合同
假设已有src/report/exportCsv.ts、src/report/types.ts 和 tests/report/export.test.ts。可运行的提示如下:
如果代理建议“顺便统一 CSV 和 JSON 的序列化架构”,应先判断是否属于范围。当前任务的验收是新导出合同,不是重构两个导出器;重构可以另开任务,避免把功能 diff 和架构 diff 混在一起。
失败追问示例:
14 案例四:陌生仓库中定位登录 500
这是一个“先证据、后修改”的案例。提示分两阶段。 第一阶段只读:15 最终验收清单
在接受 Codex 的“已完成”之前,逐项核对:需求证据
- 目标描述的是可观察行为,而不是泛泛的质量词。
- 空输入、失败路径、兼容性或用户关键路径已经写入目标或验证。
- 每条目标都能对应到测试、命令、请求、截图或人工步骤。
范围证据
- 代理读取了正确入口、调用方、类型、配置和现有测试。
-
git status --short和git diff --stat显示的文件在授权范围内。 - 没有把一次性需求写入全局规则或无关文档。
- 没有修改生成文件、lockfile、迁移或配置,除非明确允许。
约束证据
- 函数签名、接口字段、状态码、权限和旧行为符合约束。
- 没有无理由新增依赖、改变架构或顺便重构。
- 日志、截图、测试夹具和输出没有泄露敏感信息。
- 没有执行未经确认的网络、删除、生产写入、提交或发布操作。
验证证据
- 目标测试实际运行并通过,命令和退出结果有记录。
- lint、格式、类型检查或构建已按项目要求运行。
- 至少一个失败或边界路径得到验证。
- 页面改动检查关键视口、键盘焦点和错误状态;接口改动检查响应码、超时、权限拒绝和重复请求。
- 已查看完整 diff,并运行
git diff --check。 - 未验证事项、环境限制和下一步责任人已明确写出。
交付边界
- 当前工作区的原有未提交改动没有被覆盖。
- 未要求提交时,Codex 没有自行提交或推送。
- 需要回滚时,知道应恢复哪个补丁、反向提交或环境版本。
16 一份可按任务填写的提示骨架
下面不是“泛化改代码模板”,而是一张提交前检查表。只保留与任务相关的行,填入真实路径、输入和命令:/plan,要求代理指出缺口;简单任务也可以只写四件套,但不能省略验证。执行过程中如果出现新事实,更新目标或约束并重新确认范围,不要让代理依据旧假设继续扩张。
小结
提示词四件套的核心不是写得长,而是让四类决定归位:- 目标决定结果,不让代理替你发明需求。
- 范围决定边界,让探索和修改可审查。
- 约束决定不能牺牲什么,保护接口、数据、依赖和流程。
- 验证决定何时算完成,把“感觉应该可以”变成证据。
/plan,再拆成每步可验证的小任务;遇到有明确可测终点的长任务,再考虑 /goal。提速优先减少猜测、返工和无关上下文,其次才考虑模型或快速模式。失败时保留证据、缩小范围、追问事实,直到根因和验收都清楚。
参考资料:参考/codex/13-prompting.md、参考/codex/31-speed.md、参考/codex/36-best-practices.md。