Spring Boot Migration
Purpose
Use this skill for phased upgrade work on existing Spring Boot applications. This skill adds value through the migration scanner, the Boot 4 / Modulith 2 / Testcontainers 2 reference guides, and a strict migration order that avoids mixing too many changes at once.
Critical rules
- Never migrate blindly. Scan the codebase first.
- Never apply every migration at once. Follow phased upgrades.
- Treat Spring Boot 4, Spring Modulith 2, and Testcontainers 2 as the intended target stack for this skill unless the user asks for a narrower target. Boot 4's Java baseline is 17; recommend Java 25 for new compile targets but do not force an upgrade past what the migration actually requires.
- Verify after each phase and stop when failures appear.
Workflow
Step 1: Scan the project
Use the migration scanner before planning or editing. It reads pom.xml, build.gradle, or build.gradle.kts (whichever the project has) plus Java sources, properties files, and Flyway migrations:
python3 "${CLAUDE_SKILL_DIR}/scripts/scan_migration_issues.py" /path/to/project
Use the scan output to identify:
- current Spring Boot version
- starter rename work
- annotation and import migrations
- configuration changes
- Spring Modulith compatibility
- Testcontainers compatibility
Step 2: Identify which migrations apply
Load only the references that match the codebase:
| Migration | Trigger | Read |
|---|
| Spring Boot 4.0 | Boot 3.x to 4.x upgrade | references/spring-boot-4-migration.md |
| Spring Modulith 2.0 | Existing Modulith 1.x usage | references/spring-modulith-2-migration.md |
| Testcontainers 2.x | Existing Testcontainers 1.x usage | references/testcontainers-2-migration.md |
| Cross-cutting scenarios and pitfalls | Mixed upgrade planning | references/migration-overview.md |
Step 3: Plan the migration in phases
Use the reference guides to plan and execute in this order.
Phase 1: Dependencies
- update
pom.xml or build.gradle
- rename starters where required
- add or remove dependencies needed by the target stack
- align version properties
Phase 2: Source-code changes
- update imports and package names
- migrate test annotations
- fix Jackson 3 issues
- fix Testcontainers API changes where relevant
Phase 3: Configuration
- update
application.properties or application.yml
- apply Boot 4 defaults intentionally
- update Spring Modulith event-store configuration if relevant
Phase 4: Verification
- run unit tests
- run integration tests
- run container-based tests where present
- check for deprecations and startup failures
Step 4: Use the right migration order for mixed upgrades
When multiple ecosystems are involved, use this order:
- Spring Boot 4
- Spring Modulith 2
- Testcontainers 2
Read references/migration-overview.md before deviating from this sequence.
Step 5: Report progress after each phase
After each phase, report:
- what changed
- what remains
- what failed, if anything
- whether it is safe to continue
Reference loading guide
- Spring Boot 4 migration details:
references/spring-boot-4-migration.md
- Spring Modulith 2 migration details:
references/spring-modulith-2-migration.md
- Testcontainers 2 migration details:
references/testcontainers-2-migration.md
- Mixed scenarios and common issues:
references/migration-overview.md
Available script
scripts/scan_migration_issues.py
Output format
When planning or reporting the migration, return:
## Migration scope
- Current versions:
- Target versions:
## Planned phases
1. ...
2. ...
3. ...
## Files expected to change
- `path/to/file`
## Verification
- Tests or checks to run
When not to use this skill
- Creating a new Spring Boot project from scratch
- Broad architecture advice without an actual migration task
- JPA-specific implementation work that belongs in
spring-data-jpa