ドキュメントAEMユーザーガイド

AEM Cloud Migration Skillの使用 using-cloud-migration-skill

最終更新日： 2026年9月17日
  • 適用対象：
  • Experience Manager as a Cloud Service

作成対象：

  • Developer

このリファレンスでは、サポートされている各移行パターン、BPAの調査結果の提供方法、大規模なプロジェクト全体でのセッションの管理方法について説明します。 概要と設定の手順については、概要を参照してください。

移行Runbookの生成 migration-runbook

プロジェクト全体を評価する場合は、単一のパターンに名前を付ける代わりに、Runbookから始めます。 担当者に次のプロンプトを入力します。

Review my code for AEMaaCS migration

スキルは、コードを変更することなく、プロジェクトルートで​ 読み取り専用migration-runbook.md ​を生成します。 Runbookは、移行スキルが対処できる​ 個の ​個のパターンをカバーし、それぞれに対して次のレコードを含みます。

  • 使用される検出戦略（BPA/CAM所見、アナライザー、またはヒューリスティックコンテンツスキャン）
  • 影響を受けるファイルとパターンごとの検索回数
  • パターンの移行セッションを開始するためのコピー&ペーストプロンプト

Runbookはマークダウンと共に調査結果キャッシュも書き込むため、後のパターンセッションでは、既に発見された調査結果を再利用します。エージェントは再スキャンしません。 ランブックを使用して、最初に取り組むパターンの優先順位を決め、次に説明するようにパターンセッションを開始します。

NOTE
Runbookは読み取り専用です。 コードを編集することはなく、ヒューリスティック（非BPA）の結果は、信頼できるカウントではなく、確認する候補の一致です。

セッションの仕組み workflow-overview

すべての移行セッションは、次の順序に従います。

  1. パターンに名前を付ける:1つのパターンを指定します（例：scheduler）
  2. 調査結果を提供: BPA CSV ファイル、MCP経由のCAM、または特定のファイル パスから
  3. エージェントが変換ルールを読み取ります: スキルは、コードを変更する前に、関連する変換ルールをコンパニオン code-assessment スキルから読み取ります
  4. 5人の最初のバッチ: エージェントは、最大5人の調査結果を変換し、変更された内容を報告します
  5. 確認して続行：各バッチを確認したら、continueに返信して次のバッチに進みます

エージェントは一度に1つのパターンと1つのバッチを処理します。 自動的には処理されません。各バッチには確認が必要です。

移行パターン patterns

スケジューラー scheduler

AEMaaCSのステートレスでコンテナ化されたランタイムと互換性のないsling.commons.schedulerまたはScheduler インジェクションを使用するJava クラスをターゲットにします。

BPA パターン ID: scheduler

エージェントは、コンストラクターベースのスケジューラー登録を@Activate / @Deactivateのライフサイクルメソッドに置き換えて、@Designateを使用してScheduler注入されたジョブをRunnable実装の@Componentに変換します。

ResourceChangeListener resource-change-listener

AEMaaCSの更新が必要なResourceChangeListenerまたはResourceChange個のリスナー実装をターゲットにします。

BPA パターン ID: resourceChangeListener

レプリケーション replication

AEMaaCSではサポートされていないcom.day.cq.replication.Replicatorまたは関連するレプリケーション APIを読み込むクラスをターゲットにします。 エージェントは、それらをContentDistribution ベースの同等のものに置き換え、対応するOSGi サービス参照を更新します。

BPA パターン ID: replication

イベントリスナー event-listener

AEMaaCS イベント処理セマンティクスのために更新する必要があるOSGi EventListenerまたはEventHandler実装をターゲットにします。

BPA パターン ID: eventListener

イベントハンドラー event-handler

AEMaaCSに適応させる必要がある同期OSGi EventHandler サービスをターゲットにします。

BPA パターン ID: eventHandler

Asset API asset-api

非推奨のAssetManager、DAMEvent、またはサポートされていないDAM APIを使用してクラスをターゲットにします。 Agentは、サポートされているAEM Assets API同等の機能に置き換えます。

BPA パターン ID: assetApi

カフェインへのGuava キャッシュ guava-cache

Guavaのキャッシュ （com.google.common.cache.*、Cache、CacheBuilder、LoadingCacheなど）を使用するバンドルをターゲットにします。 AEM as a Cloud Serviceでは、サポートされているインプロセスキャッシュライブラリはCaffeineであるため、エージェントはMavenの依存関係を入れ替え、インポートを更新し、影響を受けるコールサイトを調整します。 カフェインは同じ著者によって書かれており、そのAPIは意図的にほぼ同じであるため、変更はほとんどが機械的です。

BPA パターン ID: guavaCache

BPAはこのパターンを​ バンドル ​の精度（サブタイプ custom.guava.cache）で報告するので、エージェントはバンドルをGuava キャッシュを実際に読み込むJava ファイルに解決し、それらを編集します。 Guava キャッシュの使用は、従来のCloud Serviceから引き継いだコードでのみ行われ、ネイティブのAEM コードでは行われないので、このパターンはcode-assessmentではなく、移行スキルでのみ提供されます。

NOTE
guavaCacheは信頼できる唯一の情報源としてBPAを利用しています。 BPAまたはCAM ソースが利用できない場合、エージェントはフォールバックしてJava ファイルをスキャンし、未確認の候補としてimport com.google.common.cache インポートします。

HTL Lint （data-sly-test） htl-lint

data-sly-test: redundant constant value comparison回のプリント警告を生成するui.apps以下のHTL テンプレートをターゲットにします。 エージェントは、コンテンツパッケージを直接スキャンすることで、影響を受けるテンプレートを検出します。このパターンでは、BPA CSVまたはCAM接続は必要ありません。

BPA パターン ID: htlLint

NOTE
htlLint件の調査結果がBPA CSV書き出しに表示されません。 このパターンのセッションを開始すると、エージェントはダイレクトファイルスキャンを通じてこれらのパターンを検出します。

CLOUD MANAGERへのOSGi設定 osgi-cloud-manager

ui.configのOSGi設定を、完全な環境固有の処理を使用して、Cloud Manager互換の.cfg.json形式に変換します。 いくつかの関連タスクについて説明します。

形式の変換​を構成

AEMaaCSでは、OSGi設定を.cfg.json ファイルとして保存し、環境固有の設定を実行モードでスコープ設定されたフォルダー（config.author/、config.publish/、config.dev/など）に格納する必要があります。 エージェント：

  • 既存の.config、.cfg、およびXML形式のOSGi設定を.cfg.jsonに変換します
  • オーサー固有の値とパブリッシュ固有の値の両方を含む設定を、実行モードでスコープ設定されたファイルに分割します
  • OSGi メタタイプの仕様（文字列、整数、ブール値、配列）に対してプロパティタイプを検証します
  • Adobeが所有するPIDを自動変換するのではなく、手作業によるレビュー用にフラグを付けます

秘密鍵と環境変数

コミットされた設定ファイルからプレーンテキストシークレットと環境固有の値を移動し、Cloud Managerのプレースホルダーに置き換えます。

  • $[secret:NAME]: パスワード、トークン、その他の機密値の場合
  • $[env:NAME]：環境ごとに異なる機密性のない値（サービス URLなど）の場合

対応する変数とシークレットはCloud Managerに適用され、実行時に挿入されます。値はソースコントロールに保存されません。

IMPORTANT
エージェントは会話で秘密値を出力しません。 機密データはすべてデジタル化されたハンドオフファイルに書き込まれ、Cloud Manager APIまたはUIを介して適用されます。

サポートされていない実行モード （URC）

AEM as a Cloud Serviceでは、固定の実行モード ID セットをサポートしています。 サポートされていない実行モードを使用する設定フォルダーは、一度デプロイしても効果がありません。 エージェントは、次のようなサポートされていない実行モード設定（URC）にフラグを立てます。

  • 不明な実行モードトークン （例：config.qaまたはinstall.local）
  • 有効なconfig.author.devの代わりに環境トークン – config.dev.authorの前に続く階層トークン
  • config.Author.devなどの小文字でないトークンと、予約されたconfig.preview （プレビューはパブリッシュから継承）

URCの結果は、最初にベストプラクティスアナライザー（サブタイプ unsupported.runmode、重大度CRITICAL）から得られます。BPA ソースが報告しない場合、エージェントはconfig.*およびinstall.*個のフォルダーをセーフティネットとしてローカルにスキャンします。 検出するたびに、フォルダーパス、問題のある実行モード、および修復が報告されます。設定がまだ必要かどうかを評価し、サポートされている実行モードに変更するか、古い場合は削除します。 注文のみの違反の場合、すべてのトークンが有効ですが、注文されていない場合、エージェントは安全な再注文を自動的に適用できます（例えば、config.dev.authorをconfig.author.devに変更）。不明なトークンやその他のあいまいなケースにはフラグが付けられ、解決できます。

構成形式の変換と秘密鍵の外部化にはBPA CSVまたはCAMは必要ありません。URC検出では、使用可能な場合にBPAの結果が使用されます。 次の内容でセッションを開始：

Scan my config files and create Cloud Manager environment secrets or variables.

ダイアログの移行（レガシーUI） dialog-migration

クラシック UI ダイアログをタッチ UIに変換します。 エージェントは2つのダイアログサブタイプを処理します。ExtJS / Classic UI cq:Dialogの定義はCoral 3 _cq_dialog構造として再構築され、既存のCoral 2 ダイアログはCoral 3にアップグレードされます。 また、リスナー、optionsProvider、namePrefixおよび更新filter.xmlも引き継ぎます。

BPA パターン ID: lui （ダイアログ サブタイプのみ）

同じコンポーネントに対してダイアログとカスタムウィジェットの両方の結果が存在する場合は、最初にカスタムウィジェットの移行を実行して、ダイアログが変換される前にすべてのxtype参照が解決されるようにします。

Convert my Classic UI dialogs to Touch UI Coral 3.

カスタムデザインウィジェット（従来のUI） custom-design-widgets

カスタム ExtJS ウィジェット （cq:Widget定義とカスタム xtype値）を移行します。 エージェントはウィジェットをインベントリし、各xtypeを既知のCoral 3にマッピングするか、直接マッピングが存在しない場合にGranite UI フォームコンポーネントを基礎モードにします。

BPA パターン ID: cdw

Migrate my custom ExtJS widgets (CDW findings) from CAM.

テンプレートの近代化 template-modernization

静的テンプレートを編集可能なテンプレートに変換し、対応するAEM Modernize Tools書き換えルール（構造、コンポーネント、ポリシールール）を生成します。 エージェントは、テンプレートを検出してテンプレートごとのプランを生成し、テンプレートごとにプラン テンプレートを実行し、生成された/conf構造を検証するという3つのフェーズで実行されます。

発見時に、エージェントは、ネストまたはグループ化されたテンプレートフォルダーを含むapps/<appId>/templates/の下のテンプレートを任意の深さで移動し、ページコンポーネントのリソースタイプに基づいて、各静的テンプレートをレガシーまたはカスタムとして分類します。 この分類は、BPA レポートがなくても保持されるため、カスタムテンプレートはレガシーテンプレートとは異なる方法で処理されます。

このパターンでは、BPA パターン IDは使用されません。 次の内容でセッションを開始：

Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.

Dispatcher コンバージョン dispatcher-conversion

AMSまたはオンプレミスのApache HTTPDおよびDispatcher設定をAEM as a Cloud Service構造に変換します。 この機能は、Adobeが管理するDispatcher Converter ツールをラップし、検出、設定の生成、出力検証、検証を追加します。

エージェントは段階的なフローで動作します。

  1. 検出とインベントリ – 設定​ モード ​を決定し、フィルター、書き換え、キャッシュ ルールのベースライン カウントを記録します。 認識されるモードは、standard （AMS）、flexible （モノリシックオンプレミス）、v1 （古いレイアウト）、already-cloud、not-dispatcherおよびunknownです。 already-cloud、not-dispatcher、またはunknownの場合、エージェントは停止し、続行する前に確認を求めます。
  2. コンフィギュレーションの計画と生成 - コンバーターの構成を構築し、プランを確認します。
  3. Convert - AdobeのDispatcher コンバーターを実行します（初回使用時に自動インストールされます）。
  4. Verify – 出力をベースラインに照らし合わせてチェックします。 空のフィルターセット （filter-acl-loss）は、続行する前に解決する必要があるハードストップです。
  5. 境界を越えたハンドオフ - Cloud Manager環境変数をOSGi設定フローにルーティングし、CDNまたはセキュリティヘッダー候補にフラグを付けます。
  6. Validate - Cloud Service Dispatcher バリデーターを実行し、統合コンバージョンレポートを生成します。

Runbook パターン id: dispatcherConversion （設定レイアウトからヒューリスティックに検出されました）。 このパターンでは、BPAやCAMは使用されません。 次の内容でセッションを開始：

Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.
NOTE
クリーンな作業ツリーに対してこれを実行し、変換された出力を簡単にレビューしてロールバックできるようにします。 自動処理の程度は、検出されたモードによって異なります。standard （AMS）設定はほぼ自動化されていますが、flexibleおよびv1 レイアウトにはさらにレビューが必要です。

BPA Source オプション bpa-source

ソース
用途
BPA CSV ファイル
AEM インスタンスまたはCloud Acceleration ManagerからCSVを書き出しました。 セッションの開始時にファイルパスを指定します。
MCP経由のCAM
AEM Cloud Migration MCPが設定されています。 エージェントはCAM プロジェクトをリストし、どのプロジェクトを使用するかを確認し、調査結果を直接取得します。 ​ クラウド移行MCPの使用を参照してください。
手動ファイル パス
BPA レポートなしで特定のファイルを移行する場合。 プロンプトで直接パスを指定します。

MCP エラー処理 mcp-errors

MCP接続がエラー（プロジェクトが見つからないエラーや認証エラーを含む）を返した場合、エージェントは停止し、エラーを表示します。 自動的に別のソースに切り替わることはありません。 停止した状態から、次のことができます。

  • 表示されたエージェントのリストから正しいプロジェクトを確認します
  • 代替としてBPA CSV パスを指定します
  • 手動による移行用に特定のJava ファイルパスを指定する

大規模なレポートをまたいだセッション管理 large-reports

多くの発見があるBPA レポートの場合、バッチによるバッチ処理のアプローチにより、次の段階的な検証が可能になります。

  1. 各バッチの差分の確認
  2. パターン範囲のコミットメッセージでバッチをコミットする
  3. 次のバッチを開始するには、continueに返信してください
  4. パターンのすべての調査結果が完了したことをエージェントが報告するまで繰り返します

コミットごとに​ 1つのパターン ​を使用すると、Git履歴を読み取り可能な状態に保つことができ、必要に応じて個々のパターン変換を簡単に元に戻すことができます。

NOTE
すべての調査結果が処理される前にセッションを終了した場合は、新しいセッションで同じパターンとBPA ソースで再起動します。 エージェントは中断したところから再開します。

Workspace範囲 workspace-scope

エージェントは、開いているIDE ワークスペースフォルダー内でのみファイルを検索および編集します。 親ディレクトリ、兄弟フォルダー、またはディスク上の他の場所はスキャンしません。

BPA検索がワークスペースに存在しないファイルパスを参照する場合、エージェントは停止し、欠落しているパスを通知します。 正しいプロジェクトフォルダーを開くか、パスを明示的に指定して続行します。

recommendation-more-help
experience-manager-cloud-service-help-main-toc