migrate-spring-to-quarkus

Spring Boot から Quarkus への移行

Spring Boot アプリケーションを Quarkus に移行するための、モジュール式でゲート駆動のプロセスです。

重要なルール

• 移行できないコードを削除しないでください。 コードの一部を完全に移行できない場合は、元のコードをそのまま残し、変更が必要な内容と理由を説明する // TODO: Migration required — <reason> コメントを付けてください。これは次の場合にも適用されます。
  • 変換方法がわからないメソッド、クラス、アノテーション
  • 明確に対応する Quarkus の仕組みがない Spring 固有のパターン
  • 目的が不明な設定コードや配線コード コードを削除する必要がある場合（例：Spring 専用の基底クラス）は、削除した内容と理由を同じ場所に // REMOVED: コメントで記録してください。
• ビルドを壊さないでください。 各フェーズの後に、<target> でコンパイルコマンドを実行してください（Maven の場合は cd <target> && ./mvnw clean compile -DskipTests、Gradle の場合は cd <target> && ./gradlew clean compileJava -x test）。ビルドが壊れた状態で次のフェーズに進まないでください。
• ソースは読み取り専用です。 <source> 内のファイルは変更しないでください。すべての変更は <target> に加えてください。唯一の例外は <source>/migration-metadata/ で、ここには抽出メタデータを書き込めます。
• すべての判断を記録してください。 移行方法を選ぶ際は、トレードオフをユーザーに説明してください。
• 変更を黙って行わないでください。 ファイルの変更はすべて意図的で、追跡可能でなければなりません。フェーズの後にチェックが失敗した場合は、原因を特定して修正してください。チェックを省略したり、失敗の原因となったコードを削除したりしないでください。

参照ファイル

モジュールに取り組む際は、該当する参照ファイルを読み込んでください。

参照先	使用するタイミング
references/dependency-map.md	ビルドモジュール：依存関係とプラグインのマッピング
references/annotation-map.md	コードモジュール：アノテーション、DI、REST、Data、Security の移行
references/config-map.md	ビルドモジュール：設定プロパティの移行

ステップ 1：モジュールを実行する

手順

• 次の Decision Gate Table に従って、各モジュールの手順を実行してください。
• 評価したモジュールとゲートチェック、およびステータスを、必ず次の形式で記録してください。 Gate result: and <CONDITION_EVALUATED>

判断ゲートテーブル

• 各モジュールについて、<source> を調べて適用対象かどうかを判断します。ゲートの状態が PASS の場合にのみ、モジュールを実行します。
• ゲートの結果を判断するには <source> を調べてください。内容を確認せずに grep コマンドを実行して判断しないでください。コードベースに関する理解に基づいて判断してください。

モジュール	ゲートチェック	ゲート結果
prerequisite	JDK のバージョン、ビルドツール（Maven ≥ 3.6、推奨 3.9 以上／Gradle ≥ 7、推奨 8.x）、コンテナランタイム	常に — ハードチェックに失敗した場合は、移行全体を中止します。以降のモジュールは実行されません
planning	前提条件チェックに合格していること	常に — <target>/migration-spec.yaml を生成します
build	pom.xml の Spring Boot の親／スターター／spring-boot-maven-plugin、または build.gradle(.kts) の Spring Boot／io.spring.dependency-management プラグイン	Spring Boot のビルドマーカーが見つかった場合は PASS、それ以外は SKIP
code	Java ソース内の Spring アノテーション（@Component、@Service、@Controller、@Repository、@Entity、@Autowired など）	Spring アノテーションが見つかった場合は PASS、それ以外は SKIP
messaging	Java ソース内の @KafkaListener、@RabbitListener、@JmsListener、@SendTo、@EnableKafka、@EnableRabbit、KafkaTemplate、RabbitTemplate、JmsTemplate	いずれかが見つかった場合は PASS、それ以外は SKIP
frontend	templates/ または webapp/ 内の Thymeleaf／JSP テンプレート、static/ 内の静的リソース、webapp/ または META-INF/resources/ 内の JSF XHTML ファイル、FreeMarker テンプレート（.ftl、.ftlh、.ftlx）、freemarker.* のインポート、または FreeMarkerConfigurer Bean	ビュー層が見つかった場合は PASS、それ以外は SKIP
testing	テストソース内の Spring テストアノテーション（@SpringBootTest、@WebMvcTest、@MockBean）	Spring テストが見つかった場合は PASS、それ以外は SKIP
cleanup	他のすべてのモジュールを実行した後に残っている Spring 関連成果物	常に -- 他のすべてのモジュールの実行後に実行します

実行プロトコル

STEP 0 — PREREQUISITE GATE (mandatory, runs before everything else)
  1. LOAD modules/prerequisite/prerequisite.md and execute all checks
  2. IF prerequisite gate == FAIL
       → log "Migration aborted — prerequisite gate failed: <failing check(s)>"
       → STOP immediately. Do not evaluate or execute any further module.
  3. IF prerequisite gate == PASS (warnings are allowed)
       → log "Prerequisite gate: PASS — proceeding with migration"
       → continue to the module loop below

FOR module IN [planning, build, code, messaging, frontend, testing, cleanup]:

  1. EVALUATE — inspect <source> for the gate condition
  2. DECIDE
     IF gate == ALWAYS → proceed to step 3
     IF gate == PASS   → proceed to step 3
     IF gate == SKIP   → log "Module {name}: SKIPPED — {reason}", mark checkbox, continue
  3. LOAD — read the module file and relevant reference files
  4. EXECUTE — read from <source>, write to <target>. Follow the module instructions, adapting to the chosen strategy
  5. COMPILE — run the compile command in <target> (`cd <target> && ./mvnw clean compile -DskipTests` for Maven, `cd <target> && ./gradlew clean compileJava -x test` for Gradle)
     Fails → load [modules/compile-fix.md](modules/compile-fix.md) and follow the retry procedure.
             If compile-fix reports MANUAL_REVIEW_REQUIRED (unresolved errors after 3 retries),
             ask the user whether to continue with the next module or stop the migration.
  6. LOG — mark checkbox as done

個別モジュールの実行

移行フロー全体を通さずに単一のモジュールを実行するには、モジュールフォルダー内のすべてのファイルを直接読み込んでください。

• 「modules/build/build.md を読み込んで実行する」
• 「frontend モジュールだけを実行する」
• 「cleanup モジュールを再実行する」

モジュールでは、現在の <source> と <target> のパス、および選択済みの戦略（すでに決定されている場合）を使用します。戦略が選択されていない場合、モジュールが確認します。

ステップ 2：移行を検証する

すべての検証チェックは <target> に対して実行します。各チェックを順番に実行してください。チェックに失敗した場合は、続行する前に停止して修正してください。

#	チェック	コマンド（<target> 内で実行）	合格基準
1	ビルド	cd <target> && ./mvnw clean package -DskipTests / cd <target> && ./gradlew clean build -x test	終了コード 0、コンパイルエラーなし
2	Spring 依存関係なし	<target> のビルドファイルで org.springframework を検索	Spring 依存関係が 0 件（その移行戦略を使う場合の Spring 互換拡張を除く）
3	Quarkus あり	<target> のビルドファイルで io.quarkus を検索	Quarkus BOM と少なくとも 1 つの拡張機能が存在する
4	テスト合格	cd <target> && ./mvnw test / cd <target> && ./gradlew test	@QuarkusTest を使用してすべてのテストに合格する
5	起動	cd <target> && ./mvnw quarkus:dev / cd <target> && ./gradlew quarkusDev	アプリが起動し、curl http://localhost:8080/q/health が UP を返す
6	テンプレートの残存なし	<target> で Thymeleaf/JSP への参照を検索	意図的に残したものを除き、残存なし

ステップ 3：レポート作成

検証が完了したら、レポート作成 モジュールを実行します。このモジュールは検証結果とすべてのモジュールごとのデータを読み込み、以下を生成します。

• <target>/migration-metadata/execution-metadata.json -- エージェント、モデル、トークン、コスト、所要時間、検証結果
• <target>/migration-summary.md -- 全 13 セクションの移行レポート

チェック結果を含め、正確な finished_at タイムスタンプを記録できるよう、レポート作成モジュールは検証の後に実行する必要があります。

コンソールサマリー

レポート作成モジュールの完了後、生成されたファイルを開かなくても概要をすぐに確認できるよう、以下の内容をユーザーに直接提示してください。

各質問には正直に回答してください。

1. 問題なく移行できたものは何ですか？ 1 対 1 で対応付けられたパターン。
2. 手動での判断が必要だったものは何ですか？ 自明ではない判断内容。
3. TODO として残されたものは何ですか？ すべての // TODO: Migration required コメントと、その理由。
4. コードを削除しましたか？ 削除したもの、場所、その正当性。実行時のリスクがあれば明示してください。
5. 最初に失敗したチェックは何ですか？ 検証時の失敗内容と修正方法。
6. スキルのリファレンスに不足しているものは何ですか？ 判断する必要があったマッピング。

次に、以下の形式でレビューを提示してください。

## Migration Report: [app-name]

### Summary
- Source: [source directory path]
- Target: [target directory path]
- Strategy: [Full Migration / Spring Compatibility]
- Agent: [AI agent name - e.g claude, pi, opencode, gemini, etc]
- Model: [model name — e.g. claude-sonnet-4-6, check system context]
- Modules completed: [X/8]
- Checks passed: [X/6]
- Token usage: [input tokens / output tokens — check session stats]
- Estimated cost: [~$X.XX — token counts × per-model pricing from anthropic.com/pricing]

### Changes by Module
| Module | Files changed | Key changes |
|--------|--------------|-------------|
| build | pom.xml or build.gradle(.kts), application.properties | ... |
| code | ... | ... |
| frontend | ... | ... |
| testing | ... | ... |

### Validation Results
| Check | Result | Notes |
|-------|--------|-------|
| Builds | PASS/FAIL | |
| No Spring deps | PASS/FAIL | |
| Has Quarkus | PASS/FAIL | |
| Tests pass | PASS/FAIL | |
| Starts up | PASS/FAIL | |
| No leftover templates | PASS/FAIL | |

### Unmigrated Code (TODOs)
| File | Line | What | Why not migrated |
|------|------|------|-----------------|

### Removed Code
| File | What was removed | Justification |
|------|-----------------|---------------|

### Skill Improvement Suggestions
- [Any missing mappings, unclear instructions, or edge cases discovered]