Claude Code 团队使用指南

本指南面向开发团队，涵盖核心原则、CLAUDE.md 配置详解、工作流程、进阶技巧与安全规范。力求简洁实用、有启发性。

1. 什么是 Claude Code

Claude Code 是 Anthropic 推出的智能体编程助手（Agentic Coding Assistant），它不只是代码补全工具，而是能够：

理解整个代码库的上下文
自主编辑多个文件
执行命令行操作
运行测试并根据结果迭代
与 Git、GitHub、CI/CD 深度集成

核心理念：把 Claude 当作一个"新入职的高级工程师"——能力很强，但需要你给予清晰的项目背景和工作规范。

2. 核心使用原则

2.1 六大黄金法则

原则	详细说明	实践建议
明确上下文	Claude 不了解你的项目历史，必须通过 CLAUDE.md 告诉它	每个项目根目录放置详细的 CLAUDE.md
小步迭代	一次让 Claude 做一件事，避免复杂的多步任务	拆解任务："先写测试 → 再实现功能 → 最后重构"
有疑就问	不确定时让 Claude 先解释思路，再动手	用 "请先分析这个问题" 开头
尊重代码风格	保持与现有代码一致，不自作主张改风格	在 CLAUDE.md 中明确代码规范
验证优先	所有输出都需要验证——测试、Review、人工检查	设置自动化测试，关键代码人工 Review
安全第一	敏感操作需确认，生产环境需严格权限	使用权限系统，设置操作 Hook

2.2 心智模型：PIV 循环

高效使用 Claude Code 的核心工作流：

Plan（规划）：明确任务目标，让 Claude 先制定计划
Implement（实现）：执行代码修改、文件操作
Validate（验证）：运行测试、检查结果、人工确认

3. CLAUDE.md 配置详解

3.1 什么是 CLAUDE.md

CLAUDE.md 是项目的"说明书"，每次 Claude 开始工作时都会读取它。作用包括：

提供项目背景和架构信息
定义编码规范和风格要求
列出常用命令和脚本
标注注意事项和禁止操作
给出 Claude 的行为指令

3.2 文件层级结构

Claude Code 支持多级配置文件，优先级从低到高：

优先级（低 → 高）：

~/.claude/CLAUDE.md          # 全局配置：个人偏好，适用所有项目
    │
    ▼
./CLAUDE.md                   # 项目配置：团队共享，提交到 Git
    │
    ▼
./CLAUDE.local.md             # 本地覆盖：个人定制，加入 .gitignore
    │
    ▼
./src/module/CLAUDE.md        # 模块配置：特定目录的规则

3.3 完整的 CLAUDE.md 模板

# 项目名称：MyApp

## 🎯 项目简介

MyApp 是一个面向自由职业者的发票管理 SaaS 平台。

**核心功能**：
- 创建和管理客户
- 生成专业发票
- 追踪付款状态
- 导出财务报表

## 🛠️ 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 + TypeScript + Vite |
| 状态管理 | Zustand |
| 数据获取 | TanStack Query (React Query) |
| UI 组件 | Shadcn/ui + Tailwind CSS |
| 后端 | Node.js + Express + TypeScript |
| 数据库 | PostgreSQL + Prisma ORM |
| 认证 | JWT (HttpOnly Cookie) |
| 测试 | Vitest + React Testing Library + Playwright |
| CI/CD | GitHub Actions |

## 📁 项目结构

```
myapp/
├── src/
│   ├── components/      # 可复用 UI 组件
│   │   ├── ui/          # 基础 UI 组件（Button, Input 等）
│   │   └── features/    # 业务功能组件
│   ├── pages/           # 页面级组件
│   ├── hooks/           # 自定义 React Hooks
│   ├── utils/           # 工具函数
│   ├── api/             # API 请求封装
│   ├── stores/          # Zustand 状态管理
│   ├── types/           # TypeScript 类型定义
│   └── styles/          # 全局样式
├── server/
│   ├── routes/          # API 路由
│   ├── controllers/     # 业务逻辑
│   ├── services/        # 服务层
│   ├── middleware/      # 中间件
│   └── prisma/          # 数据库 Schema
├── tests/
│   ├── unit/            # 单元测试
│   ├── integration/     # 集成测试
│   └── e2e/             # 端到端测试
└── docs/                # 项目文档
```

## 📏 编码规范

### 通用规范
- 使用 **TypeScript**，开启严格模式（strict: true）
- 2 空格缩进，单引号，无分号
- 文件命名：kebab-case（如 `user-profile.tsx`）
- 组件命名：PascalCase（如 `UserProfile`）
- 函数/变量：camelCase（如 `getUserData`）
- 常量：UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`）

### React 规范
- ✅ 只使用函数式组件 + Hooks
- ✅ 使用 named exports（非 default export）
- ✅ Props 必须定义 TypeScript 接口
- ✅ 使用 React Query 进行数据获取
- ❌ 禁止使用 Class 组件
- ❌ 禁止直接在组件中写 fetch

### 后端规范
- 所有 API 返回统一格式：`{ success: boolean, data?: T, error?: string }`
- 使用 Prisma 进行数据库操作，禁止原生 SQL
- 敏感信息通过环境变量配置

## 🖥️ 常用命令

```bash
# 开发
npm run dev              # 启动前端开发服务器
npm run server           # 启动后端服务器
npm run dev:all          # 同时启动前后端

# 测试
npm run test             # 运行单元测试
npm run test:watch       # 监听模式运行测试
npm run test:coverage    # 生成覆盖率报告
npm run test:e2e         # 运行端到端测试

# 代码质量
npm run lint             # ESLint 检查
npm run lint:fix         # 自动修复 ESLint 问题
npm run format           # Prettier 格式化
npm run typecheck        # TypeScript 类型检查

# 数据库
npm run db:migrate       # 运行数据库迁移
npm run db:seed          # 填充测试数据
npm run db:studio        # 打开 Prisma Studio

# 构建
npm run build            # 生产构建
npm run preview          # 预览生产构建
```

## 🔧 开发环境

### 环境要求
- Node.js >= 18.0.0
- npm >= 9.0.0
- PostgreSQL >= 14

### 环境变量

```bash
# .env.example
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
JWT_SECRET=your-secret-key
API_BASE_URL=http://localhost:3001
```

## ⚠️ 重要注意事项

### 已知问题
- 🐛 Dashboard 页面在数据量 > 5000 条时会有性能问题
- 🐛 iOS Safari 中日期选择器有兼容性问题
- 🐛 PDF 导出在 Firefox 中偶尔失败

### 架构决策记录
- 选择 Zustand 而非 Redux：更轻量，适合中小型项目
- 使用 Prisma：类型安全，迁移方便
- JWT 存 HttpOnly Cookie：防止 XSS 攻击

## 📋 给 Claude 的指令

### ✅ 必须做
- 每个新函数都要添加 TypeScript 类型注解
- 新功能必须包含对应的单元测试
- 使用 React Query 进行所有 API 调用
- 遵循现有的错误处理模式
- 公共函数添加 JSDoc 注释
- 提交前确保 `npm run lint` 和 `npm run typecheck` 通过

### ❌ 禁止做
- 不要修改 CI/CD 配置（.github/workflows/*）
- 不要修改 Prisma Schema 而不告知
- 不要删除任何文件而不先确认
- 不要在代码中硬编码敏感信息
- 不要使用 `any` 类型
- 不要跳过测试直接提交

### 💡 偏好
- 优先选择函数式编程风格
- 小函数、单一职责
- 有意义的变量名，代码即文档
- 处理边界情况和错误场景

## 🚀 未来规划

- [ ] 实现实时通知（WebSocket）
- [ ] 添加暗黑模式
- [ ] 迁移到 Next.js（SEO 优化）
- [ ] 添加多语言支持

3.4 全局配置示例（~/.claude/CLAUDE.md）

适用于个人所有项目的通用规则：

# 全局 Claude 配置

## 我的开发偏好

- 我使用 macOS + VS Code + Zsh
- 偏好函数式编程风格
- 喜欢简洁的代码，厌恶过度抽象

## 通用工作原则

- 修改文件前先解释你的计划
- 删除任何文件前必须先确认
- 不确定时主动询问，不要猜测
- 每次修改后建议运行的验证命令

## 代码风格

- 使用 TypeScript 时开启 strict 模式
- 优先使用 const，避免 let
- 使用可选链（?.）和空值合并（??）
- 注释写为什么，不写是什么

## Git 习惯

- Commit message 使用 Conventional Commits 格式
- 小步提交，一个功能一个 commit
- 提交前运行 lint 和 test

3.5 使用 @ 导入复用配置

大型项目可以拆分配置并通过 @ 导入：

# CLAUDE.md

@docs/coding-standards.md
@docs/api-conventions.md
@docs/testing-guide.md

4. 日常工作流程

4.1 任务启动：给出好的指令

❌ 不好的指令：

帮我写一个用户功能

✅ 好的指令：

请在 src/components/features/ 目录下创建一个 UserProfile 组件：

功能要求：
1. 显示用户头像、姓名、邮箱
2. 支持编辑模式切换
3. 编辑保存时调用 PATCH /api/users/:id

技术要求：
1. 使用 React Query 的 useMutation 处理更新
2. 使用 zod 进行表单验证
3. 添加对应的单元测试

请先告诉我你的实现计划，然后再开始编码。

4.2 复杂任务分解

对于大任务，先让 Claude 制定计划：

我需要为项目添加多语言支持（i18n），请先帮我：
1. 分析当前项目结构
2. 评估几种 i18n 方案的优缺点
3. 制定一个分步实施计划

不要立即动手，先把计划给我看。

4.3 TDD 工作流

推荐的测试驱动开发流程：

第一步：先写测试
"请为 calculateInvoiceTotal 函数编写单元测试，覆盖以下场景：
- 正常计算含税金额
- 处理空行项
- 处理折扣
- 边界值测试"

第二步：运行测试（应该失败）
"运行测试，确认测试失败"

第三步：实现功能
"现在实现 calculateInvoiceTotal 函数，让所有测试通过"

第四步：重构
"测试通过了，请检查代码是否有优化空间"

4.4 代码审查工作流

让 Claude 帮助 Review 代码：

请审查 src/utils/date.ts 的代码，关注：
1. 类型安全性
2. 边界情况处理
3. 性能问题
4. 可读性和可维护性

给出具体的改进建议。

5. 进阶技巧与自动化

5.1 自定义命令

在 .claude/commands/ 目录下创建自定义命令：

<!-- .claude/commands/new-component.md -->
# 创建新组件

根据以下模板创建 React 组件：

1. 在 src/components/features/ 创建组件文件
2. 创建对应的类型定义
3. 创建对应的测试文件
4. 更新 index.ts 导出

使用项目标准的代码风格。

使用方式：/new-component UserAvatar

5.2 子代理（Subagents）

对于复杂任务，可以让 Claude 分配子任务：

请使用子代理并行完成以下任务：
1. 子代理1：更新所有组件的 PropTypes 为 TypeScript 接口
2. 子代理2：为缺少测试的 utils 函数添加测试
3. 子代理3：更新 README 文档

最后汇总所有变更。

5.3 Git Hooks 集成

在 .claude/settings.json 中配置：

{
  "hooks": {
    "pre-commit": "npm run lint && npm run typecheck",
    "pre-push": "npm run test"
  }
}

5.4 CI/CD 集成

GitHub Actions 中使用 Claude Code：

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Review
        uses: anthropics/claude-code-action@v1
        with:
          task: "review-pr"
          claude-md: "./CLAUDE.md"

6. 安全与权限管理

6.1 权限层级

权限级别	适用场景	Claude 能力
只读	代码分析、问答	读取文件，不能修改
标准	日常开发	读写源码，运行测试
完全	高级自动化	可执行任意命令（谨慎！）

6.2 安全最佳实践

## 安全规则（加入 CLAUDE.md）

### 绝对禁止
- ❌ 不要在代码中出现任何 API Key、密码、Token
- ❌ 不要执行 rm -rf、drop database 等破坏性命令
- ❌ 不要修改生产环境配置
- ❌ 不要绕过代码审查直接合并

### 必须确认
- ⚠️ 删除文件前请先列出并确认
- ⚠️ 修改数据库 Schema 前请先说明影响
- ⚠️ 安装新依赖前请说明原因
- ⚠️ 修改权限相关代码前请 Review

6.3 敏感操作保护

使用 Hook 保护敏感操作：

{
  "protectedPaths": [
    ".env*",
    "*.pem",
    "*.key",
    "server/config/production.ts",
    ".github/workflows/*"
  ],
  "confirmBefore": [
    "delete",
    "overwrite",
    "npm publish",
    "git push --force"
  ]
}

7. 常见问题与避坑指南

7.1 常见问题

问题	原因	解决方案
Claude 不了解项目背景	CLAUDE.md 不完整	补充项目描述、架构、约定
生成的代码风格不一致	没有明确编码规范	在 CLAUDE.md 中详细定义
执行了不该执行的命令	权限太宽松	使用权限系统和 Hook
上下文丢失	会话太长，信息漂移	新任务开启新会话
修改了不该改的文件	没有设置保护路径	配置 protectedPaths

7.2 调试技巧

当输出不符合预期时：

1. 让 Claude 解释决策
   "请解释你为什么选择这种实现方式？"

2. 提供反馈并要求修正
   "这不符合我们的规范，请按照 CLAUDE.md 中的 XX 规则重写"

3. 分步验证
   "请先只做第一步，我确认后再继续"

4. 请求对比方案
   "请给出两种实现方案，并对比优缺点"