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

本文介绍如何为Vue3+Pinia+TypeScript项目编写CLAUDE.md配置文件。

该文件用于规范AI生成的代码质量，包含以下核心内容：

基础模板：定义技术栈(Vue3+Pinia+TS)、代码规范(强制使用<script setup>语法、严格类型检查)、目录结构；

详细配置：包括Vue组件规范(TypeScript接口定义)、Pinia Store写法(组合式API)、API请求封装等；

禁止事项：如避免模板复杂计算、禁止直接修改Store状态等；

可扩展性：支持添加UI组件库偏好、路由约定等自定义配置。

通过维护该文件，可确保AI生成的代码符合项目规范，减少手动调整。

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

CLAUDE.md 文件是 Claude Code 的项目配置文件，放在项目根目录下，用于告诉 AI 你的项目规范、技术栈和代码风格。

写好这个文件，AI 生成的代码质量会大幅提升。

一、基础模板（直接可用）

在项目根目录创建 CLAUDE.md 文件，内容如下：

bash 复制代码

# 项目概述

这是一个基于 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 lang="ts">` 语法
- 组件文件名使用 PascalCase (如 `UserProfile.vue`)
- Props 和 Emits 必须显式声明类型
- 模板中避免复杂的表达式，复杂逻辑放到 `computed` 或函数中

```vue
<script setup lang="ts">
// Props 示例
interface Props {
  userId: number
  showAvatar?: boolean
}
const props = withDefaults(defineProps<Props>(), {
  showAvatar: true
})

// Emits 示例
interface Emits {
  (e: 'update', value: string): void
  (e: 'close'): void
}
const emit = defineEmits<Emits>()
</script>

TypeScript

启用 strict: true 模式
避免使用 any，特殊情况用 unknown 并做类型守卫
API 响应数据必须定义类型接口
工具函数需要完整的类型签名

Pinia Store

使用组合式 API 风格 (Setup Store)
Store 文件命名: useXxxStore.ts
状态、计算属性、方法按逻辑分组

TypeScript 复制代码

// store 示例
export const useUserStore = defineStore('user', () => {
  // state
  const userInfo = ref<UserInfo | null>(null)
  const token = ref<string>('')

  // 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 }
})

目录结构

TypeScript 复制代码

src/
├── api/           # API 接口定义，按模块划分
├── assets/        # 静态资源
├── components/    # 公共组件
├── composables/   # 组合式函数 (VueUse 风格)
├── layouts/       # 布局组件
├── router/        # 路由配置
├── stores/        # Pinia Store
├── types/         # TypeScript 类型定义
├── utils/         # 工具函数
├── views/         # 页面组件
└── App.vue

常用模式

API 请求

所有 API 调用统一放在 api/ 目录
使用已配置好的 axios 实例，自动携带 token
响应拦截器已统一处理错误

TypeScript 复制代码

// api/user.ts 示例
import request from '@/utils/request'
import type { LoginParams, LoginResponse } from '@/types/user'

export const userApi = {
  login(data: LoginParams) {
    return request.post<LoginResponse>('/auth/login', data)
  }
}

组合式函数 (Composables)

复用逻辑抽取到 composables/ 目录
函数名以 use 开头

TypeScript 复制代码

// composables/useTable.ts
export function useTable<T = any>(fetchFn: () => Promise<T[]>) {
  const data = ref<T[]>([])
  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 命名
列表页需提供分页逻辑 (使用 usePagination composable)
表单需提供校验规则 (使用组件库的校验器)

禁止事项

❌ 不要在模板中直接调用方法进行复杂计算
❌ 不要在 <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 组件库偏好

如果你用的是特定组件库，可以明确告诉 AI：

markdown

复制代码

## UI 组件库 (Element Plus)
- 表单使用 `<el-form>` 配合 `:model` 和 `:rules`
- 表格使用 `<el-table>`，列定义用 `<el-table-column>`
- 图标使用 `<el-icon>` 包裹组件
- 消息提示用 `ElMessage`，确认框用 `ElMessageBox.confirm`

2. 路由约定

markdown

复制代码

## 路由配置

- 路由懒加载: `() => import('@/views/xxx.vue')`
- 路由元信息: `meta: { title: string, requiresAuth?: boolean }`
- 登录守卫在 `router.beforeEach` 中统一处理

3. 样式规范

markdown

复制代码

## 样式规范

- 使用 `<style scoped lang="scss">`
- 变量定义在 `src/styles/variables.scss`
- 全局样式在 `src/styles/index.scss` 引入
- BEM 命名规范: `.block__element--modifier`

4. 测试要求

如果项目需要测试：

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.md，AI 会优先读取更近的配置：

复制代码

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 生成的代码会非常贴合你的项目风格，基本不需要手动调整，直接运行就能用。