规格驱动开发：让 Coding Agent 少改错方向的需求写法

新的失败模式：错得又快又多

人写代码的时代，理解偏差的破坏力有限——手速跟不上脑速，写错的代码三天就露馅，返工成本上限可估。Agent 时代的算式变了：理解偏差 × 执行速度。你说「优化一下这个模块」，Agent 三分钟产出两千行改动，横跨十个文件——方向一旦错了，返工虽然也是它做，但审查两千行错误改动的时间一点没少。更麻烦的是，方向错误的改动往往是「合理地错」：每一步都符合字面要求，合起来却不是你要的东西，审查时很难一眼看出问题。代码生产变快之后，瓶颈从「写」移到了「说清楚要什么」。

为什么规格突然值钱

你脑子里有一大堆模型没有的上下文：上周口头讨论的折中方案、这个接口三年前踩过的坑、团队对「什么样的代码能合入」的品味。Agent 一概不知，它只看你给的那句话。

规格（spec）的本质就是把这些缺失的上下文显式写下来——它是给模型的「上下文补丁」。还有一层原因：Agent 的工作记忆就是上下文窗口。人协作可以靠追问、白板、邮件随时补齐信息，Agent 只认请求里给的东西——规格写得越全，它脑中的世界模型就越接近你脑中的那一个。反过来，当你发现 Agent 总在同一类问题上跑偏，那通常不是模型不行，而是这类上下文从来没被写下来过。

一份好规格的六个部分

目标与不目标。 目标说要做成什么；不目标（non-goal）同样重要——「本次不改鉴权模块」「不引入新依赖」，一句话就能挡掉大片跑偏。
接口与数据结构约定。 函数签名、表结构、API 的输入输出提前定死，避免 Agent 自作主张发明一套。
边界条件与错误处理。 空列表怎么办、上游超时怎么办、并发下怎么表现。这些恰恰是 Agent 最容易跳过的部分。
验收标准。 必须是可测试的陈述：「POST /api/orders 在库存不足时返回 409 且错误体包含 sku 字段」，而不是「处理好库存不足的情况」。
涉及文件与约束。 明确可以改哪些文件、不许碰哪些文件；有代码规范、性能约束也写进来。
现有代码的关键事实。 相关模块在哪、复用哪个现成函数、哪段历史代码是刻意为之不要「顺手修复」。

三个反模式

形容词需求。「做得优雅一点」「更健壮一些」——没有可验证含义的词，Agent 只能按自己的理解执行，而它的理解未必是你的。改法是把形容词翻译成可验证的陈述：「优雅一点」换成「所有错误路径都有日志，抛出的异常带错误码」。
无限定范围。「顺便把周边也优化下」——「周边」在 Agent 那里是一个可以无限展开的词，改动面瞬间失控。
把实现步骤写成规格。 规格该写 what 与验收标准，不是 how。手把手写「第一步改这个文件第二行」既限制不住模型，还会漏掉你没想到的实现路径。例外：当你确实知道某个坑时，把「为什么必须这么做」写成约束。

实操流程

计划确认环。 下发规格后，先要求 Agent 复述它理解的需求与执行计划，你确认无误再放行。这一步能拦下大部分理解偏差，成本只有一轮对话。
大任务拆里程碑。 一个规格拆成可独立验收的几段，粒度以「一段能被人工确认」为准，每段产出都应该能运行、能测试，而不是一堆半成品改动。
每个里程碑跑测试。 验收标准写成测试用例，让 Agent 自己跑、自己过，人只看结果。
规格本身可以迭代。 执行中暴露的问题——没料到的边界、被误解的约定——值得回写进规格，下一次同类任务直接复用，规格会越写越准。

一个规格模板

## 目标
<一两句话说清要做什么，为什么>

## 不目标
<明确列出本次不做什么>

## 接口/数据结构
<函数签名、表结构或 API 契约>

## 边界与错误处理
<空输入、失败路径、并发等边界行为>

## 验收标准
- [ ] <可测试的陈述 1>
- [ ] <可测试的陈述 2>

## 涉及文件与约束
<可改动的范围、不许碰的部分、项目约定>

## 现有代码事实
<相关模块位置、可复用的函数、历史包袱>

小结

规格驱动不是多写文档，是把「说不清楚的需求 × 跑得飞快的 Agent」这对风险拆掉。六个部分里「不目标」与「验收标准」性价比最高；计划确认环是零成本的保险。Agent 时代开发者最值得投资的技能，是从「写代码的人」变成「写清楚问题的人」。