前端项目如何做 vibe coding

Vue 项目 Vibe Coding 指南

Vibe Coding 指以自然语言与 AI（如 Cursor Agent）协作完成软件开发的模式：你描述意图，AI 读代码、改代码、跑命令；你负责方向、验收与关键决策。

本文档面向 Vue 3 项目，给出一条可重复、可落地的 Vibe Coding 流程------从业务需求澄清，到技术选型、架构设计、Skill/Rule 定义，再到日常开发与质量把关。不绑定某一具体业务，可作为任意 Vue 项目的启动模板。

---

1. 核心观念：Vibe Coding ≠ 无规矩地生成代码

很多失败案例来自：需求一句话带过 → AI 直接改代码 → 风格漂移、架构混乱、难以维护。

正确的 Vibe Coding 是 「人定方向 + AI 执行 + 机器校验」 的三段式：

人：业务目标、边界、验收标准
AI：调研、选型建议、实现、重构、补测试
机器：ESLint / vue-tsc / Vitest / CI / Git Hook

规矩越前置，AI 越像「带规范的 pair programmer」，而不是「碰运气的代码生成器」。

---

2. 完整流程总览

flowchart LR A[① 澄清业务需求] --> B[② AI 辅助技术选型] B --> C[③ AI 辅助架构设计] C --> D[④ 查询 / 定义 Skill] D --> E[⑤ 定义 Rules + Lint] E --> F[⑥ 迭代开发] F --> G[⑦ 验证与 Review] G --> F

阶段	人的职责	AI 的职责	产出物
① 需求澄清	写清用户、场景、约束、验收	追问遗漏、整理 PRD 草稿	需求说明 / 用户故事
② 技术选型	拍板最终方案	对比方案、列 trade-off	ADR / 技术栈文档
③ 架构设计	确认分层与边界	目录结构、模块图、数据流	docs/architecture.md
④ Skill	决定装哪些、是否自研	检索社区 Skill、起草 SKILL.md	.cursor/skills/
⑤ Rules + Lint	确认团队规范	生成 .mdc、补 ESLint 规则	.cursor/rules/、lint 配置
⑥ 迭代开发	拆任务、验收	读上下文、小步改代码	功能代码
⑦ 验证	关键路径人工测	跑 lint/test、修报错	可合并的 PR

原则：先文档与规矩，再写功能；先架构与边界，再让 AI 动刀。

---

3. 阶段 ①：澄清业务需求（一切起点）

在让 AI 写任何代码之前，先把需求说到 AI 和人都能执行 的程度。

3.1 需求应包含的要素

要素	说明	示例
用户与场景	谁在用、在什么设备/环境下用	iPad 横屏排练、后台运营人员
核心用户旅程	从进入到完成目标的步骤	登录 → 选项目 → 编辑 → 导出
功能边界	做什么、不做什么	本期不做离线同步、不做多租户
非功能需求	性能、兼容、安全、合规	首屏 < 3s、支持 Chrome/Safari、数据不出境
验收标准	可测试的完成定义	「导出文件可被 X 软件打开且无乱码」
现有约束	必须沿用的栈、设计系统、API	已有 REST 后端、必须用 Element Plus

3.2 用 AI 帮忙「补全需求」

需求初稿往往不完整。可以让 AI 担任 需求分析师，而不是程序员：

我是 Vue 3 前端，要做 [一句话描述]。
请列出：① 可能遗漏的用户场景 ② 边界情况 ③ 非功能风险 ④ 需要我确认的问题清单。
不要写代码，只输出结构化需求追问。

AI 应输出 问题清单，你逐条回答后再进入下一阶段。避免 AI 在假设未验证的情况下直接选型或编码。

3.3 需求文档最小模板

建议在 docs/ 或 Issue 中留一份短 PRD（一页以内即可）：

# [功能名]

## 背景
## 用户与场景
## 用户故事（As a ... I want ... So that ...）
## 范围（In / Out）
## 验收标准（Given / When / Then 或 checklist）
## 依赖与风险

后续所有 Architecture、Skill、Rule、Prompt 都应能 回溯到这份 PRD。

---

4. 阶段 ②：AI 辅助技术选型

需求清楚后，再讨论「用什么技术实现」。这一步 AI 给建议，人做决策。

4.1 选型时要喂给 AI 的上下文

业务需求：[粘贴 PRD 摘要]
团队能力：[熟悉 Vue，不熟悉 React Native]
硬性约束：[必须 Web + 可选 App、后端已是 Java、部署在阿里云]
偏好：[TypeScript、倾向开源、可接受 WASM 体积]
请给出 2～3 套前端技术方案，对比：开发效率、维护成本、包体积、生态、风险。
最后给出推荐方案与「若不选推荐方案的后果」。
不要直接生成项目代码。

4.2 Vue 项目常见选型维度

维度	典型选项	选型考量
框架	Vue 3	团队主栈；默认 Composition API + <script setup>
构建	Vite	生态默认；SSR 需 Nuxt
UI 库	Element Plus / Naive UI / Vant / Ionic Vue	B 端 vs C 端 vs 移动端壳
状态	Pinia	全局状态；服务端状态可用 TanStack Query
路由	Vue Router	标准方案
跨端	Capacitor / uni-app	原生能力 vs 一套代码多端
SSR/SSG	Nuxt 3	SEO、首屏、同构
测试	Vitest + Vue Test Utils + Playwright/Cypress	单测 + E2E 分工
样式	Tailwind / SCSS / CSS Modules	与设计系统是否一致

4.3 输出：技术决策记录（ADR）

让 AI 把结论整理成 Architecture Decision Record，避免后续对话中 AI「换栈」：

# ADR-001：前端技术栈

## 状态：已采纳
## 背景
## 决策
- Vue 3 + Vite + TypeScript + Pinia + Vue Router
- UI：Element Plus
## 备选方案及未采纳原因
## 后果（正面 / 负面）

将 ADR 放入仓库（如 docs/adr/），并在 .cursor/rules/ 中加一条 alwaysApply 规则引用主栈，防止 AI 擅自引入 React 或 Options API 全家桶。

---

5. 阶段 ③：AI 辅助架构设计

选型确定后，先画架构再写页面。这是 Vibe Coding 中最容易被跳过、也最容易翻车的步骤。

5.1 架构设计要回答的问题

1. 代码放哪里？（目录与分层）
2. 数据怎么流？（Props / Emit / Store / API / 本地缓存）
3. 哪些是纯逻辑、哪些是 UI？（可否单测）
4. 模块边界是什么？（谁不能 import 谁）
5. 扩展点在哪里？（新页面、新 API、新插件）

5.2 推荐 Prompt：让 AI 出架构草案

基于以下 PRD 和 ADR，为 Vue 3 项目设计前端架构。

要求：
1. 给出 src/ 目录树及每个目录的一句话职责
2. 画数据流（用户操作 → 组件 → composable → api/lib → 后端/存储）
3. 说明 Pinia store 与 composable 的分工原则
4. 列出 3 条「禁止事项」（如：页面组件不得直接 axios、lib 不得 import .vue）
5. 给出 2～3 个核心模块的组件拆分草图（props/emits）

约束：Composition API + script setup；不引入新框架。
输出 markdown，不要写实现代码。

5.3 Vue 项目通用分层模型

适用于多数中大型 Vue 应用：

src/
├── views/              # 路由级页面：编排、布局、组合 composable
│   └── feature/
│       ├── IndexPage.vue
│       └── components/ # 仅本 feature 使用的子组件
├── components/         # 跨 feature 复用的展示组件
├── composables/        # useXxx：组合式逻辑、副作用、与 Vue 生命周期绑定
├── stores/             # Pinia：跨页面共享、可持久化的应用状态
├── api/                # HTTP 客户端、请求封装、DTO 类型
├── lib/                # 纯 TS 领域逻辑（无 Vue 依赖，易单测）
├── router/
├── assets/
└── types/

经验法则：

层级	放什么	不放什么
views/	页面编排、路由参数、组合子面板	复杂算法、直接 DOM 操作
composables/	表单状态、分页、轮询、与 ref 绑定的逻辑	与 UI 无关的纯计算（应下沉 lib）
stores/	用户信息、全局 UI 偏好、购物车等	巨型「万能 store」
lib/	格式化、校验、解析、业务规则	import { ref } from 'vue'
api/	REST/GraphQL 调用	业务分支判断

5.4 架构文档应固化到仓库

AI 生成的架构草案经你修订后，写入 docs/architecture.md，内容包括：

• 目录约定
• 数据流图（可用 mermaid）
• Store 划分表
• 命名规范（组件、composable、emit）
• 与后端/API 的边界

之后在每次开发 Prompt 里可写：「遵循 docs/architecture.md」，减少 AI 自创目录结构。

5.5 用 AI 做「架构 Review」

首版架构或重大功能上线前：

阅读 docs/architecture.md 和 src/views/order/ 下的实现。
找出：① 违反分层的文件 ② 重复逻辑 ③ 难以测试的部分 ④ 建议拆分的 composable。
输出优先级 P0/P1 的重构清单，不要直接改代码。

---

6. 阶段 ④：查询、安装与定义 Skill

Skill 是教 AI 如何完成某类任务 的操作手册（工作流、检查清单、领域步骤），存放在：

• 项目级：.cursor/skills/（团队共享，随仓库版本管理）
• 个人级：~/.cursor/skills/（跨项目）

6.1 Skill 与 Rule 的分工

	Skill	Rule
作用	教「怎么做一件事」的流程	约束「在这个项目里必须/禁止怎样写」
粒度	任务型（写 composable、做 Code Review）	规范型（目录、命名、分层）
示例	vue-best-practices	globs: **/*.vue 的组件约定

两者互补：Skill 管方法，Rule 管边界。

6.2 如何「查询」现有 Skill

社区与官方来源：

1. vuejs-ai/skills --- Vue / Pinia / composable 等
2. Cursor 文档与社区分享的 Skill 仓库
3. 团队内部 Git 仓库中的 .cursor/skills/

安装方式示例：

# Cursor CLI（网络可达时）
npx skills add vuejs-ai/skills \
  --skill vue-best-practices \
  --skill vue-pinia-best-practices \
  -a cursor -y

Vue 项目常见起步 Skill：

Skill	用途
vue-best-practices	Composition API、SFC、组件拆分、响应式
vue-pinia-best-practices	Store 写法、解构陷阱、持久化
create-adaptable-composable	MaybeRef 可复用 composable

在 Prompt 中 显式激活 ：Use vue skill, ...（具体 invocation 方式以 Cursor 当前版本为准）。

6.3 何时需要「自定义 Skill」

社区 Skill 覆盖 框架通用实践 ，不覆盖你的 业务领域。出现以下情况应自研 Skill：

• 有固定的领域工作流（如「新增一种导出格式」的 6 步检查清单）
• 有第三方 SDK 的非 obvious 用法（WASM、Canvas、WebRTC）
• 有团队统一的 PR Review / 发布流程
• 同一类任务 AI 反复犯同样的错

6.4 自定义 Skill 的结构

.cursor/skills/your-domain-feature/
├── SKILL.md           # 必需：frontmatter + 步骤说明
├── reference.md       # 可选：详细 API、协议
└── examples.md        # 可选：正反例

SKILL.md frontmatter 示例：

---
name: vue-feature-module
description: >-
  Add a new feature module to this Vue app: views, composable,
  api, and tests. Use when creating routes or feature folders.
---

正文应包含：

1. 触发条件（何时用本 Skill）
2. 分步工作流（有序步骤，可勾选）
3. 必须阅读的仓库文件列表
4. 完成后的验证命令（npm run lint 等）
5. 反模式（不要做什么）

让 AI 帮你起草 Skill：

我们项目做 [领域简述]。AI 在 [具体任务] 时经常 [犯错描述]。
请为 Cursor 起草一个项目 Skill：name、description、分步 workflow、
验证清单、3 条 anti-patterns。格式符合 SKILL.md frontmatter 规范。

6.5 Skill 维护

• 与代码一起 PR Review；Skill 过时比没有 Skill 更危险
• 大 Skill 拆成 SKILL.md + reference/，避免单次上下文过长
• 在 docs/ 或 .cursor/skills/README.md 记录安装与更新命令

---

7. 阶段 ⑤：定义 Rules 与 Lint（为 IDE 立规矩）

Skill 解决「怎么做」，Rule + Lint 解决「不能越界的线」。

7.1 Cursor Rules（.cursor/rules/*.mdc）

建议按关注点拆分，而非一个巨型 rule 文件：

Rule 文件	globs 示例	内容
vue-core.mdc	**/*.{vue,ts}	script setup、路径别名、命名
vue-pages.mdc	**/*.vue	页面 / 组件放置、props-emits
pinia-stores.mdc	src/stores/**	store 命名、持久化、storeToRefs
api-layer.mdc	src/api/**	错误处理、类型、禁止在组件里裸 fetch
domain-lib.mdc	src/lib/**	纯 TS、禁止 import Vue
project-stack.mdc	alwaysApply: true	ADR 摘要：栈、测试命令、分支策略

Rule 编写原则：

• 每条规则 可执行（「用 storeToRefs」而非「注意响应式」）
• 引用 仓库内真实路径 作为范本（参考 src/stores/user.ts）
• 控制在 50 行以内 为宜；细节放 docs/
• 用 globs 精准触发，减少无关上下文噪音

让 AI 生成 Rule 草案：

根据 docs/architecture.md，生成 3 个 Cursor rule 文件（.mdc）：
1. Vue 页面与组件放置
2. Pinia store 约定
3. src/lib 纯函数边界
每个 rule 含 frontmatter（description、globs）、条目化约束、一个正确示例。

7.2 ESLint + TypeScript + Git Hook

AI 生成的代码必须通过 机器门禁，否则 Vibe Coding 不可持续。

推荐基线（Vue 3 + TS）：

eslint + eslint-plugin-vue + @vue/eslint-config-typescript
vue-tsc（类型检查）
Vitest（单测）
husky + lint-staged（提交前）
CI 中复跑 lint / typecheck / test

package.json 脚本示例：

{
  "scripts": {
    "lint": "eslint src tests",
    "typecheck": "vue-tsc --noEmit",
    "test:unit": "vitest run"
  },
  "lint-staged": {
    "*.{vue,ts,js}": "eslint --max-warnings 0"
  }
}

.husky/pre-commit：

npm run typecheck
npx lint-staged

在 Rule 或 Skill 中写明：「改完代码必须跑 lint + typecheck」，并在 Prompt 末尾附上相同要求。

7.3 可选：AGENTS.md

部分团队会在根目录增加 AGENTS.md，给 AI 一段 项目入口说明（如何启动、测试命令、目录地图、链接到 architecture）。与 Rules 类似但更偏「 onboarding 索引」。

---

8. 阶段 ⑥：日常 Vibe Coding 开发循环

规矩就绪后，进入高频迭代。推荐 单次任务一个闭环。

8.1 任务拆分

把 PRD 拆成 可在一个会话内完成 的小任务：

• ✅ 「订单列表页：composable 分页 + 表格组件 + 空状态」
• ❌ 「把整个电商后台做完」

8.2 标准 Prompt 模板

Use vue skill.

## 背景
[链到 PRD 或 architecture 的一两句话]

## 任务
[具体、可验收的一句话]

## 约束
- 遵循 docs/architecture.md 与 .cursor/rules/vue-pages.mdc
- 不修改 [明确不动的模块]
- Composition API + script setup + TypeScript

## 相关文件（可选）
@src/views/order/IndexPage.vue

## 完成后
npm run lint && npm run typecheck && npm run test:unit
简述改动文件与如何手动验证。

8.3 AI 开发逻辑（Agent 侧应遵循的顺序）

1. 读需求与约束 → 确认任务范围
2. 读 architecture、相关 rule、现有同类代码
3. 规划改动文件列表（先列表，再动手）
4. 小步修改：优先 lib/composable，再改 UI
5. 跑 lint / typecheck / test，修到通过
6. 输出：改了什么、如何验证、已知限制

Vue 特有注意点：

• 新组件默认 <script setup lang="ts">，Props down / Emits up
• 从 Pinia 解构状态用 storeToRefs
• 列表性能：大列表考虑虚拟滚动；避免在列表项里堆抽象组件
• 路由级页面做 编排，业务逻辑进 composable / lib

8.4 适合交给 AI 的工作

类型	示例
样板代码	CRUD 表格、表单、对话框、路由注册
重构	从巨型 .vue 抽 useXxx
类型与 lint	补类型、修 ESLint、修 vue-tsc 报错
测试	为 lib/ 纯函数写 Vitest
文档	ADR、API 说明、组件 props 文档

8.5 需人工主导、AI 辅助的工作

类型	原因
安全与权限模型	AI 易漏边界 case
支付、隐私、合规	需法务/安全 review
核心领域算法	需 spec + 单测 + 人工验算
包体积与性能预算	需 profiling，非猜
破坏性 API 变更	需版本策略与迁移计划

---

9. 阶段 ⑦：验证、Review 与持续改进

9.1 验证层次

L1 机器：lint + vue-tsc + unit test（每次提交）
L2 本地：npm run dev 手动走用户旅程
L3 集成：E2E（Playwright / Cypress）关键路径
L4 人审：架构边界、安全、UX、无障碍

Prompt 中要求 AI 自己跑 L1；L2～L4 由你或 CI 负责。

9.2 用 AI 做 Code Review

Review 本次 diff（不要改代码）：
1. 是否违反 docs/architecture.md
2. 是否有重复逻辑可抽 composable/lib
3. 是否有明显性能问题（大列表、watch 滥用）
4. 测试是否覆盖核心分支
输出按严重程度排序的 findings。

9.3 从失败中更新 Skill / Rule

若 AI 重复犯同一错误：

1. 不要只在聊天里纠正一次
2. 把纠正写进 Rule （硬约束）或 Skill（流程步骤）
3. 必要时加 单测 锁住行为

Vibe Coding 的复利来自：每一次翻车都让规矩变强一点。

---

10. Vibe Coding 的优劣（Vue 项目视角）

10.1 优势

优势	说明
交付速度快	表单、列表、路由、Store 样板极快
降低入门成本	新人通过对话 + architecture 快速定位模块
规范可编码	Skill + Rule 把团队习惯注入 AI 上下文
重构友好	「抽到 composable」类机械搬迁 AI 擅长
文档即 spec	PRD / ADR / architecture 可直接当 Prompt 附件

10.2 劣势与风险

风险	表现	缓解
上下文有限	漏读关联文件，改了一处坏另一处	小任务、显式 @ 文件、先规划后改
架构漂移	每个会话一种写法	ADR + Rules + architecture 固化
幻觉 API	编造不存在的 Vue 库 API	以 lockfile 和现有代码为准；typecheck 兜底
上帝组件	逻辑全堆进 .vue	Rule 限制 + 强制 composable 拆分
测试债务	改完不跑 test	pre-commit + Prompt 要求跑 test
过度抽象	无意义的 helper 层	「最小 diff」写进 Rule
隐私	业务数据进入模型	企业隐私设置、脱敏、本地模型（若可用）

10.3 何时适合 / 不适合

适合 Vibe Coding：

• greenfield 或中等复杂度的 Vue 功能模块
• UI 迭代、Design system 落地
• 技术债清理（lint、类型、拆组件）
• 有清晰 PRD 和 architecture 的迭代

应降低 AI 自主权：

• 金融、医疗等强合规场景的核心链路
• 无 spec 的复杂算法
• 大规模迁移（Vue 2→3、换 UI 库）需分阶段人工掌舵

---

11. 新项目 Checklist（可直接复制）

## Vibe Coding 启动清单

- [ ] PRD：用户、范围、验收标准
- [ ] ADR：Vue 3 技术栈定稿
- [ ] docs/architecture.md：目录、数据流、Store 划分
- [ ] 安装社区 Vue Skill（vue-best-practices 等）
- [ ] 自定义领域 Skill（如有）
- [ ] .cursor/rules/：vue / pinia / api / lib 分层规则
- [ ] ESLint + vue-tsc + Vitest + husky
- [ ] CI：lint + typecheck + test
- [ ] 首个 feature 用小任务 + 标准 Prompt 试跑一轮
- [ ] 根据翻车更新 Rule / Skill

---

12. 附录：Prompt 速查

需求澄清

针对 [功能]，列出必须确认的 10 个问题，按优先级排序。不要写代码。

技术选型

给定 PRD 和约束，输出 2 套 Vue 前端方案对比表 + 推荐 ADR 草稿。

架构设计

输出 src/ 目录树、数据流 mermaid、Pinia 划分、3 条禁止事项。不要写实现。

创建 Skill

为 [任务类型] 起草 .cursor/skills/xxx/SKILL.md，含 workflow 与 anti-patterns。

创建 Rule

根据 architecture 生成 .mdc rule：globs、可执行条目、正例一行。

功能开发

Use vue skill. 任务：... 约束：architecture + rules. 完成后 lint + typecheck + test。

架构 / Code Review

Review [路径或 diff]，只输出 findings，按 P0/P1 排序，不改代码。

---

13. 总结

正确的 Vue Vibe Coding 路径：

1. 先讲清业务 --- PRD 与验收标准是一切的前提
2. 再让 AI 帮选型与架构 --- 人拍板，AI 调研与起草，结果写入 ADR / architecture
3. 然后立规矩 --- 社区 Skill + 自研 Skill + Cursor Rules + Lint/Hook
4. 再小步开发 --- 显式约束、读现有代码、最小 diff、机器验证
5. 最后从失败中迭代规矩 --- Rule / Skill / 测试与文档同步进化

Vibe Coding 的价值不在于「少写代码」，而在于 在明确边界内放大实施速度。边界越清晰，AI 越可靠；规矩越薄，翻车越频繁。