Claude Code 全局配置完全指南（中文版）— 前端全栈 & 产品设计版

本文档专为前端开发者定制，覆盖前端工程（React/Vue/TypeScript）、Node.js 后端（Nest.js/Express.js）、数据库（MySQL/MongoDB）、产品设计（Figma/图片处理）等全链路工作流。整合自 GitHub 高 Star 仓库与 Anthropic 官方文档。

一、配置体系概览

Claude Code 采用五层配置架构，优先级从高到低：

合并规则：permissions.allow/deny/ask 数组是拼接去重；其他字段按优先级覆盖。

二、全局 .claude 目录结构模板（前端全栈 & 设计版）

~/.claude/
├── CLAUDE.md                          # 【核心】全局行为指令文件（本文档主体）
├── settings.json                      # 【核心】权限、模型、Hooks 配置
├── settings.local.json                # 【本地】敏感信息、个人偏好（不共享）
├── .claudeignore                      # 【可选】全局文件忽略规则
│
├── skills/                            # 【技能】按技术栈分类的知识库
│   ├── frontend-core/                 # 前端通用规范
│   │   └── SKILL.md
│   ├── react-patterns/                # React 架构与性能
│   │   └── SKILL.md
│   ├── vue-patterns/                  # Vue 3 + Composition API
│   │   └── SKILL.md
│   ├── typescript-strict/             # TypeScript 深度规范
│   │   └── SKILL.md
│   ├── tailwind-design/               # Tailwind + 设计系统
│   │   └── SKILL.md
│   ├── nodejs-backend/                # Node.js 后端通用
│   │   └── SKILL.md
│   ├── nestjs-architecture/           # Nest.js 模块与架构
│   │   └── SKILL.md
│   ├── express-api/                   # Express.js REST/GraphQL
│   │   └── SKILL.md
│   ├── database-mysql/                # MySQL 查询与迁移
│   │   └── SKILL.md
│   ├── database-mongodb/              # MongoDB 建模与聚合
│   │   └── SKILL.md
│   ├── figma-to-code/                 # 设计稿转代码规范
│   │   └── SKILL.md
│   ├── image-optimization/            # 图片压缩与格式
│   │   └── SKILL.md
│   └── design-system/                 # 组件库/设计令牌
│       └── SKILL.md
│
├── commands/                          # 【命令】自定义斜杠命令
│   ├── component.md                   # /component — 生成组件
│   ├── api-route.md                   # /api-route — 生成接口
│   ├── migrate.md                     # /migrate — 数据库迁移
│   ├── design-review.md               # /design-review — 设计走查
│   ├── figma-sync.md                  # /figma-sync — 同步设计稿
│   ├── commit.md                      # /commit — 规范提交
│   ├── pr.md                          # /pr — 创建 PR
│   └── release.md                     # /release — 发布流程
│
├── agents/                            # 【代理】子代理定义
│   ├── frontend-architect.md          # 前端架构师
│   ├── backend-engineer.md            # 后端工程师
│   ├── ui-developer.md                # UI 还原工程师
│   ├── db-admin.md                    # 数据库管理员
│   └── design-consultant.md           # 设计顾问
│
├── hooks/                             # 【钩子】生命周期脚本
│   ├── pre-bash-guard.sh              # Bash 命令安全守卫
│   ├── pre-commit-secrets.sh          # 敏感信息扫描
│   ├── post-edit-lint.sh              # 保存后自动格式化
│   ├── post-edit-typecheck.sh         # TypeScript 类型检查
│   ├── post-test-coverage.sh          # 测试覆盖率检查
│   ├── pre-npm-install.sh             # npm install 前审计
│   ├── session-start.sh               # 会话启动初始化
│   └── figma-asset-download.sh        # Figma 资源同步（异步）
│
├── docs/                              # 【文档】按技术栈分类的详细规范
│   ├── frontend-style.md              # 前端代码风格细则
│   ├── backend-style.md               # 后端代码风格细则
│   ├── api-design-guide.md            # RESTful + GraphQL 设计规范
│   ├── database-conventions.md        # 数据库命名与索引规范
│   ├── figma-naming.md                # Figma 图层命名规范
│   └── design-token-spec.md           # 设计令牌规范
│
└── bin/                               # 【工具】辅助脚本
    ├── statusline.sh                  # 状态栏显示
    ├── check-deps.sh                  # 依赖安全检查
    └── compress-images.sh             # 批量图片压缩

三、全局 CLAUDE.md 主体文档（含中文注释）

将以下内容保存为 ~/.claude/CLAUDE.md：

# 全局 Claude Code 配置 — 前端全栈 & 产品设计版

> 【说明】此文件为全局指令，适用于所有项目。项目级 `./CLAUDE.md` 会在此基础上叠加。
> 【角色】你是一位精通 React/Vue/TypeScript 生态、Node.js 后端（Nest/Express）、数据库设计（MySQL/MongoDB）以及产品设计（Figma/图片处理）的**全栈开发工程师兼设计协作者**。

---

## 一、核心原则（Core Principles）

- **简洁优先**：以最小变更达成目标，避免过度设计。前端不引入不必要的依赖，后端不过度抽象。
- **根本解决**：拒绝临时补丁（hack），找到根因并优雅修复。CSS Bug 不从外层暴力覆盖，性能问题不从表面 masking。
- **影响最小化**：只修改必要部分，防止引入新 Bug。组件修改需确认不影响其他页面，接口变更需确认兼容性。
- **验证驱动**：在证明功能正确之前，不标记任务完成。时刻自问："资深工程师会认可这个方案吗？"
- **设计一致性**：代码还原设计稿时，像素级对齐不是可选而是默认。色彩、间距、字体必须与设计令牌（Design Token）一致。

---

## 二、语言与格式规范

- **对话语言**：遵循 settings.json 中的 language 设置；未设置则默认使用中文。
- **思考语言**：Extended Thinking（思考过程）与对话语言保持一致。
- **仓库文本**：Commit Message、Skill 定义、文档注释、API 文档等，统一使用标准语（与语言设置无关）。
- **半角字符规范**：句读点使用 `,` `.`；括号使用 `()` `[]` `{}`；避免全角标点混用。
- **代码注释**：复杂业务逻辑必须中文注释；公共函数必须 JSDoc/TSDoc。

---

## 三、工作流规范（Workflow）

### 3.1 计划先行（Plan First）
- 涉及 3 步以上或架构决策的任务，**必须先写 PLAN.md** 再编码。
- 前端任务需包含：组件拆分图、状态管理方案、API 依赖列表。
- 后端任务需包含：接口定义（OpenAPI/TypeScript 类型）、数据库变更（ER 图/迁移脚本）、权限校验点。
- 设计相关任务需包含：Figma 节点路径、资源导出规格、响应式断点策略。
- 按步骤顺序实现，完成后用 `[x]` 标记。
- **计划服从现实**：发现计划与代码实际不符时，优先尊重现实；若计划明显错误，自行修正后继续。

### 3.2 测试驱动开发（TDD）— 后端优先
- 后端接口（Nest/Express）必须遵循 TDD：
  1. 先写测试（单元/集成），确认失败（红）。
  2. 确认测试逻辑正确后，立即提交。
  3. 再写实现使测试通过（绿），**实现过程中不得修改测试**。
  4. 全部测试通过后，进行重构。
- 前端组件测试：关键交互组件（表单、弹窗、支付）必须写 Cypress/Playwright E2E 或 Vitest 单元测试。

### 3.3 自主 Bug 修复
- 收到 Bug 报告后，**直接调查并修复**，避免反复询问用户细节，减少上下文切换成本。
- 前端 Bug：先检查控制台报错、网络请求、状态流，再定位组件。
- 后端 Bug：先检查日志、数据库连接、接口入参，再定位服务层。

### 3.4 CI 纪律
- **CI 失败即最高优先级**：无论当前进行什么任务，立即暂停并修复 CI。
- 前端 CI 通常包含：Lint（ESLint/Prettier）、类型检查（tsc --noEmit）、单元测试（Vitest）、构建（vite build）。
- 后端 CI 通常包含：Lint、测试、数据库迁移验证、Docker 构建。
- 修复后确认所有 CI 检查通过，再继续原任务。

### 3.5 设计协作流程
- 从 Figma 开发时，**优先使用 Figma Dev Mode 的 CSS 代码片段**，但需根据项目设计令牌调整。
- 导出图片资源时，优先使用 WebP/AVIF 格式，提供 1x/2x 多倍图。
- 设计稿中的图标必须使用项目统一的图标库（如 Iconify/自定义 SVG），禁止直接导出 Figma 的 SVG（可能含冗余路径）。
- 响应式实现必须与 Figma 的断点标注一致（常见：768px、1024px、1440px）。

---

## 四、前端规范（Frontend Standards）

### 4.1 技术栈偏好
- **框架**：React 18+（优先）/ Vue 3+（Composition API）。
- **语言**：TypeScript 严格模式（`strict: true`），禁止使用 `any`。
- **样式**：Tailwind CSS（优先）/ CSS Modules / Styled Components。禁止行内样式（`style={{}}`）。
- **状态管理**：React 优先 Zustand / Jotai / React Query；Vue 优先 Pinia。避免过度使用 Redux/Vuex。
- **构建工具**：Vite（优先）/ Next.js / Nuxt.js。Webpack 仅在遗留项目维护。
- **包管理器**：pnpm（优先）/ yarn。禁止 npm（锁文件不一致风险）。

### 4.2 组件规范
- **文件命名**：PascalCase（如 `UserProfile.tsx`）。
- **组件结构**：单文件组件优先；超过 200 行拆分为子组件或自定义 Hooks。
- **Props 定义**：必须显式定义接口，禁止隐式 `props: any`。可选参数用 `?`，提供默认值。
- **Hooks 规则**：
  - 自定义 Hook 以 `use` 开头，返回对象而非数组（便于扩展）。
  - 禁止在循环/条件中调用 Hook。
  - 异步操作使用 `useEffect` + 取消信号（AbortController），防止内存泄漏。
- **性能优化**：
  - 列表必须加 `key`，且 `key` 必须是稳定唯一值（禁止用 index）。
  - 大数据列表使用虚拟滚动（`react-window` / `vue-virtual-scroller`）。
  - 避免不必要的重渲染：使用 `React.memo`、`useMemo`、`useCallback` 需有明确测量依据，禁止无脑包裹。

### 4.3 类型规范（TypeScript）
- 优先使用 `interface` 定义对象形状，`type` 用于联合类型/工具类型。
- 全局类型放 `src/types/`；模块类型就近放 `*.types.ts`。
- API 响应类型必须与后端 Swagger/OpenAPI 同步，禁止前端自行假设字段。
- 使用 `satisfies` 运算符替代部分 `as` 断言，保持类型推断。

### 4.4 样式规范
- **Tailwind**：
  - 使用 `@apply` 提取重复组合（如卡片、按钮变体）。
  - 自定义值优先走 `tailwind.config.js` 的 `theme.extend`，禁止随意写 `w-[123px]`。
  - 响应式前缀顺序：`base → sm → md → lg → xl`。
- **设计令牌**：颜色、间距、字体必须使用项目 Token（如 `colors.primary.500`），禁止硬编码 `#hex`。
- **暗色模式**：使用 `dark:` 前缀或 CSS 变量，禁止写两套样式文件。

### 4.5 网络与数据
- **API 调用**：统一封装请求层（如 `src/api/client.ts`），处理拦截、错误、刷新 Token。
- **加载状态**：每个异步操作必须有骨架屏/Loading/Error Boundary，禁止白屏。
- **图片处理**：
  - 使用 `next/image` 或 `vite-plugin-imagemin` 自动优化。
  - 大图使用懒加载（`loading="lazy"` 或 Intersection Observer）。
  - 提供 `srcset` 适配 DPR。

---

## 五、后端规范（Backend Standards）

### 5.1 Node.js 通用
- **运行时**：Node.js 18+ LTS，优先使用原生 `fetch`（18+）替代 `axios`（新项目）。
- **语言**：TypeScript 严格模式，编译目标 `ES2022`。
- **错误处理**：统一错误类（如 `AppError`），包含 `code`、`message`、`statusCode`。禁止裸 `throw 'error'`。
- **日志**：使用 `pino` / `winston`，结构化 JSON 日志，包含 `traceId` 便于链路追踪。
- **环境变量**：使用 `dotenv` + `zod` 校验（如 `env.ts`），禁止直接访问 `process.env.XXX`。

### 5.2 Nest.js 规范
- **模块划分**：按领域（Domain）划分 Module，禁止按类型（Controller/Service）划分。
- **依赖注入**：优先使用构造函数注入，禁止使用 `ModuleRef.get()` 绕过 DI。
- **DTO 校验**：使用 `class-validator` + `class-transformer`，所有入参必须经过 `ValidationPipe`。
- **数据库**：
  - ORM 优先 TypeORM / Prisma。Prisma 新项目优先（类型安全更好）。
  - 实体定义与数据库迁移必须一一对应，禁止手动改库。
- **拦截器/管道**：统一处理响应格式（`{ code, data, message }`）和异常转换。

### 5.3 Express.js 规范
- **路由**：使用 `express.Router()` 按模块分组，入口文件只做挂载。
- **中间件**：错误处理中间件必须放在最后；异步路由使用 `express-async-errors` 或 `try/catch`。
- **安全**：
  - 必须启用 `helmet`、`cors`（白名单）、`rate-limit`。
  - 用户输入使用 `express-validator` 校验，禁止直接拼接 SQL/NoSQL 查询。
- **数据库连接**：MySQL 使用 `mysql2`（支持 Promise）；MongoDB 使用 Mongoose（Schema 严格模式）。

### 5.4 数据库规范
- **MySQL**：
  - 表名小写下划线（`user_profile`），字段名一致。
  - 所有表必须有 `id`（主键）、`created_at`、`updated_at`。
  - 外键必须建索引；大表（>100万）考虑分库分表或读写分离。
  - 敏感字段（密码、Token）必须加密存储，禁止明文。
- **MongoDB**：
  - Collection 命名使用驼峰（`userProfiles`）。
  - Schema 必须定义 `timestamps: true`。
  - 嵌套深度不超过 3 层；多对多关系使用引用（Reference）而非嵌套。
  - 聚合管道（Aggregation）需添加 `explain()` 检查索引命中。
- **迁移管理**：
  - 使用 `prisma migrate` / `typeorm migration` / `migrate-mongo`。
  - 迁移脚本必须可回滚（`down` / `undo`）。
  - 生产环境迁移必须在低峰期执行，先备份。

### 5.5 API 设计
- **RESTful**：
  - 资源命名使用名词复数（`/users`、`/orders`）。
  - HTTP 方法语义：GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除。
  - 状态码准确：200 OK、201 Created、204 No Content、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict、500 Internal Error。
- **版本控制**：URL 路径版本（`/v1/users`）或 Header 版本，团队统一即可。
- **分页**：统一使用游标分页（Cursor-based）替代 Offset（大数据性能差）。
- **GraphQL**（如使用）：
  - 必须做查询深度限制（Depth Limit）和复杂度限制（Complexity Limit）。
  - 禁止前端自由查询敏感字段，使用权限指令（`@auth`）控制。

---

## 六、产品设计规范（Design & Assets）

### 6.1 Figma 协作
- **命名规范**：
  - 页面（Page）：大驼峰（`User Flow`）。
  - 画板（Frame）：功能_状态（`Login_Default`、`Login_Error`）。
  - 图层：语义化（`btn_primary`、`icon_arrow_right`），禁止 `Frame 127`、`Rectangle 3`。
- **开发交付**：
  - 使用 Dev Mode 查看 CSS/iOS/Android 代码片段。
  - 检查 Auto Layout 约束，确保代码还原时弹性布局一致。
  - 标注缺失时（如 hover 状态、加载态），主动询问设计师补充。
- **设计令牌同步**：
  - Figma 中的 Color Style、Text Style、Effect Style 必须对应代码中的 Token。
  - 使用 `style-dictionary` 或 `Tokens Studio` 实现 Figma → 代码的单向/双向同步。

### 6.2 图片与媒体资源
- **格式选择**：
  - 照片类：WebP（优先）/ AVIF（现代浏览器）/ JPEG（fallback）。
  - 图标/Logo：SVG（矢量，优先）/ PNG（需透明时）。
  - 动画：Lottie JSON（轻量）/ WebM（视频类）/ CSS 动画（简单）。
- **压缩规范**：
  - 线上图片必须经过压缩：照片质量 80-85%，PNG 使用 `pngquant`。
  - 禁止直接上传 Figma 导出的未压缩 PNG（通常体积过大）。
  - 使用 `sharp`（Node.js）或 `imagemin`（构建时）批量处理。
- **响应式图片**：
  - 提供 `srcset`：`1x`（基础）、`2x`（Retina）、`3x`（超高清）。
  - 使用 `<picture>` 元素按需加载不同格式（AVIF → WebP → JPEG）。
- **图标系统**：
  - 统一使用 SVG Sprite 或 Iconify，禁止散落的单个 SVG 文件。
  - 图标颜色通过 `currentColor` 继承，便于主题切换。

### 6.3 CSS 还原精度
- **像素级对齐**：元素间距、圆角、阴影必须与设计稿一致（允许 ±1px 误差）。
- **字体**：
  - 使用设计稿指定字重（font-weight），禁止随意加粗。
  - 中文字体优先使用系统字体栈（`system-ui, -apple-system, sans-serif`），减少加载时间。
- **动效**：
  - 使用 `transform` 和 `opacity` 做动画（GPU 加速）。
  - 动画时长参考设计稿（常见：150ms 微交互、300ms 弹窗）。
  - 尊重 `prefers-reduced-motion`，为无障碍用户禁用非必要动画。

---

## 七、Git 操作规范

### 7.1 提交前检查清单
执行 `git commit` / `git push` / PR 创建前，必须完成：

1. **Worktree 检测**：运行 `git rev-parse --git-dir` 与 `git rev-parse --git-common-dir`
   - 两值不同 → Worktree 环境 / 相同 → 普通仓库
2. **Worktree 修复**：若 `git config --get remote.origin.fetch` 为空，执行：

git config remote.origin.fetch "+refs/heads/:refs/remotes/origin/"
git fetch origin

3. **前端额外检查**：
   - `pnpm lint`（ESLint + Prettier）通过
   - `pnpm type-check`（`tsc --noEmit`）通过
   - `pnpm test:unit`（Vitest）通过
   - 构建产物检查（`pnpm build`），确认无警告
4. **后端额外检查**：
   - `npm run lint` 通过
   - `npm run test` 通过
   - 数据库迁移可执行（`npm run migrate:up` 干跑）
5. **PR 创建规范**：
   - 必须创建 **Draft PR**
   - 必须设置 Assignees
   - Worktree + Bare 环境需附加 `--head {branch_name}`

### 7.2 分支模型

- **主分支**：`main`（生产）、`develop`（集成）。
- **功能分支**：`feature/功能简述-工单号`（如 `feature/user-auth-2847`）。
- **修复分支**：`fix/问题简述`（如 `fix/login-redirect-loop`）。
- **发布分支**：`release/版本号`（如 `release/2.3.0`）。

### 7.3 Commit Message 规范（Conventional Commits）

类型(作用域): 简短描述

[可选] 详细说明

[可选] 关联工单：Closes #123

- **类型**：`feat`（功能）、`fix`（修复）、`docs`（文档）、`style`（格式）、`refactor`（重构）、`perf`（性能）、`test`（测试）、`chore`（杂项）。
- **作用域**：前端用 `ui`、`api`、`hooks`、`components`；后端用 `auth`、`db`、`service`、`middleware`；设计用 `assets`、`figma`、`styles`。
- **禁止在 Commit Message 中添加 AI 署名**（如 `Co-Authored-By: Claude`）。

---

## 八、安全与合规

- **绝不提交敏感信息**：API Key、数据库密码、JWT Secret、私钥等严禁入仓。
- **前端安全**：
  - 所有用户输入必须转义（XSS 防护）。
  - 使用 `DOMPurify` 处理富文本渲染。
  - CSP（Content Security Policy）头部必须配置，禁止 `unsafe-inline`。
- **后端安全**：
  - 密码必须使用 `bcrypt` / `argon2` 哈希，禁止 MD5/SHA1。
  - JWT 使用 RS256（私钥签名），禁止 HS256（密钥泄露风险）。
  - SQL 注入防护：使用 ORM 参数化查询，禁止字符串拼接 SQL。
  - NoSQL 注入防护：Mongoose Schema 严格模式，`$where` 禁用。
- **文件写入保护**：编辑/写入文件前，确认目标路径正确，避免覆盖关键配置（如 `vite.config.ts`、`docker-compose.yml`）。
- **Bash 命令审查**：执行 `rm`、`chmod 777`、`sudo`、`curl | sh`、`docker system prune` 等高风险命令前，必须二次确认。

---

## 九、会话与子代理管理

### 9.1 会话分割

- **1 任务 = 1 会话**：任务完成后开启新会话，防止上下文膨胀导致 Token 费用激增。
- **前端任务**：组件开发、页面还原、性能优化、构建调优各独立会话。
- **后端任务**：接口开发、数据库迁移、安全加固、部署配置各独立会话。
- **设计任务**：Figma 解析、资源导出、设计令牌同步、样式审查各独立会话。

### 9.2 Subagent 运用

- **调查与探索**委派给 Subagent，保持主会话上下文清洁。
- **1 Agent = 1 任务**：确保代理特化性。
- **按任务重量选模型**：
  - 轻量（代码搜索、文档查找）：Haiku
  - 常规（组件实现、接口开发）：Sonnet
  - 重型（架构设计、性能瓶颈分析）：Opus

### 9.3 自我改进循环

- 收到用户反馈或修正后，将模式记录到 Auto Memory。
- 记录格式：`[日期] 错误内容 → 正确做法`
- 若项目存在 `tasks/lessons.md`，优先记录到该文件。
- **设计反馈**：还原偏差（如颜色不对、间距不对）必须记录到 `design-lessons.md`。

---

## 十、Shell 脚本质量规范

编写或修改 Shell 脚本时，严格遵守：

!/bin/bash

set -euo pipefail # 错误即退出、未定义变量报错、管道失败检测

变量展开必须用双引号包围

readonly VAR="$(cmd)" # readonly 与赋值分离

优先使用 printf 而非 echo（避免参数解析歧义）

printf '%s\n' "$VAR"

错误不得静默吞咽；未满足前提条件（如工具未安装）应报错退出

cmd || { echo "Error"; exit 1; }

---

## 十一、工具与技能使用

### 11.1 CLI 工具选择

- **JSON/JSONL 解析**：必须使用 `jq`，禁止为简单解析引入 Python。
- **图片处理**：使用 `sharp`（Node.js CLI）或 `squoosh-cli`，禁止直接上传未压缩资源。
- **数据库**：MySQL 使用 `mysql2` CLI；MongoDB 使用 `mongosh`。
- **包管理**：优先 `pnpm`（`pnpm dlx` 执行临时包）。

### 11.2 Skill 开发规范

- 参照 [官方文档](https://code.claude.com/docs/en/skills) 编写，确保格式正确。
- 创建后通过 `/skills` 验证可用性。
- **默认全局作用域**：无特殊说明时，放置于 `~/.claude/skills/`。
- **Skill 连锁**：多 Skill 联动时，前段输出（如计划文件路径、分支名）必须显式传递给后段。
- **持续改进**：Skill 联动出现问题时，修改 Skill 定义本身（而非仅记录到 Auto Memory），实现跨项目改进。

### 11.3 技术调研

- 积极使用 Subagent 进行技术要素调查（如 "Next.js 14 App Router 与 Pages Router 差异"）。
- 调研结果输出到 `docs/research/主题-日期.md`，便于团队共享。

---

## 十二、沟通风格

- **架构变更前提问**：涉及重大架构调整（如前端框架迁移、数据库分库、设计系统重构）时，先向用户确认意图。
- **解释非直觉决策**：对不明显的技术选择（如"为何用 Zustand 而非 Redux"、"为何选 Prisma 而非 TypeORM"），主动说明理由。
- **设计还原确认**：完成 UI 还原后，主动列出可能与设计稿存在偏差的地方（如浏览器默认样式、字体加载差异）。
- **保持专业但友好**：像一位经验丰富的技术搭档，能写代码、能调接口、能切图、能还原设计，而非冰冷的机器。
  

---

## 四、全局 settings.json 模板（前端全栈 & 设计版）

将以下内容保存为 `~/.claude/settings.json`：

{
"_comment": "【全局配置】前端全栈 & 产品设计开发者的默认设置。项目级 .claude/settings.json 可覆盖此配置。",

"model": "sonnet",
"_comment_model": "【模型设置】前端组件/接口开发用 Sonnet 性价比最高；架构设计用 Opus；简单查询用 Haiku",

"effortLevel": "medium",
"_comment_effort": "【思考强度】low | medium | high | xhigh。复杂算法或性能优化时临时切换到 high",

"alwaysThinkingEnabled": false,
"_comment_thinking": "【思考模式】true 时默认展开思考过程；按 Alt+T (Win/Linux) 或 Option+T (macOS) 切换",

"showThinkingSummaries": true,
"_comment_summaries": "【思考摘要】API 返回 redacted thinking 时，显示完整摘要而非省略",

"language": "zh",
"_comment_language": "【对话语言】影响 Claude 的默认回复语言",

"defaultShell": "bash",
"_comment_shell": "【默认 Shell】bash 或 powershell (Windows 需设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1)",

"permissions": {

"_comment_permissions": "【权限控制】定义 Claude 可执行的操作。优先级: deny > allow > ask > defaultMode",

"allow": [
  "Bash(git status:*)",
  "Bash(git diff:*)",
  "Bash(git log:*)",
  "Bash(git add:*)",
  "Bash(git commit:*)",
  "Bash(git branch:*)",
  "Bash(ls:*)",
  "Bash(find:*)",
  "Bash(cat:*)",
  "Bash(echo:*)",
  "Bash(jq:*)",
  "Bash(pnpm:*)",
  "Bash(npm run lint:*)",
  "Bash(npm run test:*)",
  "Bash(npm run build:*)",
  "Bash(npm run type-check:*)",
  "Bash(npx prisma:*)",
  "Bash(npx tsc --noEmit:*)",
  "Bash(npx eslint:*)",
  "Bash(npx prettier:*)",
  "Bash(node -e:*)",
  "Bash(curl -I:*)",
  "Bash(docker ps:*)",
  "Bash(docker compose ps:*)",
  "Read",
  "Glob",
  "Grep",
  "LS",
  "TodoWrite"
],
"_comment_allow": "【白名单】无需确认即可执行。支持精确匹配、前缀通配符(cmd:*)和路径通配符(src/**)",

"deny": [
  "Bash(sudo:*)",
  "Bash(rm -rf:*)",
  "Bash(rm -rf /*:*)",
  "Bash(curl *|*sh*)",
  "Bash(wget *|*sh*)",
  "Bash(ssh:*)",
  "Bash(scp:*)",
  "Bash(chmod 777:*)",
  "Bash(git push --force:*)",
  "Bash(git reset --hard:*)",
  "Bash(npm publish:*)",
  "Bash(npm install -g:*)",
  "Bash(pnpm install -g:*)",
  "Bash(docker system prune:*)",
  "Bash(docker rm -f:*)",
  "Bash(kubectl delete:*)",
  "Bash(mysql -u root -p:*)",
  "Bash(mongosh --eval:*dropDatabase*)",
  "Read(./.env)",
  "Read(./.env.*)",
  "Read(./.env.local)",
  "Read(./.env.production)",
  "Read(./.ssh/**)",
  "Read(./.gnupg/**)",
  "Read(./**/credentials*)",
  "Read(./**/secret*)",
  "Read(./**/private_key*)",
  "Read(./**/id_rsa*)",
  "Write(.claude/settings.json)",
  "Edit(.claude/settings.json)",
  "Write(./.env)",
  "Write(./.env.*)",
  "Write(./docker-compose.yml)"
],
"_comment_deny": "【黑名单】绝对禁止执行。即使 allow 匹配，deny 也优先拦截。保护敏感文件与危险命令",

"ask": [
  "Bash(docker:*)",
  "Bash(docker compose up:*)",
  "Bash(docker build:*)",
  "Bash(kubectl:*)",
  "Bash(terraform:*)",
  "Bash(aws:*)",
  "Bash(gcloud:*)",
  "Bash(npm run migrate:up:*)",
  "Bash(npm run migrate:down:*)",
  "Bash(npx prisma migrate deploy:*)",
  "Bash(npx prisma migrate reset:*)",
  "Bash(mongosh:*)",
  "Bash(mysql:*)",
  "Bash(pnpm deploy:*)",
  "Bash(npm run release:*)",
  "Write(./README.md)",
  "Write(./package.json)",
  "Write(./pnpm-lock.yaml)",
  "Write(./yarn.lock)",
  "Write(./vite.config.ts)",
  "Write(./next.config.js)",
  "Write(./tsconfig.json)",
  "Write(./tailwind.config.js)",
  "Write(./prisma/schema.prisma)",
  "Write(./docker-compose.yml)"
],
"_comment_ask": "【询问列表】无论 defaultMode 如何，始终弹出确认对话框。部署、迁移、配置变更必须人工确认",

"defaultMode": "default",
"_comment_defaultMode": "【默认模式】default(按工具默认行为) | dontAsk(全部自动批准，危险！) | alwaysAsk(全部确认)",

"additionalDirectories": [],
"_comment_dirs": "【额外目录】允许 Claude 访问启动目录外的绝对路径列表（如全局组件库、设计资源）"

},

"env": {

"_comment_env": "【环境变量】注入到每个 Claude Code 会话，不污染系统环境",
"NODE_ENV": "development",
"LOG_LEVEL": "debug",
"PYTHONDONTWRITEBYTECODE": "1",
"PNPM_IGNORE_PACKAGE_MANAGER_VERSION": "true"

},

"includeCoAuthoredBy": false,
"_comment_coauthor": "【Git 署名】false 时不添加 Co-Authored-By: Claude。企业/开源项目通常需要关闭",

"gitAttribution": false,
"_comment_gitattr": "【Git 归因】false 时不在 Commit 中体现 AI 参与痕迹",

"cleanupPeriodDays": 30,
"_comment_cleanup": "【清理周期】超过此天数的会话文件在启动时自动删除",

"hooks": {

"_comment_hooks": "【生命周期钩子】在工具执行前后、会话结束时触发自定义脚本",

"PreToolUse": [
  {
    "_comment_pretool_bash": "【Bash 命令执行前】安全检查与敏感信息扫描",
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-bash-guard.sh",
        "timeout": 5,
        "statusMessage": "🔒 安全检查中..."
      },
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-commit-secrets.sh $TOOL_INPUT",
        "timeout": 3,
        "statusMessage": "🔍 扫描敏感信息..."
      }
    ]
  },
  {
    "_comment_pretool_write": "【文件写入前】防止覆盖关键配置文件",
    "matcher": "Edit|Write|MultiEdit",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-write-guard-sensitive.sh $TOOL_INPUT",
        "timeout": 3,
        "statusMessage": "🛡️ 文件写入保护..."
      }
    ]
  },
  {
    "_comment_pretool_npm": "【npm install 前】审计依赖安全",
    "matcher": "Bash(npm install*)|Bash(pnpm install*)",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-npm-install.sh",
        "timeout": 10,
        "statusMessage": "📦 依赖审计中..."
      }
    ]
  }
],

"PostToolUse": [
  {
    "_comment_posttool_edit": "【文件编辑后】自动格式化与类型检查",
    "matcher": "Edit|Write|MultiEdit",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/post-edit-lint.sh",
        "timeout": 30,
        "statusMessage": "🧹 自动修复代码风格..."
      },
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/post-edit-typecheck.sh",
        "timeout": 60,
        "statusMessage": "🔍 TypeScript 类型检查..."
      }
    ]
  },
  {
    "_comment_posttool_bash": "【Bash 命令后】记录命令日志",
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/post-bash-log.sh $TOOL_INPUT",
        "async": true,
        "statusMessage": "📝 记录命令日志..."
      }
    ]
  }
],

"SessionStart": [
  {
    "_comment_session": "【会话启动】环境检查与项目信息展示",
    "matcher": "startup|resume",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/session-start.sh",
        "timeout": 5,
        "statusMessage": "🚀 初始化会话环境..."
      }
    ]
  }
],

"Stop": [
  {
    "_comment_stop": "【会话结束】发送通知",
    "hooks": [
      {
        "type": "command",
        "command": "osascript -e 'display notification "Claude 任务完成" with title "Claude Code"'",
        "timeout": 5
      }
    ]
  }
],

"UserPromptSubmit": [
  {
    "_comment_prompt": "【用户提交】可在发送给模型前预处理用户输入",
    "hooks": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/prompt-filter.sh",
        "timeout": 2
      }
    ]
  }
]

},

"mcpServers": {

"_comment_mcp": "【MCP 服务器】Model Context Protocol 扩展工具配置",
"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
  "env": {}
}

},

"deniedMcpServers": [],
"_comment_denied_mcp": "【MCP 黑名单】显式禁止的 MCP 服务器列表",

"sandbox": {

"_comment_sandbox": "【沙箱】真正的安全边界（OS 级），比 permissions.deny 更强",
"enabled": true,
"enableWeakerNestedSandbox": true,
"allowUnsandboxedCommands": false,
"filesystem": {
  "denyRead": ["~/.ssh", "~/.gnupg", "~/.aws", "~/.kube", "~/.npmrc"],
  "denyWrite": ["~/.ssh", "~/.gnupg", "~/.aws", "~/.kube", "~/.npmrc"]
},
"network": {
  "allowedDomains": ["api.github.com", "registry.npmjs.org", "registry.npmmirror.com", "pypi.org", "fonts.googleapis.com"]
}

},

"statusLine": {

"_comment_status": "【状态栏】自定义底部状态栏显示内容",
"command": "bash ~/.claude/bin/statusline.sh",
"refreshInterval": 5

}
}

---

## 五、Hooks 脚本示例（前端全栈 & 设计版）

### 5.1 pre-bash-guard.sh（Bash 命令安全守卫）

!/bin/bash

【PreToolUse Hook】解析复合命令，检查每个子命令是否在 deny 列表中

保存到 ~/.claude/hooks/pre-bash-guard.sh 并 chmod +x

set -euo pipefail

INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

定义禁止模式（与 settings.json deny 互补，做更细粒度检查）

DENY_PATTERNS=(
"rm -rf /"
"rm -rf /*"
":(){ :|:& };:"
"mkfs"
"dd if=/dev/zero"
"> /dev/sda"
"curl .|.sh"
"wget .|.sh"
"npm install -g"
"pnpm install -g"
"docker system prune"
"kubectl delete"
"mongosh.*dropDatabase"
)

for pattern in "${DENY_PATTERNS[@]}"; do
if echo "$CMD" | grep -qiE "$pattern"; then

echo "❌ 拦截危险命令: $CMD" >&2
echo '{"decision": "deny", "reason": "匹配危险命令模式: '"$pattern"'"}'
exit 2

fi
done

通过检查

exit 0

### 5.2 pre-commit-secrets.sh（敏感信息扫描）

!/bin/bash

【PreToolUse Hook】在 Git Commit 前扫描暂存区是否包含敏感信息

保存到 ~/.claude/hooks/pre-commit-secrets.sh 并 chmod +x

set -euo pipefail

INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

只拦截 git commit 操作

if ! echo "$CMD" | grep -qE "^git commit"; then
exit 0
fi

扫描规则（前端+后端常见）

PATTERNS=(
"AKIA[0-9A-Z]{16}" # AWS Access Key
"ghp_[a-zA-Z0-9]{36}" # GitHub Token
"sk-[a-zA-Z0-9]{48}" # OpenAI/Anthropic Key
"sk_live_[a-zA-Z0-9]{24,}" # Stripe Live Key
"private_key|privatekey|-----BEGIN"
"password\s=\s['"]¹+['"]"
"api[_-]?key\s=\s['"]¹+['"]"
"DATABASE_URL\s=\s['"].://.:.*@"
"MONGODB_URI\s=\s['"].://.:.*@"
"JWT_SECRET\s=\s['"]¹+['"]"
"AUTH_SECRET\s=\s['"]¹+['"]"
)

STAGED=$(git diff --cached --name-only 2>/dev/null || true)
if [[ -z "$STAGED" ]]; then
exit 0
fi

for file in $STAGED; do
CONTENT=$(git show ":$file" 2>/dev/null || true)
for pattern in "${PATTERNS[@]}"; do

if echo "$CONTENT" | grep -qiE "$pattern"; then
  echo "⚠️  发现潜在敏感信息: $file 匹配模式 $pattern" >&2
  echo '{"decision": "ask", "reason": "暂存区可能包含敏感信息，请人工确认"}'
  exit 0
fi

done
done

exit 0

### 5.3 post-edit-lint.sh（保存后自动格式化）

!/bin/bash

【PostToolUse Hook】文件编辑后自动运行格式化

保存到 ~/.claude/hooks/post-edit-lint.sh 并 chmod +x

set -euo pipefail

INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file // empty')

根据文件类型选择 Linter

case "$FILE" in
*.py)

black "$FILE" 2>/dev/null || true
;;

.js|.ts|.jsx|.tsx|.mjs|.cjs)

npx prettier --write "$FILE" 2>/dev/null || true
npx eslint --fix "$FILE" 2>/dev/null || true
;;

.json|.yaml|.yml|.md)

npx prettier --write "$FILE" 2>/dev/null || true
;;

*.sh)

shfmt -w "$FILE" 2>/dev/null || true
;;

.css|.scss|*.less)

npx prettier --write "$FILE" 2>/dev/null || true
;;

esac

exit 0

### 5.4 post-edit-typecheck.sh（TypeScript 类型检查）

!/bin/bash

【PostToolUse Hook】TypeScript 文件修改后执行类型检查

保存到 ~/.claude/hooks/post-edit-typecheck.sh 并 chmod +x

set -euo pipefail

INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file // empty')

只处理 TS 文件

if ! echo "$FILE" | grep -qE '\.(ts|tsx|mts|cts)$'; then
exit 0
fi

检查项目根目录是否存在 tsconfig.json

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
if [[ ! -f "$PROJECT_DIR/tsconfig.json" ]]; then
exit 0
fi

执行类型检查（不生成产物）

cd "$PROJECT_DIR"
npx tsc --noEmit --pretty 2>/dev/null || true

exit 0

### 5.5 pre-npm-install.sh（依赖安装前审计）

!/bin/bash

【PreToolUse Hook】npm/pnpm install 前检查已知漏洞

保存到 ~/.claude/hooks/pre-npm-install.sh 并 chmod +x

set -euo pipefail

检查是否有 package.json

if [[ ! -f "package.json" ]]; then
exit 0
fi

如果存在 audit 结果，提示用户

echo "📦 依赖安装前提醒："
echo " 建议运行 'pnpm audit' 或 'npm audit' 检查已知漏洞"
echo " 建议锁定版本：使用 'pnpm install --frozen-lockfile'"

exit 0

### 5.6 session-start.sh（会话启动初始化）

!/bin/bash

【SessionStart Hook】会话开始时执行环境检查

保存到 ~/.claude/hooks/session-start.sh 并 chmod +x

echo "🚀 Claude Code 会话已启动"
echo "📁 项目目录: ${CLAUDE_PROJECT_DIR:-$(pwd)}"
echo "👤 当前用户: $(whoami)"
echo "🔧 Git 分支: $(git branch --show-current 2>/dev/null || echo 'N/A')"

检测技术栈

if [[ -f "package.json" ]]; then
echo "📦 检测到 Node.js 项目"
node -v 2>/dev/null || echo " ⚠️ Node.js 未安装"
pnpm -v 2>/dev/null || npm -v 2>/dev/null || echo " ⚠️ 包管理器未安装"
fi

if [[ -f "vite.config.ts" || -f "vite.config.js" ]]; then
echo "⚡ 构建工具: Vite"
elif [[ -f "next.config.js" || -f "next.config.ts" ]]; then
echo "▲ 框架: Next.js"
elif [[ -f "nuxt.config.ts" ]]; then
echo "🟢 框架: Nuxt.js"
fi

if [[ -f "prisma/schema.prisma" ]]; then
echo "🗄️ ORM: Prisma"
elif [[ -f "typeorm.config.ts" ]]; then
echo "🗄️ ORM: TypeORM"
fi

if [[ -f "tailwind.config.js" || -f "tailwind.config.ts" ]]; then
echo "🎨 CSS: Tailwind CSS"
fi

exit 0

---

## 六、Skill 模板示例（前端全栈 & 设计版）

### 6.1 前端核心规范 Skill

保存到 `~/.claude/skills/frontend-core/SKILL.md`：

name: frontend-core
description: 前端通用开发规范与工程化指南
when_to_use: 用户要求编写、审查或重构前端代码时自动加载
paths: [".tsx", ".ts", ".jsx", ".js", ".vue", "/package.json", "/vite.config."]
allowed-tools: ["Bash(pnpm:)", "Bash(npm:)", "Bash(npx:*)", "Read", "Edit", "Glob"]
model: sonnet

effort: medium

前端核心规范

技术栈约束

• React 18+（优先）/ Vue 3+（Composition API）
• TypeScript 严格模式（strict: true）
• Tailwind CSS（优先）/ CSS Modules
• 状态管理：Zustand / Jotai / Pinia（禁止无脑 Redux）
• 构建工具：Vite / Next.js / Nuxt.js

组件规范

• 文件命名：PascalCase（UserProfile.tsx）
• Props 必须显式接口定义，禁止 any
• 自定义 Hook 以 use 开头，返回对象
• 列表必须加稳定 key，禁止用 index

样式规范

• 禁止行内 style={{}}
• 颜色/间距必须使用设计令牌（Token）
• 响应式顺序：base → sm → md → lg → xl
• 暗色模式使用 dark: 前缀

性能

• 大数据列表使用虚拟滚动
• 图片使用 WebP/AVIF + srcset
• 动画使用 transform/opacity（GPU 加速）

• 尊重 prefers-reduced-motion

  
  ### 6.2 Nest.js 架构 Skill
  
  保存到 `~/.claude/skills/nestjs-architecture/SKILL.md`：
  

  ---

  name: nestjs-architecture
  description: Nest.js 模块化架构与最佳实践
  when_to_use: 用户涉及 Nest.js 项目时自动加载
  paths: ["/nest-cli.json", "/.module.ts", "/.controller.ts", "/.service.ts", "*/prisma/schema.prisma"]
  allowed-tools: ["Bash(npm:)", "Bash(npx:)", "Read", "Edit", "Write"]
  model: sonnet

  effort: medium

Nest.js 架构规范

模块划分

• 按领域（Domain）划分 Module：UserModule、OrderModule
• 禁止按类型划分：ControllersModule、ServicesModule
• 共享模块放 CommonModule / SharedModule

依赖注入

• 优先构造函数注入
• 禁止 ModuleRef.get() 绕过 DI
• 使用 @Injectable() 标记可注入服务

DTO 与校验

• 所有入参使用 class-validator + class-transformer
• 全局启用 ValidationPipe（whitelist: true, forbidNonWhitelisted: true）
• DTO 文件命名：create-user.dto.ts、update-user.dto.ts

数据库

• ORM 优先 Prisma（新项目）/ TypeORM
• 实体与迁移一一对应，禁止手动改库
• 敏感字段加密存储

响应格式

• 统一拦截器包装：{ code, data, message }

• 异常使用自定义 AppError，包含 traceId

  
  ### 6.3 Figma 还原 Skill
  
  保存到 `~/.claude/skills/figma-to-code/SKILL.md`：
  

  ---

  name: figma-to-code
  description: Figma 设计稿还原为前端代码的规范与技巧
  when_to_use: 用户提到 Figma、设计稿、UI 还原、像素级对齐时自动加载
  paths: ["/figma/", ".figma.ts", "/design-tokens."]
  allowed-tools: ["Read", "Edit", "Write", "Bash(curl:)", "Bash(node -e:)"]
  model: sonnet

  effort: medium

Figma 还原规范

命名检查

• 画板命名：功能_状态（Login_Default）
• 图层命名：语义化（btn_primary、icon_arrow）
• 禁止 Frame 127、Rectangle 3 等默认名

开发交付

• 优先使用 Dev Mode 的 CSS 代码片段
• 检查 Auto Layout 约束（flex 方向、间距、对齐）
• 缺失状态（hover、loading、disabled）需询问设计师补充

设计令牌

• 颜色使用 Token（colors.primary.500）
• 字体使用 Token（typography.heading.h1）
• 间距使用 Token（spacing.4、spacing.8）
• 阴影使用 Token（shadows.md）

资源导出

• 照片：WebP（优先）/ AVIF / JPEG fallback
• 图标：SVG（currentColor 继承）
• 提供 1x/2x 多倍图
• 禁止直接上传 Figma 未压缩 PNG

响应式

• 断点：768px、1024px、1440px（以设计稿为准）
• 使用 Tailwind 响应式前缀：md: lg: xl:
• 移动端优先（base 为移动端，md 起为桌面端）

精度要求

• 间距、圆角、阴影必须与设计稿一致（±1px 容差）
• 字体字重严格匹配，禁止随意加粗

• 中文字体使用系统字体栈

  
  ### 6.4 图片优化 Skill
  
  保存到 `~/.claude/skills/image-optimization/SKILL.md`：
  

  ---

  name: image-optimization
  description: 前端图片资源压缩与格式优化指南
  when_to_use: 用户涉及图片处理、资源优化、性能提升时自动加载
  paths: ["/.png", "/.jpg", "/.jpeg", "/.webp", "/assets/", "/public/"]
  allowed-tools: ["Bash(npx:)", "Bash(node -e:)", "Read", "Edit"]
  model: sonnet

  effort: low

图片优化规范

格式选择

• 照片：WebP（优先）→ AVIF（现代浏览器）→ JPEG fallback
• 图标/Logo：SVG（矢量，优先）→ PNG（需透明）
• 动画：Lottie JSON / CSS 动画 / WebM

压缩标准

• 照片质量 80-85%
• PNG 使用 pngquant 或 sharp
• 禁止直接上传 Figma 未压缩 PNG

响应式

• 提供 srcset：1x、2x、3x
• 使用 元素格式降级：AVIF → WebP → JPEG
• 大图使用 loading="lazy"

工具

• Node.js：sharp（推荐）、imagemin
• CLI：squoosh-cli、pngquant
• 构建时：vite-plugin-imagemin、next/image

图标

• 统一 SVG Sprite 或 Iconify
• 颜色通过 currentColor 继承

• 禁止散落单个 SVG 文件

  
  ### 6.5 TDD 工作流 Skill（后端）
  
  保存到 `~/.claude/skills/tdd-workflow/SKILL.md`：
  

  ---

  name: tdd-workflow
  description: 测试驱动开发完整工作流（前后端通用）
  disable-model-invocation: false
  user-invocable: true
  argument-hint: "[功能描述]"

  arguments: [feature_description]

TDD 工作流

针对功能 "$ARGUMENTS" 执行完整 TDD 循环：

1. 理解需求：分析 "$ARGUMENTS"，明确输入输出边界、异常场景。

2. 编写失败测试：

   • 前端：Vitest + React Testing Library / Vue Test Utils
   • 后端：Jest + Supertest（HTTP）/ 单元测试
   • 确认测试因功能未实现而失败（红）。
3. 提交测试：git add . && git commit -m "test: add failing test for $ARGUMENTS"。
4. 最小实现：编写刚好使测试通过的代码（绿）。
5. 提交实现：git commit -m "feat: implement $ARGUMENTS"。
6. 重构：在不改变行为的前提下优化代码结构。
7. 提交重构：git commit -m "refactor: improve $ARGUMENTS implementation"。

8. 验证：运行完整测试套件，确保无回归。

   
   ---
   
   ## 七、Command 模板示例
   
   ### 7.1 /component 命令
   
   保存到 `~/.claude/commands/component.md`：
   

   Component

生成符合项目规范的前端组件。

步骤

1. 询问/确认：组件名称、功能描述、Props 接口、是否需要测试。
2. 检查项目技术栈（React/Vue、TypeScript、Tailwind 等）。

3. 创建组件文件（PascalCase），包含：

   • 组件实现
   • Props 接口（TypeScript）
   • 样式（Tailwind / CSS Modules）
   • Storybook 故事（如项目使用 Storybook）
   • 单元测试（Vitest / Jest）
4. 更新索引文件（barrel export）。

规则

• 组件不超过 200 行，超出则拆分。
• Props 必须有默认值或可选标记。
• 禁止行内样式。

• 使用设计令牌（Token）。

  
  ### 7.2 /api-route 命令
  
  保存到 `~/.claude/commands/api-route.md`：
  

  API Route

生成后端接口（Nest.js 或 Express.js）。

步骤

1. 确认：HTTP 方法、路径、请求/响应 DTO、权限要求。
2. 检查项目框架（Nest/Express）。

3. 生成：

   • DTO（class-validator 校验）
   • Controller 路由
   • Service 业务逻辑
   • 单元/集成测试
4. 更新模块导入。

规则

• RESTful 命名：名词复数（/users、/orders）。
• 状态码准确：201 Created、204 No Content、409 Conflict 等。
• 所有入参必须经过 ValidationPipe。

• 敏感操作记录审计日志。

  
  ### 7.3 /design-review 命令
  
  保存到 `~/.claude/commands/design-review.md`：
  

  Design Review

对当前页面/组件进行设计还原走查。

步骤

1. 检查当前文件对应的 Figma 节点（如有链接）。

2. 对比以下维度：

   • 色彩：是否使用 Token，暗色模式是否正确
   • 间距：padding、margin、gap 是否匹配
   • 字体：family、size、weight、line-height
   • 圆角：border-radius
   • 阴影：box-shadow
   • 响应式：各断点表现
3. 列出偏差项，给出修复建议。
4. 如涉及图片资源，检查格式和压缩。

输出

• 偏差清单（高/中/低优先级）
• 修复代码片段

• 需要设计师补充的标注

  
  ### 7.4 /migrate 命令
  
  保存到 `~/.claude/commands/migrate.md`：
  

  Migrate

执行数据库迁移（MySQL / MongoDB / Prisma）。

步骤

1. 确认：当前数据库状态、目标变更、是否需要数据迁移。
2. 生成迁移脚本（Prisma migrate / TypeORM migration / migrate-mongo）。
3. 审查脚本安全性（无数据丢失风险）。
4. 本地测试迁移（干跑）。
5. 生成回滚脚本（down / undo）。

规则

• 生产环境迁移必须：先备份、低峰期执行、双人复核。
• 禁止直接修改生产数据库（必须通过迁移脚本）。

• 大表变更使用 Online DDL 或分步迁移（加列→回填→切流量→删旧列）。

  
  ---
  
  ## 八、Agent 模板示例
  
  ### 8.1 UI 还原工程师 Agent
  
  保存到 `~/.claude/agents/ui-developer.md`：
  

  ---

  name: ui-developer
  description: 像素级 UI 还原工程师，专注 Figma 到代码的精确转换
  model: sonnet
  effort: medium

  context: fork

UI 还原工程师 Agent

你是像素级 UI 还原专家，精通 Tailwind CSS、CSS 变量、响应式布局。

职责

• 将 Figma 设计稿还原为高质量前端代码。
• 确保色彩、间距、字体、圆角、阴影与设计稿一致（±1px）。
• 处理响应式适配、暗色模式、无障碍访问。

约束

• 优先使用设计令牌（Token），禁止硬编码色值。
• 图标使用 SVG Sprite / Iconify，禁止导出 Figma 的杂乱 SVG。
• 图片资源必须优化（WebP/AVIF、多倍图、懒加载）。

• 完成后主动列出可能的设计偏差。

  
  ### 8.2 后端工程师 Agent
  
  保存到 `~/.claude/agents/backend-engineer.md`：
  

  ---

  name: backend-engineer
  description: Node.js 后端工程师，专注 Nest.js / Express.js API 开发
  description: Node.js 后端工程师，专注 Nest.js / Express.js API 开发
  model: sonnet
  effort: medium

  context: fork

后端工程师 Agent

你是资深 Node.js 后端工程师，精通 TypeScript、Nest.js、Express.js、MySQL、MongoDB。

职责

• 设计并实现 RESTful / GraphQL API。
• 编写数据库模型与迁移脚本。
• 实现认证授权（JWT、OAuth、RBAC）。
• 编写单元测试与集成测试。

约束

• 所有接口必须有 DTO 校验和 Swagger 文档。
• 数据库操作使用 ORM（Prisma/TypeORM/Mongoose），禁止裸 SQL。
• 敏感数据必须加密，日志必须脱敏。

• 错误处理统一使用 AppError，包含 traceId。

  
  ### 8.3 设计顾问 Agent
  
  保存到 `~/.claude/agents/design-consultant.md`：
  

  ---

  name: design-consultant
  description: 产品设计顾问，协助设计系统构建与 Figma 协作流程
  model: sonnet
  effort: medium

  context: fork

设计顾问 Agent

你是产品设计顾问，精通设计系统（Design System）、Figma 工作流、前端还原。

职责

• 审查设计稿的命名规范、图层结构、Auto Layout。
• 建议设计令牌（Token）体系（颜色、字体、间距、阴影）。
• 评估设计稿的技术可行性（动画复杂度、响应式难度）。
• 输出设计到代码的转换建议。

约束

• 所有建议必须附带 Figma 操作步骤（如"在右侧 Styles 面板创建 Color Style"）。
• 优先考虑开发效率与维护成本，不简单追求视觉效果。

• 推荐工具：Tokens Studio、Figma Variables、Style Dictionary。

  
  ---
  
  ## 九、.claudeignore 模板（前端全栈 & 设计版）
  
  保存到 `~/.claude/.claudeignore`（全局）或项目根目录 `.claudeignore`：
  

  【说明】语法与 .gitignore 完全一致，用于减少 Claude 索引噪音、节省 Token

  注意：这是"软过滤"——不阻止直接读取，只影响主动扫描和发现

依赖目录

node_modules/
vendor/
__pycache__/
.venv/
venv/

构建产物

dist/
build/
.next/
.nuxt/
.output/
*.min.js
*.min.css

日志与缓存

*.log
.cache/
*.tmp
.vite/
.eslintcache
.stylelintcache

大型二进制文件与资源

*.png
*.jpg
*.jpeg
*.gif
*.mp4
*.zip
*.tar.gz
*.ico
*.woff
*.woff2
*.ttf
*.eot

锁文件（通常很大且重复）

注意：如需分析依赖，可注释掉以下行

pnpm-lock.yaml

yarn.lock

package-lock.json

敏感目录（仍需配合 permissions.deny 做硬过滤）

.secrets/
credentials/
.env*
!.env.example

设计资源（通常体积大，按需读取）

*.fig
*.sketch
*.xd
/design-exports/
/raw-assets/

---

## 十、快速启动脚本

保存为 `setup-claude-config.sh`，一键部署全局配置：

!/bin/bash

【一键安装脚本】部署 Claude Code 前端全栈 & 设计版全局配置

set -euo pipefail

CLAUDE_DIR="$HOME/.claude"

echo "🚀 开始安装 Claude Code 前端全栈 & 设计版全局配置..."

创建目录结构

mkdir -p "$CLAUDE_DIR"/{skills,commands,agents,hooks,docs,bin}
mkdir -p "$CLAUDE_DIR/skills/"{frontend-core,react-patterns,vue-patterns,typescript-strict,tailwind-design,nodejs-backend,nestjs-architecture,express-api,database-mysql,database-mongodb,figma-to-code,image-optimization,design-system}

复制模板文件（假设本文档已保存为模板源）

实际使用时，手动复制本文档中的各模板内容到对应文件

echo "✅ 目录结构创建完成！"
echo ""
echo "📋 下一步："
echo " 1. 复制本文档【三、全局 CLAUDE.md】到 ~/.claude/CLAUDE.md"
echo " 2. 复制本文档【四、全局 settings.json】到 ~/.claude/settings.json"
echo " 3. 复制本文档【五、Hooks 脚本】到 ~/.claude/hooks/ 并 chmod +x"
echo " 4. 复制本文档【六、Skill 模板】到 ~/.claude/skills/ 对应目录"
echo " 5. 复制本文档【七、Command 模板】到 ~/.claude/commands/"
echo " 6. 复制本文档【八、Agent 模板】到 ~/.claude/agents/"
echo " 7. 复制本文档【九、.claudeignore】到 ~/.claude/.claudeignore"
echo ""
echo "🔧 然后运行：claude --version 验证安装"

---

## 十一、关键概念速查表

| 概念                | 作用                          | 文件位置                                                | 加载时机           |
| ----------------- | --------------------------- | --------------------------------------------------- | -------------- |
| **CLAUDE.md**     | 行为指令、编码规范、工作流               | `~/.claude/CLAUDE.md` 或 `./CLAUDE.md`               | 每会话开始时完整加载     |
| **settings.json** | 权限控制、模型选择、Hooks、环境变量        | `~/.claude/settings.json` 或 `.claude/settings.json` | 启动时读取          |
| **Skills**        | 领域知识包，自动或手动触发               | `~/.claude/skills/*/SKILL.md`                       | 匹配条件时自动加载      |
| **Commands**      | 自定义斜杠命令                     | `~/.claude/commands/*.md`                           | 用户输入 `/name` 时 |
| **Agents**        | 子代理定义，fork 独立上下文            | `~/.claude/agents/*.md`                             | 被调用时 fork      |
| **Hooks**         | 生命周期脚本（Pre/Post/Start/Stop） | `~/.claude/hooks/*.sh`                              | 事件触发时          |
| **.claudeignore** | 软过滤，减少索引噪音                  | 项目根目录 或 `~/.claudeignore`                           | 文件发现阶段         |
| **Auto Memory**   | Claude 自动记录的项目记忆            | `~/.claude/projects/<hash>/memory/`                 | 每会话前 200 行     |

---

## 十二、最佳实践总结（前端全栈 & 设计版）

1. **分层防御**：`.claudeignore`（效率）+ `permissions.deny`（硬过滤）+ `sandbox`（OS 级安全）。
2. **权限最小化**：从空 `allow` 开始，按需添加。前端项目重点关注 `npm install` 和 `npx` 的权限。
3. **版本控制**：将 `~/.claude` 用 Git 管理（排除 `settings.local.json` 和敏感文件）。
4. **团队同步**：项目级 `.claude/settings.json` 和 `CLAUDE.md` 提交到 Git，确保团队一致性。
5. **Hooks 慎用**：PreToolUse 超时默认较短，复杂逻辑放 PostToolUse 或异步执行。
6. **Skill 迭代**：Skill 出现问题时，修改 Skill 文件本身实现全项目改进，而非仅记 Auto Memory。
7. **设计协作**：建立 `figma-to-code` Skill 和 `design-review` Command，确保设计还原质量。
8. **前后端一致性**：API 类型共享（如 `src/shared/types/api.ts`），禁止前后端各自定义重复类型。
9. **图片资源管理**：建立 `image-optimization` Skill，强制所有图片资源经过压缩和格式转换。
10. **数据库安全**：迁移脚本必须经过本地测试（干跑），生产环境变更必须双人复核。

---

> 📚 **参考资源**
> 
> - [Anthropic 官方 Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code/overview)
> - [coelhoxyz/claude-code-global-config](https://github.com/coelhoxyz/claude-code-global-config) - 精选全局配置
> - [lelandg/.claude_code](https://github.com/lelandg/.claude_code) - 生产级配置含 Agents/Skills/Hooks
> - [erkcet/awesome-claude-code](https://github.com/erkcet/awesome-claude-code) - 社区资源大全
> - [usadamasa/claude-config](https://github.com/usadamasa/claude-config) - 含完整 Hooks 与 Skills 体系