CLAUDE.md — 全局配置文档

适用范围：全局（~/.claude/CLAUDE.md）
技术栈：HTML / CSS / Javascript / Typescript / 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. 遇到不确定的问题，先说明再行动：不要静默地做出可能有副作用的假设
7. 验证驱动：在证明功能正确之前，不标记任务完成。时刻自问："资深工程师会认可这个方案吗？"
8. 设计一致性：代码还原设计稿时，像素级对齐不是可选而是默认。色彩、间距、字体必须与设计令牌（Design Token）一致

三、工作流规范（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）

四、技术规范（Tech Stack）

4.1 前端通用规范

• 组件文件使用 PascalCase（MyComponent.vue）
• 工具函数文件使用 camelCase（formatDate.ts）
• 组件props、事件必须编写TS类型约束，杜绝any滥用
• 优先使用组合式API / Hooks，禁止混用老旧写法
• 优先使用 interface 定义对象形状，type 用于联合类型/工具类型
• CSS 类名使用 kebab-case
• 严格按照 Figma 设计稿，CSS 尽量实现像素级对齐，元素间距、色值、字体大小、行高、圆角、阴影必须与设计稿一致（允许 ±1px 误差）
• 优先使用 CSS 变量管理主题色和间距
• 图片资源：WebP 优先，SVG 用于图标
• 禁止内联样式（动态样式除外）

4.2 Node.js 后端规范

• 统一使用 async/await，禁止回调地狱
• 所有路由必须有错误处理中间件兜底
• 环境变量通过 .env 管理，禁止硬编码敏感信息
• 接口返回统一格式：{ code, data, message }
• 接口敏感数据（密码、隐私信息）返回前端前自动脱敏处理
• RESTful 方法语义化：GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
• HTTP 状态码准确：200 OK、201 Created、204 No Content、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict、500 Internal Error
• 日志：使用 winston 或 pino，区分 info / warn / error 级别

五、 Git 操作规范

5.1 提交前检查清单

执行 git commit / git push / PR 创建前，必须完成：

1. 前端额外检查：

   • pnpm lint（ESLint + Prettier）通过
   • pnpm type-check（tsc --noEmit）通过
   • pnpm test:unit（Vitest）通过
   • 构建产物检查（pnpm build），确认无警告

2. 后端额外检查：

   • npm run lint 通过
   • npm run test 通过
   • 数据库迁移可执行（npm run migrate:up 干跑）

3. PR 创建规范：

   • 必须创建 Draft PR
   • 必须设置 Assignees

5.2 分支模型

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

5.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 等高风险命令前，必须二次确认。

七、项目工程化通用约束

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

八、禁止行为清单（严格执行）

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