大家都在学提示词，但这不是根本问题
过去两年，"提示工程"这个词被炒得很热。怎么写系统提示、如何做 few-shot、Chain-of-Thought 的技巧......这些内容充斥着各类博客和教程。
但我观察到一个反直觉的现象：在真实项目里，AI 给出烂代码的最常见原因，不是提示词技术不行，而是需求本身没说清楚。
换句话说，问题出在"写"这一步，而不是"提示"这一步。
这听起来像废话，但它揭示了一个被严重低估的能力：把需求描述清楚的能力------或者更正式地说，Spec-Driven Development（规格驱动开发）。
在 AI 还没普及的时代，这个能力叫"需求分析"或"技术设计"，是 Tech Lead 和架构师的职责，普通工程师可以靠"我问一下 PM""你补充一下细节"糊弄过去。但在 AI 大规模进入开发流程之后，这个能力变成了每个工程师的必修课。
因为你现在的"同事"，是一个不会主动追问的模型。你不说清楚，它就猜。猜错了，你返工；猜对了，纯属运气。
一个可以做实验的案例
我来给一个具体例子，感受一下差距。
需求：实现一个"用户搜索"功能。
版本一（模糊规格）：
实现一个用户搜索功能，支持按名字搜索，返回匹配的用户列表。你把这句话丢给 AI，它会给你一个函数，能跑起来，看起来"正确"。但你没说的东西太多了：
• 搜索是精确匹配还是模糊匹配？支持拼音？
• 搜索结果按什么排序？
• 一次最多返回多少条？有没有分页？
• 空字符串搜索返回什么？全量？空列表？报错？
• 搜索词有没有长度限制？超出怎么处理？
• 已注销/封禁的用户要不要出现在结果里？
• 搜索性能要求是什么？100ms？1s？
• 大小写敏感吗？"Zhang San" 和 "zhang san" 是同一个结果？
AI 在这 8 个问题上全都会做出隐性假设。某些假设可能和你的业务逻辑完全冲突，但代码跑起来完全不报错，你只能等上线后用户反馈才能发现。
版本二（清晰规格）：
## 功能：用户搜索 API
### 接口
GET /api/users/search?q={keyword}&page={page}&size={size}
### 输入约束
- keyword: 1-50 个字符，不允许空字符串（返回 400）
- page: 从 1 开始，默认 1
- size: 10-100，默认 20，超出范围返回 400
### 搜索行为
- 对 username 和 display_name 字段做模糊匹配（LIKE %keyword%）
- 大小写不敏感
- 不返回 status=BANNED 或 status=DELETED 的用户
- 结果按 last_active_at DESC 排序
### 返回结构
{
"users": [{"id", "username", "display_name", "avatar_url"}],
"total": 数量,
"page": 当前页,
"has_more": bool
}
### 性能要求
- P99 在编写代码前，生成者与评估者就"完成"的定义达成一致。生成者提出实现方案和验证方法，评估者审核。这种"协商"机制确保了开发过程忠实于规格书，同时避免了过早过度规范。这个机制的核心是：把"完成"的定义写下来，在执行之前达成共识。
这是一个极其古老的工程智慧------测试驱动开发（TDD）的本质也是这个，先写测试（即定义"完成"），再写实现。
在 AI 协作的语境下，这个智慧有了新的形式：你写规格（Sprint Contract），AI 写代码，然后用规格验证代码。三个步骤，每一步都可以独立检查。
我把它抽象成一个更通用的工作流：
| 步骤 | 谁来做 | 产出 | 检查点 |
|---|---|---|---|
| 1. 写规格 | 工程师 | 接口定义 + 边界条件 + 验收测试用例 | 边界情况是否覆盖完整？ |
| 2. 让 AI 生成代码 | AI | 实现代码 + 单元测试 | 代码是否符合规格的约束？ |
| 3. 验证 | 工程师 + 自动化 | 测试报告 | 所有验收用例是否通过？ |
| 4. 反馈修正 | AI（带反馈上下文） | 修复后的代码 | 针对具体失败用例修复，而非重写 |
这个流程不是为了让开发变慢，而是为了让返工变少。前期多花 20 分钟写清楚规格，可以省掉后期 2 小时的 debug。
一个好规格长什么样
有些人一听"写规格"就觉得是要整 50 页的需求文档，开始抵触。但规格不需要很长，需要的是完整覆盖必要的维度。
我总结了一个轻量级规格模板，适合在 AI 协作场景下使用：
## 功能名称
一句话描述这个功能做什么。
## 背景与目标
为什么要做这个？解决什么问题？不要写废话，一两句说清楚就行。
## 接口/函数签名
明确输入输出类型，包括：
- 入参：名称、类型、是否必须、默认值
- 出参：结构、类型
- 可能的错误返回
## 业务规则
按优先级列出业务逻辑约束，例如：
- 规则一：什么情况下返回什么
- 规则二：边界情况如何处理
- 规则三：性能要求是什么
## 明确不做的事（Out of Scope）
这一栏极其重要。明确写出这个版本不实现什么，
可以防止 AI 过度实现，也可以防止未来被追责。
## 验收测试用例
至少 4 条：
1. 正常路径：最典型的使用场景
2. 边界路径：输入在合法范围的边缘
3. 异常路径：非法输入如何处理
4. 安全路径（如适用）：注入、权限绕过等这个模板用 Markdown 写，5-10 分钟就能填完。但它强迫你回答那些"不言而喻"的问题。
Out of Scope 是最被忽视的一栏
工程师写规格时最容易忽略的，是"不做什么"。
举个例子：你在做一个"评论"功能的第一版。你的规格里写了文本评论的所有细节，但没写"不支持图片评论"。AI 可能会给你加一个上传图片的逻辑，因为评论功能支持图片是"显然"的。
或者更隐蔽的情况：你没说评论不需要审核，AI 实现了一个异步审核队列，把你的评论功能变成一个需要 MQ 的复杂系统。
Out of Scope 不是在说"这些以后再做"，它是在说"这次实现的边界在哪里"。这个边界说清楚了，你和 AI 的协作才是可控的。
一个练习规格写作的方法
推荐一个具体可操作的练习方式，不需要任何额外工具：
方法：逆向拆解你用 AI 写出来的烂代码
找一段你用 AI 生成的、后来发现有问题的代码（几乎每个人都有这样的经历）。然后问自己：
• AI 在哪里做了你没想到的假设？
• 如果当时写了规格，这个问题能避免吗？
• 要避免这个问题，规格里需要加哪一句话？
把答案写下来，加进你的规格模板。重复 10 次，你的规格模板会变成一个针对你自己项目的"坑点清单"，比任何通用模板都有用。
这个练习有一个副产品：你会开始对代码质量的判断更加敏锐。"这段代码对空输入的处理是不是有问题？" "这个 API 的错误码语义是不是不一致？" ------这些问题，是 AI 生成代码无法自动识别的，但是有规格写作习惯的工程师会自然地去检查。
从规格到可验证系统
说到底，规格写作能力的本质是把模糊的意图转化成可验证的标准。
这个能力在 AI 出现之前就很重要，只是没被特别强调。在 AI 成为开发流程核心参与者之后，它变得不可或缺------因为你的"协作方"无法靠上下文推断你的意图，只能靠你显式说出来的规格。
林俊旸在那篇文章里说，未来的竞争优势来自"环境设计"，关键指标是"稳定性、现实性、覆盖范围、抗欺骗性"。
我认为规格写作是"环境设计"的起点。
一个写了清晰规格的工程师，给 AI 的是一个有边界、有验收标准、有错误路径的任务。这个任务可以被自动验证，失败可以被精确定位，修复可以有针对性。这是一个"稳定、有覆盖范围、能抗欺骗"的环境。
一个不写规格的工程师，给 AI 的是一个模糊意图。AI 会尽力猜，有时猜对，有时猜错，错了你还不知道为什么。
两种工作方式，在个人效率上可能差 3-5 倍。在团队层面，这个差距会被放大。
一个更大的视角
有个说法流传很广：未来工程师的价值不在于"写代码"，而在于"知道写什么代码"。
这话对，但不够具体。"知道写什么代码"背后是一整套能力：
• 理解业务目标，把它翻译成技术需求
• 识别关键的边界情况和风险点
• 把"想要什么"转化成"什么算做到了"
• 知道哪些地方 AI 可能犯错，提前设防
这不是什么新能力，它是系统性工程思维的体现。只是在 AI 时代，这个能力的经济价值被大幅提升了------因为它决定了你能不能把 AI 的生产力真正"解锁"。
会用 ChatGPT 的人很多。能给 ChatGPT 写出一份清晰规格、让它一次性生成高质量代码的人，目前还是少数。
这个差距，就是机会。
下一步值得探索的方向
如果你对规格驱动开发感兴趣，几个值得深入的方向：
• BDD（行为驱动开发）：Gherkin 语法是一种把规格写成机器可读格式的方法，和 AI 协作有天然的契合性
• OpenAPI / JSON Schema：对于 API 开发，这是最成熟的"可验证规格"格式，AI 对这两种格式的理解能力远超自然语言
• 形式化方法（Formal Methods）：对于安全性要求高的系统，TLA+ 或 Alloy 提供了比 Markdown 规格更强的可验证性，虽然学习曲线陡，但 AI 在辅助生成这类规格方面已经开始有实际价值
• Property-based Testing：Hypothesis（Python）或 fast-check（JS）这类工具，可以从规格自动生成大量测试用例，配合 AI 生成代码，是一个很有潜力的组合
规格写作是个看起来平凡、但做到极致很难的能力。现在开始练，比两年后 AI 工具更成熟时再学，要划算得多。
本文基于 Anthropic Harness 研究报告、林俊旸技术长文及实际 AI 协作工程实践整理