vibe-coding —— 步骤化 Vibe Coding skills 包

从想法到发布的傻瓜式流程：每一步一个命令，迷路了敲 /vibe。 AI 主导执行、人做决策与验收；方法论详见 vibe-coding-guide.md。

版本

• 当前版本：根目录 VERSION；变更记录：CHANGELOG.md。
• 项目里查自己用的哪个版本：cat docs/vibe/_pack/VERSION（含版本号 + commit + 安装时间）。
• 升级 = 重跑上面的安装命令（幂等覆盖）。
• 移动端组件库 persagy-vant 是独立升级线：pnpm up persagy-vant，详见下方「移动端：怎么用组件库」。
• 维护者约定：凡改 skills/ rules/ templates/ 必须 bump VERSION 并在 CHANGELOG 记一行，语义化版本。

安装（30 秒）

在要使用流程的工程目录执行（单仓多工作区时是具体工程目录，不是仓库根——本仓即 meos-mobile-hybird/，不要在 APC-BOT-MOBILE 根目录跑）。一行命令，无需 clone 本仓库：

cd <你的工程目录>   # 例：cd meos-mobile-hybird
curl -fsSL https://gitea.meos.center/tannengzong/vibe-coding/raw/branch/main/scripts/online-install.sh | bash

装到 ~/.claude/skills/ + ~/.agents/skills/ 全局共用（每个项目仍需再跑一次装 _pack）：

curl -fsSL https://gitea.meos.center/tannengzong/vibe-coding/raw/branch/main/scripts/online-install.sh | bash -s -- --global

Qoder / Trae 用户（测试团队常用）加对应参数，可叠加：

curl -fsSL https://gitea.meos.center/tannengzong/vibe-coding/raw/branch/main/scripts/online-install.sh | bash -s -- --qoder --trae

• --qoder：skills 另装一份到项目 .qoder/skills/——Qoder 与 Claude Code 同用 SKILL.md 格式，重启 IDE 后 / 唤起即可用。
• --trae：Trae 没有 skills 概念，脚本会写一条调度规则到 .trae/rules/vibe-coding.md——对话里敲 /vibe-xxx，Trae 的 agent 按规则去读 .agents/skills/ 下对应的 SKILL.md 严格执行。不把 21 个 skill 全文灌进 rules（那会撑爆它每轮的上下文）。

已 clone 本仓库、想从本地装（离线 / 开发本包时）

cd <你的工程目录>
bash <本包路径>/scripts/install.sh          # 或加 --global

脚本会把 16 个 skill（12 个流程 skill + /vibe 仪表盘 + /grilling 内核 + design-for-web / design-for-mobile 两个设计规范 skill）同时装进项目 .claude/skills/（Claude Code）和 .agents/skills/（Codex 等 agentskills.io 标准 CLI），规则与模板装进 docs/vibe/_pack/。装完开新会话即可。（--global 装到 ~/.claude/skills/ + ~/.agents/skills/ 全局共用，但每个项目仍需跑一次脚本装 _pack。）

顺带装移动端组件库：如果当前目录是个前端工程（有 package.json 且依赖里有 vue），脚本会额外把 persagy-vant 装进来（版本范围写成 ~0.0.24，不是 pnpm add 默认的 ^——库还在 0.0.x，semver 下 ^0.0.24 等于精确钉死、pnpm up 永远升不上去）并打印实装版本号——移动端开发不用再手动装组件库。不是前端工程就跳过，只打印一行手动命令，不会在后端工程或空目录里留下 node_modules。

参数	作用
--global	skills 装到 ~，组件库安装始终是项目级的，绝不会装到 $HOME
--with-vant	强制装组件库（即使没检测到 vue 依赖）
--no-vant	完全跳过组件库安装（CI 友好）

Codex（ChatGPT）用户：触发前缀是 $ 不是 /——文档里所有 /vibe-xxx 读作 $vibe-xxx（或用 /skills 选择器挑）；步骤 skill 已随包配好 agents/openai.yaml（禁止隐式自动触发，保护步骤感）；Linear/Neo4j 等 MCP 配在 ~/.codex/config.toml（RAG 的 Codex 配置示例见 rules/rag-read.md）。其余流程完全一致。

移动端：怎么用组件库

移动端原型和开发必须用 persagy-vant（公共 npmjs.org，无需任何 registry 配置）。不要自己实现组件库已有的控件、面板或交互。

新建原型——design-for-mobile 会自己跑脚手架并装依赖，你只要提需求：

你：/vibe-2-prototype        ← 端型是 mobile 时自动加载 design-for-mobile
或：直接说「按这份 PRD 做移动端原型」

在已有工程里开发——先确认组件库在位（在线安装时若命中前端工程已自动装好），然后正常提需求即可：

pnpm add persagy-vant@latest    # 已装过可跳过

skill 内部的选型链路是固定的：先读随 npm 包发布的 node_modules/persagy-vant/skills/use-persagy-vant/（业务组件选型表 + 复用规则），再按 es/<组件>/*.d.ts 取确切 API。API 权威顺序：.d.ts > 随包 skill > 本 skill 的 overrides.md > 用法速查文档。组件库没有的能力，按组件缺口流程上报，不要手搓近似替代品。

11 个业务组件已随 0.0.24 全部发布：单人/多人选择、对象/位置选择、物料添加、批量数量录入、工单筛选、底部操作栏、小蓝标、筛选标签、视频预览。

组件库更新

组件库和本 skills 包是两条独立的升级线：

pnpm up persagy-vant     # 只升组件库

starter 钉 ~0.0.24，所以这条命令吃 patch 但不跨 minor（库还在 0.0.x，minor 位常带破坏性变更，跨版本要人工确认）。新组件、新复用规则都随 npm 包一起来，不需要重装本 skills 包——下次会话让 AI 重读一遍随包 skill 即可。

已知缺件：bot-mobile 不在发布产物中（它依赖未发布的 meos-bot-web）。包内也不含 README.zh-CN.md，所以确切 API 只看 .d.ts，别按库仓库的 README 猜。

3 分钟上手

你：/vibe
AI：还没初始化 → 引导 /vibe-setup

你：/vibe-setup
AI：三个必问（需求中枢用 Linear 还是本地 md？门禁命令？发布命令？）
    + 一个可选问（要接业务语义图 RAG 吗？不接不影响）
    → 写入 CLAUDE.md 指针块，建 docs/vibe/ 目录。每个项目只做一次。

你：/vibe-0-idea        ← 只有想法/一堆文档时从这里开始
AI：拷问式访谈（分轮提问、每轮 ≤3 题各带推荐答案），共识落盘 00-idea.md + 词汇表

你：/vibe-1-prd         ← 需求已想清楚可直接从这里开始
AI：综合成 PRD → 建 Issue → 30 秒定级 Size → 告诉你下一步敲什么

之后每一步收尾都有导航块：本步结果、落盘产物、下一步命令，回复「继续」即推进。任何时候中断，新会话敲 /vibe 找回位置。

流程地图

0 想法拷问 → 1 需求成单(定级) → 2 原型 → 3 契约实测 → 4 实现方案 → [用例+测资] → 5 实现 → 6 验收 → 7 发布归档
配套支线：/vibe-testcases 用例设计(实现前)   /vibe-testdata 测资准备   /vibe-hotfix 小缺陷直修
          /vibe-unittest 单测覆盖率报告(随时)  /vibe-handoff 提测准入文档(6后7前,有独立测试团队才走)
QA 支线(测试团队,提测评审通过后按序)：/vibe-qa-testpoints → /vibe-qa-testcases → /vibe-qa-review

Size 路由：S(微) = 1→5→7        省仪式不省护栏
           M(常规) = 1→(2)→(3)→4→(用例)→5→6→7
           L(大) = 0→1(拆子单)→全程（用例必做）

命令	干什么
/vibe	仪表盘：我在哪一步、下一步敲什么（只读不执行）
/vibe-setup	项目初始化（一次）：需求中枢/门禁/发布/项目端型 → CLAUDE.md 指针块
/vibe-0-idea	想法拷问：分轮问清目标/用户/边界，落盘共识+词汇表
/vibe-1-prd	需求成单：只综合不访谈 → PRD → Issue + Size 定级，L 级拆子单
/vibe-2-prototype	原型：按端型自动加载设计 skill，生成可点击代码原型，或从只读基线移植
/vibe-3-contract	契约：文档不可信 curl 实测为准；写服务缺口即停机
/vibe-4-plan	方案：M 级 ≤10 行摘要 / L 级完整文档，人过目后才实现
/vibe-5-build	实现：门禁红回炉 → 预提交报告，人复验放行才 commit
/vibe-6-verify	验收：PRD↔实现↔测试三方一致性 + 真机验证清单
/vibe-7-ship	发布归档：一条命令发布 → 人真机验收 → 归档全量规格/用例库 → 踩坑沉淀
/vibe-testcases	用例：实现前设计功能测试用例（不看实现代码），用户确认后作实现与验收基准
/vibe-testdata	测资：提取测试数据需求清单+登记清理；自动创建预留（等后端测资说明后接入）
/vibe-unittest	单测：跑测试+覆盖率，出结构化报告（改动文件单独成组、未覆盖说明、断言真伪自抽检）；vitest·jest / JUnit·JaCoCo / pytest-cov 三栈读产物取数，数字只来自真实执行
/vibe-handoff	提测：按部门《研发提测准入规范》自动生成提测文档，10 条红线 ✅/❌/⏸ 三态自检，人执行项留缺口清单
/vibe-qa-testpoints	QA① 测试点：测试团队从 PRD 原文 + 需求侧/代码侧两份影响范围拆全量测试点，每条强制原文背书
/vibe-qa-testcases	QA② TB 用例：测试点转钉钉 Teambition XMind 嵌套格式（tc:/pc: 节点、P0 ≤20%），可无伤导入
/vibe-qa-review	QA③ 查漏补缺：覆盖/一致性/可执行性/P0 占比四轮复核，就地补齐；与研发侧 05-testcases.md 交叉查漏
/vibe-hotfix	快修：单一缺陷 ≤300 行/≤8 文件红线内直修，越线停机回流
/grilling	内核：拷问式访谈循环（vibe-0-idea 调用，也可单独用）
design-for-web	设计规范：PRD → Vue 3 + meri-plus 高保真 Web 原型（vibe-2-prototype 按端型自动加载，也可单独用）
design-for-mobile	设计规范：移动端 H5 高保真原型，Meri Design + persagy-vant 契约（同上）。组件选型与复用规则委派给随包 use-persagy-vant skill（pnpm up persagy-vant 即自动更新）；Meri Design 契约、API 坑位与勘误由本 skill 自持

It's working if（装完自查）

• 新会话敲 /vibe，它列出步骤地图并引导 /vibe-setup（而不是开始写代码）
• /vibe-setup 一次只问一题，重复跑是原地更新指针块不重复追加
• /vibe-0-idea 丢一段模糊想法，它逐题拷问且每题带推荐答案，从不一次问多题
• /vibe-1-prd 产出的 PRD 有验收标准和「不做什么」，并给出 Size 定级理由
• S 级需求收尾直接指向 /vibe-5-build，没被强加原型/契约/方案仪式
• mobile 项目跑 /vibe-2-prototype，它按指针块「项目端型」自动遵循 design-for-mobile 规范（web 项目对应 design-for-web）
• 在前端工程里跑安装命令，末尾打印 ✅ 已安装 persagy-vant@0.0.x；在后端工程/空目录里跑，只提示手动命令且不产生 node_modules
• 让 AI 做移动端选人/选位置/工单筛选，它复用 persagy-vant 业务组件，而不是自己搓一个底部面板
• /vibe-5-build 结束时是预提交报告，没有自动 commit
• 中断后新会话敲 /vibe，能从 _flow.md 恢复位置，不依赖聊天历史
• 让 /vibe-hotfix 「顺便加个小按钮」，它拒绝并指回 /vibe-1-prd
• /vibe-unittest 在没跑起来测试时说「跑失败」而不是「暂无单测」，也不编覆盖率数字
• /vibe-handoff 生成的提测文档里，自验结果/冒烟结果/部署勾选全是 ⏸ 待你确认，且准入结论是「不通过，待补充」

FAQ

没有 Linear 怎么办？ /vibe-setup 选「本地 markdown」，需求/状态全部落 docs/vibe/，流程不变。

没有门禁命令怎么办？ 会记「无门禁」并在每次交付时提示风险、要求你显式确认。建议尽早配一把梭命令（typecheck+lint+单测）。

S 级为什么跳过 2/3/4 步？ 30 分钟的活套全套仪式会拖到 1 小时以上。S 级省的是文档和多 Agent 交接，门禁、人复验、验收标准一条不少（guide §4.0）。

每个阶段都必须走吗？ 不。仪式可跳、护栏不可跳：0/2/3/4/用例都可以跳（Size 路由默认跳一部分，你也可以在任何收尾处说「跳过下一步」，会留痕记录理由）；不可跳的只有——需求成单（至少一句话需求+验收标准）、门禁、预提交报告+人复验 commit、人真机验收。

项目已经做到一半，能直接从中间开始吗？ 能，这叫中途接入：跑一次 /vibe-setup，然后直接敲你所处步骤的命令（如已在实现中 → /vibe-5-build），skill 会引导最小补卡（需求名+定级+Git 基线），前序步骤标「跳过：存量接入」，不必回头补走流程。

后端需求怎么走？ 跳过第 2 步原型（_flow.md 标「跳过」）。注意读写边界（rules/backend-boundary.md）：只读接口 AI 可生成；写动作只能接入已登记的稳定服务，新写入语义会停机输出缺口清单——这是设计行为不是 bug。

业务语义图（RAG）是什么、要配吗？ 后端组维护了三层 Neo4j 业务语义图（L2 业务概念、L3 字段/枚举/物理表/稳定 API 映射）。可选：配置后 PRD 语义确认、写动作「是否有稳定服务」判定、后端只读接口的表/字段/枚举都以图为权威只读来源（rules/rag-read.md，/vibe-setup 第 4 问引导接入，注意钉死只读）；不配置一切流程照旧。

团队踩过的坑记在哪？ 仓库 docs/vibe/pitfalls/（每坑一文件，/vibe-setup 会建目录）：第 7 步和 hotfix 收尾时 AI 自动起草、你核准后随代码提交；规划/实现前 AI 会自动 grep 相关坑。选仓库而不是 Linear 做主体，是因为坑的第一读者是 AI——仓库文件能被自动读到，Linear 要主动查才看得见；Linear 用于复盘讨论和非开发角色提坑，复盘时收编进库。

和 vibe-coding-guide.md 什么关系？ guide 是方法论（为什么这么做），skills 是执行器（一步步带你做）；guide §3.0 有步骤↔命令↔交付物对照表。

包结构

skills/       16 个 skill（装到 .claude/skills/）：14 个流程 skill + design-for-web/design-for-mobile 设计规范（移植自 MEOS_Workflow role-skills）
rules/        公共规范：收尾导航块 / 文档双轨+零元数据 / _flow 状态卡 / 后端读写边界 / RAG 只读接入
templates/    01-09 各阶段模板（含真实案例）
scripts/      online-install.sh（curl 一键装）/ install.sh（本地装）/ publish-github.sh（公开镜像同步）
rag/          业务语义图定义源（Neo4j 三层 cypher + 重建脚本 + 语义契约，本包统一维护；接入见 rules/rag-read.md）
loop/         plan-loop 自动环参考资料（引擎在主仓库，L 级可选）
assets/       流程图 SVG
vibe-coding-guide.md   方法论正文

---

整合来源：本团队 APC-BOT-MOBILE 实践（guide）+ 后端组 vibe-skills（阶段状态机/文档双轨/量化红线）+ mattpocock/skills（grilling/setup 指针块/tracer-bullet 拆票）。迭代记录见 Linear 项目「vibe-coding」（PER-96）。