| name | vibe-coding-requirements |
| description | Vibe Coding（用 AI 写代码）项目的第一步：把模糊的想法，变成 AI 能精准落地、不会跑偏的需求。 当用户说"我想做一个 XX"、"帮我用 AI 做个 demo"、"我有个想法想验证"、"帮我跟 AI 对齐需求"， 或者描述了一个还很模糊的软件/工具/系统点子时，使用此 Skill。也用于先判断"这件事到底要不要写代码"。 这是 vibe-coding-kit 套件的入口——只想跑 demo 验证想法的人，通常只需要这一个 Skill。 它不止教你说清"想要什么"，还教你用"数据旅程 + 3×4 提问"把需求补全到考虑周全，避免只描述了"一切顺利"的happy path。 即使用户没明说"规划"二字，只要 ta 准备让 AI 开始写代码、却还没把需求说清楚，就应主动用本 Skill 先做需求对齐。 |
需求对齐：把想法说成 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）。
必须产出的内容
硬性检查
自检完成声明
全部通过后声明：
"✅ S1 自助路径出口门通过：需求基准描述已写入项目说明书，覆盖四要素，格式合规，账本已记分诊结论。要做正式系统的话，转 vibe-coding-architecture（S2）。"
