vibe-coding-requirements

# 需求对齐：把想法说成 AI 能落地的需求

这是 **vibe-coding-kit** 的入口 Skill。它服务的人多半不写代码，靠 AI 把想法变成能跑的东西。最容易踩的坑不是技术，而是**需求没说清，AI 朝着错误方向飞速实现**。把需求说对，后面省一半返工。

> **套件里还有三个 Skill，在不同时刻用：**
> - 需要选技术栈 / 看不懂 AI 给的方案 → `vibe-coding-architecture`
> - demo 验证过了、要做成正式系统 → `vibe-coding-production`
> - 开发中 AI 越改越乱 / 改坏退不回去 / AI 忘事 → `vibe-coding-survival`（开发全程都建议配合它）

## 先确认：用户现在在哪一站？

| 用户想要 | 怎么办 |
|---------|-------|
| 还不确定要不要做 | 先做**阶段零**，可能根本不用写代码 |
| 快速跑个 demo 验证想法 | **阶段零 + 阶段一**，需求说清就开干，其余先不管 |
| demo 过了，要做成正式系统 | 做完本 Skill，转 `vibe-coding-architecture` 和 `vibe-coding-production` |
| 已经在做、过程中失控 | 转 `vibe-coding-survival` |

判断方法：直接问。"你现在是想先跑个 demo 看看效果，还是打算做一个要长期运行、可能给别人用的正式系统？"

---

## 阶段零：先别急着写代码

写代码不是默认选项，是其中一个选项。开工前花两分钟做这个 gut-check，可能直接省掉整个项目：

1. **有没有现成的工具/产品已经能做这件事？** 先搜一圈。能买、能用现成 SaaS、能用模板配置出来的，就别从零造——自己造的每一行代码，将来都得自己（靠 AI）维护。
2. **这件事是一次性的，还是要反复做很多次？** 一次性任务（比如整理一批数据），也许直接让 AI 帮你把事做掉就行，不必做成一个长期软件。
3. **你要"自己用"还是"给很多人用"？** 自己用，标准可以很低；给别人用，复杂度、安全责任、维护成本都翻好几倍——确认你真需要，再开始。

如果这三个问题让你发现"其实不用写代码"，那是最大的省事。

---

## 阶段一：需求澄清（四要素框架）★ 核心

**目标：** 把模糊想法，转化成 AI 能精准理解、不会跑偏的需求描述。

### 1.1 先分清"想要什么"和"想解决什么"

非技术用户最常见的失误，是直接描述"我想要的功能"，而不是"我要解决的问题"。这会让 AI 锁死在你想象的某个实现上，错过更简单的做法。

| 别这么说（描述方案） | 这么说（描述问题） |
|--------------------|------------------|
| "我要一个能上传 Excel 的后台" | "我每天要把客户发来的 Excel 整理成报表，手工做要两小时" |
| "做个带登录的网站" | "我想让几个同事各自查看自己负责的数据，别人看不到" |

先说问题，再说你设想的方案（如果有），并告诉 AI："这是我的设想，有更简单的做法可以推翻它。"

### 1.2 用四要素框架描述需求

逐条想清楚，再合并成一段话：

- **场景：** 谁在用？什么环境、什么时候用？（一个人还是多人？手机还是电脑？）
- **目标：** 最终要达成什么效果？解决前面说的什么问题？
- **约束：** 逐条问自己——
  - 预算、我自己的技术能力、时间。
  - 要不要长期运行？大概多少人用、多大数据量？
  - **数据要不要长期保存？关机重开后，之前的数据还在吗？**（这是 demo 和正式系统最大的区别之一，一定要早想清楚——很多人到上线才发现"数据怎么没了"。）
  - **会不会用到要花钱的服务？**（调用 AI 接口、短信、云服务等多按量收费，先问 AI"这大概要花多少钱"。）
- **验收标准：** 怎么算"做完了"？给出具体、能验证的标准——最好写成"我做 X，应该看到 Y"。

把四要素合并成 100–200 字的**需求基准描述**。后续每次跟 AI 对话，都把它贴在前面，确保 AI 不偏航。

> **约束这一项最容易被新手省略，却最关键：需求里有约束，方案才能被约束。** 你不告诉 AI 你只有一台小服务器、不会写代码、要控成本，它就默认按"大厂标准"给你一套又重又复杂、你根本养不起的方案。

### 1.3 哪些要写清楚，哪些留给 AI

**业务上的事你说了算，技术上的事交给 AI。**

| 你必须说清楚 | 可以交给 AI 决定 |
|------------|----------------|
| 谁用、用来干什么 | 用什么编程语言、什么框架 |
| 具体业务规则（如"超过 100 元才包邮"） | 数据怎么存、文件怎么组织 |
| 你能接受的使用方式（网页？命令行？） | 用什么库、怎么实现某个功能 |
| 哪些情况绝对不能出错 | 代码风格、目录结构 |

### 1.4 demo 跑出来不对，怎么办（关键技能）

**别去改代码，改你的描述。** 描述"差距"，而不是指挥 AI 怎么改：

- ✅ 好："我点了提交按钮，但页面没反应，我期望它弹出一个'保存成功'的提示。"（现象 + 期望）
- ❌ 差："你把那个函数改一下。"（你不知道改哪、AI 也猜不准）

报错了，把**完整的错误信息**原样复制给 AI，加一句"这是报错，帮我看怎么回事"。看不懂没关系，AI 看得懂。

### 1.5 范例对照

**反面例子（太模糊，AI 无从下手）：**
> "我想搭建一个开源项目。"

**demo 级正面例子（轻量，验证想法用）：**
> 场景：我一个人用，在自己电脑上跑。目标：我有一个文件夹全是杂乱图片，想按拍摄日期自动归类到子文件夹，省去手工整理。约束：我不会写代码，用 AI 写，希望双击就能运行，不想装一堆复杂环境，原图绝不能丢。验收标准：我指定一个文件夹，运行后里面的图片按"年-月"分好了文件夹，原图都在。

**生产级正面例子（要长期运行、对外提供服务）：**
> 场景：在本地 2核8G Linux 服务器部署，客户通过 HTTP 请求触发。目标：做一个卡密自动发货中间层，客户触发后系统验证身份、从库存分配卡密、转发核心平台完成服务、返回结果。约束：个人维护，不会写代码（用 AI 写），服务器只有一台，需长期稳定运行。验收标准：客户发起请求 → 返回卡密 → 核心平台确认服务完成；支持 token 鉴权、库存管理、操作日志。
>
> （注意：这个例子"动到了钱和库存"，正式上线前应找真人工程师把关——详见 `vibe-coding-survival` 的「红线」。）

**输出物：** 一段 100–200 字的需求基准描述。把它存进你的「项目说明书」（模板见仓库 `examples/项目说明书-模板.md`）。

---

## 阶段一·进阶：把需求"补全"——从一切顺利，到考虑周全 ★

四要素能让你说清"我想要什么"，但**产品经理最大的需求盲区，是只描述了"一切顺利"那条路径**——用户点一下、拿到结果、皆大欢喜。真正完整的需求还得回答：**输入坏了怎么办？量太大怎么办？某一步失败了怎么办？我怎么知道它出问题了？** 这些你不写进去，AI 就按它的默认猜，通常猜不对。

> 这不是能力问题。工程师能随口说"这里得加个重试"，靠的不是灵感，是脑子里"什么会坏"的条件反射。你没这个习惯，是没人教过——下面就把它教给你，而且用的是你**本来就会**的本事。

### 复用你的强项：用户旅程 → 数据旅程

你本来就擅长拆"用户旅程"：用户先干嘛、再干嘛、在哪一步会卡。把**主语从"用户"换成"数据/请求"**，同一套思维直接复用：

| 你已经会问（用户旅程） | 换个主语（数据旅程） |
|----------------------|-------------------|
| 用户操作有哪些步骤？ | 数据从进来到出去，经过哪些环节？ |
| 用户在哪一步会卡住？ | 数据在哪个环节会堵、会慢？ |
| 用户可能犯什么错？ | 哪里会收到坏的、假的、重复的输入？ |
| 用户的数据安全吗？ | 数据会不会丢、会不会泄露？ |

先让 AI 帮你把数据旅程画出来：
> "我要做 [项目]。请把数据/请求从进入到输出的每一步，用大白话画出来，每步一句话。"

### 对每一步，问 3×4 个问题（漏网之鱼生成器）

数据旅程说到底就三段：**输入 → 处理 → 输出**。对着这三段各问四个问题。**每一个答案，都是一条你差点漏掉的需求：**

```
       输入                处理                 输出
  ① 会断吗？          ① 会出错吗？          ① 结果对吗？
  ② 会太多吗？        ② 会很慢吗？          ② 会丢吗？
  ③ 会是假的吗？      ③ 会挂吗？            ③ 会泄露吗？
  ④ 断了怎么办？      ④ 挂了我怎么知道？     ④ 错了我怎么知道？
```

不用每条现在就解决——但每条你都要**给个决定**，并写进需求。举例：
- "上传的文件不是图片怎么办？" → 决定：跳过并提示，不让整个程序崩。（这就是一条新需求）
- "一次性传进来 1000 张怎么办？" → 决定：单次最多处理 200 张。（一条边界需求）
- "AI 接口超时没响应怎么办？" → 决定：重试 2 次，还不行就跳过并记下来。（一条容错需求）

一句话让 AI 帮你扫：
> "按'输入 → 处理 → 输出，每段会不会断/太多/造假/出错/变慢/挂掉/丢失/泄露'，帮我列出这个项目可能漏掉的情况，每条给一个最简单的处理建议。"

### 交给 AI 写之前，换三个身份把需求读一遍（自检）

- 👤 **当业务本人**：正常流程从头走一遍，状态有没有缺口？（比如"已下单但还没付款"这种中间状态，你写了吗？）
- 🦹 **当捣乱的人**：有人故意发坏数据、重复请求、空值，会怎样？
- 🛟 **当半夜被叫醒的运维**：它要是悄悄坏了，我**怎么第一时间知道**，而不是等用户来骂？

把这三遍读出来的缺口补进需求，你的需求就从"能跑就行"升级到"经得起用"了。

> **量力而行：** 随手跑个 demo（比如整理自己的图片），快速扫一遍即可；但凡这东西要给别人用、或一旦出错有代价，这一步千万别省——它正是 demo 和正式系统之间，最容易被忽略的那道坎。完整的风险登记和应对，留给 `vibe-coding-production`，这里只负责"把该想到的，都写进需求"。

---

## 接下来

- **只是跑 demo：** 把需求基准描述发给 AI 让它开干，同时照 `vibe-coding-survival` 的"贯穿全程四件事"来做，别翻车。
- **想做成正式系统：** 先用 `vibe-coding-architecture` 选好技术、看懂架构，再用 `vibe-coding-production` 处理上线。