用 Claude Code 做 Java 重构，卡住的地方往往不是技术，而是怎么说：同样一个任务，换种表达方式，结果可能差很远。
这篇专门聊提示词这件事。不讲原理，直接给模板和对比——哪种写法有效，哪种写法浪费时间，为什么。
一、提示词的本质：给 AI 一个"可执行的规格说明"
工程师写代码时，最重要的是需求说清楚。给 Claude Code 写提示词也是同理。好的提示词应该包含：
[上下文] + [目标] + [约束] + [验收标准]
坏提示词 vs 好提示词对比
坏例子1：太模糊
帮我优化 UserService
好例子1：明确具体
[上下文] UserService.getUserById() 目前每次调用都直接查数据库，
在高并发场景下导致数据库压力过大。
[目标] 为该方法添加 Redis 缓存，缓存用户基本信息。
[约束]
- 缓存 key 格式：user:info:{userId}
- 缓存时间：30分钟
- 用户信息更新时必须主动淘汰缓存（在 updateUser() 方法中）
- 缓存的数据是 UserInfoDTO，不是完整的 User Entity（避免敏感字段被缓存）
[验收标准]
- 修改后的代码能通过现有的 UserServiceTest
- 添加一个新测试：验证缓存命中时不访问数据库
坏例子2：指令不清晰
这段代码有问题，帮我看看
好例子2：描述症状和期望
[症状] OrderService.createOrder() 在并发测试中出现库存超卖：
压测10000个并发下单请求，商品库存50，实际成功下单了87个。
[相关代码] 在 OrderService.java 第 234-280 行
[期望行为] 使用 Redis 分布式锁确保同一商品的库存扣减串行执行
[约束]
- 锁的 key：lock:inventory:{productId}
- 锁超时：5秒（避免死锁）
- 等待锁时间：100ms（超过则返回"商品抢购中，请稍后重试"）
- 使用 Redisson 实现（项目已有 Redisson 依赖）
二、场景化提示词模板库
模板1：代码分析类
## 代码分析模板
请分析 [类名/文件路径]，按以下维度评估：
**代码质量**
- 单一职责：该类有几个明显的职责？
- 复杂度：最复杂的方法是哪个（圈复杂度估算）？
- 重复代码：有哪些逻辑重复出现？
**设计问题**
- 是否违反了 SOLID 原则？具体在哪里？
- 是否有明显的设计模式可以改善？
**风险点**
- 哪些方法在重构时需要特别小心？为什么？
**建议**
- 如果只能做一件事，最值得改进的是什么？
- 完整重构的话，建议分几步，每步的风险如何？
模板2：功能实现类
## 功能实现模板
**需要实现的功能：** [简短描述]
**输入：** [参数类型、格式、约束]
**输出：** [返回类型、格式、可能的错误情况]
**业务规则：**
1. [规则1]
2. [规则2]
3. [边界情况处理]
**技术约束：**
- 必须使用：[特定框架/库]
- 不能使用：[禁止的方式]
- 性能要求：[如果有]
**参考现有代码：** [类似功能的参考实现，让 AI 保持一致的代码风格]
**测试要求：**
- 需要覆盖的测试场景：[列出关键场景]
模板3：重构类
## 重构模板
**当前状态：** [描述现有代码的问题]
**重构目标：** [描述期望的最终状态]
**不能改变的（约束）：**
- 对外 API 接口保持不变（HTTP端点、方法签名）
- 数据库表结构不变（如果是 Entity 重构）
- [其他硬约束]
**可以改变的：**
- 内部实现方式
- 类的组织方式
- [其他]
**执行方式：**
- 请先给出完整计划，不要直接执行
- 分 [N] 步完成，每步完成后停下来等我确认
- 每步完成后运行 mvn compile 验证编译通过
**风险控制：**
- 涉及的测试文件：[列出]
- 请在最后运行 [测试命令] 确认回归
模板4：问题调试类
## 调试模板
**症状描述：**
- 错误信息：[粘贴完整的 stack trace 或错误日志]
- 触发条件：[什么操作导致了这个错误]
- 发生频率：[偶发/稳定复现/特定条件下]
**已排查的方向（没有问题的地方）：**
- [你已经检查过的地方，帮 AI 避免重复检查]
**相关代码：**
- 主要可疑位置：[文件名 + 行号]
- 相关配置：[如果是配置问题]
**期望：**
1. 先解释为什么会出现这个问题
2. 给出修复方案
3. 说明如何验证修复是否有效
三、高阶技巧：让 Claude Code 自我约束
技巧1：要求 AI 先思考再行动
对于复杂任务，加上"先分析，后执行"的指令：
在开始写任何代码之前，请先：
1. 用你自己的话重述你理解的任务（确认我们在同一频道）
2. 列出你计划修改的文件清单
3. 识别可能的风险和依赖
4. 给出执行时间估计（粗略）
只有在我确认你的理解正确之后，才开始执行。
技巧2：要求 AI 说明理由
在做任何架构决策时，请用以下格式说明：
决策：[你做了什么选择]
原因：[为什么选择这个方案而不是其他方案]
风险：[这个选择有什么潜在问题]
替代方案：[还考虑过哪些其他方案，为什么没选]
这迫使 AI 进行更深入的思考，而不是输出第一个想到的方案。
技巧3：设定"停止条件"
在长任务中设定检查点：
执行过程中，如果遇到以下任何情况，请立即停止并询问我：
1. 发现需要修改 payment 模块的任何文件
2. 发现某个修改会影响超过 20 个文件
3. 发现你不确定的业务逻辑（宁可问我也不要猜）
4. 编译失败且你不确定如何修复
技巧4：渐进式授权
不要一开始就给 AI 太大权限，逐步放开：
第一轮：请只读取代码，给我分析报告，不要修改任何文件
第二轮：（确认分析无误后）请修改 OrderQueryService.java，只修改这一个文件
第三轮：（确认效果后）请继续完成剩余的 3 个文件修改
四、调试 Claude Code 的输出
当 Claude Code 给出的方案不符合预期时，这里有几种纠正策略：
策略1：指出具体问题
❌ 无效的反馈：
这个方案不对，重新做
✅ 有效的反馈：
你生成的 OrderCreationService 有两个问题：
1. 第 45 行：你用了构造器注入，但我们项目统一用 @Autowired 字段注入
（见 CLAUDE.md 中的编码规范）
2. 第 78 行：createOrder() 方法缺少 @Transactional 注解，
这是必须的，因为它包含多个数据库写操作
请修正这两处，其他部分保持不变。
策略2：提供反例约束
你生成的代码风格和我们项目不一致。
请看 ProductService.java 中的 createProduct() 方法，
那是我们希望的风格：
- 日志记录的位置和格式
- 异常处理的方式
- 注释的详细程度
请用相同的风格重写 OrderCreationService.createOrder()
策略3：分解复杂任务
当 Claude Code 在复杂任务上表现不佳时：
我发现你对整个重构任务感到困惑，让我们把它分解。
先只关注一件事：
把 OrderService 第 100-150 行的 calculateDiscount() 方法
提取到 PromotionService 中。
其他所有的变更先不管。
策略4：要求解释后再执行
在执行这个修改之前，请先用代码注释的方式解释你的思路：
在每个关键步骤上加注释说明"为什么这样做"，
让我审查你的逻辑之后再决定是否执行。
五、Spring 特有的提示词技巧
5.1 精确指定 Spring 版本和特性
不同版本的 Spring 有不同的最佳实践：
注意：我们使用 Spring Boot 3.2 + Java 21。
请使用以下新特性（不要使用旧式写法）：
- 使用 Java Record 定义 DTO 而不是 Lombok @Data class
- 使用 @RestControllerAdvice 而不是 @ControllerAdvice
- 如果有虚拟线程（Virtual Thread）的适用场景，请使用
- 使用 Spring Data JPA 的 Interface-based Projection 而不是 @Query 返回 Map
5.2 指定注解使用规范
关于事务注解，我们的规范如下：
- 只读查询方法：@Transactional(readOnly = true)
- 写操作方法：@Transactional（不带参数，使用默认的 REQUIRED 传播级别）
- 特殊情况需要 REQUIRES_NEW：只有在需要独立事务的审计日志写入时使用
- 不在 Controller 层使用 @Transactional
请按照这个规范生成代码。
5.3 处理复杂的 MyBatis/JPA 混用场景
很多遗留项目同时使用 JPA 和 MyBatis：
这个项目混用了 Spring Data JPA 和 MyBatis Plus。
以下是分工规范，请严格遵守：
- 简单的 CRUD 操作：使用 JPA Repository
- 复杂的多表关联查询：使用 MyBatis Plus 的 Wrapper 或 XML Mapper
- 报表类查询（涉及聚合函数、复杂 GROUP BY）：一定用 XML Mapper
- 禁止在同一个 Repository 类中混用两种方式
在重构 OrderRepository 时，请按照上述规范决定每个方法用哪种方式实现。
六、提示词的"元技巧"：与 AI 建立共同语言
在长期合作中，建立专属的"项目词汇表"能大幅提升效率：
在 CLAUDE.md 中添加术语表：
## 项目术语表（Claude Code 必读）
**"门面重构"** = 保持类的对外接口不变，将内部实现委托给新的子类
**"核心链路"** = 用户下单到支付完成的完整流程，任何修改都需要格外小心
**"灰度接口"** = 需要同时支持 v1 和 v2 两个版本的接口
**"四层架构"** = 我们的 Controller → Service → Repository → Entity 分层
**"老板说别动"** = 指 legacy/ 目录下的代码，任何情况下不要修改
当我说"用门面重构处理 XXX"，你应该知道具体怎么做。
七、避免常见的提示词错误
错误1：假设 AI 有先验知识
❌ 错误：
按照公司的编码规范处理异常
（Claude Code 不知道"公司规范"是什么）
✅ 正确：
处理异常时：
1. 捕获 Exception 后用 log.error("操作失败，原因：{}", e.getMessage(), e) 记录日志
2. 向上层抛出 BusinessException（不要吞掉异常）
3. 不使用 e.printStackTrace()
错误2：一次要求太多
❌ 错误（容易出错）：
帮我重构整个 order 模块，把所有问题都修掉，
包括性能优化、代码拆分、测试补充、异常处理统一...
✅ 正确（分解任务）：
今天只做一件事：把 OrderService 中所有的日志记录方式统一。
目标是：所有 log.info 调用都使用参数化格式（用 {} 占位符而不是字符串拼接）。
涉及文件：只改 OrderService.java。
错误3：没有提供错误信息的完整上下文
❌ 错误：
编译报错了，怎么回事
✅ 正确：
编译报错，完整错误信息如下：
[ERROR] /src/main/java/com/example/order/service/OrderCreationService.java:[45,8]
error: cannot find symbol
symbol: class InventoryLockRequest
location: class OrderCreationService
这个类在重构前存在于 OrderService 内部，可能在提取时遗漏了。
请找到这个类应该放在哪里，并修复这个编译错误。
八、效率提升：Claude Code 的高级用法
8.1 批量处理相似任务
项目中有 15 个类需要做同样的改造：添加统一的日志格式。
我只需要描述一次，你按照相同的模式处理所有 15 个类。
改造规则：
1. 在类级别添加：private static final Logger log = LoggerFactory.getLogger(XXX.class);
2. 所有 System.out.println 改为 log.info
3. 所有 e.printStackTrace() 改为 log.error 格式
需要改造的类列表：
[粘贴文件列表]
每完成一个告诉我，让我看一眼再继续下一个。
8.2 使用 /compact 命令压缩上下文
当会话变得很长时，Claude Code 提供 /compact 命令来压缩历史对话，保留关键信息：
/compact
（之后继续新任务，Claude Code 会在压缩后的上下文基础上工作）
8.3 并行工作流
对于相互独立的模块，可以让多个 Claude Code 会话并行工作：
# 会话1（专注 order 模块）
处理 order 模块的重构，不要碰其他模块
# 会话2（专注 product 模块）
处理 product 模块的重构，不要碰其他模块
# 合并时，再开一个会话处理集成问题
两个模块都重构完了，现在帮我检查它们之间的接口是否仍然兼容
最后说一点
整理这些模板时，有一个规律值得关注：好的提示词本质上就是好的需求说明。能把需求写清楚，AI 就能做好；需求说不清楚，换个人来做也一样。
所以有时候写提示词写不好，不一定是 AI 的问题——可能是你自己对这个任务的目标还没想清楚。把写提示词当成一次"逼自己把需求想清楚"的过程，往往会有意外收获。
速查表贴在这里，随时取用：
附录：常用提示词速查表
| 场景 | 提示词模板关键词 |
|---|---|
| 代码分析 | "按以下维度评估...SOLID原则...风险点...改进建议" |
| 安全重构 | "先给出计划，等我确认再执行...分N步...每步编译验证" |
| 发现问题 | "扫描所有...找出...按优先级排列" |
| 代码生成 | "参考[示例类]的风格...遵守CLAUDE.md中的规范" |
| 调试错误 | "完整的错误信息...触发条件...已排查的方向..." |
| 架构设计 | "给出3种方案...分析优缺点...推荐哪个并说明理由" |
| 测试生成 | "覆盖以下场景...使用JUnit5+Mockito...命名规范..." |
| 性能优化 | "在不改变外部行为的前提下...添加缓存/优化查询..." |
