GWT 需求描述法：让 AI 听懂你的 Bug 和需求
向 AI 描述一个 Bug 或需求，本质上是在写一份可执行的验收测试。GWT（Given/When/Then）就是这份测试的语法。
问题：程序员为什么说不清需求
写过代码的人都有这种体验：明明脑子里已经跑通了整个流程，说出来却支离破碎。
「那个按钮点完之后要弹个框」 「列表加载太慢了优化一下」 「登录有时候不行」
这些话对同事说，对方能用点头和「懂的懂的」弥补信息缺口。但 AI 不会点头——它只会忠实地执行你字面上的指令，而非你脑子里的设想。
| 你对 AI 说的 | AI 实际理解的 | 你实际想要的 |
|---|---|---|
| 「列表加载太慢了优化一下」 | 可能是加 loading 动画 | 首屏 2 秒内渲染完毕 |
| 「登录有时候不行」 | 不知道什么时候、什么情况 | 错误密码时不跳转也不提示 |
| 「弹个确认框」 | 弹了，内容是什么不知道 | 显示记录名称 + 确认/取消双按钮 |
模糊需求的本质：Given（前置）、When（动作）、Then（结果）三者至少缺失其一。
GWT：一套被验证过的需求语法
GWT 源于行为驱动开发（BDD），核心就三个问题：
| 要素 | 含义 | 检验标准 |
|---|---|---|
| Given | 系统当前状态、用户是谁、有哪些数据 | 不依赖上下文就能复现场景 |
| When | 用户做了什么操作、输入了什么 | 具体到可以照做一遍 |
| Then | 期望的结果是什么、怎么验证 | 可观测、可量化、可自动化 |
这三个问题回答清楚了，需求就描述清楚了一次
对 AI 同样适用。
与 ROSCE 框架的关系
在《AI时代的精准沟通》中，我们提到 ROSCE 框架（Role/Objective/Spec/Context/Example）是与 AI 沟通的通用范式。GWT 是 ROSCE 在需求描述场景下的具体化：
| ROSCE 要素 | 映射到 GWT |
|---|---|
| Role + Context | Given — 角色、场景、前置数据 |
| Objective + Example | When — 具体操作与输入 |
| Spec | Then — 预期的输出格式与行为约束 |
ROSCE 是「怎么写指令」，GWT 是「怎么描述场景」。二者可以叠加使用。
GWT 三段详解
Given — 前置条件
前置条件决定 AI 的上下文边界。缺了它，AI 只能猜。
必须回答的问题：
- 用户是谁？（角色/权限）
- 系统处于什么状态？
- 已存在哪些数据？
- 当前在哪个页面/视图？
✅ 好：已登录的普通用户，在订单列表页，有 3 条订单：「办公桌」「办公椅」「台灯」
❌ 差：在列表页When — 触发动作
这是最容易被跳过的部分——很多人默认「AI 应该知道我怎么操作」。
必须回答的问题：
- 用户做了什么操作？
- 输入了什么内容？
- 发生的顺序是什么？
✅ 好：在搜索框输入"办公"，点击搜索按钮（或等 300ms 自动触发）
❌ 差：搜一下Then — 预期结果
最难写清楚的一环。模糊的 Then 是需求返工的根源。
必须回答的问题：
- 发生了什么变化？
- 看到了什么？听到了什么？
- 数据如何更新？
- 有什么反馈（提示/跳转/错误）？
- 正常路径、异常路径、边界值各是什么？
✅ 好：列表仅显示「办公桌」「办公椅」；顶部显示"共 2 条"；
搜索无匹配时显示空态图 + "未找到相关订单"
❌ 差：搜出来结果就行10 个实战示例
以下是编程开发中最常见的 10 类需求场景，每条展示从「模糊描述 → 完整 GWT」的转化。
1. Bug 报告：登录失败无提示
❌ 模糊：「登录有时候不行，也没提示。」
Scenario: 用户使用错误密码登录
Given 普通用户，在登录页，已注册 [email protected] / Pass1234
When 输入邮箱 [email protected]、密码 WrongPass，点击「登录」
Then
- 页面不跳转
- 密码框下方显示红色"密码错误，请重试"
- 密码框内容清空，光标聚焦到密码框
- 登录按钮保持可点击
2. 功能请求：搜索筛选
❌ 模糊：「列表页加个搜索，能按名字搜就行。」
Scenario: 用户按名字搜索订单
Given 已登录普通用户，在订单列表页，存在 3 条订单：办公桌、办公椅、台灯
When 在搜索框输入"办公"
Then
- 列表仅显示
办公桌、办公椅 - 显示结果计数"共 2 条"
- 清空搜索框恢复全部 3 条
- 搜索无匹配时显示"未找到相关订单"空态图
3. UI 交互：删除确认弹窗
❌ 模糊：「删除按钮点完后弹个确认框，别直接删了。」
Scenario: 用户删除一条记录
Given 已登录普通用户，列表中有记录「测试项目 A」
When 点击该记录右侧的「删除」按钮
Then
- 弹出模态确认框
- 标题：「确认删除」，内容包含记录名称，标注"不可恢复"
- 两个按钮：「取消」（灰色）和「确认删除」（红色）
- 点取消关闭弹窗，列表不变
- 点确认删除关闭弹窗，记录消失，顶部绿色提示"已删除"
4. 表单验证：注册校验
❌ 模糊：「注册页要做校验，邮箱格式不对要提示。」
Scenario: 用户提交不合规注册信息
Given 未登录用户，在注册页面
When 输入邮箱 not-an-email、密码 123，点击「注册」
Then
- 邮箱框下方提示"请输入有效的邮箱地址"
- 密码框下方提示"密码至少 6 位，需包含字母和数字"
- 不发送请求，按钮无 loading 状态
- 修正字段后对应错误提示即时消失
5. API 设计：分页接口
❌ 模糊：「列表数据多了，要分页。」
Scenario: 前端请求第二页订单
Given 数据库有 25 条订单，每页默认 10 条
When 发送 GET /api/orders?page=2&page_size=10
Then
data数组包含第 11-20 条total: 25，page: 2，page_size: 10has_next: true- 请求
page=3时has_next: false - 请求
page=0返回 400 + "page 必须 ≥ 1"
6. 权限控制：角色访问拦截
❌ 模糊：「普通用户不能进管理后台。」
Scenario: 普通用户直接访问管理后台 URL
Given 角色为 user 的已登录用户
When 在地址栏输入 /admin/dashboard 并回车
Then
- 重定向到首页
/ - 顶部提示"无权访问该页面"
- 不会短暂闪现后台内容再跳转（无闪烁）
7. 数据处理：导出 CSV
❌ 模糊：「报表要能导出成 Excel，人多的时候别超时。」
Scenario: 导出 10 万条记录的报表
Given 已登录管理员，在报表页，当前筛选条件下有 100,000 条记录
When 点击「导出 CSV」按钮
Then
- 10 秒内触发浏览器下载（后端异步生成，非阻塞）
- 文件名
report_YYYY-MM-DD.csv - 包含当前筛选条件的所有列
- 导出期间页面可继续操作，显示进度"正在生成文件…"
8. 并发/竞态：按钮防抖
❌ 模糊：「提交按钮点快了会重复提交，加个防重复点击。」
Scenario: 快速多次点击提交按钮
Given 已登录用户，在表单页，所有必填项已填写
When 在 500ms 内连续点击「提交」按钮 3 次
Then
- 仅发起 1 次 POST 请求
- 第一次点击后按钮禁用，文字变为"提交中…"
- 请求完成后按钮恢复可点击
- 数据库仅创建 1 条记录
9. 错误处理：网络断开
❌ 模糊：「没网的时候要给个友好提示，别白屏。」
Scenario: 弱网环境下加载列表
Given 已登录用户，在订单列表页，设备网络已断开
When 下拉刷新列表
Then
- 保留上次成功加载的数据不消失
- 顶部出现黄色横幅"网络连接异常，请检查网络后重试"
- 横幅右侧有「重试」按钮
- 不弹出系统级报错，不出现白屏
10. 性能需求：首屏加载
❌ 模糊：「首页太慢了，优化一下。」
Scenario: 访客首次访问首页
Given 未登录访客，4G 网络（下行 5Mbps，延迟 100ms），浏览器缓存为空
When 在地址栏输入首页 URL 并回车
Then
- 首屏内容（Above the fold）在 2 秒内可见
- LCP < 2.5s，FID < 100ms，CLS < 0.1
- 图片使用懒加载，占位图先显示
常见错误
| 错误 | 为什么错 | 修正 |
|---|---|---|
| 把操作细节放进 Given | Given 是状态，不是动作 | When 描述操作，Given 只描述操作前状态 |
| 多个动作塞进一个 When | 场景混杂，AI 顾此失彼 | 拆分为独立场景 |
| Then 不可验证 | "体验好""速度快"无法测量 | 给出可观测的具体指标或行为 |
| 替 AI 脑补缺失部分 | AI 不补你脑中的上下文 | 宁可多写也不假设 |
| 在 When 中描述系统行为 | When 是用户行为 | 系统行为归 Then |
| 缺少异常路径 | AI 只处理你描述的场景 | 至少覆盖空态、错误态、边界值 |
总结
GWT 是程序员的需求描述语法。与 ROSCE 框架结合使用时，效果最佳：
- ROSCE 定义范围：角色、目标、格式约束
- GWT 定义场景：前置条件、触发动作、预期结果
下次向 AI 描述需求时，试试这个检查清单：
- □ Given：AI 能复现场景吗？
- □ When：AI 能照做一遍吗？
- □ Then：AI 能验证结果吗？
- □ 异常路径：空态、错误态、边界值覆盖了吗？
三个全打勾再发送——你会发现「AI 理解错了」的频率大幅下降。
与 AI 沟通，不是「说话的艺术」，而是「需求分析的纪律」。
参考
- AI时代的精准沟通 — ROSCE 框架与约束驱动表达
- Prompt 工程
- Cucumber: GWT 规范