🍎Claude.md 是啥？让你的 AI 助手乖乖听你的话

Claude.md 是 Claude Code 的配置文件，放在项目里就能让 AI 记住你的规矩、团队的约定、项目的上下文。配置一次，永久生效。

快速开始

在你项目根目录创建 .claude/CLAUDE.md 文件：

bash 复制代码

mkdir -p .claude
touch .claude/CLAUDE.md

Claude Code 启动时会自动读取这个文件，然后乖乖按你的配置来。

全局配置 vs 项目配置

位置	范围	优先级
`~/.claude/CLAUDE.md`	所有项目生效	低
`项目目录/.claude/CLAUDE.md`	只在当前项目生效	高（会覆盖全局）

全局配置示例

直接抄，改改就能用：

markdown 复制代码

# 个人全局配置

## 回答偏好

- 所有对话用中文回复
- 代码修改前先简要说明修改思路
- 遇到多种方案时，列出选项让我选择

## 文档编写偏好

- 所有文档用中文编写，包括openspec等任何文档

## 编程偏好

- 优先使用函数式编程
- 函数不超过 30 行
- 使用描述性变量名

## Git 规范

- 提交信息用中文
- 小而聚焦的提交优于大批量提交

## 安全习惯

- 修改认证相关代码前主动提示安全影响
- 不要在代码注释或日志中输出密钥或 token

项目配置示例

项目级的配置更详细，可以包含技术栈、编码规范、Git 规则、踩坑记录等。

markdown 复制代码

# AdminCore --- Vue3 后台管理系统

基于 Vue 3 + Vite + Element Plus + TypeScript 的企业级后台管理平台。

---

## 技术栈

- **构建工具**：Vite 5.x
- **框架**：Vue 3.4 (Composition API + `<script setup>`)
- **语言**：TypeScript 5.7 (strict mode)
- **UI 组件**：Element Plus 2.4
- **状态管理**：Pinia 2.x
- **路由**：Vue Router 4.x
- **HTTP 客户端**：Axios + 自己封装的请求拦截器
- **CSS 方案**：SCSS + Element Plus CSS 变量覆盖
- **测试**：Vitest + Vue Test Utils + Playwright
- **包管理**：pnpm

---

## 常用命令

```bash
# 开发
pnpm dev                    # 启动开发服务器 (localhost:5173)
pnpm build                  # 生产构建
pnpm build:staging         # 构建 Staging 环境
pnpm preview                # 本地预览生产构建

# 测试
pnpm test                   # 运行单元测试
pnpm test:watch            # 监听模式
pnpm test:e2e               # E2E 测试（需先启动 dev server）
pnpm test:coverage          # 覆盖率报告

# 代码质量
pnpm lint                   # ESLint 检查
pnpm lint:fix              # 自动修复
pnpm typecheck              # TypeScript 类型检查
pnpm prettier               # 代码格式化

# 代码生成
pnpm generate:component     # 生成组件模板
pnpm generate:store         # 生成 Pinia Store 模板
pnpm generate:page          # 生成页面模板（含路由）


***

## 项目结构

    src/
    ├── api/                    # API 接口层
    │   ├── modules/            # 按模块划分（如 user、product、order）
    │   │   ├── user.ts         # 用户相关 API
    │   │   └── types.ts        # 模块专属类型
    │   ├── request.ts          # Axios 实例配置（拦截器、错误处理）
    │   └── index.ts            # API 统一导出
    │
    ├── components/
    │   ├── common/             # 通用业务组件
    │   ├── form/               # 表单组件
    │   └── charts/             # 图表组件（基于 ECharts）
    │
    ├── composables/            # Composables（Vue 3 组合式函数）
    │   ├── useTable.ts         # 表格数据加载逻辑
    │   ├── useForm.ts          # 表单提交逻辑
    │   ├── useDialog.ts        # 弹窗状态管理
    │   └── usePagination.ts    # 分页逻辑
    │
    ├── layouts/
    │   ├── DefaultLayout.vue   # 默认后台布局
    │   └── BlankLayout.vue     # 空白布局（如登录页）
    │
    ├── router/
    │   ├── index.ts            # 路由主文件
    │   ├── guards.ts           # 路由守卫（鉴权、权限）
    │   └── routes/
    │       ├── index.ts        # 静态路由
    │       └── dynamic.ts      # 动态路由（从后端获取）
    │
    ├── stores/                 # Pinia Stores
    │   ├── user.ts             # 用户信息、Token
    │   ├── permission.ts       # 路由权限、菜单
    │   └── settings.ts         # 系统设置
    │
    ├── types/                  # 全局类型定义
    │   ├── api.d.ts            # API 通用响应类型
    │   ├── page.d.ts           # 分页参数类型
    │   └── env.d.ts            # 环境变量类型
    │
    ├── utils/                  # 工具函数
    │   ├── storage.ts          # localStorage / sessionStorage 封装
    │   ├── format.ts           # 日期、数字格式化
    │   ├── validate.ts         # 表单验证规则
    │   └── error.ts            # 错误处理工具
    │
    └── views/                  # 页面视图（按路由组织）
        ├── dashboard/
        ├── system/
        └── login/

**关键文件说明**：

*   `src/api/request.ts` --- Axios 实例，含 Token 自动注入、401 处理、错误统一拦截
*   `src/composables/useTable.ts` --- 所有列表页的通用数据加载逻辑
*   `src/router/guards.ts` --- 路由守卫，未登录重定向、权限校验
*   `src/stores/permission.ts` --- 动态菜单和路由的权限控制

***

## 编码规范

### 文件命名

| 类型            | 规则                 | 示例                               |
| ------------- | ------------------ | -------------------------------- |
| Vue 组件        | PascalCase         | `UserList.vue`、`OrderDetail.vue` |
| TypeScript 文件 | camelCase          | `useTable.ts`、`formatDate.ts`    |
| SCSS 文件       | kebab-case         | `global.scss`、`variables.scss`   |
| API 模块        | camelCase（与后端模块对应） | `user.ts`、`orderManagement.ts`   |

### 组件规范

```vue
<!-- ✅ 正确：使用 <script setup> + 具名导出 -->
<script setup lang="ts">
import { ref, computed } from 'vue'
import type { UserItemProps } from './types'

// Props 使用 defineProps + 类型定义
const props = defineProps<UserItemProps>()

// Emits 使用 defineEmits
const emit = defineEmits<{
  edit: [id: string]
  delete: [id: string]
}>()
</script>

<!-- ✅ 正确：模板放在前面，样式放在最后 -->
<template>
  <div class="user-card">...</div>
</template>

<style scoped lang="scss">
.user-card {
  background: var(--el-bg-color);
}
</style>
```

### TypeScript 规范

```typescript
// ✅ 正确：所有函数参数和返回值有类型
function formatCurrency(amount: number): string {
  return `¥${(amount / 100).toFixed(2)}`
}

// ✅ 正确：使用 interface 定义对象类型
interface User {
  id: string
  name: string
  email: string
  roles: string[]
}

// ✅ 正确：API 响应类型统一管理
interface ApiResponse<T = unknown> {
  code: number
  message: string
  data: T
}

// ❌ 错误：禁止 any
function handleData(data: any) { ... }
```

***

## API 规范

### 请求封装（`src/api/request.ts`）

所有请求已封装：

*   **自动携带 Token**：从 `localStorage` 读取，注入 `Authorization` header
*   **自动处理 401**：跳转到登录页，清除 Token
*   **错误统一拦截**：Element Plus `ElMessage` 提示

### API 定义示例

```typescript
// src/api/modules/user.ts

import request from '../request'
import type {
  User,
  UserListParams,
  UserListResponse,
  CreateUserPayload,
  UpdateUserPayload
} from './types'

export const userApi = {
  list(params: UserListParams) {
    return request.get<UserListResponse>('/api/users', { params })
  },

  getById(id: string) {
    return request.get<User>(`/api/users/${id}`)
  },

  create(payload: CreateUserPayload) {
    return request.post<User>('/api/users', payload)
  },

  update(id: string, payload: UpdateUserPayload) {
    return request.put<User>(`/api/users/${id}`, payload)
  },

  delete(id: string) {
    return request.delete<void>(`/api/users/${id}`)
  }
}
```

### API 响应格式

```typescript
// 成功
{ "code": 200, "message": "success", "data": T }

// 分页响应
{ "code": 200, "message": "success", "data": { "list": [], "total": 100, "page": 1, "pageSize": 20 } }

// 错误
{ "code": 401, "message": "无权限访问" }
```

***

## 关键规则（禁止违反）

*   **NEVER** 将 `.env` 或 `.env.local` 提交到 Git（已配置 gitignore）
*   **NEVER** 在组件中直接操作 localStorage，使用 `src/utils/storage.ts` 封装
*   **NEVER** 在模板中使用未定义的响应式数据，会导致 TS 报错并影响性能
*   **IMPORTANT**：所有 `el-table` 必须指定 `row-key`，否则展开/选择等功能异常
*   **IMPORTANT**：删除操作前必须 `ElMessageBox.confirm` 确认
*   **IMPORTANT**：表单提交时使用 `v-loading` 防止重复提交

***

## Git 规范

### Commit 格式

    type(scope): description

    # type: feat | fix | docs | style | refactor | test | chore | perf
    # scope: view | component | api | store | router | composable

    # 示例
    feat(view): add user list search filter
    fix(component): repair table row selection bug
    docs(api): update user api documentation

### 分支命名

    feature/user-management     # 新功能
    fix/table-pagination-bug    # Bug 修复
    refactor/search-component   # 重构
    chore/update-dependencies   # 依赖更新
    docs/readme                 # 文档更新

***

## 踩坑记录（不要重复这些错误）

| 日期      | 问题                                     | 解决方案                                              |
| ------- | -------------------------------------- | ------------------------------------------------- |
| 2024-01 | `el-form` 的 `v-model` 绑定未定义的变量导致 TS 报错 | 始终先用 `reactive` 或 `ref` 定义表单对象                    |
| 2024-02 | `el-table` 未设置 `row-key` 导致选择状态错乱      | 所有 `el-table` 必须设置 `:row-key="row => row.id"`     |
| 2024-03 | `dayjs` 直接修改全局配置影响其他页面                 | 始终使用 `dayjs().format('YYYY-MM-DD')` 而非修改全局 locale |
| 2024-04 | 生产环境 Token 过期未刷新，用户被迫重新登录              | 已封装 401 自动跳转逻辑，不要修改 `request.ts`                  |
| 2024-05 | `v-for` 未加 `key` 导致列表渲染问题              | 始终添加 `:key="item.id"`，禁止使用 index 作为 key           |

***

## 配置分类参考

| 类别     | 适合放的内容                 |
| ------ | ---------------------- |
| 技术栈    | 明确版本号，包管理器             |
| 常用命令   | dev、build、test、lint    |
| 项目结构   | 目录划分、关键文件说明            |
| 编码规范   | 命名规则、组件规范、TS 规范        |
| API 规范 | 请求封装、响应格式、定义示例         |
| 关键规则   | NEVER / IMPORTANT 禁止事项 |
| Git 规范 | Commit 格式、分支命名、PR 要求   |
| 踩坑记录   | 历史问题 + 解决方案            |

***

## 常见问题

**Q: 咋知道配置生效了没？**
改完之后让 AI 做个简单的操作，比如问它"我配置的函数行数限制是多少"，能答上来就是生效了。

**Q: 多个配置冲突咋办？**
项目配置 > 全局配置，以项目目录下的为准。

***

有问题随时留言，看到必回。