一句话理解Prompt 猜意图,规格立契约——AI 从此按合同办事。 本文产出SSD 四件套质量自检 Checklist(本章末尾,可直接复制使用)好规格 vs 坏规格 10 条对照表(带反面案例)三句话迷你 proposal 模板(适用于 PoC / 一天内原型) 商业价值团队协作项目中,一个字段类型的改动如果没有 spec,平均需要工程师逐行排查代码定位影响范围;有 spec 时,改动定位到 spec 的 diff 上即可完成影响分析( 推断,非实测)。对中大型团队而言,这直接决定了需求变更是一次可控的迭代,还是一次返工事故——规格化投入的边际成本,远低于一次线上回滚的成本。 推断声明本文涉及的效率数字(40-60%、2-3 倍、70%)来自对多份公开 AI 工程效率报告的综合估算,非作者本人实测数据,仅供理解规格化收益的大致方向参考,不构成量化承诺,正文中均标注( 推断)。实战案例代码均为示意片段,非生产就绪代码。导流去向理念理解后 → 博文 10(OpenSpec 完整实操)已理解理念想直接上手 → 博文 10(跳过本篇)Spec 如何驱动高质量代码实现 → 博文 11(SDDTDD 双驱动工作流)直接让 AI 写代码,本质上是在赌 AI 猜对了你的意图。不是 AI 不够聪明——问题出在信息差上。你脑子里有架构、有约束、有历史包袱,AI 看到的只是那一句话。猜对是运气,猜错是常态。多份 AI 工程效率报告的综合估算显示,采用规格驱动开发的项目,AI 生成代码的一次通过率可提升 40-60%,团队协作效率可提升 2-3 倍( 推断,非实测)。这个方向背后其实只说明一件事:给 AI 更精确的合同,比给它更强的算力更有用。一、三个环节,每个都在猜依赖 AI猜意图的问题,体现在三个环节。不是单点失误,是系统性漏洞。需求理解:你说实现用户管理——这个词在 AI 的训练数据中出现过数十万次,每次含义不同。你的项目里可能有组织架构、角色权限、审批流程,但 AI 看到的只是通用的用户 CRUD。它不会问你,它直接补全。技术选型:你没说用 JPA 还是 MyBatis,AI 选了训练数据里频率最高的方案。如果你项目用了 MyBatis-Plus,AI 生成的新代码可能用了 JPA——它的默认选择是统计结果,不是你的项目上下文。边界定义:你没说email 全局唯一,AI 默认不做校验。你没说status 只接受 ACTIVE/INACTIVE/BANNED,AI 可能用任意字符串。当指令模糊时,AI 的策略是:选训练数据中最常见的模式填进去。三个环节叠加,就是为什么看起来正确的垃圾代码会持续产生。SSD 逐个切断这三条漏洞链路。二、SSD vs 其他驱动方式在 AI 时代,有四种主流的告诉 AI 该做什么的方式。核心区别只有一个:你的意图是否被结构化固化下来。规格驱动(SSD)proposaldesignspectasksAI 按合同执行精确可控团队共享 · 版本化Prompt 驱动实现用户管理AI 猜意图方向可能偏对话结束即丢失方式可维护性AI 准确率团队协作适用场景注释驱动低(注释易过时)中(上下文碎片化)差(无标准格式)个人快速开发提示词驱动极低(不可复用)低(窗口限制)极差(一人一 Prompt)一次性任务文档驱动中(文档与代码分离)中(需手动关联)中(可读不可执行)小型项目SSD(规格驱动)高(Spec 即代码)高(结构化契约)好(多 Agent 通用)中大型项目/团队协作注释驱动的局限:粒度天然有限。一个方法上的// 计算税费注释,无法告诉 AI 哪些税率适用、哪些可以抵扣、什么情况免征。注释描述的是做什么,不是做到什么程度。提示词驱动的致命伤:对话结束即丢失。今天花 20 分钟打磨的一条完美 Prompt,明天换一个会话就找不到了。团队协作时,每个人都在用自己的方式描述同一个需求——同一个功能,三个人写出三种理解。文档驱动的尴尬:项目有完善的 PRD 和设计文档,但 AI 从中提取信息效率很低。非结构化的自然语言段落,AI 需要自行判断哪些是关键信息、哪些是背景描述。AI 还是在猜,只是猜测的素材更多了一点。三、四件套的定位与关系SSD 的核心是四份文档组成的规格体系。它们不是可选的补充材料,是 AI 执行任务时的上下文和约束边界。缺任何一份,AI 都在某个环节开始猜。通过通过不通过 proposal做什么,为什么做边界在哪里️ design怎么做,用什么做技术选型 · 风险点 specAPI 定义 · 数据模型字段约束 · 错误码✅ tasks分几步 · 依赖关系每步验收标准 AI Agent 执行Gate 1提案确认编码 Agent 按 tasks 逐条执行Gate 2功能确认 归档 · spec 成为项目知识修正后重新 Gate 2文档回答的问题核心内容主要读者proposal做什么,为什么做需求背景、功能范围、不做事项PM / 业务方design怎么做,用什么做技术选型、架构图、模块划分、风险点工程师 / Tech LeadspecAPI 长什么样OpenAPI 定义、字段约束、错误码、数据模型AI Agenttasks分几步走任务清单、依赖关系、验收条件、Gate 检查点AI Agent实战:退款功能的四件套长什么样抽象谈四件套容易停留在概念层。下面用电商系统订单退款功能,展示四件套如何逐层递进,以及每一层为 AI 消除了哪些歧义。proposal(做什么)功能:支持买家申请退款 背景:用户投诉率上升,主因是退款流程不清晰 范围内:仅支持原路退款;仅支持全额退款 范围外:不支持部分退款;不支持跨订单合并退款;不处理纠纷仲裁 验收:退款请求提交后 24 小时内到账,成功率 ≥ 99%这一层让 AI 从一开始就知道边界。不支持部分退款这句话,价值等于省掉一次返工。design(怎么做)调用路径:后端调用支付网关退款 API → 更新订单状态 → 写退款日志 数据库变更:新增 refund_log 表(id, order_id, amount, status, gateway_ref, created_at) 幂等保障:refund_log 表对 order_id 加唯一约束,防止重复退款 风险点:支付网关超时处理(最长等待 30s,超时标记 PENDING 异步轮询)AI 在写代码前就知道选哪张表、幂等怎么做、超时怎么处理。这三点,普通 Prompt 一条都给不到。spec(API 长什么样)POST /api/orders/{orderId}/refund请求体:reason:string# 退款原因,必填,最长 200 字operator:string# 操作人 ID,必填响应:refund_id:string# 退款记录 IDstatus:enum# PROCESSING | SUCCESS | FAILEDestimated_arrival:string# 预计到账时间,ISO8601错误码:4001:订单不存在4002:订单状态不允许退款(已退款/退款中)4003:超出退款时限(下单超过 180 天)5001:支付网关调用失败这份 spec 给 AI 的不是需求描述,是合同。AI 生成 Controller 代码时,字段名、类型、错误码直接按 spec 抄写,不需要猜。tasks(怎么拆步骤)Task 1:创建 Refund Entity 数据库迁移脚本 验收:refund_log 表存在,order_id 唯一约束生效 Task 2:实现 RefundService(幂等检查 网关调用 状态更新) 验收:同一 order_id 重复调用不产生两条退款记录 Task 3:实现 RefundController(入参校验 权限检查 错误码映射) 验收:Postman 测试 4001/4002/4003 错误场景均返回正确 code Task 4:编写集成测试(正常流程 网关超时场景) 验收:测试覆盖率 ≥ 80%,CI 通过每个 Task 有明确的验收标准,AI 知道做到什么程度算完成。没有这个标准,AI 的默认行为是能跑起来就算完。四、好规格 vs 坏规格的 10 条标准#标准好规格示例坏规格示例1原子性“实现用户注册,含邮箱验证”“优化系统性能”2可验证“P99 响应时间 200ms”“速度要快”3无歧义“密码至少 8 位,含大小写字母和数字”“密码要安全”4完整性含正常流程 异常流程 边界条件只写用户登录5一致性与已有模块命名规范一致自创一套命名风格6可追踪“对应需求文档 §3.2”无来源,无上下文7版本化“v1.2,2026-03-15 更新”无版本信息8机器可读结构化 YAML / OpenAPI / JSON Schema纯自然语言段落9抽象恰当“用户通过邮箱注册”“点击输入框输入邮箱”10可演进“后续可扩展 OAuth 登录(接口预留 provider 字段)”“一次性交付,不考虑扩展”最重要也最容易被忽视的是第 8 条:机器可读。如果 AI 无法解析你的规格,它本质上还是一份传统文档,不是 SSD。测试标准很简单:把你的 spec 复制给 AI,问它根据这份 spec 生成 Controller 代码——如果 AI 需要反问你字段类型或错误码,这份 spec 就没写到位。五、SSD 的边界:什么时候不用SSD 不是银弹,过度工程化会适得其反。判断标准只有一个:这件事的模糊成本,是否高于写规格的成本。探索性任务:你不知道要什么结果,先写代码试试看。规格会锁死探索空间,这时候的不清晰是刻意保留的。典型场景是 PoC 和技术预研——三句话的迷你 proposal 就够了。三句话迷你 proposal 模板(直接套用):做什么:[一句话描述目标] 不做什么:[一句话划定边界,防止 AI 过度发挥] 验收条件:[一句话说明跑起来长什么样算成功]比如验证一个向量检索方案:做什么:验证 pgvector 在 10 万条数据下的检索延迟;不做什么:不考虑分布式部署,不做前端展示;验收条件:P95 延迟数据可复现即可,不要求生产级代码质量。10 分钟写完,比不写省下的返工时间通常更多。一天内原型:验证性 demo 不需要四件套。但要养成一个习惯:哪怕是原型,也套用上面的三句话模板——它既能对齐你和 AI 的预期,又能在原型被转正时作为正式 spec 的起点。个人项目:只有你一个人开发时,规格的团队协作价值无法体现。这种情况下,用 git commit message 级别的描述即可。等项目复杂度上升、或有人加入,再补充完整规格——此时已有的提案、设计记录和 commit history 就是规格的原始素材。一个实用的判断流程:否是否否是是任务超过1 天工作量?迷你 proposal3 句话即可有其他人参与或接手?需求是否明确不变?完整四件套proposal tasks可省略 design六、SSD 与 TDD、BDD 的关系三者不是替代关系,是不同粒度的工程约束,覆盖的问题层次不同。SSD(规格驱动)最上层回答:做什么、范围在哪里BDD(行为驱动)中间层回答:具体行为是什么Given / When / ThenTDD(测试驱动)最底层回答:实现是否正确红→绿→重构一个完整的 AI 工程实践里,三者协同工作:SSD 的 tasks定义这个功能做什么,是 BDD 场景的来源BDD 的 Given/When/Then描述具体行为,可以直接生成测试骨架TDD 的测试用例验证 AI 生成的实现代码是否符合 spec当执行者从人类程序员变成 AI Agent,规格的维度必须从单一的测试用例,扩展到整个开发流程的契约体系。SSD 是 TDD/BDD 在多 Agent 时代的自然延伸。七、反直觉结论:需求越不稳定,越需要 SSD直觉上,需求频繁变更时写规格不划算——今天写的明天就改。这个直觉是错的。原因在于:没有规格的变更,是在猜改哪里;有规格的变更,是在算改哪里。具体来看三个维度的差异:变更定位:没有 spec 时,一个字段类型的改动,需要逐行检查代码找出所有影响点。有 spec 时,改动发生在 spec 的 diff 上,影响范围一眼可见——哪些接口受影响、哪些 Task 需要重做,直接从 spec 的字段引用链推导。AI 重新执行:有规格时,需求变更的工作流是:改 proposal → 更新 spec → AI 按新 spec 重新执行受影响的 tasks。没有规格时,你需要用自然语言告诉 AI上次的代码要改这里,AI 的理解误差叠加在原本就模糊的上下文上。团队对齐:需求频繁变更时,团队最容易失步。没有规格,三个人对当前需求的理解可能是三个版本。spec 的版本号和 diff 让变更可见、可追溯、可验证。这三点合起来,就是开篇提到的那组估算数字(需求变更影响分析时间缩短约 70%, 推断)背后的逻辑——不是因为变更变少了,而是因为每次变更的边界清晰了。八、本章产出:SSD 四件套质量自检 Checklist在将规格交给 AI 执行之前,逐项检查。proposal 检查(P0,必须全部通过)写明不做什么(边界比做什么更重要)有可量化的验收条件(不是功能完成,是通过率 ≥ X%)说明为什么现在做(背景 / 触发条件)与已有功能的关系已说明(扩展 / 替换 / 独立)design 检查(P0,必须全部通过)技术选型有明确选择(不是JPA 或 MyBatis 均可)数据库变更已列出(新增/修改的表和字段)至少一个风险点已识别,有应对方案模块边界已说明(谁调用谁,谁不应该知道谁)spec 检查(P0,必须全部通过)所有字段有类型定义(string / int / enum,不是文本)enum 类型列出了所有合法值错误码已定义,且覆盖主要异常场景必填 / 选填已标注格式约束已写明(最大长度 / 正则 / 日期格式)tasks 检查(P1,强烈建议)每个 task 可以独立执行(无隐性依赖)每个 task 有明确验收标准(不是功能正常)task 之间的依赖顺序已标注每个 task 预估时间 ≤ 4 小时(超过则继续拆分)下一章预告这一篇是 SSD 的理念篇,讲的是为什么需要规格以及规格该长什么样。下一篇是 SSD 的动手篇:用 OpenSpec CLI 从零完成一个完整的 SSD 流程——从 proposal 到 design,从 spec 到 tasks,再到 AI 逐任务执行。你会看到规格文件的真实格式,以及 AI 在结构化约束下的执行效果与无约束状态下的对比。本专栏的开源落地工具IvyFlow本专栏的整套方法论——多角色工作流、阶段守卫、OpenSpecSuperpowers 双驱动、Skill/Rule/Agent 三层分层——并非纸上谈兵。它们的落地载体是 IvyFlow一个 AI-Native 开发工作流 CLI 工具也是本专栏作者的开源项目。IvyFlow 用一条命令ivy init在项目中部署 5 种角色Developer / PM / QA / Architect / DevOps共 20 条命令和约 30 个 Skill将专栏中讨论的Phase Gate、Delta Spec 反写、TDD 强制循环、SubAgent 并行扇全部编码为脚本校验而非纯 Prompt 约定——守卫脚本会硬性拦截 AI 跳过阶段的行为让流程纪律从建议变成物理约束。GitHubgithub.com/jseko/IvyFlow官方网站jseko.github.io/IvyFlow安装npm install -g ivyflow-cli ivy init如果你读完本专栏想立刻落地IvyFlow 就是这套体系的开箱即用入口。