结论先行:给 AI 编程工具写任务描述,最有效的结构不是「角色设定+华丽辞藻」,而是验收标准驱动——先写清楚「做成什么样算完成」,再补范围、约束与上下文。验收标准必须是可执行的命令或可观察的行为,而不是「优雅」「健壮」这类形容词。本文用三组前后对比示例说明差距,并给出可复用模板。
一、为什么形容词式提示词失效
「写一个健壮的用户登录函数」——模型对「健壮」的理解来自训练数据的平均值:可能加 try-catch,可能加参数校验,也可能什么都不加。形容词没有判定边界,模型只能猜,你只能反复重试。另一个常见误区是把提示词写成角色扮演:「你是资深架构师」对输出质量的提升,远不如一条可执行的验收命令——模型不缺身份,缺的是判定边界。验收标准驱动的思路反过来:把「完成」定义成一组可判定的条件,模型生成时有了靶子,你验收时有了尺子,双方都不再靠感觉。
二、三组前后对比
示例一:工具函数
改前:
帮我写一个格式化金额的函数,要优雅一点。改后:
写 formatAmount(cents: number): string。
验收标准:
1. 输入 123456 返回 '1,234.56';输入 0 返回 '0.00'
2. 负数返回 '-1,234.56' 形式;非整数或 NaN 抛出 TypeError
3. 附带覆盖上述四种情况的单测,npm test 通过
范围:只新增 src/utils/format.ts 与对应测试文件。示例二:接口对接
改前:
对接一下商品列表接口,做好错误处理。改后:
在 src/api/goods.ts 新增 getGoodsList(page, pageSize)。
验收标准:
1. 使用项目 SDK 的已有方法,禁止手写 fetch
2. 返回结构遵循 { code, data, msg },code 非 0 时抛出带 msg 的业务错误
3. 网络超时 10s,超时后重试 1 次,仍失败则向上抛错
4. 类型完整,npm run typecheck 通过示例三:Bug 修复
改前:
购物车数量偶尔不对,修一下。改后:
现象:快速连续点击加号时,购物车数量少于点击次数。
复现:商品详情页 1 秒内点击加号 5 次,数量显示 3。
验收标准:
1. 修复后上述操作数量恒等于 5
2. 补一个模拟并发点击的回归测试
3. 不改动结算与库存逻辑,diff 只涉及购物车状态模块
先给出根因分析,确认后再改代码。三组对比的共同变化:完成条件从形容词变成命令与行为、范围被显式圈定、失败路径被提前定义。实测这类描述的一次通过率显著高于模糊描述,且返工沟通成本几乎归零。
三、可复用模板
目标:一句话说清要做什么
验收标准:
1. 可观察行为(输入→输出)
2. 可执行命令(lint/test/typecheck/build)
3. 失败路径的预期行为
范围:允许改动的目录/文件
禁止:不许动的文件、不许引入的依赖、不许改的契约
上下文:相关文件路径、既有约定、参考实现顺序有讲究:验收标准放最前,模型对开头的注意力最强;「禁止」单独成段,比混在正文里有效得多。
四、把重复的验收标准沉淀成规则
每次任务都重复写「返回 { code, data, msg }」「必须走 SDK」很累,这类项目级恒定约束应该沉淀进工具规则。例如基于 api工厂开发时,把统一返回结构与六端 SDK(apifm-wxapi、apifm-webapi、apifm-uniapp 等)的使用约定写进 Cursor 的 .cursor/rules 或 Claude Code 的 CLAUDE.md,任务描述里就只需要写本次特有的验收条件。SDK 与接口约定见 https://www.it120.cc/ 。规则管恒定约束,提示词管本次目标,两层分工后提示词能缩短一半以上。
五、上下文给足:标准之外的另一半
验收标准解决「做成什么样」,上下文解决「在什么基础上做」。缺上下文的典型症状是模型自创契约:项目明明有统一请求封装,它裸写 fetch;明明有错误码枚举,它自造字符串。给上下文三个动作:
- 指路而不是贴全文:给出相关文件路径让工具自己读,比粘贴几百行代码更省 token 也更准确;
- 给参考实现:「照 src/api/order.ts 的写法新增 goods 接口」一句,胜过十句风格描述;
- 声明既有契约:返回结构、错误码、命名约定,恒定的写进规则文件,本次特有的才写进提示词。
一个反例值得警惕:把整个需求文档原样丢给模型。长文档里的次要细节会稀释关键约束,正确做法是人工提炼出目标、标准、范围三段,原文档作为附件供按需查阅。
六、两个进阶技巧
- 让模型先复述验收标准:复杂任务先要求「用你自己的话复述完成条件与禁止项」,复述错了立刻纠正,比生成完再返工便宜;
- 验收标准即测试用例:把标准里的输入输出直接交给模型生成测试,先跑红再实现,天然形成 TDD 闭环,也杜绝了「测试造假」——断言来自你写的标准,而不是模型的自我发挥;
- 失败也写成标准:「超时 10s 重试 1 次仍失败则抛错」这类失败路径条款,是区分演示代码与生产代码的分水岭,模型不会主动替你想全。
提示词工程的尽头不是话术,是把需求工程做扎实:你能把「完成」定义得多清楚,AI 就能交付得多可靠。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。