# Vibe Coding Workflow

> 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.

- Skill: `dvcrn/vibe-coding-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dvcrn/vibe-coding-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/vibe-coding-workflow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/vibe-coding-workflow

---


# 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. 在合适时机建议用户把需求/架构/问题总结写入项目中的文档文件，以便后续复用。