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 看看效果，还是打算做一个要长期运行、可能给别人用的正式系统？"

开问之前：先分诊，能推断的别问 ★

> 账本（流程状态）： 本 skill 是流程第一阶段 S1·需求对齐的"自助路径"（访谈式入口是 vibe-coding-prd，两者满足同一个 S1）。开始前读一下 docs/进度账本.md（不存在就照 examples/进度账本-模板.md 建一个，初始化到 S1）；这里的"分诊"结论就是账本里 S1.1 的轻/重判定，产出"需求基准描述"对应 S1 的核心退出条件。轻量 demo 不必逐步报门，但别跳过分诊和四要素。

新手最容易把对齐做成"审问"——一口气抛十几个问题，用户答到一半就烦了。好的需求对齐，问得少而准。 在准备每一个问题前，先过这条原则：

> 能自己（或从用户已经说的话）推断出来的，就别问；只把真需要用户拍板的留成问题。

具体两步：

• 先分诊，定深度。 用一句话判断这个需求的"分量"，深度随风险走：
• 轻（自己用、一次性、跑个 demo）→ 只问最关键的一两件事，快速进入"补全"。
• 重（要给别人用、要长期运行、一旦出错有代价）→ 四要素逐项问，再做"数据旅程"深扫。
• 能推断的，转成"推荐项"让用户一眼确认，而不是开放式问题。 比如用户说"帮我整理电脑里的图片"，你不必问"你用什么设备、要不要联网"——直接推断"本机运行、不联网、单文件脚本"，作为推荐默认值摆出来，用户点头或否决即可（见下方「推荐选项」写法）。

这一步把"深度自适应"落到实处：简单需求轻问快走，复杂需求才展开深问。

推荐选项写法：别让用户面对空白，也别替他做主

非技术用户最怕两件事：一是被一堆开放式问题问懵（"你想用什么技术？"——他哪知道），二是 AI 自作主张、闷头跑偏。正确的中间地带是：先把你的理解和默认假设讲出来，每条都做成"一眼能确认"的推荐项，用户点头或换一个即可。

固定结构（卡住时直接照搬）：

我先把需求理解一下，下面这些是我替你定的默认值（不对就直接说，我改）：

1. 谁在用：自己一个人用            [✓ 就这样]  [换一个：给同事/给客户…]
2. 它活在哪：本机双击运行的小脚本    [✓ 就这样]  [换一个：网页/常开服务器…]
3. 数据存哪：结果直接写回原文件夹    [✓ 就这样]  [换一个：要长期保存/要数据库…]
4. 成本：不调用任何要花钱的服务      [✓ 就这样]  [换一个：可以接受 AI 接口按量计费]

（最多 5 条，每条一句话。你不回，我就按这些往下走。）

• 每条假设 = 一道带推荐值的选择题，而不是空白填空。
• 默认值一律取最简可行那个（最省钱、最少依赖、最好维护）。
• 用户沉默 = 默认通过，但关键的、一旦定错代价大的（涉及钱、别人的数据、是否长期运行）必须等他明确点头。

> 这正是本套件"你有权说不""渐进式复杂度"两条信条的默认动作：不审问、不擅自做主，用推荐项把决定权轻轻交还给用户。

阶段零：先别急着写代码

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

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

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

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

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

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

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

| 别这么说（描述方案） | 这么说（描述问题） |

|--------------------|------------------|

| "我要一个能上传 Excel 的后台" | "我每天要把客户发来的 Excel 整理成报表，手工做要两小时" |

| "做个带登录的网站" | "我想让几个同事各自查看自己负责的数据，别人看不到" |

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

1.2 用四要素框架描述需求

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

• 场景： 谁在用？什么环境、什么时候用？（一个人还是多人？手机还是电脑？）
• 目标： 最终要达成什么效果？解决前面说的什么问题？
• 约束： 逐条问自己——
• 预算、我自己的技术能力、时间。
• 要不要长期运行？大概多少人用、多大数据量？
• 数据要不要长期保存？关机重开后，之前的数据还在吗？（这是 demo 和正式系统最大的区别之一，一定要早想清楚——很多人到上线才发现"数据怎么没了"。）
• 会不会用到要花钱的服务？（调用 AI 接口、短信、云服务等多按量收费，先问 AI"这大概要花多少钱"。）
• 验收标准： 怎么算"做完了"？给出具体、能验证的标准。最稳的写法是 EARS 格式：「当【前置条件】，在【动作】时，则【可观察的结果】」——逼你把含糊词（"快"、"好用"、"正常"）换成能二元判断的事实。
• ❌ 空话："系统运行正常" / "页面加载快"
• ✅ 可验证："当我指定一个图片文件夹并运行，则文件夹里的图片按'年-月'分好了子文件夹，且原图都还在"
• 更系统的写法（含数字阈值、安全类验收）见 references/方法论/PM-方法论.md 的「EARS 验收格式」。

把四要素合并成 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，这里只负责"把该想到的，都写进需求"。

补出一堆需求后，排个序——别都塞进第一版

数据旅程一扫，往往冒出十几条新需求。不是每条都要现在做。 用最朴素的优先级判断，把它们分三档：

• 必须做：不做这一版根本不能用（核心流程 + "一旦出错代价大"的那几条容错）。
• 应该做：明显该有，但晚一两版也不致命。
• 以后再说：锦上添花、或暂时想不清的——全部丢进项目说明书的「以后再说」清单，别打断主线。

判断不准时，对每条问两件事就够了：多少人会因此受益（影响面）× 不做会多疼（痛感），再对一眼做它要多大力气。要更正式的打分模型（RICE 四维评分、MoSCoW），见 references/方法论/需求优先级框架.md——但 demo 阶段心里有数即可，别为打分而打分。

接下来

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

出口门（S1 自助路径 · 声称完成前必过）

> 以下约束来自项目治理配置 harness.json 和 CLAUDE.md。

> 在声称"需求说清了"之前，你必须逐条确认。

> 全过之后：在 docs/进度账本.md 把 S1 相关步骤标 ✅（自助路径产出"需求基准描述"即满足 demo 级 S1 出口；要正式系统再补完整 prd）。

必须产出的内容

• [ ] docs/项目说明书.md 中「需求基准描述」已填写（如文件不存在，先创建并填入本节内容）
• [ ] docs/进度账本.md 已存在，S1.1 分诊结论已记录

硬性检查

• [ ] 「需求基准描述」字数在 80-300 字之间（建议 100-200 字）
• [ ] 「需求基准描述」覆盖四要素：场景、目标、约束、验收
• [ ] 需求不是描述"方案"（如"我要一个上传 Excel 的后台"），而是描述"问题"（如"我每天手工整理 Excel 要两小时"）
• [ ] 约束维度至少涉及：运行环境、维护人力、数据持久化、成本
• [ ] 验收标准是可验证的：写成"我做 X，应该看到 Y"或 EARS 格式「当【前置条件】，在【动作】时，则【结果】」，不能是"系统正常"这类空话

自检完成声明

全部通过后声明：

"✅ S1 自助路径出口门通过：需求基准描述已写入项目说明书，覆盖四要素，格式合规，账本已记分诊结论。要做正式系统的话，转 vibe-coding-architecture（S2）。"