Claude Code实战教程(3)：CLAUDE.md——给AI装上一颗项目大脑

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code 启动流程                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   1. 扫描项目根目录，找到 CLAUDE.md                          │
│         ↓                                                   │
│   2. 扫描父目录，找到上级 CLAUDE.md（向上递归）               │
│         ↓                                                   │
│   3. 读取用户级 CLAUDE.md（~/.claude/CLAUDE.md）             │
│         ↓                                                   │
│   4. 将以上内容合并注入到系统提示词中                          │
│         ↓                                                   │
│   5. 每次对话开始，Claude 都能"记住"这些规则                   │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│   ⚠️ 重要：系统提示词本身约占用 50 个指令槽位                  │
│      Claude 有效理解上限约 150 条指令                         │
│      留给 CLAUDE.md 的空间：约 100 条规则                     │
└─────────────────────────────────────────────────────────────┘

~/.claude/CLAUDE.md              ← 个人全局配置（对所有项目生效）
    ↑
项目根目录/CLAUDE.md             ← 项目级配置（团队共享，推荐放入 git）
    ↑
src/components/CLAUDE.md        ← 子目录级配置（仅对该目录下的代码生效）
    ↑
src/api/CLAUDE.md               ← 更细粒度的配置

## 项目规则
- Don't use passive voice
- Always use TypeScript
- Response length: concise
- No inline comments unless asked

我偏向直接、专业的沟通风格，但在写面向初级工程师的文档时会更温暖一些。
代码审查评论要简洁有力，不需要过度解释基础概念。

技术栈：TypeScript + Next.js + Tailwind CSS + Zustand
所有新代码必须使用 TypeScript，禁止 any。
React 组件一律使用函数组件 + hooks，不使用 class 组件。
状态管理使用 Zustand，不在组件内直接使用 localStorage。
UI 组件来自 shadcn/ui，优先使用现有组件而非自定义样式。
生产环境禁止 console.log，使用专用的 logger 模块（src/utils/logger.ts）。

## 项目概述
这是一个电商平台的后端服务，使用 NestJS + PostgreSQL 构建。
主要功能：用户管理、商品目录、订单处理、支付集成。
目标用户：B2B 采购商家，日活约 5000。

## 技术栈
- 运行时：Node.js 20 LTS
- 框架：NestJS 10
- 数据库：PostgreSQL 16 + TypeORM
- 缓存：Redis
- 测试：Jest + Supertest
- 部署：Docker + Kubernetes

## 项目结构
src/
  modules/          # 业务模块（users, products, orders, payments）
  common/           # 共享工具（filters, interceptors, guards）
  config/           # 配置文件
  main.ts           # 入口文件
test/               # 测试文件（与 src/ 结构对应）
docker/             # Docker 相关文件

## 编码规范
- 所有模块必须遵循 NestJS 的标准分层：controller → service → repository
- DTO 类放在 dtos/ 子目录，使用 class-validator 做输入校验
- 异常处理统一使用 HttpException，不在 service 层抛原生 Error
- 数据库查询使用 TypeORM QueryBuilder，避免 N+1
- API 响应统一包装为 { data, meta: { page, limit, total } }

## 命名约定
- 模块：kebab-case（user-module.ts）
- 服务类：PascalCase + Service 后缀（UserService）
- DTO：PascalCase +Dto 后缀（CreateUserDto）
- 测试文件：*.spec.ts
- 环境变量：UPPER_SNAKE_CASE

## 关键路径
- 主入口：src/main.ts
- 用户认证：src/modules/auth/
- 支付逻辑：src/modules/payments/
- 数据库配置：src/config/database.ts

## 常用命令
npm run build          # 构建
npm run start          # 本地启动
npm run test           # 运行测试
npm run test:cov       # 带覆盖率报告
npm run test:e2e       # E2E 测试

## 禁止事项
- 不要在生产代码中使用 console.log，改用 logger 模块
- 不要绕过 DTO 直接用 req.body
- 不要在 service 层直接操作 HTTP 响应对象
- 不要在数据库查询中拼接 SQL 字符串（防注入）
- 不要提交包含 .env 文件的生产密钥

## 代码的读者是谁
- 代码审查者：资深工程师，不需要解释基础概念，但需要清楚非显而易见的决策理由
- 文档读者：新入职的初级工程师，需要更详细的解释和上下文
- 未来维护者：6个月后的自己，希望快速理解当前代码的意图

## 安全要求
- 所有用户输入必须经过校验（class-validator）
- 密码必须使用 bcrypt 哈希，成本因子 ≥ 12
- API 端点必须经过 JWT 认证中间件保护
- 敏感信息不得出现在日志或错误消息中
- 数据库查询参数必须参数化，禁止字符串拼接

# Project Instructions

## 项目概述
SaaS 仪表盘前端，管理用户的订阅、团队成员和数据分析。
已上线产品，日均活跃用户约 2000。

## 技术栈
- Next.js 14 (App Router)
- TypeScript（严格模式）
- Tailwind CSS + ShadCN/UI
- Zustand（状态管理）
- TanStack Query（服务端状态）
- Vitest（测试）
- ESLint + Prettier

## 目录结构
app/            # Next.js App Router 页面
  components/   # UI 组件
  lib/          # 工具函数和 API 客户端
  hooks/        # 自定义 React Hooks
services/       # API 调用封装
store/          # Zustand stores
types/          # TypeScript 类型定义
tests/          # 测试文件

## 编码规范
- 组件使用函数组件 + TypeScript 接口
- 禁止在组件内直接使用 fetch，统一走 services/ 层
- API 响应类型必须在 types/ 中明确定义
- 使用 ShadCN 现有组件，不造轮子
- 复杂 UI 逻辑提取为 custom hook

## 禁止事项
- 禁止使用 any 类型
- 禁止直接在组件中读写 localStorage
- 禁止在服务器上执行客户端-only 的代码
- 禁止提交时包含 node_modules 或 .next 缓存

## 常用命令
npm run dev          # 开发服务器
npm run build        # 生产构建
npm run test         # 运行测试
npm run lint         # 代码检查

## 代码读者
- 同事：熟悉 Next.js，不需要解释基础概念
- 新成员：需要理解项目整体架构和数据流

/init

.claude/skills/
├── deploy/
│   └── SKILL.md          # 部署流程
├── code-review/
│   └── SKILL.md          # 代码审查流程
└── test/
    └── SKILL.md         # 测试编写规范

{
  "permissions": {
    "defaultMode": "auto"
  },
  "model": {
    "default": "claude-sonnet-5"
  }
}

# Claude Code 生成的临时文件
.claude/
!.claude/settings.json
!.claude/CLAUDE.md

# ❌ 不好的做法：把所有内容堆在根 CLAUDE.md
## 数据库规范
## 前端规范
## 测试规范
## 部署规范
## API 规范
## ...（200行）

# ✅ 好的做法：根文件只放关键规则，子目录放详细规范
# 项目根/CLAUDE.md（15行）
## 项目概述
## 技术栈
## 关键规范（全局适用的）

# src/database/CLAUDE.md（10行）
## 数据库模块专用规范

# src/frontend/CLAUDE.md（10行）
## 前端模块专用规范

# 在团队项目中，CLAUDE.md 应该在根目录并提交到 git
git add CLAUDE.md
git commit -m "docs: 更新项目规范和编码约定"