AI 成长第 2 讲：把提示词写成接口契约，而非神秘咒语

不少人使用 AI 编程时，只写一句模糊需求，却期待模型自动理解项目技术栈、团队规范和交付形式。结果一旦偏离预期，就继续叠加专家人设或所谓万能话术。真正需要补足的不是咒语，而是清晰的输入契约：把背景、任务、约束与输出格式说明白，才能减少无效猜测和反复返工。

AI 成长系列 · 第 2 讲：提示词是接口契约，不是咒语

• 系列：AI 成长系列
• 进度：02 / 18 · 入门篇
• 核心角度：你给下游服务提需求会写接口契约，对 AI 却只扔半句话然后怪它不懂你。四要素——背景、任务、约束、格式——就是 prompt 的 API 设计。

---

一、开场翻车：咒语失灵现场

阿K 上周被隔壁工位的老张刺激到了。老张用 AI 出活儿又快又好，阿K 凑过去偷师，看到老张的 prompt 开头赫然写着：

你是一位拥有 20 年经验的资深 Java 架构师，精通高并发与领域驱动设计。请深呼吸，一步一步思考……

阿K 如获至宝，整段抄了下来。

这周他接了个活：给订单系统加"导出 Excel"功能。他把咒语贴在最前面，然后写正事：

（咒语）帮我写一个导出 Excel 的功能。

输出回来：一份带注释的完整实现，用的 Apache POI，手写样式，Controller 里直接 new。能跑，但阿K 看着牙疼：公司规范用的是 EasyExcel；导出要走统一的异步任务和文件服务；返回结构必须是 Result<T>。这些 AI 一个都没对上。

阿K 把咒语加粗了一档——"世界顶级专家"改成"全球第一专家"，又跑了一遍。输出更华丽了，POI 还是 POI。

阿K 开始怀疑方向：是不是 AI 看人下菜？要不……再礼貌一点？

停一下，复盘这场翻车。**老张的咒语在他那儿好使，不是因为咒语灵，是因为老张的咒语后面还跟着三十行正经需求。**而阿K 只传了半句话的任务，剩下全指望 AI 心灵感应。

用程序员的话说：你调用一个接口，入参传了个 null，然后骂实现类返回了垃圾。

AI 不欠你一个"懂你"。它只认识你发过去的那段文本——**你没写的，等于不存在。**这不是模型能力问题——把同样的半句话发给组里最资深的工程师，他也只能靠猜。

二、核心方法：四要素接口卡

这一讲只讲一个方法：**把 prompt 当 API 设计。**四个要素，就是你这个"接口"的入参定义。

要素	回答的问题	对应接口设计
背景	你是谁？在什么环境？给谁用？	系统上下文 / 依赖说明
任务	要它做什么？	接口功能定义
约束	用什么干？不许干什么？	前置条件 / 入参校验
格式	输出长什么样？	出参 schema

背景：把它从"全网工程师"拉到"你们组的工程师"

模型默认是"见过全网的人"——你不说，它按大众做法来（大众用 POI，它就 POI）。背景就是把它拉进你的世界：技术栈、项目阶段、使用方、前置依赖。

背景：Spring Boot + EasyExcel 的订单系统，导出功能给运营后台用，对方用 Excel 2016 打开文件。

一句话，AI 就从"平均水平的互联网"切换到"你们组的业务环境"。

反面教材长这样："背景：Java 项目。"——等于没说。什么样的 Java？Spring Boot 哪个版本？谁调用？数据量多大？背景写得越像项目 README 的第一节，模型跑偏的空间越小。

任务：一个主任务，动词开头

"帮我看看这段代码"不是任务，是许愿。任务要能被验收：做什么 + 做到什么程度。

任务：实现订单列表导出 Excel 的 Service 方法，支持按状态筛选，单次最多导出 1 万行。

同一件事两种写法："帮我写个导出"（模型自由发挥，写完你来骂）对比"实现订单列表导出 Service 方法：入参是筛选条件对象，出参是文件流，超过 1 万行抛错而不是静默截断"（每一条都可验收）。后者的第一次产出，就能到八十分。

超大的任务（"帮我做个电商网站"）先自己拆——一个接口一个职责，prompt 也一样。怎么拆、怎么跟 AI 配合着拆，第 4 讲结对编程细说。

约束：把"事后骂"前置成"事前说"

约束是最值钱的要素，因为它防的是返工。技术选型、禁止事项、边界条件，全在这：

约束：用公司封装的 EasyExcelUtil；不要手写样式；异常抛 BizException 走全局处理；不要动 Controller 层。

阿K 翻车里那些"没对上"的点，全是约束。**AI 用 POI 不是它的错，是你没说。校验规则应该写在请求里，不是写在异常日志里。**写约束还有个小技巧：正向说"用什么"，负向说"不要什么"，两边都写。只写正向，模型会自作主张加戏——手写样式就是这么来的；只写负向，它不知道该往哪儿使劲。

格式：定义出参，不然每次都是开盲盒

不定义格式，同一个人连问三次能拿到三种结构。要接工具、要对比、要贴进文档的场景，格式必须定义：

格式：先给文件目录结构，再按文件给完整代码；每个文件一段，代码块标注语言。

格式不只是好看——它是你后续一切工程动作的接口：要对比两版输出，格式统一才能 diff；要把输出喂给下一个工具，格式对了才能解析。第 9 讲的提示词能沉淀成模板库，前提就是格式稳定。

万能接口卡模板

【背景】<技术栈 / 环境 / 使用方>
【任务】<动词开头的一个主任务 + 验收标准>
【约束】<必须用 / 禁止用 / 边界条件>
【格式】<输出结构 / 长度 / 语言>

四要素不用长——三五行的接口卡，胜过三十行的咒语。判断 prompt 合不合格就一个标准：**这需求要是发给组里新人，你会发这么半句话的工单吗？**不会。那你对 AI 也不该。

两个使用注意。其一，四要素不是表格题，是沟通题：熟练之后完全可以写成两段自然的大白话，只要背景、任务、约束、格式四个信息都在场，形式不重要——别为了填模板把 prompt 写成八股文。其二，要素有优先级：如果只够写两行，先写背景和约束——任务写错它会重做，方向带错它做得再漂亮也白做。

（先校准预期：四要素写全，输出也不保证满分——它只是把"猜错方向"的概率打到最低。第一次输出七十分怎么办？那是第 3 讲的事。）

三、常见错误：四种反模式

反模式一：咒语堆砌。"顶级专家""深呼吸""一步一步思考"——人设和仪式对"信息缺失"毫无帮助。该传的参数是 null，喊一万遍上帝也返回 null。（个别话术在特定场景确有小用，但那属于优化项——契约没立起来，优化无从谈起。）

反模式二：只给任务不给背景。"帮我写个导出"——模型只能按大众做法来，然后你在验收时逐条骂它"不符合我们规范"。规范不传，就等于默认不遵守。

反模式三：一句话塞十个任务。"帮我设计表、写接口、写前端、再写个部署脚本"——多职责接口是代码坏味道，prompt 同理。拆开，一张卡一件事。拆分的判断标准：这张卡要是发给你自己，你得换几种"脑子状态"才能干完？换了几次，就是几个任务。

**反模式四：不定义格式。**每次输出结构随机，没法对比、没法沉淀、没法接工具。你要的都没说，就别怪它每次给的不一样。

**反模式五：把 prompt 写成作文。**和咒语堆砌正相反的另一极：生怕漏信息，从业务起源写到人生感悟，八百字没一句约束。啰嗦不等于契约——信息密度低的 prompt，和信息缺失的 prompt，模型一样只能猜。写完扫一眼：每句话都在给模型传参数吗？不是的，删。

四、实操步骤：三步立契约

**第 1 步：写 prompt 前，先写工单。**心里过一遍："这需求发给组里新人，他会问回来什么？"他问回来的每一条，就是你漏传的参数。把这些问题记下来——它们就是你接口卡的迭代清单，也是第 3 讲反馈环节的弹药。

**第 2 步：套接口卡模板。**背景、任务、约束、格式，四行填满再发。宁多写两行，不多猜一轮。

第 3 步：发送前自检三问。

1. 有没有"它应该知道"的假设？——它什么都不知道，你公司的事只有你知道；
2. 任务是不是一个？——多了就拆；
3. 格式定了吗？——没定就是开盲盒。

**第 4 步：好用的接口卡存模板。**高频任务（写单测、写文档、写 SQL……）各存一张卡，下次改改参数直接用——这就是第 9 讲"提示词资产库"的第一块砖。

附栏：当前工具箱（2026-09）

工具细节有时效性，只进附栏。

场景	工具形态	四要素怎么用
重复性背景太多	各产品的"自定义指令 / 系统提示词"	把不变的背景、格式偏好沉淀成全局配置，任务里只写"任务 + 约束"
在 IDE 里干活	Cursor / Copilot 类的项目级规则文件（.cursorrules、CLAUDE.md 等）	项目背景写进规则文件，每次对话自动带上——"背景"要素的一劳永逸版
网页对话	通用对话窗口	四要素直接写在消息里；高频场景建个人模板片段
团队协作	团队共享文档 / 代码库	把共用的接口卡放团队级沉淀，人人改参数复用，不复写

一句话：背景要素的"沉淀"入口各工具都有——形态会变，"该传的参数一个都不能少"不会变。

五、课后练习：给同一个任务，装一次"接口"

拿你最近干过的真实任务（写代码、写文档都行），做一组对照实验：

1. 裸奔组：按你平时的习惯写一句任务（比如"帮我写个 XXX"），发出，存好输出；
2. 契约组：用四要素接口卡重写同一个任务，发出，存好输出。

可验证产出：一张对照记录，包含——

1. 两份输出各一份；
2. 契约组的接口卡原文；
3. 三条差异：契约组比裸奔组好在哪——或者你第一次发现，原来这三件事你从来没跟 AI 说清过；
4. 接口卡已存入你的模板库（第 9 讲的地基，从今天打起）。

如果契约组没赢——恭喜，你挖到了更值钱的东西：**这个任务可能复杂到一张卡说不清。**这正是第 3 讲"迭代"要解决的问题。

六、金句收尾

咒语是求神拜佛， 契约是传参干活。

AI 不欠你一个懂你——你传 null，它就返回猜。

现在你有一张合格的接口卡了。但工程里从来没有一次通过的需求：**第一版输出不满意怎么办？**下一讲讲迭代。

下一讲预告：第 3 讲《迭代：从一次失望到一次满意》——追问、给示例、给反馈的三轮闭环；以及什么时候该止损换工具。