---
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、构建或人工冒烟；
- 未验证项、兼容性风险和剩余问题。