Preface
In backend development, refactoring legacy projects is widely regarded as a tough and high-risk task. Years of accumulated redundant code, non-standard coding styles, missing comments and incomplete test suites make routine maintenance and iteration extremely difficult. Even minor code modifications may trigger online failures.
A core internal approval service of an enterprise has been running stably for three years. Built on mainstream Java technology stacks, it handles a full range of office approval workflows. The project carries a huge code base and massive technical debt. Comprehensive refactoring and optimization were completed using Claude Code without disrupting online services, which greatly shortened the project cycle and improved the overall code architecture. Nowadays, developers can access premium AI programming capabilities via domestic API gateways like TreeRouter to streamline legacy code refactoring and daily development. Combined with real-world lessons from this project, it is easy to draw clear boundaries between AI tools and manual development.
1. Profile of the Legacy Approval System: A Challenging Legacy Project
This internal approval backend service adopts Spring Boot 2.7, MyBatis-Plus, MySQL 8.0 and Maven. It covers more than ten approval scenarios including leave applications, expense reimbursement and procurement, consisting of 11 core modules with a total of 32,000 lines of code.
The system operates normally, yet long-term iteration has led to severe code issues, making developers reluctant to make adjustments. The main problems are listed below:
- Excessive code bloat and redundancy: Core files have ambiguous responsibilities.
ApprovalControllercontains nearly 4,000 lines of code andApprovalServicehas over 8,000 lines. A large amount of irrelevant logic is piled into single files, which seriously violates the Single Responsibility Principle. - Poor code readability: The entire project lacks standardized comments. Method naming is chaotic, with confusing labels such as
doApprove,doApprove2anddoApproveNew. The business purpose of the code cannot be identified intuitively. - No quality assurance mechanism: The project has 0% unit test coverage. All function verification and online testing rely purely on manual operation, bringing substantial operational risks.
- Tight schedule: The full refactoring, optimization and testing had to be finished within two weeks, with zero interruption to online business.
Traditional manual sorting would take nearly a week just to sort out the messy legacy logic. Leveraging the intelligent features of Claude Code to handle code arrangement, standardization and template code generation cut down the total workload by three working days.
2. Core Value of AI Programming: Solving Refactoring Pain Points in Three Key Scenarios
AI tools excel at standardized, repetitive and mechanical development work, which perfectly matches the requirements of legacy project refactoring. Claude Code delivered remarkable performance in this project, resolving multiple refactoring challenges and improving code standardization and iteration efficiency. Integrating AI capabilities through API gateways such as TreeRouter also helps accelerate iteration for various development projects.
2.1 Parse Legacy Code and Generate Standard Documentation in Batches
Obscure legacy business logic is the biggest obstacle to refactoring. Manual line-by-line analysis and debugging are time-consuming and likely to cause misunderstanding. Claude Code can intelligently parse core methods and generate standard Javadoc comments without altering original logic, covering function descriptions, parameter explanations, return values and business rules.
Original Code
public Boolean doApprove(Long id, Integer status, String remark, Long operatorId) {
ApprovalRecord record = approvalMapper.selectById(id);
if (record == null || record.getStatus() != 1) return false;
record.setStatus(status);
record.setRemark(remark);
record.setOperatorId(operatorId);
record.setUpdateTime(new Date());
approvalMapper.updateById(record);
if (status == 2) notifyService.sendApproved(record);
else if (status == 3) notifyService.sendRejected(record);
return true;
}
Code with AI-generated Comments
/**
* Execute approval operation, update record status and trigger relevant notifications
* Only records pending approval (status=1) can be processed, including approval pass and rejection
* @param id Unique ID of the approval record
* @param status Target status (2-Passed, 3-Rejected)
* @param remark Approval comments
* @param operatorId ID of the operator
* @return Operation result; return false for invalid records or abnormal status
*/
public Boolean doApprove(Long id, Integer status, String remark, Long operatorId) {
// Original business logic retained
}
Over 80% of the auto-generated comments are accurate and only require minor tweaks. Comment arrangement across all modules, which once took days, was completed within one day, thoroughly solving the problems of poor readability and maintainability.
2.2 Architecture Upgrade: Refactor Bulky If-Else Statements into Strategy Pattern
The original system had critical architectural flaws. Dozens of approval scenarios were processed through massive if-else branches, with a single method exceeding 1,500 lines and high code coupling. Any addition or modification of business scenarios required changes to core code, violating the Open-Closed Principle.
Claude Code quickly refactored the tangled branch logic into the classic Strategy Pattern and generated standard architecture frameworks to achieve complete business decoupling. The lengthy method was split into 14 independent classes with single responsibilities. Different approval scenarios correspond to separate implementation classes and are scheduled uniformly via a context class.
This architectural upgrade greatly enhances the maintainability and scalability of the project. New approval scenarios can be added by creating new strategy classes instead of modifying core code, optimizing the project architecture fundamentally.
2.3 Generate Test Cases to Improve the Testing System
Legacy projects with zero test coverage face huge risks during iteration. Claude Code can generate standardized JUnit5 + Mockito unit test cases in batches to cover mainstream normal scenarios and make up for testing deficiencies.
After two days of AI generation and manual optimization, the unit test coverage of core modules rose from 0% to 62%. The project no longer operates without test protection, providing solid guarantees for the stability of refactored code.
3. Practical Pitfall Guide: Five Common Critical Issues with Claude Code
AI programming tools deliver outstanding efficiency but have clear limitations. Five typical hidden problems are summarized from this practice, which are common drawbacks of all AI programming tools. Developers must stay alert to these issues when using AI tools via TreeRouter in daily work to avoid online failures.
3.1 AI Hallucination: Non-existent API Methods
AI may produce hallucinations and generate seemingly valid third-party methods that do not actually exist. During refactoring, the tool created an invalid method pretending to be a native Spring API, which caused runtime exceptions.
Key Lesson: All external dependencies and third-party API calls generated by AI must be verified against official documentation.
3.2 Context Loss When Processing Long Code
AI has limited context capacity. Feeding thousands of lines of code at once will make it forget previously defined classes, variables and coding rules, leading to naming errors, parameter mismatches and uncompilable code.
Key Lesson: Split code into small units. Process only one method or class at a time, and keep the code within 300 lines.
3.3 Poor Understanding of Complex Business Logic
AI can only recognize syntax structures rather than customized and complex business rules. The approval system had special permission logic, but the AI messed up the judgment order and disabled core privileges. This results in hidden bugs where the code compiles normally but fails to run correctly.
Key Lesson: Use AI only for framework reference when dealing with core business logic. All business rules must be reviewed line by line manually.
3.4 Incomplete Test Coverage
Auto-generated test cases only cover normal workflows and ignore edge cases such as null parameters, concurrency conflicts, process withdrawal and permission anomalies. The coverage rate looks satisfactory but conceals numerous risks.
Key Lesson: AI creates basic test templates, while developers need to add logic for edge cases, exceptions and concurrent scenarios.
3.5 Risks Behind Concise Code
AI tends to generate elegant and concise code, which may contain hidden performance and security risks. When optimizing parallel notification logic, the tool adopted the default thread pool without isolation settings, which may lead to thread pool exhaustion under high concurrency.
Key Lesson: Never deploy code that cannot be fully understood. Code elegance does not equal safety and stability.
4. Standard Collaboration Rules: Clarify the Boundary Between AI and Developers
Based on this refactoring project with 32,000 lines of legacy code, a universal collaboration specification is concluded, applicable to most backend development and refactoring work:
✅ Fully handled by AI: Generating code comments and technical documents, refactoring duplicate code, creating DTOs and test frameworks and other repetitive template work.
⚠️ AI generation + manual verification and supplementation: Unit test cases, third-party dependencies and external API encapsulation. Developers need to supplement edge logic and verify interface availability.
❌ Must be completed manually: Writing core business logic, making architectural decisions, handling concurrency and security verification and other high-risk work requiring professional judgment.
5. Refactoring Outcomes and Industry Reflections
This refactoring project powered by Claude Code achieved remarkable results. The whole cycle was shortened from 14 days to 9 days, saving three working days of manpower. The total lines of code were reduced from 32,000 to 19,000 after removing redundant logic. The unit test coverage of core modules increased from 0% to 62%. In the first two weeks after release, online bugs dropped by 60% compared with historical data, greatly improving system stability and maintainability.
AI programming tools are never replacements for developers, but powerful assistants that reduce repetitive work. Lightweight AI capabilities help standardize code and handle repetitive tasks efficiently, yet they cannot take the place of developers’ business thinking, architectural judgment and risk control capabilities.
Making good use of AI tools for mechanical work and focusing energy on high-value tasks including architecture design, business implementation and risk management, while adhering to strict code review standards, is the optimal way to achieve efficient and high-quality project iteration.
