AWS Transform custom ナレッジアイテムを活用した一貫性のある大規模コードモダナイゼーション

本記事は 2026 年 6 月 3 日に AWS Migration & Modernization Blog で公開された Consistent Code Modernization at Scale with AWS Transform custom Knowledge Items を翻訳したものです。翻訳は Solutions Architect の山崎宏紀が担当しました。

はじめに

AWS Transform custom (ATX) は、コードモダナイゼーションを大規模に自動化します。各リポジトリで AI コーディングアシスタントを個別に実行する場合と異なるのは、ATX が学習するということです。各実行からパターン、修正、エッジケースを再利用可能なナレッジとして蓄積するため、変換は実行するたびに高速化し、信頼性も向上します。

Java 8 のリポジトリを数百個抱えていたり、非推奨 API を使った Spring Boot 2.x アプリ、あるいは AWS Graviton で動かせるにもかかわらず x86 に縛られたワークロードがある場合、こうした技術的負債こそがチームの開発速度を妨げている原因です。手動でのアップグレードはスケールしません。数百のリポジトリにまたがる Java のアップグレードは単調な繰り返し作業であり、この規模の繰り返しは一貫性の欠如を招きます。

AWS Transform custom は Agentic AI を活用してこれらの変換を自動化します。一般的なシナリオに対応する AWS マネージドな変換が同梱されているほか、独自のカスタム変換定義を構築することも可能です。改善の蓄積はナレッジアイテムによって実現されます。ナレッジアイテムとは、各実行からパターン、修正、エッジケースを蓄積する再利用可能なアーティファクトであり、将来の実行で自動的に適用されます。

本記事では、サンプルの Spring Boot プロジェクトを Java 8 から 26 にアップグレードし、ナレッジアイテムがどのように生成・管理されるかを確認し、同じ変換をリポジトリのポートフォリオ全体に適用する方法をご紹介します。

開始方法

実際のプロジェクトで Java 8 から 26 へのアップグレードを実行し、Transform custom の動作を確認しましょう。

前提条件

AWS Transform custom へのアクセスが有効化された AWS アカウント
ATX CLI のインストールおよび設定
Java 8 以上、Java 26、Maven のインストール（サンプルプロジェクトのビルド用）
Git のインストール
Java と Maven の基本的な知識

シナリオ

本記事では aws-appconfig-java-sample を使用します。これは Java 8 と Maven で構築された Spring Boot アプリケーションで、非推奨の Java API や古いフレームワークバージョンに依存している、典型的なモダナイゼーション候補です。

セットアップ

リポジトリをクローンします:

git clone --depth 1 https://github.com/aws-samples/aws-appconfig-java-sample.git

ディレクトリに移動します:

cd aws-appconfig-java-sample

ローカル依存関係をインストールします:

mvn install:install-file \
-Dfile=./movie-service-utils/built-library/0_1_0/movie-service-utils-0.1.0.jar \
-DgroupId=com.amazonaws.samples \
-DartifactId=movie-service-utils \
-Dversion=0.1.0 \
-Dpackaging=jar

ビルドが通ることを確認します:

mvn clean compile -DskipTests

変換定義

変換定義 (Transformation Definition) は、Transform custom に何をどのように変換するかを指示する再利用可能なレシピです。ソースとターゲットのスタック、変換パターン、コーディング規約、そしてエージェントに従わせたい組織ナレッジが含まれます。AWS は Java のバージョンアップグレードなど一般的なアップグレード向けにマネージド変換定義を提供しています。組織固有のニーズに合わせて独自の変換定義を構築することも可能です。

変換定義の実行

インタラクティブモードと自律モードの 2 つから選択できます。インタラクティブモードでは、ツール使用の確認、計画のレビュー、ステップの承認が求められます。自律モード (-x) は確認なしですべてを実行するモードで、CI パイプラインや一括実行で使用します。

ここでは -x で自律モード、-t ですべてのツールを信頼する設定で実行します。-t は注意して使用してください。すべてのコンテキストでエージェントが任意のツールをトリガーすることを許容したくない場合もあります。CLI コマンドリファレンスにオプションの一覧があります。

AWS/java-version-upgrade は、Java プロジェクトを Java 26 にアップグレードするマネージド変換定義です:

atx custom def exec -n "AWS/java-version-upgrade" -p . -c "mvn clean compile -DskipTests" -x -t -g "additionalPlanContext=The target Java version to upgrade to is Java 26"

上記コマンドの出力を以下の画像に示します。

Transform custom transformation starting

Transform custom transformation continuing

End of Transform custom transformation

AWS/java-version-upgrade 変換定義は Java 26 をターゲットとし、アップグレードの全範囲を処理します。javax.security.cert の移行、Spring Boot のメジャーバージョンアップグレード、テスト依存関係のモダナイゼーション、ビルドツールの更新など、POM ファイル内の Java バージョン番号を変更するだけではありません。

エージェントは依存関係グラフ全体を分析し、すべての変更を一括で適用し、コンパイルとテストの両方を検証した後、すべてを単一のアトミックなコミットとして記録しました。14 件の個別の変更（依存関係のアップグレード、API の移行、ビルドツールの更新）がすべて一緒に検証されました。実行ログには、実行内容、遭遇した問題（Spring Boot 3.2.12 の ASM が Java 26 と非互換、Mockito の ByteBuddy の問題）、およびそれらの解決方法が記録されています。

14 件の変更、1 つのアトミックコミット、完全なビルドとテストの検証。しかしエージェントはコードの変更を生成しただけではありません。何がうまくいき、何がうまくいかなかったかも観察しました。この観察こそがナレッジアイテムの源であり、別のリポジトリに対する次の実行が今回よりも高速になる理由です。

結果の確認

変更は専用のローカル Git ブランチに反映されます。Transform custom はリモートにプッシュしません。標準的な Git ツールで確認できる完全な監査証跡が得られます。コミットメッセージにはすべての変更が詳細に記載され、実行ログには遭遇した問題と解決方法が記録されます。インタラクティブモード（-x なし）で実行した場合は、実行開始前に計画をレビュー・修正でき、検証ステップや外部ツールチェックなど必要なゲートを追加できます。

変換によるすべての変更を確認するには:

git diff main

diff --git a/pom.xml b/pom.xml
--- a/pom.xml
+++ b/pom.xml

@@ -5,7 +5,7 @@
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
-    <version>2.0.5.RELEASE</version>
+    <version>3.5.14</version>
</parent>

diff --git a/src/main/java/.../movies/MoviesController.java b/src/main/java/.../movies/MoviesController.java
--- a/src/main/java/.../movies/MoviesController.java
+++ b/src/main/java/.../movies/MoviesController.java

@@ -1,5 +1,5 @@
-import javax.validation.Valid;
+import jakarta.validation.Valid;

diff --git a/src/main/java/.../utils/Security.java b/src/main/java/.../utils/Security.java
--- a/src/main/java/.../utils/Security.java
+++ b/src/main/java/.../utils/Security.java

@@ -1,5 +1,5 @@
-import javax.security.cert.*;
+import java.security.cert.*;

代表的な 3 つの変更を示します。Spring Boot が 2.0.5.RELEASE から 3.5.14 に（エージェントは 3.2.12 の ASM が Java 26 のクラスフォーマットをサポートしないことを検出し、3.5.14 にアップグレードしました）、javax.validation.Valid が jakarta.validation.Valid に移行、javax.security.cert が java.security.cert に置き換えられました。完全な diff には Mockito と JUnit の依存関係更新、Gradle ビルドのモダナイゼーション、AWS SDK BOM のアップグレードも含まれます。

変更内容に問題がなければ、マージします:

git checkout main
git merge <transformation-branch-name>

変換の改善

最初の実行は動作します。面白くなるのは 2 回目からです。

リファレンスとナレッジアイテム

Transform custom が変換精度を向上させる手段は 2 つあります。リファレンスは、変換定義の作成時にアップロードする移行ガイド、API 仕様、コードサンプルなど、事前に提供するドキュメントです。即座に有効化され、完全にお客様の管理下にあります。ナレッジアイテムは、実際の変換中に何が起こったかを観察することで、システムが自ら学習したものです。Transform custom は各実行後に非同期でナレッジアイテムを生成し、無効状態で開始し、お客様がレビューして承認した場合にのみ適用されます。

リファレンスが出発点を設定し、真に価値が積み上がるのはナレッジアイテムによってです。本記事の残りでは、このナレッジアイテムに焦点を当てます。

ナレッジアイテムの管理

どのナレッジアイテムを有効にするかは、お客様が制御します。承認なしに有効化されることはありません。

これまでに蓄積されたものを一覧表示するには:

atx custom def list-ki -n "AWS/java-version-upgrade"

以下のナレッジアイテムは、先ほどの変換実行で生成されたものです。エージェントはプロジェクトのアップグレード中にこれらの問題に遭遇し、自動的に記録しました:

KI - 7f36cfd4-2926-44fa-8fa5-eb5384e65c77 - DISABLED

 Title: Mockito 5.14.2 ByteBuddy incompatible with Java 26
 Description: Mockito 5.14.2 fails to mock standard library classes like ArrayList under Java 26. Error message indicates ByteBuddy cannot modify ArrayList and related collection classes. Mockito 5.15.2 resolves the compatibility issue.
 Fix: Upgrade Mockito to 5.15.2:

 <!-- Before - ByteBuddy in Mockito 5.14.2 can't handle Java 26 -->
 <dependency>
     <groupId>org.mockito</groupId>
     <artifactId>mockito-core</artifactId>
     <version>5.14.2</version>
     <scope>test</scope>
 </dependency>

 <!-- After - Mockito 5.15.2 supports Java 26 bytecode -->
 <dependency>
     <groupId>org.mockito</groupId>
     <artifactId>mockito-core</artifactId>
     <version>5.15.2</version>
     <scope>test</scope>
 </dependency>

KI - adb1b8e6-4199-4d4d-964c-1eab5c94de1a - DISABLED

 Title: Spring Boot 3.2.12 ASM lacks Java 26 class format support
 Description: Spring Boot 3.2.12 uses ASM library version that cannot parse Java 26 class files (major version 70). Test execution fails with "Incompatible class format" during classpath scanning. Spring Boot 3.5.14 or newer required for Java 26 compatibility.
 Fix: Upgrade Spring Boot to 3.5.14:

 <!-- Before - ASM in Spring Boot 3.2.12 can't parse Java 26 classes -->
 <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>3.2.12</version>
 </parent>

 <!-- After - Spring Boot 3.5.14 includes ASM with Java 26 support -->
 <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>3.5.14</version>
 </parent>

どちらもデフォルトでは DISABLED です。有効化する前にレビューを行います。各説明には、何が変更されたか、なぜ重要か、症状、そして正確な修正方法が記録されています。これらは、Java 26 アップグレード中にエージェントが遭遇した 2 つの異なるカテゴリの問題です:

Mockito/ByteBuddy: バイトコード操作の失敗。Mockito にバンドルされた ByteBuddy が Java 26 のクラスフォーマットを処理できず、テスト時のモックが実行時に失敗する。
Spring Boot ASM: クラスフォーマット解析の失敗。Spring Boot の ASM ライブラリがクラスパススキャン中に Java 26 のバイトコードをスキャンできず、テスト実行が完全に破綻する。

どちらもコンパイルだけでは検出できません。アップグレード後のコードに対してテストを実行する必要があり、そのためビルド検証コマンドが重要になります。

ナレッジアイテムを有効化するには:

atx custom def update-ki-status -n "AWS/java-version-upgrade" --id 7f36cfd4-2926-44fa-8fa5-eb5384e65c77 --status ENABLED
atx custom def update-ki-status -n "AWS/java-version-upgrade" --id adb1b8e6-4199-4d4d-964c-1eab5c94de1a --status ENABLED

すべてのナレッジアイテムを Markdown にエクスポートしてオフラインでレビューすることもできます:

atx custom def export-ki-markdown -n "AWS/java-version-upgrade"

Markdown へのエクスポートは、チームがオフラインでナレッジアイテムをレビューしたり、スプリント計画や技術的負債レビューのセッションでどれを有効化するかを議論したりする場合に便利です。自分のコードベースに対して適用範囲が広すぎるナレッジアイテムがあれば、無効化してください。次回別のリポジトリで実行した際に、より限定的な修正パターンが生成されることがあります。そちらを有効化すれば、徐々に汎用的なアドバイスではなく、組織の実コードに即したナレッジアイテムを取捨選択していけます。

なお、これらのナレッジアイテムはお客様の組織に固有のものであり、他のお客様とは共有されません。

学習ループ

Transform custom の価値はイテレーションにあります。実行し、エージェントが学習した内容を蓄積し、有効化し、再度実行する。先ほどの 2 つのナレッジアイテムを有効化した状態で、同じ変換定義を 2 番目のリポジトリに対して実行します:

git clone --depth 1 <second-repo-url>
cd <second-repo>
atx custom def exec -n "AWS/java-version-upgrade" -p . -c "<build-command>" -x -t

最初のリポジトリでは、ビルド検証コマンドとして -DskipTests を渡しましたが、エージェントはアップグレードの検証のためにテストも独立して実行しました。そのテスト実行中に、反復的に解決した 2 つの問題に遭遇しました:

Mockito 5.14.2 が標準ライブラリクラスのモックに失敗。バンドルされた ByteBuddy が Java 26 のバイトコード操作を処理できなかったため、エージェントは 5.15.2 にアップグレード。
クラスパススキャン中に「Incompatible class format」でテスト実行が失敗。エージェントが最初に行った Spring Boot 3.2.12 へのアップグレードでは、Java 26 のクラスファイル（メジャーバージョン 70）を解析できない ASM バージョンが使用されていた。3.5.14 にアップグレード。

Transform custom はこれらを観察し、先ほどレビューしたナレッジアイテムとして蓄積し、修正内容を記録しました。エージェントは問題を解決し、その経験から再利用可能なナレッジを生成しました。

これらを有効化して 2 番目のリポジトリで実行します:

atx custom def update-ki-status -n "AWS/java-version-upgrade" --id 7f36cfd4-2926-44fa-8fa5-eb5384e65c77 --status ENABLED
atx custom def update-ki-status -n "AWS/java-version-upgrade" --id adb1b8e6-4199-4d4d-964c-1eab5c94de1a --status ENABLED

Mockito 5.14.2 または Spring Boot 3.2.x を使用して Java 26 をターゲットとする後続のリポジトリでは、Transform custom がテスト実行前に事前に修正を適用します。Mockito は 5.15.2 にアップグレードされ、Spring Boot は 3.5.14 に引き上げられます。テストは通過し、手動介入は不要です。

以前のリポジトリではデバッグと手動修正が必要だったことが、その後のすべてのリポジトリで自動的な修正になります。各実行はより高速で信頼性が高くなり、次の実行のために新しいエッジケースを蓄積します。

具体的に説明します。この変換定義を 1 週間で 15 の Spring Boot リポジトリに実行するとします。4 番目のリポジトリまでに、Mockito 5.14.2 を使用するすべてのプロジェクトに対して事前にアップグレードが適用されます。6 番目のリポジトリまでに、Java 26 をターゲットとする古い 3.x バージョンを検出するたびに Spring Boot 3.5.14 へのバージョンアップが自動的に行われます。10 番目のリポジトリでは、カスタム @Query アノテーションを持つリポジトリで Hibernate 6 のダイアレクト変更が問題になるかもしれません。すべての実行で新しいナレッジアイテムが生成されるわけではなく、エージェントが何を発見するかに依存します。しかし生成されたものをレビューし、望ましいものを有効化すれば、後続のすべての実行がその恩恵を受けます。15 番目のリポジトリは、最初のリポジトリよりもクリーンな変換になります。なぜなら、それ以前の 14 個分の蓄積された経験を持っているからです。

大規模な実行

本記事では 2 つのリポジトリを扱いました。大規模に展開する場合は、同じ変換定義をポートフォリオ全体に適用します。これが Learn-Scale-Improve フライホイールです。各実行が新しいナレッジアイテムを蓄積し、後続のすべての実行がシステムのこれまでの学習内容から恩恵を受けます。20 番目のリポジトリでは、最初のリポジトリで手動介入が必要だったパターンを自動的に処理します。

数百のリポジトリにまたがる実行には自動化が必要です。aws-transform-custom-samples リポジトリには 2 つのオープンソースアプローチがあります:

Bash 自動化: ワークステーションから並列実行、進捗ダッシュボード、自動リトライを備えて実行します。
コンテナベース実行: AWS Batch + AWS Fargate 上で数百から数千のリポジトリに対して実行します。セットアップの手順は AWS DevOps ブログの記事をご参照ください。

クリーンアップ

変換はローカルで実行され、AWS リソースはプロビジョニングされません。クリーンアップするには:

cd ..
rm -rf aws-appconfig-java-sample

AWS Batch でスケール実行を行った場合は、コンテナベース実行の README にあるクリーンアップ手順に従ってください。

まとめ

ナレッジアイテムはポートフォリオ全体で蓄積されます。各実行はエージェントが遭遇した内容に応じて新しい学びを生成する可能性があり、有効化したものが後続のすべての実行を高速化します。単発のリファクタリングスプリントではなく、今日の負債削減が明日のデリバリーを直接加速させる継続的なループが得られます。

ぜひお試しください: ご自身のリポジトリをクローンし、AWS/java-version-upgrade 変換定義を実行して、生成されるナレッジアイテムを確認してみてください。組織固有のパターン（フレームワーク移行、コーディング規約の強制、依存関係の置き換え）がある場合は、カスタム変換定義を作成し、いくつかのリポジトリで実行して学習ループの動作を確認してみてください。

AWS Transform custom ドキュメント
AWS マネージド Java アップグレード変換定義: ご自身のコードベースでお試しください
独自の変換定義を作成して組織固有のパターンに対応
aws-transform-custom-samples: 大規模実行のためのスクリプトとインフラ

Amazon Web Services ブログ