Vue3+Pinia+TypeScript 前端开发环境，CLAUDE.md 文件应该怎么写

本文介绍如何为Vue3PiniaTypeScript项目编写CLAUDE.md配置文件。该文件用于规范AI生成的代码质量包含以下核心内容基础模板定义技术栈(Vue3PiniaTS)、代码规范(强制使用script setup语法、严格类型检查)、目录结构详细配置包括Vue组件规范(TypeScript接口定义)、Pinia Store写法(组合式API)、API请求封装等禁止事项如避免模板复杂计算、禁止直接修改Store状态等可扩展性支持添加UI组件库偏好、路由约定等自定义配置。通过维护该文件可确保AI生成的代码符合项目规范减少手动调整。Vue3PiniaTypeScript 前端开发环境CLAUDE.md 文件应该怎么写CLAUDE.md文件是 Claude Code 的项目配置文件放在项目根目录下用于告诉 AI 你的项目规范、技术栈和代码风格。写好这个文件AI 生成的代码质量会大幅提升。一、基础模板直接可用在项目根目录创建CLAUDE.md文件内容如下# 项目概述 这是一个基于 Vue 3 Pinia TypeScript 的前端项目。 ## 技术栈 - **框架**: Vue 3 (Composition API使用 script setup 语法) - **状态管理**: Pinia (组合式 Store 风格) - **语言**: TypeScript (严格模式) - **构建工具**: Vite - **UI 组件库**: [根据实际填写如 Element Plus / Ant Design Vue / Naive UI] - **路由**: Vue Router 4 - **HTTP 请求**: Axios (已封装) ## 代码规范 ### Vue 组件 - 强制使用 script setup langts 语法 - 组件文件名使用 PascalCase (如 UserProfile.vue) - Props 和 Emits 必须显式声明类型 - 模板中避免复杂的表达式复杂逻辑放到 computed 或函数中 vue script setup langts // Props 示例 interface Props { userId: number showAvatar?: boolean } const props withDefaults(definePropsProps(), { showAvatar: true }) // Emits 示例 interface Emits { (e: update, value: string): void (e: close): void } const emit defineEmitsEmits() /scriptTypeScript启用strict: true模式避免使用any特殊情况用unknown并做类型守卫API 响应数据必须定义类型接口工具函数需要完整的类型签名Pinia Store使用组合式 API 风格 (Setup Store)Store 文件命名:useXxxStore.ts状态、计算属性、方法按逻辑分组// store 示例 export const useUserStore defineStore(user, () { // state const userInfo refUserInfo | null(null) const token refstring() // getters const isLoggedIn computed(() !!token.value) // actions async function login(params: LoginParams) { const res await api.login(params) token.value res.token userInfo.value res.userInfo } return { userInfo, token, isLoggedIn, login } })目录结构src/ ├── api/ # API 接口定义按模块划分 ├── assets/ # 静态资源 ├── components/ # 公共组件 ├── composables/ # 组合式函数 (VueUse 风格) ├── layouts/ # 布局组件 ├── router/ # 路由配置 ├── stores/ # Pinia Store ├── types/ # TypeScript 类型定义 ├── utils/ # 工具函数 ├── views/ # 页面组件 └── App.vue常用模式API 请求所有 API 调用统一放在api/目录使用已配置好的 axios 实例自动携带 token响应拦截器已统一处理错误// api/user.ts 示例 import request from /utils/request import type { LoginParams, LoginResponse } from /types/user export const userApi { login(data: LoginParams) { return request.postLoginResponse(/auth/login, data) } }组合式函数 (Composables)复用逻辑抽取到composables/目录函数名以use开头// composables/useTable.ts export function useTableT any(fetchFn: () PromiseT[]) { const data refT[]([]) const loading ref(false) const refresh async () { loading.value true try { data.value await fetchFn() } finally { loading.value false } } return { data, loading, refresh } }代码生成偏好组件内部状态按优先级:props→ref→reactive(仅用于复杂对象)异步操作统一使用async/await配合try/catch处理错误需要加载状态的地方用loading或pending命名列表页需提供分页逻辑 (使用usePaginationcomposable)表单需提供校验规则 (使用组件库的校验器)禁止事项❌ 不要在模板中直接调用方法进行复杂计算❌ 不要在script setup之外写 Vue 组件❌ 不要使用 Options API全部使用 Composition API❌ 不要直接修改store的 state通过 store 的 actions 修改❌ 不要硬编码 API 地址使用环境变量import.meta.env.VITE_API_BASE_URL环境变量开发环境:.env.development生产环境:.env.production主要变量:VITE_API_BASE_URL: API 接口地址VITE_APP_TITLE: 应用标题二、自定义补充项根据项目实际情况修改1. UI 组件库偏好如果你用的是特定组件库可以明确告诉 AImarkdown## UI 组件库 (Element Plus) - 表单使用 el-form 配合 :model 和 :rules - 表格使用 el-table列定义用 el-table-column - 图标使用 el-icon 包裹组件 - 消息提示用 ElMessage确认框用 ElMessageBox.confirm2. 路由约定markdown## 路由配置 - 路由懒加载: () import(/views/xxx.vue) - 路由元信息: meta: { title: string, requiresAuth?: boolean } - 登录守卫在 router.beforeEach 中统一处理3. 样式规范markdown## 样式规范 - 使用 style scoped langscss - 变量定义在 src/styles/variables.scss - 全局样式在 src/styles/index.scss 引入 - BEM 命名规范: .block__element--modifier4. 测试要求如果项目需要测试markdown## 测试 - 单元测试: Vitest - 组件测试: Vue Test Utils - 测试文件放在 __tests__ 目录命名 *.spec.ts - 核心工具函数和复杂组件必须有测试三、使用技巧1. 让 AI 读取 CLAUDE.md在 Claude Code 中只需输入 按照项目规范帮我生成一个用户管理页面AI 会自动读取CLAUDE.md并遵循其中的规范。2. 动态更新随着项目演进可以持续更新CLAUDE.md新增了公共组件更新目录结构说明调整了 API 请求格式更新 API 章节发现了常见坑点加到“禁止事项”里3. 团队共享CLAUDE.md应该提交到 Git 仓库这样整个团队都能享受一致的 AI 生成质量。四、进阶创建模块级 CLAUDE.md如果项目有独立子模块可以在子目录下也放一个CLAUDE.mdAI 会优先读取更近的配置src/views/user/CLAUDE.md # 用户模块专用规范 src/views/order/CLAUDE.md # 订单模块专用规范子模块配置示例markdown# 用户管理模块 - 页面路径: /user/:id - 相关 Store: useUserStore - API 文件: src/api/user.ts - 通用组件: UserAvatar、UserRoleTag - 新增用户时需触发 userStore.refreshList()这样 AI 在生成这个模块的代码时会同时遵守全局规范和模块特定要求。五、总结写好CLAUDE.md的核心原则明确技术栈让 AI 知道用什么框架、库定义代码规范命名、结构、写法偏好提供示例好的示例胜过千言万语列出禁止项避免 AI 写出不符合规范的代码持续维护项目变化文档也要跟上有了这份配置Claude Code 生成的代码会非常贴合你的项目风格基本不需要手动调整直接运行就能用。