CLAUDE.md — 全局配置文档

适用范围：全局（~/.claude/CLAUDE.md）
技术栈：Vue / UniApp / 微信小程序 / React / Node.js / Express / Koa / NestJS / MySQL / MongoDB / Figma / UI 设计
最后更新：2026-05

一、身份与工作上下文

我是一名以前端技术栈为核心的全栈开发者，工作内容涵盖：

• 前端：HTML / CSS / JavaScript / TypeScript，主框架为 Vue 3（Composition API），少量 React
• 跨端开发：UniApp、微信小程序（原生）
• 后端服务：Node.js，主要框架为 Express.js / Koa.js / NestJS
• 数据库：MySQL（关系型）、MongoDB（文档型）
• 产品设计：Figma UI/UX 交互设计、图片素材处理（压缩 / 裁切 / 格式转换）、设计规范维护

默认语言：中文交流，代码注释可视情况使用中文或英文。

二、核心行为准则（NON-NEGOTIABLE）

1. 优先阅读现有代码：修改前必须先理解现有代码结构和风格，不随意引入新的依赖或模式。
2. 最小化改动：只修改与任务直接相关的部分，不做"顺手"重构。
3. 类型安全优先：TypeScript 项目中，禁止使用 any，必须给出明确类型定义。
4. 不自作主张删除代码：有疑问时注释掉而非直接删除，并说明原因。
5. 执行破坏性操作前必须确认：数据库写入 / 删除、覆盖文件、生产环境操作，均须先向我确认。
6. 遇到不确定的问题，先说明再行动：不要静默地做出可能有副作用的假设。

三、技术规范

3.1 前端通用

- 组件文件使用 PascalCase（MyComponent.vue）
- 工具函数文件使用 camelCase（formatDate.ts）
- CSS 类名使用 kebab-case
- 优先使用 CSS 变量管理主题色和间距
- 图片资源：WebP 优先，SVG 用于图标
- 禁止内联样式（动态样式除外）

3.2 Vue 3 规范

- 统一使用 <script setup> + Composition API
- Props 必须定义类型，复杂类型使用 interface
- 响应式变量：简单值用 ref()，对象用 reactive()
- 异步操作统一使用 async/await，配合 try/catch
- 组件通信：父子用 props/emits，跨层级用 provide/inject 或 Pinia
- 状态管理：Pinia（不使用 Vuex）
- 路由：Vue Router 4
- 样式：scoped CSS 或 CSS Modules，避免全局污染

3.3 UniApp / 微信小程序

- UniApp 遵循 Vue 3 规范，注意平台差异用条件编译处理
- 微信小程序原生开发遵循官方最佳实践
- 图片资源尽量走 CDN，避免打包体积过大
- 避免频繁调用 setData，合并批量更新
- 网络请求统一封装，处理 loading 状态和错误

3.4 React（少量使用）

- 函数组件 + Hooks
- 状态管理：优先 useState/useReducer，复杂场景用 Zustand
- 样式：Tailwind CSS 或 CSS Modules

3.5 Node.js 后端

- 统一使用 async/await，禁止回调地狱
- 所有路由必须有错误处理中间件兜底
- 环境变量通过 .env 管理，禁止硬编码敏感信息
- 接口返回统一格式：{ code, data, message }
- 日志：使用 winston 或 pino，区分 info / warn / error 级别

Express / Koa

- 中间件按职责拆分：认证、校验、业务逻辑、错误处理
- 参数校验使用 joi 或 zod
- 路由按模块组织，统一注册

NestJS

- 遵循 Module / Controller / Service / Repository 四层架构
- DTO 使用 class-validator 装饰器校验
- 统一使用 Exception Filter 处理异常
- 依赖注入优先，避免手动实例化

3.6 数据库

MySQL

- ORM：Prisma 或 TypeORM（依项目而定）
- 所有查询必须防 SQL 注入（使用参数化查询）
- 大表操作前评估索引影响
- 事务性操作必须显式开启事务

MongoDB

- ODM：Mongoose
- Schema 必须定义，禁止完全动态文档
- 善用 lean() 提升只读查询性能
- 索引在 Schema 中声明

四、MCP 服务器配置

配置文件位置：~/.claude/settings.json 的 mcpServers 字段
命令行快速添加：claude mcp add <name> <command>

4.1 推荐 MCP 列表

4.2 Figma MCP 工作流说明

安装：claude plugin install figma@claude-plugins-official
用途：
  - 读取 Figma 文件的组件树、变量、自动布局、间距 Token
  - 直接生成 Vue / React 组件代码，与实际设计规范一致
  - 支持设计 Token 同步到代码库
典型命令：
  "读取当前 Figma 选中帧，生成对应的 Vue 3 组件，使用项目的设计 Token"

五、自定义 Skills

Skills 位置：~/.claude/skills/
每个 Skill 为独立目录，包含 SKILL.md 文件

5.1 vue-component（Vue 组件生成规范）

# ~/.claude/skills/vue-component/SKILL.md
生成符合项目规范的 Vue 3 组件时使用此 Skill。
要求：
- 使用 <script setup lang="ts">
- Props 用 defineProps<Interface>() 定义
- Emits 用 defineEmits<{...}>() 定义
- 样式用 <style scoped>，优先使用 CSS 变量
- 导出组件名与文件名保持一致

5.2 api-interface（接口封装规范）

# ~/.claude/skills/api-interface/SKILL.md
封装前端 API 请求模块时使用此 Skill。
要求：
- 基于 axios 封装，统一处理 token 注入、错误拦截、loading 状态
- 每个接口定义请求和响应的 TypeScript 类型
- 接口按业务模块分文件组织（user.ts / product.ts）
- 错误统一上报，支持自定义错误提示

5.3 nest-module（NestJS 模块脚手架）

# ~/.claude/skills/nest-module/SKILL.md
创建 NestJS 业务模块时使用此 Skill。
要求：
- 生成 module / controller / service / dto 四个文件
- DTO 使用 class-validator 校验装饰器
- Service 注入 Repository，不直接操作 ORM
- 控制器使用 @ApiTags / @ApiOperation 添加 Swagger 注释

5.4 db-schema（数据库 Schema 设计）

# ~/.claude/skills/db-schema/SKILL.md
设计数据库表结构时使用此 Skill。
要求：
- MySQL：给出建表 SQL + Prisma Schema 双版本
- MongoDB：给出 Mongoose Schema + TypeScript 接口定义
- 必须说明索引设计和原因
- 标注字段含义和约束

5.5 figma-to-code（设计稿转代码）

# ~/.claude/skills/figma-to-code/SKILL.md
将 Figma 设计稿转换为前端代码时使用此 Skill。
要求：
- 优先使用项目已有的组件库和 CSS 变量
- 间距、颜色、字体优先使用 Token，而非硬编码值
- 响应式：移动端优先，断点与项目保持一致
- 生成 Vue 组件时遵循 vue-component Skill 规范

六、自定义命令（Commands）

命令位置：~/.claude/commands/
使用方式：在对话中输入 /命令名

/new-vue-page

创建新的 Vue 页面模块，包含：
1. 页面组件文件（/views/XXX/index.vue）
2. 路由配置片段
3. 对应的 API 接口文件（/api/XXX.ts）
4. Pinia Store（如页面有复杂状态）
询问：页面名称、是否需要列表/详情/表单功能

/new-nest-api

创建 NestJS RESTful API 模块，包含：
1. Module / Controller / Service / DTO 文件
2. Swagger 文档注释
3. 基础 CRUD 方法框架
4. 错误处理
询问：模块名、使用 MySQL 还是 MongoDB、需要哪些接口

/db-design

根据业务描述，设计数据库结构：
1. ER 图描述（文字版）
2. MySQL 建表 SQL
3. Prisma Schema（如适用）
4. MongoDB Schema（如适用）
5. 索引建议

/review-code

对当前上下文代码进行代码审查，重点关注：
1. 类型安全（TS 规范）
2. 性能问题（不必要的渲染 / 查询 / 循环）
3. 安全漏洞（XSS / SQL 注入 / 敏感信息泄露）
4. 代码可维护性
5. Vue / Node.js 最佳实践

/optimize-image

给出图片素材处理方案：
1. 格式转换建议（JPG / PNG / WebP / SVG）
2. 压缩策略（有损 / 无损）
3. 尺寸裁切建议
4. 适合的 CLI 工具命令（sharp / imagemin / ffmpeg）
询问：使用场景（Web / 小程序 / App）、目标文件大小限制

/figma-export

基于 Figma 设计稿（通过 MCP 读取或粘贴设计描述），生成：
1. Vue 3 组件代码
2. 响应式适配说明
3. 设计 Token 映射表
4. 交互行为说明

/git-commit

分析当前改动，生成符合 Conventional Commits 规范的 commit message：
格式：<type>(<scope>): <subject>
类型：feat / fix / docs / style / refactor / perf / test / chore
语言：中文 subject 即可

/perf-check

对指定代码或页面进行性能分析：
1. 前端：包体积 / 渲染性能 / 网络请求优化
2. 后端：数据库查询 / 接口响应时间 / 内存占用
3. 小程序：setData 频率 / 包大小 / 首屏加载
给出具体优化建议和示例代码

七、Hooks 配置

Hooks 在 ~/.claude/settings.json 中配置
核心原则：CLAUDE.md 是建议性的，Hooks 是强制执行的

7.1 推荐 Hooks 配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] 即将执行 Bash 命令，请确认操作安全性'",
            "description": "执行 Bash 前提示"
          }
        ]
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/check-write-safety.js",
            "description": "写文件前检查是否在允许目录内"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/format-on-save.js",
            "description": "写文件后自动格式化（调用 prettier）"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 任务已完成\" with title \"Claude Code\"'",
            "description": "任务完成后发送系统通知（macOS）"
          }
        ]
      }
    ]
  }
}

7.2 Hook 脚本说明

~/.claude/hooks/check-write-safety.js

// 防止意外写入系统目录或 .env 文件
const input = JSON.parse(process.stdin.read() || '{}');
const path = input?.tool_input?.path || '';
const blocked = ['/etc/', '/usr/', '.env', 'node_modules/'];
if (blocked.some(b => path.includes(b))) {
  console.error(`[安全拦截] 禁止写入路径：${path}`);
  process.exit(2); // exit code 2 = 阻断操作
}

~/.claude/hooks/format-on-save.js

// 写入 .vue / .ts / .js 文件后自动运行 prettier
const input = JSON.parse(process.stdin.read() || '{}');
const path = input?.tool_input?.path || '';
if (/\.(vue|ts|js|jsx|tsx|css|scss)$/.test(path)) {
  require('child_process').execSync(`npx prettier --write "${path}"`, { stdio: 'inherit' });
}

八、子代理（Agents）配置

文件位置：~/.claude/agents/

8.1 frontend-reviewer（前端代码审查代理）

---
name: frontend-reviewer
description: 专注前端代码质量审查，涵盖 Vue3、TypeScript、性能和可访问性
tools: Read, Glob, Grep
model: sonnet
memory: user
---

你是一名资深前端工程师，专注于代码质量审查。
审查时重点关注：
1. TypeScript 类型完整性，是否有 any 或类型断言滥用
2. Vue 3 Composition API 使用是否规范
3. 组件职责是否单一，是否过度耦合
4. CSS 是否有潜在的样式污染
5. 是否有不必要的 re-render 风险
6. 可访问性（a11y）基础检查

给出具体行号和改进建议，附代码示例。

8.2 api-designer（接口设计代理）

---
name: api-designer
description: 设计 RESTful 或 GraphQL API 接口规范，兼顾前后端需求
tools: Read, Glob, WebSearch
model: sonnet
memory: user
---

你是一名全栈架构师，专注于 API 接口设计。
设计接口时：
1. 遵循 RESTful 规范，URI 语义清晰
2. 统一响应格式 { code, data, message, timestamp }
3. 考虑分页、过滤、排序的通用参数设计
4. 给出 TypeScript 类型定义（前后端共用）
5. 说明认证方式（JWT Bearer Token）
6. 列出可能的错误码和含义

同时考虑微信小程序端的特殊需求（如 wx.request 限制）。

8.3 db-optimizer（数据库优化代理）

---
name: db-optimizer
description: 分析和优化 MySQL / MongoDB 查询性能，给出索引和结构建议
tools: Read, Bash
model: sonnet
memory: user
---

你是一名数据库专家，专注于 MySQL 和 MongoDB 性能优化。
分析时：
1. 检查查询是否命中索引，给出 EXPLAIN 分析
2. 识别 N+1 查询问题
3. 建议合理的索引策略（避免过度索引）
4. MongoDB：检查 aggregation pipeline 效率
5. 提供优化前后的对比查询示例
6. 评估数据量增长后的性能趋势

8.4 miniprogram-advisor（小程序专项代理）

---
name: miniprogram-advisor
description: 微信小程序和 UniApp 跨端开发专家，熟悉平台限制和优化策略
tools: Read, Glob, WebSearch
model: sonnet
---

你是微信小程序和 UniApp 开发专家。
提供建议时：
1. 注意微信小程序的包大小限制（主包 2MB，分包总计 20MB）
2. setData 调用优化，避免频繁大数据量更新
3. 生命周期差异提醒（Page vs Component vs App）
4. 条件编译语法（UniApp #ifdef MP-WEIXIN）
5. 小程序登录流程（wx.login + 后端换取 openid）
6. 性能指标：FCP、LCP 在小程序中的对应优化点

九、参考文档（Docs）

使用 @ 在对话中引用，或配置为常驻上下文

常用文档快捷引用

# 在对话中使用 @ 引用本地文档
@~/.claude/docs/api-conventions.md      # 接口规范
@~/.claude/docs/design-tokens.md        # 设计 Token 规范
@~/.claude/docs/git-workflow.md         # Git 工作流规范
@~/.claude/docs/deploy-checklist.md     # 上线前检查清单

9.1 ~/.claude/docs/api-conventions.md 模板

# 接口规范

## 请求规范
- 基础 URL：通过环境变量 VITE_API_BASE_URL 配置
- 认证：Header Authorization: Bearer <token>
- 内容类型：application/json

## 响应格式
{
  "code": 0,          // 0 = 成功，非 0 = 业务错误
  "data": {},         // 业务数据
  "message": "ok",   // 提示信息
  "timestamp": 1234567890
}

## 分页参数
GET /api/list?page=1&pageSize=20&sort=createdAt&order=desc

## 错误码规范
1000: 参数错误
1001: 未授权
1002: 权限不足
1003: 资源不存在
5000: 服务器内部错误

9.2 推荐外部文档（联网查询时优先参考）

Vue 3 官方文档：    https://cn.vuejs.org/
UniApp 文档：       https://uniapp.dcloud.net.cn/
微信小程序文档：    https://developers.weixin.qq.com/miniprogram/dev/framework/
NestJS 文档：       https://docs.nestjs.com/
Prisma 文档：       https://www.prisma.io/docs/
Mongoose 文档：     https://mongoosejs.com/docs/
Pinia 文档：        https://pinia.vuejs.org/zh/

十、Settings 配置

全局 ~/.claude/settings.json 推荐配置

{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "autoCompact": true,
  "compactInstructions": "保留：技术栈信息、当前任务上下文、未完成的 TODO、关键的架构决策。丢弃：已完成的探索性讨论、重复的代码输出。",
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(git:*)",
      "Bash(node:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(mkdir:*)",
      "Bash(cp:*)",
      "Bash(mv:*)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo:*)",
      "Bash(chmod 777:*)"
    ]
  },
  "env": {
    "CLAUDE_COMPACT_THRESHOLD": "0.85"
  }
}

十一、项目级配置说明

以下为各类项目的 .claude/CLAUDE.md 建议补充内容（放在项目根目录）

Vue 项目

## 项目特定配置
- 包管理器：pnpm
- 组件库：Element Plus / Vant（具体以 package.json 为准）
- 样式方案：SCSS + CSS 变量
- 测试：Vitest + Vue Test Utils
- 构建：Vite
- 代码规范：ESLint + Prettier（配置见根目录）

NestJS 项目

## 项目特定配置
- ORM：Prisma（MySQL）/ Mongoose（MongoDB）
- 认证：JWT + Passport
- 文档：Swagger（/api-docs）
- 测试：Jest
- 部署：Docker + docker-compose
- 环境变量：.env.development / .env.production

UniApp / 小程序项目

## 项目特定配置
- 目标平台：H5 + 微信小程序（主要）
- 组件库：uni-ui / uView
- 网络请求：封装 uni.request，路径 /utils/request.js
- 状态管理：Pinia（小程序端兼容版本）
- 图片 CDN：[填写 CDN 地址]
- AppID：[填写小程序 AppID]

十二、常见工作流提示词模板

高频任务的提示词参考，可直接复用

从 Figma 生成组件

使用 Figma MCP 读取当前选中的 [组件名] 帧，
生成 Vue 3 组件，要求：
- 使用项目 design-tokens.md 中定义的 Token
- 移动端优先，兼容 375px ~ 1920px
- 提取为独立组件，Props 设计合理
- 添加必要的 TypeScript 类型

新建后端接口

为 [业务名称] 创建 NestJS 接口模块，包含：
- GET /api/[resource]（列表，支持分页和过滤）
- GET /api/[resource]/:id（详情）
- POST /api/[resource]（创建）
- PUT /api/[resource]/:id（更新）
- DELETE /api/[resource]/:id（软删除）
使用 MySQL + Prisma，DTO 加校验，Controller 加 Swagger 注释

排查线上问题

通过 Sentry MCP 拉取最近的错误：
错误 ID / 关键词：[填写]
结合代码分析根本原因，给出修复方案和预防措施

十三、Compact 指令

当上下文压缩时，Claude 应优先保留以下信息：

IMPORTANT - 压缩时必须保留：

1. 当前任务的目标和进度
2. 已确认的技术选型（框架、库版本）
3. 未完成的 TODO 列表
4. 关键的架构决策和原因
5. 数据库 Schema 或接口定义（如已讨论）

可以丢弃：

• 已完成功能的详细实现讨论
• 重复输出的完整代码块（保留文件路径即可）
• 探索性的方案对比（已选定方案后）

此文件由 Claude Code 全局加载，适用于所有项目。项目特定配置请在各项目根目录的 .claude/CLAUDE.md 中补充。