Skill: shiiyyo/vibe-coding-skill (version 1.0.0)

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

path: README.md
content: ## 项目说明

这是一个用于在 Cursor 中实践 **Vibe Coding 氛围编程规范工作流** 的技能项目。

本项目在 `.cursor/skills/vibe-coding-workflow/` 下提供了一个自定义 Skill，帮助你用 AI 以「需求 → 架构 → 代码 → 调试 → 迭代」的规范流程来完成开发任务。

---

## Skill：vibe-coding-workflow

- **名称**：`vibe-coding-workflow`
- **位置**：`.cursor/skills/vibe-coding-workflow/SKILL.md`
- **作用**：规范 AI 在整个开发过程中的协作方式，强制按照以下 5 个阶段来推进：
  - **Phase 1 需求描述**：从一句模糊想法，走到结构化、可执行的需求文档（澄清 → 技术选型 → 模板固化）；
  - **Phase 2 架构设计**：在写第一行代码前，先确定项目目录结构、模块职责、数据流向和接口约定；
  - **Phase 3 代码生成**：按模块逐步实现，确保每次只生成一个模块的代码，并与前期架构保持一致；
  - **Phase 4 调试优化**：出错时提供完整错误信息，AI 用四步循环（看错误 → 解释 → 步进操作 → 一句话总结）协助排查；
  - **Phase 5 持续迭代**：根据「新增功能 / 性能或体验优化 / 重构」三种场景，选择合适 Phase 重新进入循环。

---

## 在 Cursor 中如何使用该 Skill

- **自动触发的典型场景**：
  - 你在对话中提到：`vibe`、`氛围编程`、`规范工作流`、`Phase 1/2/3/4/5` 等关键词；
  - 你说类似的话：**“帮我按照规范工作流一步一步做这个项目”**。
  在这些情况下，助手会按照 `SKILL.md` 中定义的 5 个 Phase 来引导你推进。

- **建议的使用方式**：
  1. 在 Cursor 中打开你的项目（或本仓库）；
  2. 在聊天中直接描述你的想法，例如：
     - “我想按 Vibe Coding Workflow 做一个 XXXX 工具，请从 Phase 1 帮我开始”；  
     - “这个项目已经写了一半，现在想按规范工作流整理一下架构”；  
  3. 跟随助手的提问和阶段划分，逐步完成：
     - 需求澄清与技术选型；
     - 架构设计与文档落盘；
     - 各模块代码生成；
     - 出错时的调试与总结；
     - 上线后的功能迭代或重构。

- **使用时的注意点**：
  - 每个阶段结束前，助手都会给出**检查清单**和**需要你确认的要点**，请尽量回答清楚再进入下一步；
  - 需求文档、架构文档、调试总结等建议你保存到仓库中（如 `docs/` 目录），后续新需求或重构时可以直接复用；
  - 如果你希望暂时跳过某个 Phase，可以在对话中明确说明（例如“这次先不做架构，直接从代码生成开始”），助手会在简要提示风险后尊重你的选择。

---

## 后续扩展建议

- 如果你有团队级别的编码规范、Commit 规范、Review 规范，可以在本项目下继续新增其他 Skill，与 `vibe-coding-workflow` 搭配使用；
- 也可以为本 Skill 新增 `reference.md` 或 `examples.md`，放置你自己的实际项目示例和最佳实践，方便未来快速复用。



Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)