A comprehensive demonstration of using Claude Code for enterprise Java migration, showcasing the power of AI-assisted code modernization while emphasizing the critical importance of human oversight and validation.
- Project Overview
- Problem Statement
- Migration Objectives
- Why AI-Assisted Migration?
- The Human-in-the-Loop Approach
- Repository Structure
- Migration Process Overview
- Manual Review Checkpoints
- Benefits & Outcomes
- Key Learnings
- Getting Started
- References
This repository demonstrates a real-world enterprise Java migration from legacy versions to modern frameworks using AI-assisted coding tools. The project migrates the Transaction History Service, a Spring Boot microservice from the Bank of Anthos sample architecture, showcasing systematic modernization with AI assistance while maintaining code quality, security, and reliability through strategic human oversight.
Migration Scope:
- Spring Boot: 2.3.1.RELEASE → 3.4.4
- Java: 8 → 17
- Spring Cloud: Hoxton.SR5 → 2023.0.0
- Namespace Migration: javax.* → jakarta.*
- Dependencies: Security updates for Log4j, Guava, Mockito, and more
Key Highlight: This migration leverages Claude Code's specialized agents and slash commands to automate repetitive tasks while strategically inserting human validation at critical decision points.
Enterprise Java applications built on older frameworks face significant technical debt:
- Security Vulnerabilities: Legacy dependencies contain known CVEs (e.g., Log4j 2.13.3 → CVE-2021-44228)
- Lack of Modern Features: Missing Java 17 improvements (records, pattern matching, sealed classes)
- Framework EOL: Spring Boot 2.x reached end-of-life, leaving applications unsupported
- Namespace Changes: Jakarta EE migration requiring systematic javax.* → jakarta.* transformations
- Breaking Changes: Spring Boot 3.x introduced API changes requiring careful refactoring
Manual migration is:
- Time-Consuming: 40-80 hours for a small-to-medium microservice
- Error-Prone: Easy to miss edge cases, deprecated APIs, or security issues
- Tedious: Repetitive namespace changes across hundreds of files
- Knowledge-Intensive: Requires deep understanding of both old and new frameworks
- Risk-Heavy: Breaking changes can introduce subtle bugs
Can AI-assisted tools accelerate migration while maintaining quality and safety?
This project answers: Yes, with the right human-in-the-loop process.
-
Modernize Framework Stack
- Upgrade to Spring Boot 3.4.4 for continued support and features
- Migrate to Java 17 for performance improvements and modern syntax
- Update Spring Cloud to 2023.0.0 for cloud-native enhancements
-
Eliminate Security Vulnerabilities
- Address known CVEs in dependencies
- Update to latest secure versions (Log4j 2.23.1, etc.)
- Generate SBOM (Software Bill of Materials) for compliance
-
Maintain Functional Integrity
- Zero regression in business logic
- All existing tests passing
- API contracts unchanged
-
Improve Code Quality
- Apply modern Java 17 idioms where appropriate
- Increase test coverage (target: >80%)
- Adhere to SOLID principles and Spring best practices
-
Demonstrate AI-Assisted Workflow
- Showcase Claude Code's migration capabilities
- Document human review checkpoints
- Provide reusable templates for similar migrations
AI coding assistants like Claude Code excel at migration tasks because they:
-
Automate Repetitive Work
- Namespace transformations (javax.* → jakarta.*)
- Dependency version updates across pom.xml
- Consistent code pattern replacements
-
Leverage Deep Knowledge
- Trained on Spring Boot migration patterns
- Understand breaking changes between versions
- Know common pitfalls and solutions
-
Provide Systematic Analysis
- Scan entire codebases for deprecated APIs
- Identify security vulnerabilities
- Generate comprehensive reports
-
Execute Specialized Tasks
- Custom agents for security auditing, test generation, and build validation
- Slash commands for complex multi-step operations
- Iterative error resolution
-
Scale Efficiency
- Reduce 40-80 hour migrations to 4-8 hours of human time
- Consistent quality across all changes
- Comprehensive documentation automatically generated
This migration leverages:
-
Specialized Agents:
java-migration-specialist: Core migration logicsecurity-auditor: OWASP Top 10 and CVE scanningtest-engineer: Coverage analysis and test generationcode-reviewer: Quality and best practices validation
-
Custom Slash Commands:
/analyze-project: Pre-migration risk assessment/migrate-springboot: Systematic migration execution/validate-build: Iterative compilation error fixing/security-sast: Static application security testing/security-dependencies: Dependency vulnerability scanning/review-code: Comprehensive code quality review
-
AI-Powered Tools:
- Semantic code understanding
- Context-aware refactoring
- Pattern-based transformations
- Automated test generation
While AI excels at automation, human judgment remains irreplaceable for:
-
Strategic Decisions
- Choosing migration timing and scope
- Evaluating risk vs. reward trade-offs
- Prioritizing which issues to fix vs. accept
-
Domain-Specific Knowledge
- Understanding business logic implications
- Validating functional equivalence
- Assessing operational impact
-
Quality Assurance
- Reviewing generated code for correctness
- Ensuring adherence to team standards
- Validating security recommendations
-
Context and Nuance
- Handling edge cases AI might miss
- Making judgment calls on ambiguous situations
- Ensuring solutions fit architectural patterns
Important: This project intentionally avoids 100% automation. Fully automated migrations risk:
- Blindly applying changes without understanding impact
- Missing business-critical edge cases
- Introducing subtle bugs or security issues
- Creating technical debt through suboptimal solutions
- Loss of institutional knowledge
Our Principle: AI automates the tedious; humans validate the critical.
ai-assisted-code-migration/
├── README.md # This file - project overview and guide
├── MIGRATION.md # Detailed step-by-step migration process
├── CLAUDE.md # Claude Code project instructions
├── LICENSE # Project license
│
├── legacy-code/ # Original Spring Boot 2.3.1 / Java 8 code
│ ├── README.md # Service documentation (pre-migration)
│ ├── pom.xml # Maven configuration (legacy versions)
│ ├── src/main/java/ # Application source code
│ ├── src/main/resources/ # Configuration files
│ └── src/test/java/ # Test suite (pre-migration)
│
├── migrated-code/ # Migrated Spring Boot 3.4.4 / Java 17 code
│ ├── README.md # Service documentation (post-migration)
│ ├── pom.xml # Maven configuration (updated versions)
│ ├── src/main/java/ # Migrated application source code
│ ├── src/main/resources/ # Updated configuration files
│ └── src/test/java/ # Updated and enhanced test suite
│
└── .claude/ # Claude Code configuration
├── commands/ # Custom slash commands
│ ├── analyze-project.md
│ ├── migrate-springboot.md
│ ├── validate-build.md
│ ├── test-generate.md
│ ├── security-sast.md
│ ├── security-dependencies.md
│ ├── security-review.md
│ └── review-code.md
│
└── agents/ # Specialized AI agents
├── java-migration-specialist.md
├── security-auditor.md
├── test-engineer.md
└── code-reviewer.md
legacy-code/: Baseline Spring Boot 2.3.1 application for comparisonmigrated-code/: Successfully migrated Spring Boot 3.4.4 application.claude/commands/: Reusable slash commands for systematic migration.claude/agents/: Specialized AI agents with domain expertise
The migration follows an 8-phase systematic approach orchestrated by Claude Code:
AI Tasks:
- Scan codebase for files, packages, and dependencies
- Identify javax.* usage and deprecated APIs
- Calculate migration complexity score
- Generate risk assessment report
Human Review:
- Evaluate risk score and decide go/no-go
- Review estimated effort and timeline
- Identify business-critical areas requiring extra care
- Approve migration strategy
Outcome: Migration feasibility report with risk score and recommendations
AI Tasks:
- Update pom.xml dependencies (Spring Boot, Java, Spring Cloud)
- Transform javax.* → jakarta.* across all source files
- Update Spring Security configuration for Spring Boot 3.x
- Migrate test dependencies (JUnit 5, Mockito 5.x)
- Apply deprecated API replacements
Human Review:
- Verify dependency version selections
- Review namespace transformation completeness
- Check for business logic changes (should be none)
- Validate Spring Security configuration
Outcome: Codebase updated to Spring Boot 3.4.4 / Java 17 (may not compile yet)
AI Tasks:
- Attempt compilation and capture errors
- Classify errors by type (namespace, API, plugin)
- Apply fixes systematically
- Re-compile and verify (iterative loop)
Human Review:
- Review each batch of fixes before proceeding
- Validate that fixes don't alter business logic
- Approve when build succeeds
Outcome: Clean compilation with zero errors
AI Tasks:
- Run JaCoCo coverage analysis
- Identify untested classes and methods
- Generate JUnit 5 tests for gaps
- Create integration tests
- Verify all tests pass
Human Review:
- Review generated test quality and relevance
- Ensure tests validate actual business logic
- Add domain-specific test cases AI might miss
- Verify coverage meets team standards (>80%)
Outcome: Enhanced test suite with comprehensive coverage
AI Tasks:
- Run SpotBugs with FindSecBugs plugin
- Execute PMD with security rules
- Scan for common vulnerabilities (SQL injection, XSS, etc.)
- Generate findings report by severity
Human Review:
- Triage findings (true positives vs. false positives)
- Evaluate risk for each vulnerability
- Decide which to fix vs. accept with justification
- Approve security fixes
Outcome: SAST report with security issues addressed or accepted
AI Tasks:
- Run OWASP Dependency-Check
- Identify CVEs in dependencies
- Generate SBOM (CycloneDX format)
- Recommend version updates
Human Review:
- Review CVE severity and exploitability
- Check for breaking changes in dependency updates
- Decide on version update strategy
- Approve dependency changes
Outcome: Zero critical/high CVEs, SBOM generated
AI Tasks:
- Analyze OWASP Top 10 compliance
- Review Spring Security configuration
- Check authentication/authorization mechanisms
- Validate input sanitization
- Assess cryptographic implementations
Human Review:
- Review security posture holistically
- Validate recommendations against threat model
- Ensure security controls don't break functionality
- Sign off on security improvements
Outcome: OWASP Top 10 compliant with documented security posture
AI Tasks:
- Analyze code against SOLID principles
- Check Spring Boot best practices
- Identify design pattern issues
- Validate documentation completeness
- Run checkstyle validation
Human Review:
- Review architectural recommendations
- Ensure code maintainability
- Validate adherence to team standards
- Final approval for merge
Outcome: High-quality, maintainable code ready for production
Throughout the migration, human review is mandatory at these checkpoints:
What to Review:
- Migration complexity score (Low/Medium/High/Very High)
- Estimated effort vs. available resources
- Business impact and timing considerations
Decision Point: Proceed with migration or defer?
Why Human Judgment Matters: Only humans understand business priorities, team capacity, and strategic timing.
What to Review:
- Chosen versions for Spring Boot, Spring Cloud, dependencies
- Breaking changes in selected versions
- Compatibility matrix across dependencies
Decision Point: Approve version selections or request adjustments?
Why Human Judgment Matters: Version choices impact stability, security, and long-term maintainability. AI may not know organization-specific compatibility requirements.
What to Review:
- Namespace changes (javax.* → jakarta.*)
- Spring Security configuration changes
- Deprecated API replacements
Decision Point: Are transformations semantically equivalent?
Why Human Judgment Matters: AI might miss subtle behavior changes. Humans must verify business logic remains intact.
What to Review:
- Each batch of compilation fixes applied
- Ensure fixes don't introduce logic changes
- Verify fixes follow team patterns
Decision Point: Approve fixes and continue or request revision?
Why Human Judgment Matters: Automated fixes might solve compilation errors but introduce runtime bugs. Human review ensures correctness.
What to Review:
- Generated test coverage and relevance
- Test assertions validate actual business logic
- Edge cases are properly tested
Decision Point: Are tests sufficient or do we need additional scenarios?
Why Human Judgment Matters: AI-generated tests may achieve coverage metrics but miss critical business scenarios only domain experts understand.
What to Review:
- Each security finding (critical, high, medium, low)
- Context-specific risk assessment
- Feasibility and impact of proposed fixes
Decision Points:
- Which vulnerabilities are true positives?
- Which fixes should be prioritized?
- Which risks can be accepted with justification?
Why Human Judgment Matters: Security findings require contextual understanding. Not all reported issues are exploitable in the application's specific context. Humans must evaluate real-world risk.
What to Review:
- Architectural recommendations
- Code maintainability and readability
- Adherence to team and organization standards
Decision Point: Final approval for production deployment?
Why Human Judgment Matters: Code quality is subjective and context-dependent. Humans ensure the solution fits the team's coding culture and long-term vision.
For each checkpoint, document:
- What was reviewed: Specific changes or findings examined
- Decision made: Approved, modified, or rejected
- Rationale: Why this decision was appropriate
- Reviewer: Who performed the review
- Timestamp: When the review occurred
Example:
Checkpoint: Security Finding Triage (Phase 5)
Reviewed: SpotBugs finding "Potential SQL Injection in TransactionRepository"
Decision: Accepted Risk
Rationale: Repository uses JPA @Query with named parameters. Inputs are
validated by Spring Security JWT claims. Risk is low in this context.
Reviewer: Jane Doe (Security Engineer)
Timestamp: 2025-01-20 14:30 UTC
Traditional Manual Migration:
- Estimated Time: 120-160 hours
- Error Rate: High (easy to miss files, imports, edge cases)
- Consistency: Variable (depends on developer experience)
- Documentation: Often incomplete
AI-Assisted Migration with Claude Code:
- Total Human Time: 15-20 hours (strategic reviews)
- Total AI Time: 20-25 hours (automated transformations)
- Error Rate: Low (systematic, comprehensive coverage)
- Consistency: High (same logic applied everywhere)
- Documentation: Automatically generated at each phase
-
Comprehensive Security Scanning
- AI-powered SAST with multiple tools (SpotBugs, PMD, Semgrep)
- Dependency vulnerability scanning (OWASP Dependency-Check)
- OWASP Top 10 compliance validation
- SBOM generation for supply chain security
-
Enhanced Test Coverage
- JaCoCo coverage analysis identifies gaps
- AI generates missing unit tests
- Integration tests for critical paths
- Achieved >80% code coverage (up from ~60%)
-
Code Quality Enforcement
- SOLID principles validation
- Spring Boot best practices applied
- Checkstyle compliance verified
- JavaDoc added to public APIs
-
Consistency Across Codebase
- Uniform application of migration patterns
- Consistent naming conventions
- Standardized error handling
- No "half-migrated" inconsistencies
-
Specialized Agents: Using domain-specific agents (java-migration-specialist, security-auditor) provided expert-level guidance.
-
Phased Approach: Breaking migration into 8 distinct phases with clear success criteria prevented overwhelming complexity.
-
Strategic Human Review: Inserting review checkpoints at critical junctures caught issues AI couldn't anticipate.
-
Slash Commands: Custom commands encapsulated complex workflows, making them repeatable and shareable.
-
Iterative Validation: The
/validate-buildcommand's iterative approach systematically resolved compilation errors. -
Comprehensive Security: Multi-layer security scanning (SAST + dependency + manual review) caught vulnerabilities at different levels.
Challenge 1: AI Generated Tests Lacking Business Context
- Problem: Generated tests achieved coverage but didn't validate critical business rules.
- Solution: Human review added domain-specific test cases; AI provided template.
- Lesson: AI excels at structure; humans provide domain knowledge.
Challenge 2: Dependency Version Conflicts
- Problem: Some dependency updates introduced transitive conflicts.
- Solution: Human decided on version pinning vs. exclusions based on project needs.
- Lesson: Complex dependency management requires human judgment.
Challenge 3: Over-Aggressive Modernization
- Problem: Initial AI suggestions introduced Java 17 features extensively.
- Solution: Human review opted for conservative approach to minimize risk.
- Lesson: Modernization enthusiasm must be balanced with stability needs.
Challenge 4: Security False Positives
- Problem: SAST tools flagged many non-issues.
- Solution: Human triage separated true positives from false positives.
- Lesson: Security findings require contextual understanding.
-
Start with Analysis: Always run pre-migration analysis to understand scope and risk.
-
Commit Incrementally: Commit after each phase to enable rollback if needed.
-
Review in Context: Don't just review diffs; understand the business logic being changed.
-
Test Continuously: Run tests after each phase to catch regressions early.
-
Document Decisions: Record why you accepted or rejected AI recommendations.
-
Trust but Verify: AI is excellent but not infallible. Validate critical changes.
-
Keep Humans in the Loop: Never blindly accept automated changes to production code.
- Claude Code CLI: Install from https://claude.com/code
- Java 17: Required for migrated code
- Maven 3.8+: For building the project
- Git: For version control
-
Clone this repository:
git clone <repository-url> cd ai-assisted-code-migration
-
Review the legacy code:
cd legacy-code ./mvnw clean test # Verify baseline cat README.md # Understand the service
-
Follow the migration guide:
cat MIGRATION.md # Detailed step-by-step instructions -
Execute migration with Claude Code:
# Start in project root cd ai-assisted-code-migration # Run each phase (see MIGRATION.md for details) /analyze-project /migrate-springboot /validate-build /test-generate /security-sast /security-dependencies /security-review /review-code
-
Review migrated code:
cd migrated-code ./mvnw clean verify # All tests should pass cat README.md # Review updated documentation
To use this approach for your own Java/Spring Boot migration:
- Copy
.claude/directory to your project root - Customize agents in
.claude/agents/for your tech stack - Adjust slash commands in
.claude/commands/for your workflow - Create
CLAUDE.mdwith your project-specific instructions - Follow the 8-phase process from MIGRATION.md
- MIGRATION.md: Complete step-by-step migration guide with detailed instructions for each phase
- legacy-code/README.md: Documentation for the original Spring Boot 2.3.1 application
- migrated-code/README.md: Documentation for the migrated Spring Boot 3.4.4 application
- CLAUDE.md: Claude Code instructions and project context
- Claude Code Documentation: https://docs.claude.com/en/docs/claude-code
- Claude Code GitHub: Issues and discussions
- Custom Slash Commands: See
.claude/commands/directory - Specialized Agents: See
.claude/agents/directory
- Spring Boot 3.0 Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide
- Spring Boot 3.4 Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.4-Release-Notes
- Jakarta EE 9 Migration: https://jakarta.ee/specifications/platform/9/
- OWASP Top 10: https://owasp.org/www-project-top-ten/
- OWASP Dependency-Check: https://owasp.org/www-project-dependency-check/
- CycloneDX SBOM: https://cyclonedx.org/
This project demonstrates that AI-assisted migration can dramatically accelerate enterprise Java modernization while maintaining—and even improving—code quality and security. The key is strategic human oversight at critical decision points.
The Future of Migration:
- AI handles the tedious, repetitive work (namespace changes, dependency updates)
- Humans provide strategic direction and validation
- Together, they achieve better results than either could alone
Core Principles:
- AI accelerates but doesn't replace human judgment
- Systematic processes produce reliable outcomes
- Human-in-the-loop ensures safety and quality
- Documentation and knowledge capture multiply value
The Result: A migration process that is faster, more consistent, and higher quality than traditional manual approaches, while keeping humans in control of critical decisions.
Project Maintainers: AI-Assisted Code Migration Team Last Updated: 2025-01-20 License: See LICENSE Questions/Issues: Create a GitHub issue or discussion
Ready to migrate? Start with MIGRATION.md for step-by-step instructions.