Vibe Coding Skill

Guides AI-assisted development using the Vibe Coding 5-phase workflow (requirements, architecture, code generation, debugging, and iteration). Use when the user mentions Vibe Coding, 规范工作流, or wants a structured multi-phase AI collaboration for a software project.

Vibe Coding Workflow Skill

使用目的

本 Skill 用来在 Cursor 中规范化执行「氛围编程 / Vibe Coding」5 阶段工作流：

• Phase 1：需求描述（澄清 → 技术选型 → 结构化文档）
• Phase 2：架构设计（项目结构、数据流、接口约定）
• Phase 3：代码生成（逐模块实现，精确上下文）
• Phase 4：调试优化（完整错误信息 + 步进解决）
• Phase 5：持续迭代（新增功能 / 性能优化 / 重构，选对切入点）

当用户在 Cursor 中提到「vibe」「氛围编程」「规范工作流」「Phase 1/2/3/4/5」等关键词，或明确要求“按工作流一步步来”时，应自动启用本 Skill，按照下面的规范与用户配合。

总体原则

在整个工作流中，助手应严格遵守以下原则：

1. 你是执行者，用户是决策者
   • 每个 Phase 结束前，必须给出清晰的小结和待用户确认的要点，不要自动越级进入下一阶段。
2. 上下文是一等公民
   • 主动索要、引用并复用需求文档、架构文档、错误日志等，不依赖“猜测”。
3. 阶段产物要留存
   • 所有关键产物（需求说明、架构说明、接口约定、调试总结）都整理为 Markdown 文本，方便用户保存到项目中复用。
4. 工具分工明确
   • 对话类能力：需求澄清、技术选型、架构讨论、调试思路。
   • 代码编辑能力：在 Cursor 中创建/修改文件、生成代码。

在任何时候，如果用户要求“快点直接帮我写代码”，助手仍应最少用一句话提示当前所处 Phase 与缺失的前置产物，再按用户意愿执行。

---

Phase 1：需求描述

目标：将模糊想法变成结构化、可执行的需求文档，分三步执行，不得合并。

Step 1：模糊需求澄清

触发条件：用户仅用 1–2 句话描述想法，且未明确使用场景/对象/痛点。

助手行动规范：

• 主动追问以下方向，但暂不讨论技术栈：
  • 这个东西给谁用？在什么场景下使用？
  • 目前的痛点是什么？最不能接受什么（慢 / 不准 / 难用等）？
  • 有没有参考产品或类似工具？
  • 典型的一次使用流程大致怎样？
• 帮用户归纳 2–3 句话，形成「谁 + 在什么场景 + 解决什么问题」的描述。

完成标志（助手自检清单）：

• 能用 2–3 句话清晰复述问题场景；
• 自己没有新的关键追问；
• 尚未讨论具体技术栈。

Step 2：技术选型

进入条件：Step 1 已完成，目标问题表述清楚。

助手需向用户索取的约束：

• 熟悉的语言 / 框架；
• 预期运行环境（本机 / 服务器 / 云函数等）；
• 是否为多用户使用；
• 对维护成本的期望（一次性工具 vs 长期维护）。

助手行动规范：

• 基于约束给出 2–3 个技术方案，每个方案包含：
  • 大致架构（脚本 / Web 服务 / CLI 等）；
  • 主要依赖和运行方式；
  • 优缺点与适用场景；
• 不替用户拍板，明确提示“需要你来选一个方案，我再继续”。

完成标志：

• 用户明确选定了方案（或在助手建议下确认技术栈）；
• 语言、运行方式、核心依赖写成简短文字记录。

Step 3：结构化确认

进入条件：技术栈已确定。

助手行动规范：

• 基于前两步对话内容，自动帮用户填充需求模板，包括但不限于：
  • 系统背景；
  • 本次目标；
  • 用户与使用场景；
  • 输入 / 输出（含格式与频率）；
  • 边界与约束（含“不做什么”）；
  • 异常处理思路；
  • 验收标准（可测试的、非主观描述）。
• 将填好的模板展示给用户，要求用户：
  • 指出不准确的地方；
  • 补充遗漏信息。

完成标志：

• 模板经用户确认无重大遗漏；
• 至少列出 3 个异常场景；
• 验收标准可以用测试或清晰手工步骤检查；
• 提醒用户将该文档保存到项目中。

---

Phase 2：架构设计

目标：在写代码前，确定项目结构、模块职责、数据流向和接口约定。

进入条件：Phase 1 需求文档已经确认。

助手行动规范

• 要求用户提供或确认：
  • Phase 1 的需求文档（可为刚刚整理的 Markdown）；
  • 当前或预期的代码仓库根目录说明（如果已有项目）。
• 基于需求文档，输出：
  1. 建议的目录结构（到文件级别）；
  2. 每个目录/文件的一句话职责说明；
  3. 一份 Mermaid 数据流图（flowchart）代码；
  4. 各模块间的接口约定（函数名、参数、返回值类型等）；
  5. 设计中最脆弱/最不确定的一处，并说明原因。
• 强调此阶段不写实现代码，只定接口和结构。

完成标志（助手自检清单）

• 项目目录结构清晰，无明显职责重叠；
• 数据流图已给出，并提醒用户可在编辑器或 draw.io 中渲染；
• 各模块间调用只通过约定接口，无随意跨层调用；
• 已建议用户将架构文档保存进仓库（如 docs/architecture.md）。

---

Phase 3：代码生成

目标：逐模块在 Cursor 中完成实现，保持与架构文档一致。

进入条件：Phase 2 的架构（目录结构与接口约定）已经确认。

逐模块生成原则

对于每一个将要实现的模块，助手应：

1. 明确当前模块的：
   • 文件路径；
   • 职责描述（从架构文档拷贝或总结）；
   • 依赖的外部接口（被调用的模块和函数）；
   • 向外暴露的接口（需要提供的函数/类）。
2. 只在一个模块的上下文内生成代码，不要一次性尝试完成整个项目。
3. 使用 Cursor 的代码能力时，优先在对应文件中：
   • 创建/补全函数签名；
   • 按约定实现逻辑；
   • 保持与前一阶段接口约定的一致性。

生成顺序建议

• 先实现基础模块（工具函数、数据模型、存储层）；
• 再实现业务逻辑层；
• 最后实现界面层或外部适配层；
• 每个模块生成后，至少做一次最小验证：
  • 能被 import；
  • 关键函数能被调用（可用简单示例或小测试）。

完成标志

• 所有模块均有对应实现，并与架构文档一致；
• 未出现架构文档中未定义的新模块或跨层调用；
• 配置、常量等集中管理，而非散落硬编码；
• 提醒用户做一次整体提交，并在说明中标明完成的模块范围。

---

Phase 4：调试与问题排查

目标：通过完整信息 + 解释原因 + 步进执行的方式，与用户协作解决问题。

基本调试循环（四步）

1. 获取完整信息
   • 引导用户粘贴：
     • 完整报错文本（从头到尾）；
     • 触发错误前的具体操作；
     • 期望行为与实际行为；
     • 已尝试过但无效的方案。
2. 解释原因
   • 用大白话解释错误含义；
   • 给出 1–3 个最可能的原因，标出优先排查顺序。
3. 给出分步方案
   • 提供清晰的、可逐步执行的修复步骤；
   • 要求用户按步反馈每一步的结果，不要一次性跑完。
4. 总结记录
   • 问题解决后，输出一句话总结：
     • 问题：____；
     • 原因：____；
     • 解决方法：____；
   • 提醒用户将这条记录保存以便下次复用。

当多轮尝试仍未解决

• 若同一问题在同一对话中连续 3 轮以上未解决，应主动建议：
  • 开启新对话；
  • 从头贴出完整错误和已尝试方案；
  • 明确要求“请从不同角度重新分析，不要重复之前方向”。

---

Phase 5：持续迭代

目标：在项目已运行的基础上，针对新增功能 / 性能或体验优化 / 重构选择合适切入点，再回到对应 Phase。

三种典型迭代场景

1. 新增功能 → 从 Phase 1 重新开始

   • 把新功能视为一个小项目；
   • Phase 1 的“系统背景”中说明现有项目与技术栈；
   • 之后照常走 Phase 2 → 3 → 4。

2. 性能或体验优化 → 从 Phase 4 切入

   • 功能正确但慢 / 难用 / 输出不理想；
   • 直接描述“感受上的问题”+ 相关代码；
   • 使用 Phase 4 的调试循环定位并改进。

3. 代码结构混乱 → 从 Phase 2 切入

   • 代码可以跑，但可维护性差、难以扩展；
   • 回到架构设计，重新划分模块和职责；
   • 先完成重构，再在新结构基础上加功能。

完成标志

• 明确本次改动属于哪一类场景；
• 对应 Phase 的关键输出物有更新（需求文档 / 架构文档等）；
• 提醒用户在提交记录中说明本次迭代的目的与范围。

---

快速使用指引（给助手）

当检测到用户有较大开发需求时，优先：

1. 判断当前所处 Phase；若尚未开始，则从 Phase 1 Step 1 启动；
2. 明确告诉用户：“现在我们按 Vibe Coding Workflow 的 Phase X 来做”，并简要说明本阶段目标；
3. 严格使用本 Skill 中的阶段输出物清单作为是否进入下一阶段的依据；
4. 在合适时机建议用户把需求/架构/问题总结写入项目中的文档文件，以便后续复用。