别让 Agent 猜需求：前端用「一页 Spec」把返工砍掉一半

发布日期：2026-08-04

标签：前端 / AI 编程 / Cursor / Spec 驱动 / Vibe Coding / 工程实践

上周一个同事跟我说：

「我用 Cursor 一天能干完以前三天的活。但奇怪的是，这个迭代我反而更累------因为返工也变成三倍了。」

这句话把我钉住了。

不是模型变笨了，也不是 Rules 没写好。真正的问题更朴素：

Agent 写代码的速度，已经远远超过我们「把需求说清楚」的速度。

你随口一句「做一个筛选面板」，它能给你状态管理、URL 同步、埋点、骨架屏、空态动画。第二天产品说「只要三个下拉，不要进 URL」------你不是在修 Bug，你是在拆除一座没人批准的大楼。

📌 Agent 收到「做一个筛选面板」之后的心理活动：既然你没说不要，那我就全都要。

我在别急着 Vibe Coding 里写过：能跑不等于能交付。这篇是它的续集，回答更落地的问题------

那到底怎么对齐？要不要上 Spec Kit？要不要写十页文档？

我的答案很克制：

大多数前端需求，不需要完整 SDD 工具链。你需要的是一页「写给 Agent 看的 Spec」。

写清楚再生成，返工会肉眼可见地下降。这篇文章给你：为什么、怎么写、两个完整例子、以及什么时候别写。

全文大约 12～15 分钟。建议按顺序读完------后面的模板，是直接能粘进 Cursor 的。

一、为什么「猜需求」在 AI 时代特别贵？

以前手写慢，猜错了也只错一小块。现在 Agent 猜错，会错得又快又完整。

以前手写猜错	现在 Agent 猜错
少写一个状态	多造一层状态机
少一个空态	顺手引入三个抽象 Hook
改三五个文件	改十几二十个文件
你记得自己为什么这么写	你要先读懂它的世界观再删

Agent 的强项，恰恰是把模糊话补成「看起来完整」的实现。模糊 = 它自由发挥；自由发挥 = 你的仓库方言被互联网平均水平覆盖。

所以 AI 时代前端真正变贵的，不是敲代码，而是这三件事没对齐：

目标：用户完成后到底能做什么？
边界：这次明确不做哪些？
验收：怎样才算做完，而不是「看起来能点」？

Spec 的本质，不是写文档 overlapping PRD，而是把这三件事写成 Agent 无法假装读过的约束。

🎭 左边：一句「好用一点」，现场变施工队狂欢。右边：一页 Spec，机器人终于知道围栏在哪。

二、先澄清：Spec ≠ 又一份 PRD

很多人一听 Spec，脑海里浮现的是：开两天评审会、输出三十页、没人维护。

那不是我们要的。

	传统 PRD	写给 Agent 的 Spec
读者	人（产品 / 设计 / 开发）	人先确认，再交给 Agent 执行
篇幅	常常很长	多数需求一页就够
重点	背景、价值、商业目标	行为、边界、验收、约束
生命周期	需求评审后常被遗忘	跟着这次改动走，做完可归档
失败表现	理解不一致	Agent 乱抽象、乱扩 scope

一句话：

text 复制代码

PRD 讲「为什么做」
Spec 讲「做成什么样算对，以及绝不能做成什么样」

你仍然需要和产品对齐；Spec 是把对齐结果，翻译成 可执行的交付契约。

这也是为什么最近「Spec 驱动开发 / SDD」这么火------GitHub Spec Kit、OpenSpec 都在做同一件事：先规格，后实现。但前端日常迭代里，我更推荐从 最小一页 Spec 开始，而不是一上来装整套工具链。工具是放大器；没有 Spec 肌肉，工具只会帮你更快产出空文档。

三、前端 Spec 为什么要单独说？

后端 Spec 常围绕接口与数据；前端 Spec 多了三块 Agent 最爱「自由发挥」的地方：

1. 界面状态，不只是主路径

AI 默认写快乐路径。前端翻车却经常发生在：

空列表
加载中
加载失败 / 重试
无权限
字段超长 / 极端数据

不写进 Spec，它几乎不会主动补齐。

2. 交互细节，不是「能点就行」

例如筛选面板：

条件变化是立即请求，还是点「查询」才请求？
是否同步到 URL？刷新后能否恢复？
移动端是抽屉还是折叠？

这些不写，Agent 会按「常见最佳实践」各选一套------往往不是你们产品要的那套。

3. 仓库方言，大于互联网最佳实践

你们是用已有 FilterBar，还是新建 AdvancedFilterOrchestrator？

表单是 Formily、React Hook Form，还是项目封装？

Spec 里点名 参考文件，比写一百句「请遵循最佳实践」有用。

四、一页 Spec 模板（可直接复制）

下面这页，是我过去半年用得最多的结构。够短，才会真写；够硬，Agent 才跑不偏。

🧾 理想中的 Spec：薄到能捏在手里，硬到 Agent 撕不烂「不做清单」。

markdown 复制代码

# Spec：<功能一句话名>

## 1. 目标（用户能完成什么）
- 作为 <角色>，我可以 <动作>，以便 <价值>
- 成功时用户看到：...
- 失败时用户看到：...

## 2. 范围
### 做
- ...
### 明确不做
- ...
- ...

## 3. 界面与状态
| 状态 | 表现 | 触发 |
| --- | --- | --- |
| loading | ... | 首次进入 / 刷新 |
| empty | ... | 列表长度为 0 |
| error | ... | 接口失败，提供重试 |
| ready | ... | 有数据 |

## 4. 交互规则
- ...
- ...

## 5. 数据与接口
- 使用接口：`METHOD /path`
- 关键字段：...
- 错误码处理：...

## 6. 约束（仓库方言）
- 参考实现：`src/.../Xxx.tsx`
- 允许改动的目录：`src/features/foo/**`
- 不要新增的模式：不要新建全局 store；不要引入未使用的 UI 库
- 技术约束：React 19 + 现有组件库；移动端优先

## 7. 验收清单（人工手测）
- [ ] ...
- [ ] ...
- [ ] ...

## 8. 开放问题（未确认前禁止实现）
- [ ] ...

怎么用进 Cursor（最小闭环）

🔁 最小闭环就四步：写清 → 对齐方案 → 最小实现 → 按清单勾。缺任何一步，都容易退回「盲修三轮」。

text 复制代码

1. 你先写 Spec（或让 Ask/Plan 帮你起草，人改）
2. Plan 模式：基于 Spec 列出将改文件与风险，等你确认
3. Agent 模式：只按确认后的 Spec 最小实现
4. 你按「验收清单」手测，不通过就回到 Spec 改约束，而不是让它盲修三轮

一段可直接粘贴的开场白：

text 复制代码

先不要改代码。

请阅读我附上的 Spec，并输出：
1. 你理解的目标与「不做清单」
2. 将修改的文件列表（尽量少）
3. Spec 中仍模糊、需要我确认的点
4. 建议的手测顺序

等我确认后，再按 Spec 最小改动实现。
禁止引入 Spec 未允许的新架构模式。

这和四模式选型是配套的：Spec 解决「对齐什么」，模式解决「用哪把刀」。

五、例子 1：模糊需求如何变成可执行 Spec

产品原话

「列表上面加个筛选，好用一点。」

如果直接丢给 Agent，常见结果是：日期范围、关键词、三个下拉、URL 同步、本地缓存、重置动画......全来了。

对齐后的一页 Spec（节选）

markdown 复制代码

# Spec：订单列表筛选（基础版）

## 1. 目标
- 运营可以按「订单状态 + 下单日期」缩小列表，快速找到待处理订单。
- 成功：列表按条件刷新；失败：Toast + 保留上次成功结果。

## 2. 范围
### 做
- 状态下拉：全部 / 待支付 / 已支付 / 已取消
- 下单日期：开始日、结束日（可清空）
- 点击「查询」后请求；点击「重置」恢复默认并请求
### 明确不做
- 不同步 URL
- 不做关键词搜索
- 不做筛选条件本地缓存
- 不改表格列与导出

## 3. 界面与状态
| 状态 | 表现 |
| --- | --- |
| loading | 表格骨架，筛选区可点但查询按钮 loading |
| empty | 表格空态文案：「暂无符合条件的订单」 |
| error | 表格区错误态 + 重试 |
| ready | 正常表格 |

## 4. 交互规则
- 仅点击查询/重置才请求；改条件不自动请求
- 结束日早于开始日：Inline 错误，阻断查询
- 移动端：筛选收入折叠面板，默认收起

## 6. 约束
- 参考：`src/pages/order/OrderList.tsx` 现有分页与请求封装
- 只改 `src/pages/order/**`
- 复用现有 `DateRangePicker`、`Select`，禁止新增筛选相关依赖

## 7. 验收清单
- [ ] 选「待支付」+ 日期区间，点查询，列表变化正确
- [ ] 重置后恢复默认并重新请求
- [ ] 结束日 < 开始日无法查询并有提示
- [ ] 接口失败可重试，不丢筛选条件
- [ ] 刷新页面后筛选条件不保留（符合「不同步 URL」）

把这页丢进 Plan，再进 Agent------产出会「少得令人安心」。少，才是这个场景的正确形状。

六、例子 2：活动页「图集段落」------连交互隐喻都写进 Spec

前端还有一类需求更虚：「做好看一点」「有点高级感」。这类最容易 Vibe 翻车。

产品原话

「旅行回顾那一块别用普通轮播了，要有感觉。」

Spec 关键片段

markdown 复制代码

# Spec：旅行回顾图集（叙事段）

## 1. 目标
- 用户愿意停留并主动浏览 6～12 张旅行照片，而不是 3 秒滑走。
- 成功标准：首屏后第一屏图集可完整体验主交互；不阻塞下方报名 CTA。

## 2. 范围
### 做
- 使用「胶卷条」隐喻：横向拖动 + 松手吸附整帧
- 展示 title / 短描述
- 提供桌面与移动端基础手势
### 明确不做
- 不做自动播放
- 不做 3D / WebGL
- 不在本段塞表单或倒计时
- 不替换页面其它轮播（商品 SKU 区仍用原轮播）

## 4. 交互规则
- 松手必须吸附到整帧，禁止停在半帧
- 用户开始拖动后，禁止任何自动切帧
- 图片加载失败显示占位，不中断整条胶卷

## 6. 约束
- 若使用组件库，优先轻量 CSS 方案；禁止为了本段引入 Three.js
- 图片需压缩到合适宽度；组件内不做运行时超大图缩放凑合

## 7. 验收
- [ ] 12 张图可横滑，松手吸附
- [ ] 弱网下失败图有占位
- [ ] CTA 仍在第二屏可见，不被图集抢光注意力

你会发现：Spec 写的不是「用哪个 npm 包」，而是 行为与边界。组件可以自研，也可以用现成的------契约先于实现。这和「先选型库再凑需求」是反过来的。

七、什么时候一页不够？什么时候别写？

🚦 口诀只有一句：返工更贵就写 Spec；写 Spec 更贵就别表演流程。别一上来就扛三十页 PRD 和整箱工具。

值得升级成「多页 / SDD 工具」的信号

跨 3 个以上端或仓库
涉及权限、钱、隐私、订单状态机
大重构（路由体系、状态体系、设计体系迁移）
多人并行，且需要同一份真相源

这时可以考虑 Spec Kit / OpenSpec 等工具，把 Constitution → Specify → Plan → Tasks → Implement 跑起来。它们适合 重约束场景，不是每天改个按钮的标配。

可以不写正式 Spec 的信号

文案、间距、颜色微调
真正的一次性 Spike / Demo，做完就扔
你自己两分钟能手写完，且无人接手

原则是：

返工成本 > 写 Spec 成本，就写。

写 Spec 成本 > 返工成本，就别表演流程。

八、五个把 Spec 写废的坑

写 Spec 也会翻车。下面五个，我都真实踩过------表情包预警 🚨

坑 1：写成散文，没有「不做清单」 🕳️

只写「要做好用」，等于没写。Agent 最需要的是 Negative Space：什么不许做。

没有「不做」，就等于默认「你可以做宇宙」。

坑 2：验收不可测 🌫️

「体验流畅」「高大上」无法勾选。改成：「弱网下 3 秒内出骨架」「失败可重试且保留条件」。

坑 3：Spec 和仓库脱节 🧬

不写参考文件，它就会发明新模式。点名 参考 OrderList.tsx，产出会像你们团队写的。

坑 4：写完不更新，实现漂了还硬修代码 🧊

产品改口时，先改 Spec，再改代码。否则你在用对话记忆对抗文件，必输。

坑 5：把 Spec 当成让 AI「自己想需求」的借口 🎰

起草可以交给 Ask/Plan，确认必须是人。人没点头的开放问题，禁止进入实现------把这一条写进 Spec 第 8 节。

九、和 Rules / Skills / MCP 怎么分工？

很多人把所有东西都塞进 Prompt，然后抱怨模型健忘。其实它们管的是不同层：

层级	解决什么	例子
Rules	长期、全局的仓库规矩	技术栈版本、禁止任意 `any`、目录约定
Skills	可复用流程	「按搜车规范生成页面」「跑完 lint 再交卷」
MCP	外部系统真相	Figma 标注、语雀 PRD、GitLab MR
本次 Spec	这一次需求的契约	范围、状态、验收、不做清单

关系可以记成：

text 复制代码

Rules 保证「像我们」
Skills 保证「按步骤」
MCP 保证「看得到真东西」
Spec 保证「这次做对的事」

Rules 再完善，也替代不了本次 Spec------全局规矩回答不了「这个迭代到底同不同步 URL」。

延伸阅读：Rules 与 Skills 分层、MCP 工作流。

十、一张可直接贴进团队的检查表

开工前（给人看，也给 Agent 看）：

目标能用一句话说清「用户完成后能做什么」
「不做清单」至少有 2 条
空 / 错 / 加载 / 无权限状态有交代
点名了参考文件或允许改动的目录
验收清单每条都能手测打勾
开放问题已清空，或明确「未确认禁止实现」

开工后：

Plan 输出的文件列表你已确认
Agent 没有引入 Spec 外的架构
按验收清单手测，而不是只看「能跑」
产品改口时先改 Spec 再改代码

如果你在团队推广 Cursor，这张表比再分享十个「神级 Prompt」更有用------它训练的是 对齐能力，不是咒语。

结语：把「说清楚」重新当成核心技能

AI 没有让「写代码」消失。它让「写代码」变便宜了，于是更贵的能力暴露出来：

把模糊需求钉成可验证契约的能力。

一页 Spec 看起来很土，土正是优点------短到你愿意写，硬到 Agent 跑不掉。

从明天开始，你可以只改一个习惯：

在对 Agent 说「帮我做」之前，先丢给它一页 Spec，并强迫它复述范围。

复述不对，就还没到写代码的时候。

如果你愿意，评论区可以贴一次你最近最模糊的需求原话（打码敏感信息）。我可以按本文模板，帮你改成一版可执行的前端 Spec 骨架。

写在最后的三句话（方便收藏）

Agent 猜需求的成本，已经高于写一页 Spec。
前端 Spec 必须写状态、交互、仓库方言，而不只是功能列表。
先让 Agent 复述范围，再允许它改代码。