6.3 KiB
6.3 KiB
name, description
| name | description |
|---|---|
| vue-coding-style | 面向 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 任务
- 读取作用域内的
AGENTS.md、项目说明和用户提供的需求文档。 - 检查
package.json、锁文件、Vue/Vite/TypeScript 版本、tsconfig*、ESLint/格式化配置、测试配置和可用脚本。 - 阅读目标文件、直接调用方、相邻同类实现、共享类型、路由、store、API 层和相关测试。
- 区分以下内容：
- 用户明确要求；
- 当前代码与配置事实；
- 本技能给出的默认建议。
- 明确行为边界、非目标、兼容性、风险和可执行的验收方式；存在通用 Vibe Coding 治理 skill 时，同时遵守其分级与门禁。
- 在未核实依赖版本前，不使用较新宏、实验性 API 或废弃特性。
规则优先级
按以下顺序处理冲突：
用户本次明确要求
→ 已确认的需求与验收标准
→ 作用域最近的项目指令
→ 项目配置、自动化规则和相邻代码惯例
→ 本技能的 Vue 默认规范
→ 个人偏好
若更高优先级规则会引入明显缺陷、安全问题或不可验证行为，先暴露冲突和影响，再请求用户决策。不得静默绕过项目规则。
按任务加载参考
- 每次编写或修改 Vue 代码，读取 references/core-standards.md。
- 涉及目录、组件边界、composable、Pinia、Router、API 或 SSR，读取 references/architecture.md。
- 涉及实现、修复、测试、性能、安全、可访问性或交付，读取 references/quality-gates.md。
- 编写新组件、composable、store 或测试且需要范式时，读取 references/examples.md。
- 执行代码 Review 或完成交付前，读取 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 或全局样式，除非它们在确认范围内。
实施流程
- 将验收行为写成可观察结果，优先补充或更新能失败的测试。
- 选择最小改动面，复用项目现有组件、composable、类型、tokens 和工具函数。
- 先建立数据与类型边界，再实现状态与行为，最后连接模板和样式。
- 同时处理 loading、empty、error、disabled、权限不足和异步竞态等适用状态。
- 检查窄视口、键盘、焦点、文本溢出和主题变量等界面边界。
- 自查变更是否引入无关格式化、重复抽象、死代码、调试输出或不必要依赖。
- 运行项目已有验证命令；根据锁文件使用对应包管理器，不得混用。
验证与交付
优先运行项目现有脚本，并按风险选择：
定向测试
→ lint
→ vue-tsc / typecheck
→ 完整单元或组件测试
→ build
→ 关键页面或 E2E 冒烟
对小改动可以只执行受影响范围与必要静态检查；对路由、共享状态、公共组件、构建配置或安全相关改动扩大回归范围。只报告实际执行的命令和结果；无法运行的检查标记为“未验证”并说明原因。
交付时说明：
- 实际行为变化和主要文件；
- 关键设计选择及其项目依据；
- 已执行的测试、类型检查、lint、构建或人工冒烟；
- 未验证项、兼容性风险和剩余问题。