AWS Transform custom: モダナイゼーションのための包括的コードベース分析

本記事は 2026 年 4 月 15 日に Migration & Modernization Blog で公開された AWS Transform: Comprehensive Codebase Analysis for Modernization を翻訳したものです。翻訳は Solutions Architect の山崎宏紀が担当しました。

アプリケーションのモダナイゼーションは、多くの場合、困難なタスクから始まります。それは、システムの仕組みを理解するための包括的なレガシーコードベース分析です。多くのレガシーアプリケーションは長年にわたる段階的な変更を経て進化しており、ドキュメントは限られ、依存関係は密結合し、ビジネスロジックは複数のサービスやモジュールに分散しています。エンジニアリングチームにとって、この可視性の欠如は共通の課題を生み出します。モダナイゼーションを開始する前に、開発者はソースコードを確認してアプリケーションアーキテクチャ、動作パターン、隠れた依存関係を理解するための時間を費やす必要があります。この作業を行っても、サービス間の依存関係、アーキテクチャ上の制約、埋め込まれたビジネスルールなどの重要な知見は、変更がより複雑でコストがかかるプロジェクトの後半で明らかになることがよくあります。

AWS Transform の包括的コードベース分析マネージド変換は、アプリケーションの明確でエビデンスに基づいた理解を提供することで、これらの課題に対処します。これにより、数か月分の手作業を節約し、モダナイゼーションへの取り組みを加速できます。この記事では、変換の仕組み、前提条件、実行手順、実践的なシナリオを含めた結果の解釈方法、より広範なモダナイゼーションの取り組みとの関係、ベストプラクティス、トラブルシューティングガイダンスについて説明します。この記事を読み終えた頃には、ドキュメントが不十分なレガシーコードベースを構造化されたナビゲーション可能なナレッジベースに変換するための再現可能なアプローチを習得できるでしょう。

AWS Transform の包括的コードベース分析の仕組み

この変換は、静的コード解析に基づいて動作します。決定論的ツール、基盤モデル（FM）、大規模言語モデル（LLM）、グラフニューラルネットワーク、自動推論を組み合わせて、アプリケーションコードベースの 4 つの重要な側面を分析します。

システム全体のコンポーネントの関係と依存関係
コードがどのように機能するかを明らかにする動作パターン
実装に埋め込まれたアーキテクチャ上の決定
ステークホルダーとのコミュニケーションのために平易な言葉で抽出されたビジネスロジック

この多層的な分析により、技術チームとビジネスリーダーの両方が、実装中に問題が発生する前に十分な情報に基づいたモダナイゼーションの意思決定を行うのに役立つ構造化されたドキュメントが生成されます。

前提条件

開始する前に、以下を確認してください。

AWS Transform コマンドラインインターフェース（CLI）がインストールされていること: 詳細はスタートガイドを参照。
AWS 認証情報が設定されていること: 適切な権限で AWS CLI をセットアップし、AWS 認証情報に AWS Transform サービスを呼び出す権限があることをこちらで確認。最低限、transform-custom: * の権限が必要。
クリーンな状態の読み取り可能なファイルを含む Git ソースコードリポジトリを準備すること: コミットされていない変更はコミットまたはスタッシュ。

推定所要時間: 30〜45 分（分析の実行時間を除く。実行時間はコードベースのサイズによって異なります）

ステップバイステップガイド: 包括的コードベース分析の実行

以下の手順では、レガシーアプリケーションに対して AWS Transform の包括的コードベース分析を実行し、主要なステークホルダーと結果を共有し、インサイトに基づいて行動するまでの完全なプロセスを説明します。

ステップ 1: 環境の確認

AWS Transform が正しくインストールおよび設定されていることを確認します。

atx -version
atx custom def list

上記のコマンドは、AWS/early-access-comprehensive-codebase-analysis などの利用可能な AWS Transform マネージド変換を表示します。

注: 早期アクセス変換 (early-access-*) は機能しますが、お客様のフィードバックに基づいて頻繁に更新される可能性があります。時間が経つと、変換の名前が「AWS/comprehensive-codebase-analysis」として一覧に表示されるようになります。

Terminal output showing the 'atx custom def list' command displaying a table with the AWS/early-access-comprehensive-codebase-analysis transformation listed

図 1: AWS マネージド変換のリストで包括的コードベース分析変換が利用可能であることを確認

ステップ 2: コードベースの準備

Git リポジトリがクリーンな状態であることを確認します。

git status

Terminal window showing git status command output with nothing to commit, working tree clean message

図 2: 分析を実行する前に Git リポジトリがクリーンな状態であることを確認

既存のソースコードリポジトリをクローンします。

git clone <repository-url>

Terminal window displaying git clone command cloning the Prince of Persia Apple II repository from GitHub

図 3: 包括的分析のためにレガシーコードベースリポジトリをクローン

ステップ 3: ターミナルで以下のコマンドを実行

AWS Transform を使用して包括的分析を開始します。これにより、リポジトリ内のすべてのファイルと依存関係に対して深い静的解析が実行されます。

cd /path/to/your/project
atx custom def exec -p /path/to/your/repository -n AWS/early-access-comprehensive-codebase-analysis -c "noop" -x -t

注:

-n は変換名を指定します
-c "noop" – ビルドコマンド（no operation – ビルドステップをスキップ）
-x – 確認プロンプトなしでツールを自動信頼/実行
-t – インタラクティブターミナルモードを有効化

Terminal showing AWS Transform custom CLI execution with region confirmation and managed transformation indicator

図 4: AWS Transform CLI を使用して包括的コードベース分析変換を実行

ステップ 4: 追加コンテキストの提供（オプション）

よりターゲットを絞った分析を行うために、設定ファイルを使用して追加のガイダンスを提供できます。

transform-config.yaml という名前のファイルを作成します。

cat > transform-config.yaml << 'EOF'
codeRepositoryPath: /Users/milola/Prince-of-Persia-Apple-II
transformationName: AWS/early-access-comprehensive-codebase-analysis
buildCommand: noop
additionalPlanContext: |
  Focus analysis on the following areas:
  - Document the overall architecture and code structure
  - Identify deprecated or outdated coding patterns
  - Highlight areas that may benefit from modernization
  - Analyze dependencies and their relationships
EOF

カスタム設定ファイルを実行します。

atx custom def exec -g file://transform-config.yaml -x -t

Terminal displaying AWS Transform execution using created YAML configuration file which includes additional plan context

図 5: YAML 設定ファイルを使用して追加コンテキスト付きで分析を実行

ステップ 5: 分析のモニタリング

処理が進むにつれて、階層的なドキュメント構造にまとめられた分析結果、優先度付けされた技術的負債のインサイト、簡単にナビゲートできる相互参照されたナレッジベースが提供されます。コードベースのサイズと複雑さに応じて、完全なプロセスには通常 45 分から 2 時間以上かかります。

ステップ 6: 結果の確認

分析が完了すると、4 つの領域にわたって整理された包括的なドキュメントセットが表示されます。

技術的負債レポート: 古くなったコンポーネントの優先度付きビュー、重大度別にランク付けされたセキュリティの問題、長期的な影響について評価されたメンテナンスの懸念事項。
アーキテクチャドキュメント: コンポーネントの依存関係グラフ、サービスの相互作用パターン、データフロー図を含むシステム全体の概要。
ビジネスロジックの抽出: 複雑なプロセスのわかりやすい言葉での説明。主要なビジネスルール、バリデーションロジック、外部統合ポイントを浮き彫りにします。
コード分析: コードベースのファイルごとの内訳。複雑度メトリクス、コード品質の指標、具体的なリファクタリングの機会を提示します。

以下は、プロジェクト概要、技術的負債レポート、コード分析出力、システムアーキテクチャ概要のスクリーンショットです。

プロジェクト概要:

Markdown documentation showing Prince of Persia Apple II project overview with introduction, game description, key features including rotoscoped animation and puzzle-platform gameplay, and technical achievements

図 6: ビジネスコンテキストと技術的成果を含む、包括的コードベース分析によって生成されたプロジェクト概要ドキュメント

技術的負債レポート:

Technical debt analysis showing critical severity rating with executive summary highlighting 45-year-old code, obsolete toolchains, and quick impact summary table

図 7: プラットフォームの陳腐化やハードウェア依存関係を含む、重大度別に優先度付けされた重要な問題を強調する技術的負債レポート

コード分析:

Code quality analysis displaying critical interpretation with technical debt ratio and code quality indicators table

図 8: 複雑度、保守性の指標、品質評価を示すコード分析メトリクス

システムアーキテクチャ概要:

System architecture documentation showing architectural strengths and weaknesses with specific assessment of modularity and coupling

図 9: モジュール性と結合度の具体的な評価を含む、システムの強みと弱みを示すアーキテクチャドキュメント

ステップ 7: ナレッジベースのナビゲーション

生成されたドキュメントは、ハイレベルなレビューと詳細な調査の両方をサポートするように構造化されています。

ルートレベルでは、エグゼクティブサマリーが最も重要な技術的負債の分析結果とともに表示され、即座に注意を要するインサイトが明らかになります。さらに掘り下げると、ドメインレベルでは関連するコンポーネントが論理的なクラスターにグループ化され、コンポーネントレベルでは個々のモジュールの詳細な分析が提供されます。

ドキュメント全体を通じて、相互参照が関連するコンポーネントと依存関係を接続し、チームがコンテキストを失うことなくシステム全体の関係を追跡しやすくなります。

トップから始めて、モダナイゼーションの優先事項に最も関連する領域を分析してください。

ステップ 8: エクスポートと共有

各グループが受け取る内容を、それぞれの責任と意思決定のニーズに基づいてカスタマイズします。このターゲットを絞ったアプローチにより、各チームはモダナイゼーションの取り組みにおける自分たちの役割に最も関連するインサイトに基づいて即座に行動できます。

まず、エンジニアリングチームに技術的負債レポートを提示してください。これにより、モダナイゼーション中に遭遇するリファクタリングの優先順位とアーキテクチャ上の制約が把握できます。

アーキテクチャチームは、ターゲット状態の計画と慎重な検討が必要な統合ポイントの特定に、システム全体のドキュメントが非常に有用であると感じるでしょう。

ビジネスステークホルダーは、わかりやすい言葉でのビジネスロジック抽出から大きな恩恵を受けます。これにより、変換中に重要なワークフローとルールが保持されていることを検証できます。

セキュリティチームも、依存関係の分析とアーキテクチャのインサイトを確認して、モダナイゼーションプロセスの早い段階でセキュリティに関する考慮事項を特定できます。

ステップ 9: インサイトに基づいた行動

出力は、それに基づいて何を行うかによってのみ価値が決まります。短期的には、関連するセキュリティの問題への対処、優先度の高い技術的負債の正式なドキュメント化、今後のスプリント計画への分析結果の組み込みに注力してください。戦略的には、アーキテクチャのインサイトがモノリシックシステムの分解の決定に情報を提供し、依存関係の分析に基づいてモダナイゼーションの各フェーズの実施順序を決定します。技術的負債データは、測定可能なリスクと影響に基づいた説得力のあるビジネスケースを構築するための基盤を提供します。

実践的なシナリオ

数十年の歴史を持ち、ドキュメントが最小限で、理解できる開発者が限られているモノリシックアプリケーションを引き継いだとします。そして、ビジネスステークホルダーは数か月ではなく数週間以内にモダナイゼーションのタイムラインを必要としています。包括的コードベース分析は、そうでなければ広範な手作業を必要とするディスカバリーフェーズを加速し、数週間ではなく数時間で実行可能な結果を提供します。コンポーネントの相互作用を示す完全な依存関係グラフを生成し、リスクと影響で優先度付けされた技術的負債のホットスポットを特定し、技術とビジネスの理解を橋渡しするビジネスロジックを抽出し、分解戦略に情報を提供するアーキテクチャのインサイトを提供します。この基盤により、特定のコンポーネントをリファクタリングするか、リプラットフォームするか、置き換えるかについて十分な情報に基づいた意思決定が可能になり、推測ではなくエビデンスに裏付けられた現実的なモダナイゼーションタイムラインをビジネスステークホルダーに提供できます。

より広範なモダナイゼーションの取り組みとの関係

包括的コードベース分析は、単独ではなく、より広範なモダナイゼーション機能と連携して動作するように設計されています。生成されるインサイトは、モダナイゼーションジャーニー全体を通じて使用できます。分解の計画では、インサイトが実際の依存関係とアーキテクチャの境界に基づいてモノリシックアプリケーションを管理可能なドメインに分解する方法の理解を提供します。技術的負債の分析は、リスク、影響、ビジネス価値に基づいた順序付きの作業を確保し、モダナイゼーションの各フェーズの優先順位を決定します。詳細なコンポーネント分析は、システムのどの部分が変換の候補であり、どの部分が完全な置き換えの候補であるかを示すことで、リファクタリングの決定を明確にします。ビジネスステークホルダーにとっては、抽出されたビジネスロジックがモダナイゼーション投資のビジネスケースを構築するために必要なナラティブを提供します。これを、後続のすべてのステップをより意図的でより良い情報に基づいたものにする基盤と考えてください。

ベストプラクティス

変換を実行する前に、結果に影響を与える可能性のある既知の問題や制限事項を文書化し、注力すべき特定の懸念領域を特定してください。

変換をターゲットを絞ったインサイトに導くために明確な追加コンテキストを提供し、出力を充実させることができる関連するアーキテクチャ図やドキュメントを含めてください。

分析が完了したら、チームとして技術的負債の分析結果をレビューし、技術的な重大度だけでなくビジネスへの影響に基づいて修正の優先順位を決定してください。

インサイトをスプリント計画と長期的なロードマップに活用し、技術者と非技術者の両方のステークホルダーとドキュメントを共有して、全員がシステムの全体像を理解できるようにしてください。

トラブルシューティング

結果に具体的なインサイトが不足している場合

出力が一般的すぎると感じる場合、最も効果的な修正方法は、エージェントにより明確な方向性を与える additionalPlanContext を通じてより詳細なコンテキストを提供することです。認証、決済処理、特定のサービスレイヤーなど、最も関心のある注力領域やドメインを指定し、エージェントがよりターゲットを絞った分析結果を生成できるように、既存のアーキテクチャドキュメントや図を参考資料として含めることを検討してください。

分析が完了しない場合

分析が完了できない場合は、エージェントが自力で解決できない可能性のある依存関係や設定ファイルの欠落を確認し、プロセスに干渉する可能性のあるコミットされていない変更がない、クリーンな状態の Git リポジトリであることを確認してください。大規模または複雑なコードベースの場合は、エージェントをガイドするために焦点を絞った additionalPlanContext を提供してください。

ドキュメントが広範すぎる場合

生成されたドキュメントが必要以上に広い範囲をカバーしている場合は、additionalPlanContext でモジュールやドメインを指定してスコープを絞ってください。また、リポジトリ全体ではなく特定のサブディレクトリに対して分析を実行することもできます。これにより、システム全体の出力を確認する必要なく、最も重要な領域に焦点を当てた実行可能なインサイトを得ることができます。

まとめと次のステップ

コードベースを理解することは、モダナイゼーション成功の基盤です。AWS Transform の包括的コードベース分析は、数か月の手動ドキュメント作成を数時間の AI によるインサイト生成に変換します。これにより、コードを変更する前に十分な情報に基づいた意思決定を行うための明確さが得られます。この基盤があれば、リアクティブではなく戦略的にモダナイズでき、レガシーアプリケーションをビジネスを推進するスケーラブルで保守可能なシステムに変えることができます。

次のステップとして、パイロットモダナイゼーションプロジェクトから始めてください。以下の追加リソースを確認し、レガシーコードベースに対して包括的コードベース分析を実行してください。アーキテクチャのインサイトを分解の計画に活用し、技術的負債の分析結果に基づいてモダナイゼーションの各フェーズの優先順位を決定し、抽出されたビジネスロジックをステークホルダーと共有してアラインメントを構築してください。定期的に再実行して進捗を追跡し、モダナイゼーションの取り組みが計画した成果を達成していることを検証できます。

Amazon Web Services ブログ