Claude Code 全局通用配置文档（汉化注释版+全局模板）

一、前言说明

本文档基于 GitHub 高星通用 Claude Code 规范原版翻译优化，保留核心编码准则，新增中文详细注释，解决 AI 编码常见的过度设计、擅自改代码、需求臆测、无效重构、范围失控等问题。

同时配套提供全局生效 .claude 目录配置模板，配置后所有本地项目自动复用规则，无需每个项目单独新建 CLAUDE.md。

适用场景：所有前端、后端、客户端、脚本等工程项目，通用无适配门槛。

二、全局通用 CLAUDE.md（中文完整版+详细注释）

使用说明：可放置于项目根目录，或放入全局 .claude 目录实现全局生效，是 Claude Code 编码的核心约束规则。

# Claude Code 全栈开发全局行为规范
# 适用：前端开发 + Node后端(Express/NestJS) + MySQL/MongoDB + Figma设计对接 + 图片资源处理
# 核心宗旨：精准需求落地、极简代码实现、遵循框架规范、前后端风格统一、设计严格还原

---

## 一、编码前置思维准则（通用所有工作）
### 1. 严禁主观臆断开发
1. 需求模糊、接口字段不明确、设计尺寸未定、数据库字段缺失时，**优先提问确认**，不自行定义字段、默认值、交互逻辑。
2. 同一需求存在多种实现方式，主动列出2种最优方案，由使用者选定后再开发。
3. 发现业务逻辑漏洞、接口设计不合理、数据表结构冗余，直接提出优化建议，不强行编写不合理代码。
4. 对接设计稿/后端接口存在冲突，立刻暂停开发，标注冲突点等待统一规范。

### 2. 坚持极简开发，拒绝过度设计
1. 只实现明确提出的功能，**不提前预留未知扩展功能**，不额外新增无用接口、页面组件、数据库字段。
2. 单次使用逻辑不封装通用工具类，页面独立逻辑不强行抽离公共组件。
3. 接口、函数、组件只做单一职责，不堆砌多重业务逻辑。
4. 非线上正式环境，不编写复杂容错、高并发冗余代码，满足业务使用即可。

### 3. 外科式精准修改，最小范围改动
1. 仅修改指定页面、组件、接口、数据表，**绝不私自优化无关代码、调整项目原有格式、重构稳定业务代码**。
2. 严格跟随项目现有技术规范：前端统一项目Eslint/Prettier，后端遵循Nest/Express原生编码风格。
3. 仅清理**本次开发产生的无用导入、变量、接口**，原有项目遗留冗余代码只备注不删除。
4. 跨文件改动必须提前说明改动范围，禁止静默修改全局配置、路由、中间件。

### 4. 结果导向，开发完成必校验
1. 前端：写完页面必须核对设计稿尺寸、颜色、交互、适配兼容性；
2. 后端：写完接口必须自测入参、出参、异常场景，保证可正常联调；
3. 数据库：新增表/字段必须校验关联关系，避免脏数据；
4. 所有开发任务完成后，主动给出自测方式、使用说明，确认达标再结束。

---

## 二、前端专属开发规范（Vue / React / TypeScript）
1. **组件规范**
   - 公共组件统一放入`components`，业务页面组件放置页面目录，分层清晰；
   - 优先使用组合式API / Hooks，禁止混用老旧写法；
   - 组件props、事件必须编写TS类型约束，杜绝`any`滥用。
2. **样式规范**
   - 严格按照Figma设计稿：色值、字体大小、行高、边距、圆角、阴影**1:1还原**；
   - 优先使用项目全局样式变量，不随意写固定色值、固定尺寸；
   - 移动端/PC端优先做自适应适配，避免固定死宽高。
3. **请求与状态**
   - 统一封装Axios请求，统一请求拦截、响应拦截、错误提示；
   - 全局状态仅存放全局公共数据，页面私有数据优先使用本地状态；
   - 接口请求字段命名和后端保持统一，大小写、命名风格一致。
4. **资源处理规范**
   - 图片资源优先压缩后引入，webp格式优先，大图片做懒加载；
   - 本地静态资源统一存放`assets`，线上资源统一使用CDN地址；
   - 禁止在代码内硬编码大量图片地址，统一管理资源路径。

---

## 三、Node.js 后端开发规范（Express + NestJS）
### 1. Express 通用规范
1. 路由分层管理，按业务模块拆分路由文件，不全部堆在入口文件；
2. 统一封装响应格式：成功/失败固定`code、msg、data`结构，前后端统一对接；
3. 全局统一异常捕获，接口报错友好返回信息，不直接抛出原生错误堆栈；
4. 中间件按需引入：登录校验、权限校验、跨域、日志分开管理，不滥用中间件。

### 2. NestJS 框架强制规范
1. 严格遵循 Nest 模块化思想：**模块、控制器、服务、实体分层**，不打乱目录结构；
2. 依赖注入统一使用框架原生写法，不随意改写Nest生命周期；
3. 接口请求参数统一使用`DTO`做数据校验与类型约束；
4. 全局拦截器、过滤器、管道统一复用，不重复编写相同拦截逻辑；
5. 接口版本、接口前缀统一配置全局，不在单个控制器单独定义。

### 3. 接口通用规则
1. RESTful 风格规范：GET查、POST增、PUT改、DELETE删，语义清晰；
2. 分页、排序、筛选统一约定传参格式，全项目接口保持一致；
3. 敏感数据（密码、隐私信息）返回前端自动脱敏处理；
4. 接口注释清晰，标注入参、出参、使用场景，方便前端联调。

---

## 四、数据库开发规范（MySQL + MongoDB）
### 1. MySQL 规范
1. 数据表命名统一小写+下划线，字段命名简洁易懂，预留基础通用字段（id、创建时间、更新时间、删除状态）；
2. 常用查询字段建立索引，禁止全表无索引大数据查询；
3. 多表关联查询简化语句，复杂拆分业务逻辑，避免超长SQL；
4. 涉及数据新增、修改、删除关键业务，优先考虑事务控制；
5. 禁止直接拼接SQL语句，使用参数化查询防止注入。

### 2. MongoDB 规范
1. 集合命名语义化，文档结构扁平化设计，避免多层深度嵌套；
2. 分页查询使用游标分页，大数据量避免一次性查询全部数据；
3. 统一时间字段存储格式，状态字段统一枚举值管理；
4. 合理设置字段默认值，减少前端空值兼容成本。

---

## 五、产品设计 & Figma 对接 & 图片处理规范
1. **Figma 设计稿还原**
   - 严格读取Figma标注：尺寸、间距、字体、颜色、图标、交互状态（默认/hover/选中/禁用）全部对齐；
   - 设计组件复用优先复用项目已有组件，不重复造相同样式；
   - 设计存在歧义、缺少交互逻辑，直接罗列疑问点同步确认。
2. **图片处理工作规范**
   - 支持格式转换：JPG/PNG/WebP/AVIF 按需转换，优先压缩减小体积；
   - 支持图片裁切、比例裁剪、水印添加、尺寸统一缩放；
   - 批量图片处理优先编写简易Node脚本实现自动化，不手动重复操作；
   - 运营活动图、首页banner优先适配多端尺寸，区分移动端/PC端尺寸。
3. **产品辅助工作**
   - 可协助梳理简易产品流程、页面跳转逻辑、接口业务流程文档；
   - 输出前后端联调文档、字段说明文档简洁清晰，不冗余堆砌。

---

## 六、项目工程化通用约束
1. 版本管理：不随意修改`.gitignore`，不提交环境变量、本地配置、日志文件、依赖缓存；
2. 环境区分：严格区分开发环境、测试环境、正式环境配置，环境变量统一管理；
3. 依赖管理：前端不随意安装无用UI库、工具库；后端不引入冗余Node第三方包；
4. 注释规范：复杂业务逻辑、特殊兼容逻辑必须写中文注释，通用简洁逻辑无需多余注释；
5. 兼容适配：前端兼顾主流浏览器、移动端适配；后端接口兼容低版本调用逻辑。

---

## 七、禁止行为清单（严格执行）
1. 禁止擅自更换项目技术栈、修改项目目录结构；
2. 禁止前端随意改写全局路由、状态管理核心逻辑；
3. 禁止后端随意改动数据库主表结构、删除原有业务字段；
4. 禁止为了简洁省略必要的参数校验、权限判断；
5. 禁止脱离设计稿自由发挥写页面样式与交互；
6. 禁止编写无法维护、无注释、逻辑混乱的一次性后端接口。

三、全局生效 .claude 目录配置模板（核心）

3.1 全局配置目录路径

Claude Code 支持全局公共配置，所有本地项目自动加载，无需每个项目单独配置：

• Windows 全局目录：C:\\Users\\你的用户名\\\.claude\\
• Mac / Linux 全局目录：\~/\.claude/

若无该目录，手动新建即可，全局优先级：全局.claude配置 \< 项目根目录CLAUDE.md（项目配置可覆盖全局配置）。

3.2 完整目录结构模板

在全局 \.claude 目录下创建如下结构，实现规则全局永久生效：

.claude/
├── CLAUDE.md        # 全局通用编码规则（上方汉化完整版）
├── config.json      # Claude Code 全局行为配置
└── ignore-patterns  # 全局忽略文件/目录规则（可选）

3.3 全局 config.json 配置文件

该文件控制 Claude Code 全局运行行为，统一所有项目的 AI 编码逻辑，直接复制使用：

{
  // 全局启用自定义规则优先级，优先读取全局 CLAUDE.md
  "rulePriority": "globalFirst",
  // 禁止 AI 擅自执行无关重构、格式优化
  "autoRefactor": false,
  // 禁止自动修改非目标文件
  "unrestrictedFileEdit": false,
  // 开启修改溯源，所有改动必须关联需求
  "requireChangeReason": true,
  // 复杂任务强制先输出方案再编码
  "requirePlanBeforeAction": true,
  // 完工强制验证功能、测试用例
  "requireVerification": true,
  // 禁止过度封装、过度扩展
  "preventOverEngineering": true,
  // 保留项目原有代码风格，不强制统一个人风格
  "enforceProjectStyle": true,
  // 禁止AI私自优化前端样式/排版/格式，仅修改需求指定的样式
  "allowFrontendStyleOptimize": false,
  // 禁止AI打乱后端(Nest/Express)模块化结构，严格遵循框架目录规范
  "allowBackendModuleChaos": false,
  // 强制严格1:1还原Figma设计稿，不允许AI自由发挥样式、尺寸、交互
  "strictDesignRestore": true,
  // 强制严格校验数据库规范(命名/索引/安全/结构)，杜绝不规范SQL和集合设计
  "strictDbRuleCheck": true
}

3.4 全局 ignore-patterns 忽略规则（可选）

配置后 AI 不会读取、修改、询问以下文件，避免误改配置、依赖、缓存文件：

# 前端忽略
node_modules/
dist/
build/
out/
.nuxt/
.next/
.vite/
coverage/
*.log
.env*
.DS_Store
pnpm-lock.yaml
yarn.lock
package-lock.json

# 后端Node忽略
logs/
uploads/
temp/
prisma/migrations/
mongodb-data/
mysql-data/
nest-cli.json 不随意修改

四、全局配置生效步骤

1. 创建全局目录：根据系统找到对应 \.claude 目录，不存在则手动新建；
2. 放入配置文件：将上方汉化版 CLAUDE.md、config.json、ignore-patterns 放入目录；
3. 重启 Claude Code：关闭当前会话，重新打开终端/编辑器，配置自动全局生效；
4. 优先级适配：单个项目如需特殊规则，可在项目根目录新建 CLAUDE.md，自动覆盖全局规则。

五、配置核心优势

• 全局统一：所有项目无需重复配置，一次部署永久生效；
• 杜绝翻车：彻底解决 AI 过度设计、乱改代码、臆测需求、无效重构问题；
• 适配性强：兼容 VS Code、Cursor、IDE 内置 Claude Code 所有客户端；
• 轻量化：无冗余规则，只约束核心问题，不限制正常开发逻辑。

（注：文档部分内容可能由 AI 生成）