Skip to main content

这页解决什么问题

“帮我改一下”“这个报错修一下”“加个功能”都像任务,实际上缺少 Codex 做出正确决定所需的信息。信息不完整时,代理会自行猜测文件、行为、技术方案和完成标准;即使最后能运行,也可能改错地方、扩大范围,或者遗漏边界条件。 这页提供一套可反复使用的提问方法:
  • 目标:任务完成后,用户或系统应该得到什么可观察的结果。
  • 范围:允许检查和修改哪些文件、函数、接口或环境。
  • 约束:哪些行为、依赖、接口、数据和权限必须保持不变。
  • 验证:用什么命令、测试、请求、截图或人工步骤证明已经完成。
四件套不是一段固定模板,也不是“把代码全部贴给模型”。它是一种决策顺序:先定义结果,再限定边界,随后补充限制,最后提供可运行的证据。每项都尽量写成可以核对的事实。
本页的命令、斜杠命令和配置行为以本机 Codex 版本为准。先运行 codex --help,需要时再查看对应子命令的帮助。本文不要求提交、推送或发布改动。

先看一个完整闭环

假设你发现订单详情页在接口返回空数组时显示“加载中”。不要直接输入“修一下订单页面”。可以先写成:
这段话给了 Codex 四种不同的信息:要达成的用户可见行为、先后排查的范围、不能改变的合同、可以产生通过或失败结果的检查。它仍然允许代理阅读代码后调整具体实现,但不允许代理替你决定需求本身。

01 模糊需求与高质量需求

模糊不等于简洁

短句只有在双方共享足够背景时才有效。同一个会话里刚刚讨论过文件、复现步骤和验收标准,后续说“按刚才方案继续”可能足够;新会话、陌生仓库或多人交接时,这句话就不够。 下面的左列缺少的是“决定空间”,不是字数: 高质量需求不要求你预先知道实现方式。你可以只规定“结果、边界和证据”,把实现方案交给 Codex;但不能把“结果是什么”也交出去。例如,“使用缓存优化”是方案,“重复请求相同参数时在 30 秒内复用结果”才是可验收的目标。

四个缺口分别会造成什么

提问前逐项问自己:
  1. 完成后谁能观察到什么变化?
  2. 它应该从哪里开始查,最多动到哪里?
  3. 哪些接口、目录、依赖、数据或行为不能改变?
  4. 哪条命令或哪组步骤能证明成功,失败时能定位到什么?

02 目标:把结果写成可观察行为

目标应描述“结束时世界有什么不同”,而不是描述代理要做的动作。优先写输入、条件、输出和不变项。

目标的三种颗粒度

行为目标适合 bug 和功能:
质量目标适合性能、可靠性和兼容性:
交付目标适合文档、测试和审查:
避免只写这些无法直接判定的词:
  • “更优雅”
  • “更健壮”
  • “体验更好”
  • “全面优化”
  • “按最佳实践重写”
如果确实要改善体验,把它翻译成用户动作和结果:点击提交后 2 秒内显示成功或明确错误;移动端 390px 宽度不出现横向滚动;键盘可以从输入框移动到提交按钮。

目标与方案分开

把方案写成不可更改的指令,会过早限制排查;把方案完全省略,又可能让代理选择不符合项目约定的实现。更稳妥的写法是区分“必须满足的结果”和“允许采用的方向”:
目标中的数字、接口字段、状态码、文件格式和用户动作都应尽量来自真实需求。不要为了显得精确而编造指标;未知指标可以明确要求先测基线并回报。

03 范围:给出边界和探索路径

范围回答两个问题:Codex 可以读什么,最终可以改什么。两者不一定相同。排查一个接口可能需要阅读路由、配置、日志和调用方,但最终只应修改服务实现和测试。

文件上下文怎么给

优先点名最相关的文件,并说明它们的关系:
如果不知道文件在哪里,可以给探索范围和停止条件:
不要把“全仓库”当作默认上下文。范围越大,代理越难判断哪些内容与任务相关;同时,输出中的无关文件会占用上下文窗口。

文件名、选区、日志和截图

不同材料适合不同的上下文方式: 日志不要只写“报了空指针”。应保留调用坐标和前后事件:
截图上下文也要可执行:
截图不能替代 DOM、日志或测试。它说明“看到了什么”,不一定说明根因;要求代理结合组件、样式和实际交互验证。

保护敏感上下文

提交上下文前先脱敏: 保留时间、状态码、错误类型、路由形状、请求 ID 的脱敏版本和数据结构。不要把 .env、SSH 私钥、完整客户记录、生产令牌或可直接访问的私有链接粘贴到提示词中。线上操作先规定“只读取证,不改生产状态”,需要改变权限、数据、计费、通知或部署时单独确认。

04 约束:写清楚不能变的东西

约束不是“请写得好一点”,而是实现必须服从的边界。常见约束包括:
  • 代码边界:只改指定目录,不改迁移、锁文件或生成文件。
  • 接口边界:函数签名、HTTP 方法、状态码、字段名和排序保持不变。
  • 依赖边界:只用已有依赖,或只能使用标准库。
  • 兼容性边界:支持的运行时、数据库版本和旧客户端行为不变。
  • 数据边界:不读取或写入生产数据,不修改历史记录,不记录敏感值。
  • 流程边界:不提交、不推送、不发布;失败后停止扩大范围。
  • 风格边界:沿用现有目录、命名、测试框架和错误处理方式。
把“不要动某物”配上可替代路径,代理更容易完成任务:
范围和约束要能被 diff 检查。比如“只改一个函数”不等于“只能有一个文件变化”:如果需要补测试,应明确允许测试文件变化;如果不允许改动配置,也应明确列出配置文件为禁止项。

05 验证:从“看起来完成”到证据

验证是四件套中最容易漏掉、却最能减少返工的一项。好的验证至少包含命令、对象和通过条件:
而不是:

分层验证

按风险从近到远排列验证,失败时更容易定位:
  1. 语法或格式:格式化、lint、静态检查。
  2. 局部行为:目标函数或组件的单元测试。
  3. 模块行为:相关服务、页面或接口测试。
  4. 系统行为:构建、集成测试、启动后请求或浏览器操作。
  5. 回归审查:查看 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:
先运行基线:
向 Codex 提供模糊需求:
这个请求没有定义空列表的目标,也没有说明是否要改测试。代理可能添加类型、改变返回值,或只做格式调整。更高质量的请求是:
验收不只看“函数里有 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

这是一个“先证据、后修改”的案例。提示分两阶段。 第一阶段只读:
第二阶段在确认根因后再改:
线上验收必须回到原始路径。如果没有生产权限或不能重放请求,应明确写“未验证线上恢复”,而不是把本地测试通过表述成线上已恢复。保留时间、状态码、日志行和脱敏请求 ID,方便有权限的人补证据。

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。