## 最佳实践

这篇文档汇集了大量 Claude Code 用户在实际开发中总结出的经验。无论你是刚开始使用 Claude Code 的新手，还是已经有一定基础想进一步提效的老手，都能在这里找到有价值的技巧。

我们按照从入门到进阶的顺序组织内容，建议你先通读一遍，然后在日常工作中逐步应用。

## 项目初始化最佳实践

好的开始是成功的一半。在一个项目中首次使用 Claude Code 之前，花 10 分钟做好初始化，后续每一次交互都会更高效。

### 第一步：创建 CLAUDE.md

这是最重要的一步。`CLAUDE.md` 就像你给 Claude 写的一份「项目说明书」，每次启动 Claude Code 时它会自动读取这个文件，理解你的项目背景。

**为什么这一步如此重要？**

不写 CLAUDE.md，你会反复跟 Claude 解释同样的事情：

```
你：用 pnpm 安装依赖
Claude：好的，运行 npm install...
你：不是 npm，是 pnpm！
Claude：抱歉，运行 pnpm install...
```

有了 CLAUDE.md，这些基础信息只需说一次。

**CLAUDE.md 模板示例：**

```markdown
# 我的项目名称

## 概述
这是一个基于 Next.js 15 的电商后台管理系统，使用 TypeScript 编写。

## 技术栈
- 运行时：Node.js 22 LTS
- 框架：Next.js 15 (App Router)
- 样式：Tailwind CSS v4
- 数据库：PostgreSQL 16 + Prisma ORM
- 包管理器：pnpm 9
- 测试框架：Vitest + Playwright

## 常用命令
- 安装依赖：`pnpm install`
- 开发服务器：`pnpm dev`（端口 3000）
- 运行测试：`pnpm test`
- 代码检查：`pnpm lint`
- 数据库迁移：`pnpm prisma migrate dev`
- 构建生产：`pnpm build`

## 编码规范
- 严格使用 TypeScript，禁止 `any`
- React 组件使用函数式写法 + hooks
- 样式只用 Tailwind，不写内联 style 和 CSS 文件
- 所有 API 路由统一返回 `{ success: boolean, data?: T, error?: string }`
- 数据库查询统一走 service 层，不在 route 中直接调用 Prisma
- 提交信息格式：`feat:` / `fix:` / `docs:` / `refactor:` 等前缀

## 项目结构
- `src/app/` — 页面和 API 路由（App Router）
- `src/components/` — 可复用 UI 组件
- `src/components/ui/` — 基础组件（Button、Input 等）
- `src/services/` — 业务逻辑层
- `src/lib/` — 工具函数和配置
- `prisma/` — 数据库 schema 和迁移文件

## 注意事项
- 不要手动修改 `prisma/migrations/` 下的文件
- 环境变量配置在 `.env.local`（不提交到 Git）
- API 鉴权中间件在 `src/middleware.ts`
- 图片资源放 `public/images/`，使用 next/image 组件加载
```

**使用 /init 快速生成：**

如果不想手写，可以用 `/init` 命令让 Claude 自动分析项目并生成：

```
/init
```

Claude 会扫描你的项目结构、package.json、配置文件等，自动生成一份 CLAUDE.md。然后你再手动补充一些它可能遗漏的团队约定。

### 第二步：配置 .claudeignore

和 `.gitignore` 类似，`.claudeignore` 告诉 Claude 哪些文件不需要关注。这不仅能加速搜索，还能避免 Claude 被无关文件干扰。

```bash
# .claudeignore

# 依赖目录
node_modules/
vendor/
.venv/

# 构建产物
dist/
build/
.next/
out/

# 大型数据文件
*.sql
*.csv
*.sqlite
data/

# 二进制和媒体文件
*.jpg
*.png
*.mp4
*.zip

# 自动生成的代码
generated/
*.gen.ts
prisma/migrations/

# 日志
logs/
*.log
```

### 第三步：在 CLAUDE.md 中描述目录结构

这一步经常被忽略，但效果显著。Claude 理解了目录结构后，就知道该在哪里找文件、在哪里创建文件：

```markdown
## 项目结构
src/
├── app/                 # Next.js App Router
│   ├── (auth)/          # 需要登录的页面
│   ├── (public)/        # 公开页面
│   └── api/             # API 路由
├── components/
│   ├── ui/              # 基础 UI 组件（shadcn/ui）
│   ├── forms/           # 表单组件
│   └── layouts/         # 布局组件
├── services/            # 业务逻辑（每个模块一个文件）
├── hooks/               # 自定义 React hooks
├── lib/                 # 工具函数
│   ├── auth.ts          # 认证相关
│   ├── db.ts            # 数据库连接
│   └── validators.ts    # Zod schema 定义
└── types/               # TypeScript 类型定义
```

## 日常编码最佳实践

初始化做好后，日常使用中的这些习惯能让你事半功倍。

### 清晰描述需求，而非模糊指令

这是最基本也是最重要的原则。Claude 不是读心术大师，你说得越清楚，它做得越好。

| 模糊指令（效果差） | 清晰描述（效果好） |
|---|---|
| 「改一下登录功能」 | 「在 src/app/api/auth/login/route.ts 中添加登录失败次数限制：同一 IP 5 分钟内失败 5 次后锁定 15 分钟，用 Redis 存储计数」|
| 「帮我写个组件」 | 「创建一个 UserAvatar 组件，放在 src/components/ui/ 下。接受 name 和 imageUrl 两个 props，没有图片时显示姓名首字母，使用 Tailwind 的 rounded-full 做圆形头像」|
| 「这个有 bug，修一下」 | 「用户反馈在商品列表页点击翻页后，筛选条件会丢失。请检查 src/app/products/page.tsx 中的分页逻辑，确保 URL query params 在翻页时被保留」|

### 善用 @ 引用提供上下文

当你需要 Claude 参考特定文件时，用 `@` 符号直接引用，比让它自己搜索更快更准：

```
看看 @src/services/order-service.ts 和 @src/types/order.ts，
然后在 order-service 中添加一个取消订单的方法，要检查订单状态是否允许取消。
```

**几种 @ 引用方式：**

```bash
@src/services/auth.ts       # 引用单个文件
@src/components/            # 引用整个目录
@package.json               # 引用配置文件
@https://nextjs.org/docs    # 引用在线文档（会抓取内容）
```

> **省钱技巧**：主动用 `@` 引用相关文件，比让 Claude 自己搜索整个项目要便宜得多。因为 Claude 搜索时会读取大量文件，消耗额外的 token。

### 一次只做一件事

避免在一个提示中塞太多任务。Claude 在专注做一件事时表现最好：

```
# 不推荐：一次性要求太多
"给用户模块添加头像上传功能，顺便把登录页的样式改一下，
还有那个搜索框的防抖也加上，对了密码重置的邮件模板也更新一下。"

# 推荐：分步进行
第 1 步："在 UserProfile 组件中添加头像上传功能，使用 S3 存储"
第 2 步："更新登录页样式，参考 @docs/design-spec.md 中的设计稿"
第 3 步："给搜索框添加 300ms 防抖，使用自定义 hook"
第 4 步："更新密码重置邮件模板，参考 @src/templates/welcome.html 的风格"
```

### 让 Claude 先看再改

处理已有代码时，先让 Claude 理解代码再动手修改，效果远比直接修改好：

```
# 第一步：先理解
"阅读 @src/services/payment-service.ts，告诉我现在支付流程的处理逻辑，
特别是错误处理和重试机制。不要改任何代码。"

# 第二步：再规划
"基于你的理解，我想添加微信支付渠道。请制定修改方案，列出需要改动的地方。"

# 第三步：执行修改
"方案看起来没问题，开始执行吧。先改 payment-service.ts。"
```

### 用 Plan Mode 处理复杂任务

对于涉及多个文件的大型任务，使用 Plan Mode（按 `Shift+Tab` 切换）让 Claude 先制定计划：

```
[Plan Mode]
我需要给现有系统添加 RBAC（基于角色的访问控制）权限系统。
现在用户只有 admin 和 user 两种角色，我需要支持自定义角色和细粒度权限。
请先分析现有代码，制定详细的实施计划。
```

Claude 会生成一份分步计划，你确认后再切换回正常模式逐步执行。

### 善用 /clear 和 /compact

这两个命令是上下文管理的核心工具：

```bash
/compact    # 压缩当前对话历史，保留关键信息，释放上下文空间
/clear      # 彻底清空对话历史，从零开始

# 使用时机：
# - 切换到完全不同的任务 → /clear
# - 同一任务但对话太长 → /compact
# - 感觉 Claude 的回复变差了（上下文过载）→ /compact
# - 刚完成一个功能，要开始下一个 → /clear
```

> **重要原则**：当你换一个话题时，一定要先 `/clear`。残留的旧上下文不仅浪费 token，还可能让 Claude 的回复受到干扰。

## 代码审查最佳实践

Claude Code 不仅能写代码，还能帮你审查代码。

### 使用 /review 命令

快速审查当前 Git 变更：

```
/review
```

Claude 会检查所有未提交的更改，指出潜在问题：
- 逻辑错误和边界情况
- 安全隐患（SQL 注入、XSS 等）
- 性能问题
- 代码风格不一致
- 缺少错误处理

### 让 Claude 写测试验证修改

修改代码后，让 Claude 写测试来验证：

```
我刚才修改了 @src/services/order-service.ts 中的取消订单逻辑。
请为这个方法编写单元测试，覆盖以下场景：
1. 正常取消待发货订单
2. 尝试取消已发货订单（应该失败）
3. 取消不存在的订单
4. 并发取消同一订单
```

### 多轮审查工作流

对于重要的代码变更，可以进行多轮审查：

```
# 第一轮：整体审查
"审查 @src/services/payment-service.ts 的最新改动，
重点关注安全性和错误处理。"

# 根据反馈修改后，第二轮：
"请重新审查修改后的代码，这次重点关注性能和边界情况。"

# 第三轮（可选）：对比审查
"对比修改前后的代码，确认所有问题都已修复，没有引入新问题。"
```

## 调试最佳实践

Bug 修复是 Claude Code 的强项之一。掌握正确的调试姿势，能让 Claude 帮你更快定位问题。

### 提供完整的错误日志

不要只给 Claude 看错误信息的最后一行，提供完整的上下文：

```
运行 pnpm build 时报错了，完整错误日志如下：

```
Type error: Argument of type 'string | undefined' is not assignable
to parameter of type 'string'.
  Type 'undefined' is not assignable to type 'string'.
  > 42 |   const user = await getUser(session.userId)
       |                                      ^^^^^^^
  43 |   return NextResponse.json(user)
```

这个错误发生在 @src/app/api/user/route.ts 中。
我怀疑是 session 类型定义的问题，请帮我检查。
```

### 分步调试：先诊断后修复

别急着让 Claude 直接修复，先让它诊断：

```
# 第一步：诊断
"用户报告登录后偶尔会跳转到 404 页面。
请检查 @src/middleware.ts 和 @src/app/(auth)/layout.tsx，
分析可能导致这个问题的原因。先不要修改代码。"

# 第二步：确认原因后再修复
"你的分析很有道理，确实是 session 过期时重定向逻辑有问题。
请修复这个问题，同时添加适当的错误日志方便后续排查。"
```

### 用截图辅助

Claude Code 支持读取截图，对于 UI 相关的 bug 特别有用：

```
看看这张截图 @screenshot.png，表格的最后一列文字被截断了。
请检查 @src/components/DataTable.tsx 中的样式，修复这个问题。
```

在终端中，你可以直接拖拽图片到 Claude Code 的输入区域，它会自动处理。

## Git 工作流最佳实践

Claude Code 与 Git 深度集成，善用这些特性能让版本管理更轻松。

### 使用 /commit 自动生成提交消息

Claude 会分析你的代码变更，自动生成规范的提交消息：

```
/commit
```

生成的提交消息通常包含：
- 变更类型前缀（feat、fix、refactor 等）
- 简洁的变更描述
- 影响范围说明

如果你对自动生成的消息不满意，可以要求修改：

```
/commit
# Claude 生成的消息不够好？
"提交消息请更详细一些，说明为什么要改这个逻辑"
```

### 功能分支 + PR 工作流

推荐的工作流程：

```bash
# 1. 创建功能分支
git checkout -b feature/order-cancel

# 2. 启动 Claude Code 开发
claude

# 3. 开发过程中多次小步提交
> "实现取消订单的基本逻辑"
> /commit

> "添加取消原因字段和验证"
> /commit

> "添加取消订单的单元测试"
> /commit

# 4. 完成开发，创建 PR
> 为当前分支创建 Pull Request，总结所有提交的变更，生成规范的 PR 描述
```

### 避免在 main 分支直接修改

```
# 在 CLAUDE.md 中添加这条规则：
## Git 规范
- 所有修改必须在功能分支上进行，不要直接修改 main 分支
- 分支命名：feature/xxx、fix/xxx、refactor/xxx
- 提交前运行 `pnpm lint && pnpm test` 确保没有问题
```

写入 CLAUDE.md 后，Claude 会自动遵守这些规则。如果你不小心在 main 分支让它修改代码，它会提醒你先创建分支。

## 团队协作最佳实践

Claude Code 在团队中使用时，统一规范能让协作更顺畅。

### 共享 CLAUDE.md 规范

将 CLAUDE.md 提交到 Git 仓库，团队成员共享同一份项目配置：

```bash
# 项目根目录的 CLAUDE.md → 提交到 Git
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md project configuration"

# 个人偏好的配置 → 放在 .claude/CLAUDE.md，加入 .gitignore
echo ".claude/CLAUDE.md" >> .gitignore
```

**团队 CLAUDE.md 应包含：**
- 项目技术栈和架构说明
- 编码规范和命名约定
- 常用命令和脚本
- 目录结构说明
- 团队约定（分支策略、提交规范、review 流程）

**个人 .claude/CLAUDE.md 可以包含：**
- 个人编码偏好
- 常用代码片段
- 特定开发环境配置

### PR Review 标准化

在 CLAUDE.md 中定义 PR review 标准，让 Claude 执行一致的审查：

```markdown
## PR Review 标准
审查代码时请检查以下方面：
1. **功能正确性**：是否完整实现了需求
2. **错误处理**：是否覆盖了异常情况
3. **安全性**：是否有 SQL 注入、XSS、权限绕过等风险
4. **性能**：是否有不必要的数据库查询、内存泄漏
5. **测试覆盖**：新增代码是否有对应测试
6. **代码风格**：是否符合项目规范
7. **文档**：公共 API 是否有 JSDoc 注释
```

### 代码风格一致性

通过 CLAUDE.md 强制统一代码风格：

```markdown
## 代码风格
- 命名：组件用 PascalCase，函数/变量用 camelCase，常量用 UPPER_SNAKE_CASE
- 文件名：组件文件用 PascalCase（如 UserAvatar.tsx），其余用 kebab-case
- import 顺序：React → 第三方库 → 内部模块 → 类型 → 样式
- 函数最大行数：50 行，超过请拆分
- 组件 props 超过 3 个时用 interface 定义
```

## 进阶技巧汇总

以下是一些资深用户积累的高级技巧：

### 自定义 Slash 命令

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

```bash
# .claude/commands/review-security.md
请对以下代码进行安全审查，重点检查：
1. SQL 注入风险
2. XSS 攻击面
3. CSRF 防护
4. 权限校验是否完整
5. 敏感数据是否加密
6. 日志中是否泄露敏感信息

检查范围：$ARGUMENTS
```

使用时：

```
/review-security @src/app/api/
```

### 多文件协同修改

需要同时修改多个文件时，给 Claude 清晰的全局视图：

```
我需要给订单系统添加优惠券功能，涉及以下文件：
- @src/types/coupon.ts — 新建，定义优惠券类型
- @src/services/coupon-service.ts — 新建，优惠券业务逻辑
- @src/services/order-service.ts — 修改，在结算时应用优惠券
- @src/app/api/coupons/route.ts — 新建，优惠券 API
- @prisma/schema.prisma — 修改，添加 Coupon 模型

请按照上面的顺序依次处理，每完成一个文件告诉我。
```

### 利用 Extended Thinking

对于复杂的架构决策，让 Claude 使用扩展思考：

```
[使用 Opus 模型]
我在考虑把现在的 REST API 迁移到 GraphQL。
请深入分析利弊，考虑以下因素：
1. 现有 50+ 个 API 端点的迁移成本
2. 前端查询优化的收益
3. 缓存策略变化
4. 团队学习曲线
5. 与现有 React Query 的集成方案

不需要写代码，给我一份详细的技术分析报告。
```

### 让 Claude 自己验证

养成让 Claude 验证自己修改的习惯：

```
修改完成后，请：
1. 运行 pnpm lint 检查是否有格式问题
2. 运行 pnpm test 确认没有破坏现有测试
3. 如果有类型错误，自己修复
```

## 常见误区

最后，列举一些应该避免的做法：

| 误区 | 正确做法 |
|------|---------|
| 把整个文件内容粘贴到对话中 | 用 `@文件路径` 引用 |
| 一个提示让 Claude 做 5 件事 | 一次做一件，分步进行 |
| 描述需求时含糊不清 | 给出具体的文件、行为、预期结果 |
| 不用 CLAUDE.md | 花 10 分钟写好，节省后续无数时间 |
| 从不 /clear 或 /compact | 换话题时 /clear，对话长时 /compact |
| 不让 Claude 理解就直接改 | 先读代码，再规划，最后执行 |
| 只用 Opus 做所有事情 | 日常用 Sonnet，复杂决策才用 Opus |
| 出错了反复重试同样的命令 | 换个思路，提供更多上下文 |

掌握这些最佳实践需要时间，建议你先从最基本的几点开始：创建 CLAUDE.md、清晰描述需求、一次做一件事。这三点就能显著提升你的使用体验。随着使用的深入，再逐步应用更多进阶技巧。