Claude Code 最佳实践 —— 用好 AI 编程的 20 条法则

---

入门教程
https://blog.csdn.net/qq_41187116/article/details/161903118?spm=1001.2014.3001.5501 教的是「CC 能做什么」，这篇教的是「怎么把 CC 用出花」。
每一条都是真金白银换来的经验。

---

一、心法篇 —— 使用 CC 的正确姿势

法则 1：你不是在「写代码」，你是在「做 Code Review」

这是用好 CC 最核心的心态转变。

新手做法                          老手做法
═══════════════════════          ═══════════════════════

"帮我写个登录功能"               "帮我写个登录功能"
        ↓                               ↓
盯着屏幕等 AI 输出                 打开手机刷两条微博
        ↓                               ↓
"好像能用，过"                    回来看一眼输出
        ↓                               ↓
（从不检查细节）                   跑一遍测试 → 读关键逻辑
                                      ↓
                                  "这里边界条件没处理，
                                   这里异常没兜底，
                                   这个 SQL 可能慢，
                                   改一下再给我看"

你自己写的代码你会仔细测试，AI 写的代码凭什么不？

CC 写代码的速度是你的 10 倍，但它的代码质量大概是你能力的 70%-90%。你的价值不是打字快，而是判断力——知道什么是对，什么是错，什么需要改。

实践要诀：

• AI 交代码后，先让它自己跑测试。测试不过，直接让它修，你看都不要看。
• 测试过了，你只读三个地方：入口参数校验、核心业务逻辑、异常处理。其他地方扫一眼就行。
• 看到不懂的代码就让它解释。你在审代码，审的人有权要求解释。

---

法则 2：把 AI 当作一个「聪明但没见过世面的实习生」

这个实习生：

• 知识面极广（读过 GitHub 上几乎所有开源代码）
• 学习能力极强（你教一次就能记住）
• 但没见过你的代码库，也不了解你的业务上下文
• 而且会自信满满地犯错

所以你对待它的方式应该是：

✅ 好的做法                    ❌ 坏的做法
─────────────────────────     ─────────────────────────
给它足够的上下文               甩一句话就走
教它你的项目规范               指望它自动猜到你的习惯
分步引导，逐步深入             一次性提 10 个需求
验证关键步骤                   盲目信任输出

---

法则 3：越具体的需求，越好的输出

这是一个被反复验证的规律：

模糊的需求                       具体的需求
─────────────────────────       ─────────────────────────
"给我写个工具类"                 "写一个 StringUtils 工具类，
                                 放在 com.example.common.util 包下，
                                 和项目中已有的 DateUtils 风格一致。
                                 先读一下 DateUtils 再写。"

"这个接口太慢了，优化一下"       "GET /api/users/list 接口耗时 2.3s，
                                 看了一下日志，慢在数据库查询。
                                 用 EXPLAIN 分析一下，看看能不能加索引。
                                 先别改代码，告诉我你的分析。"

具体的需求不是让你写更多字，而是消除 AI 的猜测空间。 AI 猜的越多，错的越多。

---

法则 4：用 CLAUDE.md 建立「持久上下文」

前面说了 AI 像个实习生——CLAUDE.md 就是你的《新员工手册》。不用每次重复同样的要求。

一个真正有用的 CLAUDE.md 只写三样东西：

# CLAUDE.md

## 1. 技术栈（让 AI 知道用什么写）
- Java 11, Spring Boot 2.7, MyBatis-Plus 3.5
- 构建用 Maven，部署用 Docker

## 2. 硬性规范（让 AI 不犯错）
- API 路径必须 `/api/v1/` 开头
- 密码必须 BCrypt，SQL 必须参数化
- Controller 不写业务逻辑，只做转发

## 3. 常用命令（让 AI 自己能跑）
- 编译：mvn compile -DskipTests
- 单测：mvn test -Dtest=类名
- 启动：mvn spring-boot:run

不要写的：

• “写出高质量的代码”——这是废话，AI 本来就会尽量写好的
• “遵循最佳实践”——太抽象，AI 无法执行
• 5000 字的项目背景介绍——AI 的注意力也有限，重点越多越记不住

一个判断标准：CLAUDE.md 中的每条规范，能不能用一个「对/错」来验证？能，留下。不能，删掉。

---

法则 5：用 /init 生成初稿，再手改

/init 能快速生成 CLAUDE.md 的骨架，但它不了解你的偏好。执行后自己改一遍：

/init
# Claude Code 扫完项目，生成初版 CLAUDE.md

# 然后你说：
> 把 CLAUDE.md 里的废话删掉，只保留技术栈、编码规范和命令三部分。
   加上一条：和数据库相关的操作，必须先给我看 SQL 再执行。

---

二、对话篇 —— 每次交互都高效

法则 6：一个好的需求包含三要素

结构化的需求格式
═══════════════════════════════════

  1. 上下文：在哪个文件/模块/功能里？
  2. 目标：要做什么？期望的结果是什么？
  3. 约束：有哪些限制条件？

实例：

> 在 UserService.java（上下文）中
  添加一个修改邮箱的功能（目标），
  要求：
  - 新邮箱不能和已有用户的邮箱重复
  - 修改后发送验证邮件（先留一个 TODO，邮件功能还没实现）
  - 方法加上事务注解 @Transactional
  （约束）

> （Claude Code 一次到位）

---

法则 7：复杂任务先让它「说方案」，再让它「写代码」

这是新手最容易跳过的步骤，也是最容易翻车的步骤。

你：帮我重构 UserService，把所有业务逻辑拆到不同的 Service 里

AI：（一通操作猛如虎，改了 15 个文件）

你：等等，我不是这样想的……

正确的做法：

你：帮我分析一下 UserService，如果要按职责拆分成多个 Service，
   你会怎么拆？先给我方案，不要改代码。

AI：（列出一个拆分方案，3 个新的 Service 类的职责划分）

你：方向可以。但 EmailService 不要单独拆，邮件逻辑还很简单。
   另外 UserQueryService 这个名字不好，叫 UserReadService。

AI：明白，更新方案如下……

你：可以，按这个方案执行。

你省下的是「推倒重来的 30 分钟」，花掉的是「确认方案的 2 分钟」。

---

法则 8：新人上手项目，先让 AI 带你读代码

进一个新项目，最难的永远是「理解现有代码在干嘛」。别自己闷头读：

> 帮我分析这个项目的整体架构。先读 pom.xml 了解技术栈和依赖，
  然后读 application.yml 了解配置，最后读主要的 Controller 类，
  用中文给我讲清楚这个项目是做什么的、怎么分层的、数据怎么流转的。

> 这个 UserController 里的 getUserOrders 方法逻辑有点复杂，
  帮我画一个调用链路图，从 Controller → Service → Mapper → SQL，
  每一步做什么用一句话说明。

> 项目中关于「订单状态」的处理分布在哪些文件里？帮我列出来，
  每个文件是和订单状态的哪个方面相关的。

把 AI 当成代码导游，而不是只把它当成代码打字机。

---

法则 9：善用 /compact，别硬撑

对话到 50 轮以上，AI 响应变慢、开始「忘记」早期内容——这时候 /compact 比任何 prompt 技巧都管用。

什么时候该 compact？
═══════════════════════

  ✅ AI 开始「忘事」——你明明说过要用 MyBatis，它给你写 JDBC
  ✅ 回复明显变慢
  ✅ 输出质量下降，开始写一些很「模板化」的代码
  ✅ 上下文使用超过 60%

/compact 不会丢项目信息（CLAUDE.md、文件内容不会丢），丢的只是早期对话的细枝末节。该压就压，别心疼。

---

法则 10：给 AI 看错误信息，不要自己翻译

❌ "运行报了一个什么 null 的错误，好像是空指针"
✅ （直接把整个 stack trace 粘贴过来）

完整的错误信息包含了精确的：

• 错误类型（NullPointerException / SQLException / …）
• 出错位置（文件名 + 行号）
• 调用链（谁调了谁）

AI 需要的是原始数据，不需要你来总结。你总结的过程中反而可能漏掉关键信息。

---

三、代码篇 —— 让 AI 写出好代码

法则 11：让 AI「模仿现有代码风格」

AI 最擅长的不是创造，是模式匹配。给它一个样本，它比你自己写规范文档还有效。

> 先读一下 UserController.java 和 UserService.java，
  然后按照一模一样的风格（注释格式、命名习惯、异常处理方式），
  给我写 ProductController 和 ProductService。

这样写出来的代码和你已有的代码放在一起，看不出是两个人写的。

这比在 CLAUDE.md 里写 500 字的代码规范有效得多。

---

法则 12：一个需求一个需求来，不要批量

❌ "帮我写用户注册、登录、修改密码、找回密码、邮箱验证、手机绑定……"
✅ "帮我写用户注册" → 验收 → "好，接着写登录" → 验收 → ...

为什么？

• 上下文干净：AI 的注意力是有限资源，一次塞太多会顾此失彼
• 出错好修：一个问题修一个地方，而不是 10 个功能都坏在一起
• 你能跟上：每一步你都理解做了什么，不会最后面对一堆不认识的新文件

---

法则 13：写好测试是你的安全网

AI 写代码很快，但改代码时可能引入回归问题。让 AI 自己写测试，然后每次改代码后跑测试——这是最低成本的防错机制。

> 写完这个功能后，给我写对应的单元测试，
  覆盖正常情况、边界情况（空值、null、超长字符串）、异常情况。

> 改完后运行 mvn test，确保之前的功能没问题。

把「改代码→跑测试→发现失败→AI 修→再跑测试」变成一个自动循环，你不用插手。你只需要在测试全绿的时候做最后的 Code Review。

---

法则 14：重构别一步到位，做「渐进式重构」

❌ "帮我把整个项目从 MyBatis 迁移到 JPA"
   （100 个文件同时改 → 出了事根本回不去）

✅ "先把 UserMapper 改成 UserRepository 试一下"
   → 验证通过
   → "好，接下来改 ProductMapper"
   → 验证通过
   → ...

每次只改一个小的、可验证的单元。每次改完跑测试。确保每一步都是可以安全回退的。

---

四、工具篇 —— 把 CC 的能力用到极致

法则 15：搜索优于猜测

不确定某段代码在哪、某个方法被谁调用、某个配置在哪生效——不要猜，让 AI 搜。

> 帮我找出项目中所有直接调用 userMapper.findById 的地方

> 帮我搜一下 application.yml 中所有和 redis 相关的配置

> 找一下项目中哪个地方定义了 OrderStatus 枚举

你知道的信息和 AI 知道的信息有差距时，就会产生 Bug。搜索是消除信息差的唯一方式。

---

法则 16：让 AI 帮你读 Git 历史

> 帮我看看最近 3 次提交改了哪些文件，总结一下每次提交做了什么

> 帮我看看 src/main/java/com/example/UserService.java 这个文件
  最近半年谁改过，每次改了什么内容

> 帮我对比一下 feature/new-payment 分支和 main 分支的差异，
  重点关注和数据库相关的改动

理解「一段代码是怎么变成今天这样的」往往比「这段代码现在长什么样」更重要。Git + CC = 代码考古利器。

---

法则 17：复杂查询让 AI 写 SQL，但执行前先审查

> 帮我写一个查询：
  统计过去 30 天，每个商品分类下，
  订单金额排名前 10 的用户，按总消费金额降序排列。
  先给我看 SQL 和执行计划，不要直接跑。

写 SQL 是 AI 的强项，但执行 SQL 必须经过你的审查。 尤其是涉及 UPDATE/DELETE 的时候。

---

五、避坑篇 —— 那些让你怀疑人生的瞬间

法则 18：AI 会「编造」不存在的 API

这是 AI 最常见的错误——它见过太多代码，可能会混用不同版本的 API 或者「发明」一个看起来合理但不存在的类/方法。

怎么防范？
═══════════════════════════

  1. 每写完一个功能，立即编译：mvn compile
     编译不过 → 说明引用了不存在的类或方法
  2. 跑测试，不只是单元测试，还要跑集成测试
  3. 看到不认识的 import，让 AI 解释它是哪个依赖提供的

编译器和测试是你最好的朋友。它们不会像 AI 一样「自信地犯错」。

---

法则 19：代码越改越烂怎么办？果断重启

有时候 AI 会陷入一种状态：越修 bug 越多，越改越复杂。这时候不要继续修修补补。

> 刚才的修改方向不对。请回到修改之前的状态，
  我们换个思路重新做。（配合 git checkout 或备份恢复）

或者更直接：

> /clear    （清掉糟糕的讨论，重新开始）

一个干净的新对话 + 明确的需求 > 在一个混乱的对话中修修补补。

---

法则 20：不要在同一个对话里做两个不相干的任务

❌ 一个对话里：
   写登录 → 修 CSS 样式 → 改数据库索引 → 部署配置 → 写文档

✅ 一个对话一个主题：
   对话 1：用户认证模块（注册+登录+登出）
   对话 2：前端样式优化
   对话 3：数据库性能调优

为什么？AI 会根据整个对话的上下文来理解你的项目。上下文里塞满了不相关的东西，AI 会「分心」，输出质量下降。而且 /compact 的时候也不会把不同主题的内容搅在一起。

一个对话 = 一个主题。完成就 /clear，下一个。

---

六、速查清单

每次开始新任务前

• /context 看看上下文用量，超过 60% 就 /compact
• 和上一个任务是同一主题吗？不是就 /clear
• 需求说清楚了吗？（上下文 + 目标 + 约束）

AI 交代码后

• mvn compile（或对应语言的编译）通过了吗？
• 测试跑过了吗？
• 我自己看了核心逻辑吗？（入口校验 + 业务逻辑 + 异常处理）

遇到问题时

• 把完整的错误信息给 AI 了吗？（不是我的总结）
• 让 AI 先分析原因再动手修了吗？
• 修完后跑了相关测试吗？

对话管理

• 过 10 轮左右看看 /context，高了就 /compact
• 一个主题搞定了就 /clear
• CLAUDE.md 还是准的吗？（项目变了，它也得跟着变）

---

最后的话

Claude Code 是一个「力量放大器」。你给它 1 分的判断力，它还你 10 分的产出。你给它 0 分的判断力，它也还你 0 分——只是速度快一点。

这些法则没有一条是关于「怎么让 AI 更聪明」的，全都是关于「你怎么更聪明地使用 AI」。 因为 AI 已经够聪明了，缺的不是算力，是你驾驭它的方法。

---

本指南版本：v1.0 | 2026 年 7 月
前置阅读：CC入门课程.md