109 lines
6.3 KiB
Markdown
109 lines
6.3 KiB
Markdown
---
|
|
name: vue-coding-style
|
|
description: 面向 Vue 前端 Vibe Coding 的工程化编写、修改、修复、重构、审查与验证规范。凡任务涉及 Vue 3、Vue SFC、Composition API、script setup、TypeScript、Vue Router、Pinia、Vite、Vitest、组件、页面、composable、store、前端接口层、样式、可访问性、性能、测试或 Vue 代码 Review 时使用。默认采用主流 Vue 3 + TypeScript 技术路线，但必须先服从项目现有版本、工具链和局部约定；处理 Vue 2 或 Options API 项目时不得擅自迁移。
|
|
---
|
|
|
|
# Vue Coding Style
|
|
|
|
## 核心目标
|
|
|
|
以可维护、类型安全、可测试、可访问和可验证为目标完成 Vue 变更。优先保持项目一致性，再应用本技能的默认规范。只修改本次需求所需内容，禁止借机升级依赖、迁移 API 风格或重排无关代码。
|
|
|
|
## 开始任何 Vue 任务
|
|
|
|
1. 读取作用域内的 `AGENTS.md`、项目说明和用户提供的需求文档。
|
|
2. 检查 `package.json`、锁文件、Vue/Vite/TypeScript 版本、`tsconfig*`、ESLint/格式化配置、测试配置和可用脚本。
|
|
3. 阅读目标文件、直接调用方、相邻同类实现、共享类型、路由、store、API 层和相关测试。
|
|
4. 区分以下内容：
|
|
- 用户明确要求；
|
|
- 当前代码与配置事实；
|
|
- 本技能给出的默认建议。
|
|
5. 明确行为边界、非目标、兼容性、风险和可执行的验收方式；存在通用 Vibe Coding 治理 skill 时，同时遵守其分级与门禁。
|
|
6. 在未核实依赖版本前，不使用较新宏、实验性 API 或废弃特性。
|
|
|
|
## 规则优先级
|
|
|
|
按以下顺序处理冲突：
|
|
|
|
```text
|
|
用户本次明确要求
|
|
→ 已确认的需求与验收标准
|
|
→ 作用域最近的项目指令
|
|
→ 项目配置、自动化规则和相邻代码惯例
|
|
→ 本技能的 Vue 默认规范
|
|
→ 个人偏好
|
|
```
|
|
|
|
若更高优先级规则会引入明显缺陷、安全问题或不可验证行为，先暴露冲突和影响，再请求用户决策。不得静默绕过项目规则。
|
|
|
|
## 按任务加载参考
|
|
|
|
- 每次编写或修改 Vue 代码，读取 [references/core-standards.md](references/core-standards.md)。
|
|
- 涉及目录、组件边界、composable、Pinia、Router、API 或 SSR，读取 [references/architecture.md](references/architecture.md)。
|
|
- 涉及实现、修复、测试、性能、安全、可访问性或交付，读取 [references/quality-gates.md](references/quality-gates.md)。
|
|
- 编写新组件、composable、store 或测试且需要范式时，读取 [references/examples.md](references/examples.md)。
|
|
- 执行代码 Review 或完成交付前，读取 [references/review-checklist.md](references/review-checklist.md)。
|
|
|
|
只加载当前任务需要的参考文件，但交付前必须执行 Review 清单。
|
|
|
|
## 默认技术基线
|
|
|
|
仅在新项目或项目没有相反约定时采用：
|
|
|
|
- 使用 Vue 3、Single-File Components、Composition API、`<script setup lang="ts">`。
|
|
- 使用严格 TypeScript，并以 `vue-tsc` 覆盖 SFC 与模板类型检查。
|
|
- 使用 Vite 及项目已选择的包管理器。
|
|
- 使用 Vue Router 管理客户端路由，使用 Pinia 管理确有跨页面或跨组件共享价值的客户端状态。
|
|
- 使用 ESLint、`eslint-plugin-vue` 和项目既有格式化方案；新配置优先 Flat Config。
|
|
- 使用 Vitest 做单元/组件测试，使用 `@vue/test-utils` 测试 Vue 组件；关键用户路径按项目选择执行 E2E。
|
|
|
|
不要因默认基线而改造成熟的 Vue 2、Options API、Nuxt、JS-only 或其他既有项目。除非用户明确授权迁移，否则在既有风格内完成最小改动。
|
|
|
|
## 不可妥协的实现约束
|
|
|
|
- 保持单向数据流：props 向下、事件向上；禁止修改 props。
|
|
- 为组件边界提供明确的 props、emits、slots 和 exposed API；避免把内部实现暴露给父组件。
|
|
- 让模板保持声明式；将复杂派生、分支和数据转换移入 `computed`、函数或 composable。
|
|
- 让 `computed` 保持纯净；仅用 `watch`/`watchEffect` 处理副作用，并清理定时器、监听器、请求和过期异步结果。
|
|
- 使用稳定且唯一的 `key`；禁止以数组索引标识可增删、排序或筛选的列表项。
|
|
- 优先局部状态，其次复用 composable，最后才使用 Pinia；不得把所有状态全局化。
|
|
- 在请求边界区分加载、空数据、失败和成功状态；不得吞掉异常或只在控制台记录面向用户的失败。
|
|
- 禁止用 `any`、无依据的类型断言、`@ts-ignore` 或 non-null assertion 掩盖可建模问题。
|
|
- 优先原生语义 HTML；保证键盘操作、焦点、表单标签和必要的 ARIA 语义。
|
|
- 禁止把密钥放入客户端代码或 `VITE_*` 环境变量；谨慎使用 `v-html`，未经可信净化不得渲染外部 HTML。
|
|
- 不为假设的未来需求提前建立抽象；出现第二个真实复用点并且语义稳定时再提取。
|
|
- 不改变依赖、构建配置、公共 API 或全局样式，除非它们在确认范围内。
|
|
|
|
## 实施流程
|
|
|
|
1. 将验收行为写成可观察结果，优先补充或更新能失败的测试。
|
|
2. 选择最小改动面，复用项目现有组件、composable、类型、tokens 和工具函数。
|
|
3. 先建立数据与类型边界，再实现状态与行为，最后连接模板和样式。
|
|
4. 同时处理 loading、empty、error、disabled、权限不足和异步竞态等适用状态。
|
|
5. 检查窄视口、键盘、焦点、文本溢出和主题变量等界面边界。
|
|
6. 自查变更是否引入无关格式化、重复抽象、死代码、调试输出或不必要依赖。
|
|
7. 运行项目已有验证命令；根据锁文件使用对应包管理器，不得混用。
|
|
|
|
## 验证与交付
|
|
|
|
优先运行项目现有脚本，并按风险选择：
|
|
|
|
```text
|
|
定向测试
|
|
→ lint
|
|
→ vue-tsc / typecheck
|
|
→ 完整单元或组件测试
|
|
→ build
|
|
→ 关键页面或 E2E 冒烟
|
|
```
|
|
|
|
对小改动可以只执行受影响范围与必要静态检查；对路由、共享状态、公共组件、构建配置或安全相关改动扩大回归范围。只报告实际执行的命令和结果；无法运行的检查标记为“未验证”并说明原因。
|
|
|
|
交付时说明：
|
|
|
|
- 实际行为变化和主要文件；
|
|
- 关键设计选择及其项目依据；
|
|
- 已执行的测试、类型检查、lint、构建或人工冒烟；
|
|
- 未验证项、兼容性风险和剩余问题。
|
|
|