Claude.md 是 Claude Code 的配置文件，放在项目里就能让 AI 记住你的规矩、团队的约定、项目的上下文。配置一次，永久生效。
快速开始
在你项目根目录创建 .claude/CLAUDE.md 文件：
bash
mkdir -p .claude
touch .claude/CLAUDE.mdClaude 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: 多个配置冲突咋办？**
项目配置 > 全局配置，以项目目录下的为准。
***有问题随时留言，看到必回。