Codex 总猜错你的心,五件套把一句话需求写成工程任务

Codex 总猜错你的心,五件套把一句话需求写成工程任务

「帮我加一个登录功能。」你把这句话丢给 Codex,半分钟后它还你两百行代码,什么都对,又什么都不对。Web 框架写成 Express,你项目里用的明明是 Fastify。数据访问直接怼在控制器里,你们团队的规矩是走 Repository 模式。错误处理一水儿的 throw,你们早换成 Result 类型了。你想骂它笨,先别急。

问题多半不在 Codex,在你给它的那一句话上。它能读到的就这一句,项目用什么框架、哪些目录不能碰、什么样算修好,这些你心里默认的前提,一个字都没写。它只能按全网最常见的做法去猜,每一项都猜得理直气壮,每一项都和你项目对不上。老雷这两年陪不少团队跑 AI 编程落地,见得最多的卡点就是这个,不是工具不行,是派活的人以为一句话够用了。

这篇把一句话需求改成工程任务的路子拆开讲,五件套模板、最容易栽的几个反模式、需求没想清楚时的反向访谈,都是今天就能用上的东西。

vibe coding 有个被忽略的注脚

先说清一条分界线。Andrej Karpathy 2025 年初提出 vibe coding 的时候,原话里有个限定被绝大多数人忽略了,这种彻底交给感觉的写法,适合的是用完即弃的周末玩具项目。随手一句话让 AI 写个爬数据脚本、试个新库,失败成本接近零,怎么爽怎么来。

一旦代码要上生产、要多人协作、要碰钱和用户数据,氛围编程立刻失效。Red Hat 工程团队把 AI 编程分成四层,vibe 负责探索和原型,spec 负责真要上线的代码,skill 负责重复的工作流,agent 负责规格清晰的长任务。新手最大的误区就是把第一层当成了全部。

Codex 跑偏,绝大多数时候是你拿 vibe 的写法干了 spec 的活。

多花两分钟把需求写成规格,换少返工一整轮。这两分钟是 AI 编程里投入回报比最高的两分钟。

五件套,两分钟把话说成规格

OpenAI 官方最佳实践里,一条合格的工程提示词有四件是必填的,目标 Goal、上下文 Context、约束 Constraints、完成标准 Done When,社区在中间补了一件输入 Inputs,凑成五件套。模板长这样。

# Goal

一句话讲清干完是什么样,具体、可验证、不模糊

# Context

@ 引用一到三个真正相关的文件,附上报错日志和复现步骤

# Inputs

数据形状、示例载荷、边界条件

# Constraints

不能引入新依赖,保持函数签名,必须沿用现有模式

# Done When

哪些测试要过,哪些 lint 要干净,真机上什么行为算对

拿一个真实场景填一遍。修 Safari 登录失效的 bug,模糊版是「帮我修一下登录的 bug」,这么发它一定乱猜。工程版长这样。

# Goal

修复用户在 Safari 17.4 以上点登录按钮没反应的 bug

# Context

@src/lib/auth.ts 登录逻辑

@tests/auth.spec.ts 现有测试

现象是点击无反应、控制台没报错、Network 面板看不到请求发出

只在 Safari 复现,Chrome 和 Firefox 正常

# Constraints

不要改 signIn() 函数签名,其他模块在调

不要引入新依赖,不要动 UI

# Done When

pnpm test:auth 全过

Safari 真机点登录能进主页,Network 面板看得到 POST /api/login

多花了一分钟,换来的是它不用猜。加功能和重构两类任务填法一样,侧重点不同。加功能重点写输入边界和架构约束,做头像上传就把格式、大小上限、存到哪个桶、走不走 Server Action 一次写死。重构重点写保持什么不变,「把六层嵌套 if-else 改成早返回模式,所有函数签名不动,现有测试全过」,而不是「重构这个文件让它更好」。更好是什么,AI 不知道,你下周一回来看也不知道。

填五件套还有一条心法,告诉它目的,不要告诉它路径。别写「先读 A 文件再扫 B 文件然后调 C 函数」,写「修这个 bug,相关上下文在 @A @B」。给约束,不给步骤,模型自己会找路,你画好的路反而容易把它带沟里。

扁平矢量插画,一张分成五格的五件套任务卡片摆在桌面,机器人逐格核对图标打上对勾,旁边的开发者递出卡片

八个反模式里,最伤的是这三个

社区里高频踩的提示词反模式有八个,过于模糊、上下文过载、一次塞多个任务、没有完成标准、不审 diff 就合并、沉没成本、假设它懂你项目、优化目标没量化。前四个靠五件套基本就避掉了,后四个里最伤的是这三个。

一个是沉没成本陷阱。对话跑歪了,你花三十分钟试图掰回来,每多掰一轮,它被前面的错误锚定得越深。给自己立个硬规则,同一个对话里来回掰超过三轮还不收敛,立刻开新对话。把这次为什么跑偏写进新提示词的开头,五分钟往往比三十分钟管用。

沉没成本不是学费,是罚金。越舍不得,罚得越重。

一个是 @ 引用越多效果越差。这是重度使用后最反直觉的一条。往提示词里塞五六个 @ 引用,以为上下文越多它越懂,结果它常拿最大的那个文件当主参考,把真正相关的小文件忽略了。引用精确到一到三个真正相关的文件,拿不准哪个相关,先让它自己扫。

一个是客气语气。「最好不要引入新依赖哦」「请尽量不要动 main 分支」,AI 不擅长读你的语气,只擅长读明确的命令式。把最好不要改成禁止,把请尽量改成必须。老雷给大家提个醒,约束这种事对模型和对合同一样,一个字都别客气。

扁平矢量插画,机器人绕着打结的虚线弯路打转,路边散落纸团和叉号路牌,旁边的人递上一张画着对勾直路的新卡片

需求没想清楚,让它反过来访谈你

五件套摆在你面前,你发现自己连 Done When 都填不出来,说明问题不在提示词,在需求本身。这时候别硬编,两个办法。

一是 Plan 模式。Codex CLI 里敲 /plan,把模糊需求原样丢进去,它不会立刻动手,会先扫文件、提澄清问题、给一份分步计划,你审完计划它才开工。OpenAI 官方的说法是对多数用户这是最简单也最有效的选项,新手上手前两周建议把它当默认开关,慢一点,跑偏少一大截。

二是反向访谈,需求连自己都说不清的时候用。直接让它别写代码,先问你。

我想做的目标是 X,细节没完全想清楚。

在你写代码之前,反过来访谈我,

提出 5 到 7 个最关键的澄清问题,

覆盖边界条件、失败回退、性能要求、集成点,

一次问一个,直到你能产出一份精确规格为止。

不要写代码,只问问题。

它会接连问你,失败状态怎么展示给用户,并发上限多少,数据保留多久。像医生问诊,你说不舒服,医生不会直接开药,会先问哪里不舒服、多久了、吃过什么。这些问题不是它不专业,恰恰是它知道关键变量在哪。让 AI 当问诊医生,比让 AI 当算命先生靠谱得多。

还有个副产品别浪费。你回答过的那些问题,回头看看,好几条其实是项目规则,该进 AGENTS.md 的就升级过去,下次不用再答一遍。老雷见过的团队里,AGENTS.md 长得好的,多半都是反向访谈喂出来的。

先 vibe 后 spec,别在生产代码上找感觉

两种风格不是二选一,是有先后。社区跑出来的主流节奏是先 vibe 后 spec,两阶段走。

第一阶段用模糊提示词让 AI 快速试一到两个方案,看哪个方向能跑通,这一步是探路,代码丑一点无所谓。第二阶段方向定了,写五件套规格,让它按规格实现,补测试,再亲手审一遍 diff,然后才谈上线。

什么样的活必须走第二阶段,列四条就够了。要上生产、有多人协作、碰钱和用户数据、改核心架构和数据模型。反过来,周末玩具、试新框架、一次性脚本,放心 vibe,别浪费规格的功夫。

最常见的翻车是把这个顺序走反了。拿一句模糊需求直接写生产代码,跑通了算运气,跑不通就在烂对话里无限返工。真出了事别纠结,第一阶段的探索成果当草稿,第二阶段把五件套重新写一遍再让它实现,看起来慢,其实是最快的路。

最后给一个每周十分钟的复盘动作。翻一遍这周跑偏的对话,问自己三个问题,哪个跑偏是因为没写约束,哪个是因为没写完成标准,哪个是因为把五件事塞进了同一条提示词。教训直接进 AGENTS.md。积累的不是模板,是对自己思维盲区的认识。老雷自己跑了一年多,这条十分钟的复盘比任何高级技巧都值钱。

发出提示词之前,最后过一遍这五条。目标写了吗,@ 引用收到三个以内了吗,约束写了吗,完成标准写了吗,这件事和别的任务拆开了吗。五条全过,再按回车。

说到底,Codex 跑偏,多数时候不怪它,怪你只给了它一句话。五件套不是什么高级心法,就是把你想清楚的事说清楚。这套写法我自己也还在迭代,不成熟的地方肯定有,但它足够简单,今晚就能用上。

扁平矢量插画,道路前段是涂鸦探索小径插着玩具旗,过闸后变成画有标线和里程牌的正式车道,机器人推着规格卡片换装前行