AI 时代最被低估的工程师技能：把需求写清楚

📰 科技要闻

• 前阿里千问技术负责人林俊旸离职后发布长文，系统阐述从"推理思维"到"智能体思维"的范式转移，强调环境设计与验证机制是下一阶段核心壁垒。

• Anthropic 发布 Harness 架构研究，其"冲刺合同"机制将验收标准前置，实现多 Agent 自主完成长时程开发任务，成本与质量均达到新水位。

• 苹果公司据报道将开放 Siri 接入第三方 AI 助手，标志着主流科技公司开始正式拥抱 AI 能力的平台化整合战略。

大家都在学提示词，但这不是根本问题

过去两年，"提示工程"这个词被炒得很热。怎么写系统提示、如何做 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 < 200ms（数据量 < 100万用户时）
- username 和 display_name 需要建全文检索索引### 测试用例
1. keyword="zhang"，返回所有用户名或显示名包含 zhang 的活跃用户
2. keyword=""，返回 400
3. keyword="a"*51，返回 400
4. 搜索结果中不包含 BANNED 用户（即使 username 匹配）

把这段规格给 AI，得到的代码和第一版有本质差别——不只是功能完整，而且边界情况处理正确，测试用例直接可以跑。

同样是"写给 AI 的输入"，质量差距是天壤之别。

为什么工程师天然不擅长写规格

这不是在批评任何人，而是有结构性原因的。

原因一：工程师习惯"跑起来再说"

代码是可执行的，跑一下就知道对不对。这个即时反馈循环让工程师形成了"边做边想"的思维习惯。写规格是反直觉的：你要在代码还不存在的情况下，想清楚所有的可能性。

这种"前置思考"很累，而且收益是延后的。短期来看，直接写代码更快——至少能出点东西。

但这个逻辑在 AI 协作的场景下失效了。因为 AI 写代码的速度比你快得多，"先写再改"的循环成本急剧上升：你可能已经有了 300 行代码，但它们建立在错误的假设上。

原因二：隐性知识无法显式化

经验丰富的工程师在脑子里存了大量的"不言而喻"：登录接口要防暴力破解、搜索结果要考虑脏数据、分页要考虑游标还是 offset……

但这些知识在脑子里，不会自动出现在规格文档里。写文档的时候你想的是"这很显然，不用写"，结果 AI 完全不知道这个假设，生成出来的代码漏了这个最重要的约束。

这是一种认知偏差——知识的诅咒（Curse of Knowledge）：越懂的人，越难站在不懂的角度去描述问题。

原因三：规格文档是"成本"而非"产出"

在大多数团队的考核体系里，写代码是产出，写文档是开销。Sprint velocity 看 story points，不看规格质量。架构评审会关注技术方案，但很少有人认真看边界情况有没有列全。

这个激励结构导致规格文档要么不写，要么写得敷衍。

短期这没问题，因为开发团队内部可以靠沟通弥补。但 AI 没有办法"靠沟通弥补"——它没有上下文，没有隐性记忆，没有办法问你"这个边界情况你想怎么处理"。

Anthropic 的"冲刺合同"是个好框架

Anthropic 在他们的 Harness 研究里，提到了一个叫"冲刺合同"（Sprint Contract）的机制：

在编写代码前，生成者与评估者就"完成"的定义达成一致。生成者提出实现方案和验证方法，评估者审核。这种"协商"机制确保了开发过程忠实于规格书，同时避免了过早过度规范。

这个机制的核心是：把"完成"的定义写下来，在执行之前达成共识。

这是一个极其古老的工程智慧——测试驱动开发（TDD）的本质也是这个，先写测试（即定义"完成"），再写实现。

在 AI 协作的语境下，这个智慧有了新的形式：你写规格（Sprint Contract），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 协作工程实践整理