Don’t Rush to Refactor a Legacy Java Project—Use Claude Code to Map the System First

Many Java developers fear not new projects but inheriting old Spring Boot systems that have been running for years without clear documentation, tests, or guidance. The article argues that the first thing to do when taking over such a project is not to modify code but to understand its structure.

Why the article avoids “AI writes code”

Recent AI‑Java posts focus on letting AI generate Controllers, DTOs, or unit tests, which no longer attracts readers. The real pain point is the common scenario of a newcomer facing dozens of packages, Controllers, Services, Mappers, configuration files, obscure table names, and missing documentation while the business is still live.

Step 1 — Read‑only analysis with Claude Code

Claude Code can read files, analyze project structure, and execute commands via sub‑agents. The recommended prompt is:

请你分析当前 Java Spring Boot 项目。
要求：
1. 只读取代码，不要修改任何文件。
2. 不执行会改变项目状态的命令。
3. 先识别项目使用的技术栈。
4. 再分析项目的模块结构。
5. 找出最核心的业务模块。
6. 找出主要入口 Controller。
7. 找出核心 Service。
8. 找出数据库访问层。
9. 找出配置文件。
10. 最后输出一份《项目初始理解报告》。
报告格式：
一、项目技术栈
二、模块结构
三、核心业务模块
四、主要接口入口
五、关键 Service
六、数据库访问方式
七、配置文件说明
八、初步风险点
九、下一步建议

This prompt forces Claude Code to stay in a read‑only mode and produce a structured “initial understanding report”.

Result — A report more useful than a README

An example output includes the tech stack (Spring Boot 2.7, MyBatis Plus, MySQL, Redis, RabbitMQ, XXL‑JOB, Maven multi‑module) and lists core business modules such as order‑api, order‑service, inventory‑service, etc., followed by identified risk points like complex cancellation logic, unclear idempotency in payment callbacks, long Service methods, and insufficient test coverage.

Step 2 — Map the business flow

After the module map, ask Claude Code to trace a critical flow (e.g., order creation) from the Controller down to Services, Mappers, Redis, message queues, and external calls, marking each step’s purpose, transaction boundaries, failure points, idempotency handling, and the most dangerous modification spots.

POST /api/orders/create
 ↓
OrderController.createOrder
 ↓
OrderAppService.create
 ↓
UserService.checkUserStatus
 ↓
CouponService.lockCoupon
 ↓
InventoryService.lockStock
 ↓
OrderDomainService.calculateAmount
 ↓
OrderRepository.save
 ↓
PaymentService.createPayOrder
 ↓
OrderEventPublisher.publishCreatedEvent

Step 3 — Identify high‑risk code

Prompt Claude Code to list classes/methods that should not be touched by newcomers, focusing on order, payment, inventory, permission, scheduled tasks, and message consumption. The output includes risk reasons, pre‑modification checks, and suggested tests (e.g., duplicate callbacks, signature errors, missing orders, already‑paid callbacks).

Step 4 — Find low‑risk clean‑up opportunities

Claude Code can also suggest easy wins such as removing unused imports, duplicate code, stale TODOs, dead methods, unclear logs, vague exception messages, and poorly named tests—areas that help a newcomer get familiar without affecting core logic.

Step 5 — Generate a living document

Instead of writing a full README, ask Claude Code to produce a developer‑focused document for a specific module (e.g., order module) that covers responsibilities, main interfaces, core classes, state flow, transactions, messages, scheduled tasks, risks, and verification checklists. The document is saved as a markdown file (e.g., docs/order‑module.md) after manual review.

Why not refactor immediately

The article warns against impulsively asking AI to refactor large classes or upgrade dependencies before understanding historical compatibility logic. Removing legacy conditionals (e.g., if (channel.equals("OLD_APP")) { // old version handling }) without full context can break production.

Minimal executable workflow

Run a read‑only analysis to get the initial report.

Pick a core business flow (order creation, payment callback, etc.) and map its call chain.

Ask for a high‑risk code scan.

Generate module‑level documentation.

Have experienced team members review the AI output.

Decide whether to make any code changes.

Conclusion

The key takeaway is that for legacy Java projects the most valuable use of AI is to help developers understand modules, business chains, risks, and safe entry points before attempting any code changes.