commerce-app-migrate

App Management への移行

ユーザーが、Adobe Commerce App Builder プロジェクトを Integration Starter Kit または Checkout Starter Kit から、@adobe/aio-commerce-lib-app を使用する新しい App Management の方式に移行したい場合に、このスキルを使用します。

このスキルは、検出 → ドメイン分析 → 質疑応答 → 設定の組み立て → 実行という移行全体を調整します。プロジェクトを完全に移行し、デプロイ可能な状態にします。

確認プロトコル

[await] と記された各ステップでは、そのターンを直ちに終了し、以降は何も出力せず、開発者の返信を待ってから続行してください。

自動モード： --auto または --yes を指定して呼び出された場合、あるいはコンテキストから自動化パイプラインであることが示されている場合（対話型ターミナルがない場合）は、すべての [await] ポイントをスキップし、次のステップに進んでください。

ドキュメントスキャンのみモード： --doc-scan-only を指定して呼び出された場合は、Analyzer の後にあるすべての移行ステップをスキップしてください。ステップ 1 の完了後（Analyzer が ProjectSnapshot を返した後）：

• alreadyMigrated === false の場合は、次を出力します。

  --doc-scan-only requires the project to already be migrated to App Management.
  No app.commerce.config.ts (or .js) was found.
  
  Run /commerce-app-migrate (without --doc-scan-only) to perform the migration first.
  

  その後、停止します。

• alreadyMigrated === true の場合は、該当するクロスカッティング警告を適用してから、Executor をドキュメントスキャンのみモードで呼び出します。ファイルは変更しません。 ステップ 2～5 には進まないでください。

---

事前確認

ほかの作業を行う前に、現在のディレクトリが App Builder プロジェクトのように見えることを確認してください。次の項目がすべて存在することを確認します。

• app.config.yaml
• package.json
• 次のうち少なくとも 1 つ：actions/ ディレクトリ、src/ ディレクトリ、actions-src/ ディレクトリ （一部のプロジェクトでは、TypeScript を actions-src/ から actions/ にコンパイルします。actions/ は gitignore の対象となり、新規チェックアウト時には存在しない場合があります）

どの条件も満たさない場合は、直ちに停止して次を出力します。

This directory does not appear to be a Commerce App Builder project.
Expected to find: app.config.yaml, package.json, and an actions/ or src/ directory.

Please run this skill from the root of your App Builder project.

事前確認に失敗した場合は、それ以上先に進まないでください。

---

ステップ 1：Analyzer エージェントを実行する

Agent ツールを使用して、Analyzer エージェント（${CLAUDE_SKILL_DIR}/agents/analyzer.md で定義）を呼び出します。 Analyzer は現在のディレクトリを読み取り、ProjectSnapshot JSON オブジェクトを返します （スキーマは ${CLAUDE_SKILL_DIR}/shared/schema.md で定義）。

概要を表示する前に、次の早期終了条件を確認してください。

alreadyMigrated === true の場合： 次を出力します。

This project appears to already be migrated to App Management.
Found: app.commerce.config.ts (or app.commerce.config.js with ESM defineConfig)

Re-running migration would overwrite your existing configuration.
If you want to re-generate specific sections, please specify which
section to update: metadata / eventing / installation / adminUi / businessConfig

その後、該当するクロスカッティング警告を適用します（下記のサブセクションを参照）。

次に、Executor エージェント（${CLAUDE_SKILL_DIR}/agents/executor.md）を ドキュメントスキャンのみモードで呼び出し、プロジェクトに関するドキュメントの推奨事項を作成します。

• Executor に mode = "doc-scan-only" を渡します
• Analyzer の ProjectSnapshot JSON を渡します
• assembled config = null を渡します（書き込む新しい設定はありません）

Executor は、既存の app.commerce.config.ts と照合しながら README.md と env.dist をスキャンし、ファイルを変更せずに「ドキュメントの推奨事項」レポートを出力します。

開発者が特定のセクションの更新を明示的に要求しない限り、ステップ 2～5（ドメインエージェント、質疑応答、設定の組み立て、完全な実行）には進まないでください。

Executor がドキュメントの推奨事項を出力したら、停止してください。「検出されたプロジェクト：」の概要ブロックや、以下の移行確認プロンプトには進まないでください。

Analyzer が結果を返したら、人が読める概要を出力します。 検出されたプロジェクト： 種類： Starter Kit 認証モード： (<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "Both PaaS + SaaS" | unknown = "Unknown">) アクションパッケージ： ( packages) オンボーディング：<comma-separated list of script paths with purposes, or "none"> パッケージマネージャー：

移行に含まれるもの：confidence !== "none" のドメインのリスト

該当するクロスカッティング警告を適用してください（下のサブセクションを参照）。

hasMeshConfig === true の場合、次も追加してください：

⚠ API Mesh の設定が検出されました（mesh.json）。
Mesh の設定は自動移行できないため、手動で保持する必要があります。

次に質問してください：

これは正しいですか？（yes / no — いいえの場合は、問題点を説明してください）
Enter キーを押すか、"yes" と入力すると自動的に続行します。

[await]

修正への対応：

• 開発者が starterKitType を修正した場合、続行する前に ProjectSnapshot を更新してください
• 開発者が authMode を修正した場合、更新してください
• 修正内容を反映した概要を再表示して、確認されるまで再度質問してください

不明な starterKitType への対応： starterKitType === "unknown" の場合は、extensionPointsInUse を確認してください：

• "commerce/backend-ui/1" が含まれている場合 → これは Admin UI SDK v1 拡張機能です。starterKitType = "unknown" のまま続行してください。admin-ui-sdk ドメインエージェントが v2 に移行します。 次のメモを表示してください："Admin UI SDK v1 (commerce/backend-ui/1) を検出しました。v2 (commerce/backend-ui/2) に移行します。"

• すべての confidence 値が "none" で、extensionPointsInUse が空の場合： 次を出力してください：

  このプロジェクトは Integration Starter Kit または Checkout Starter Kit を
  ベースにしていないようです。イベントコンシューマー、webhook、Admin UI SDK の
  パターンは検出されませんでした。
  
  移行では、メタデータのみを含む最小限の app.commerce.config.ts を生成できます。
  続行しますか？（yes / no）
  

  開発者が no と回答した場合は停止してください。yes と回答した場合は、ドメインの結果を空のまま続行してください。

• それ以外の場合は、開発者に質問してください：

  このプロジェクトがどのスターターキットをベースにしているか判断できませんでした。
  Integration Starter Kit と Checkout Starter Kit のどちらですか？
  選択肢：[integration / checkout / adminUiSdk / custom]
  
  わからない場合は、ドキュメントを参照してください：
    • Integration Starter Kit：https://developer.adobe.com/commerce/extensibility/starter-kit/integration/
    • Checkout Starter Kit：    https://developer.adobe.com/commerce/extensibility/starter-kit/checkout/
  

  続行する前に、回答に基づいて ProjectSnapshot を更新してください。

クロスカッティング警告

移行の状態にかかわらず、ProjectSnapshot で該当するフィールドが設定されている場合は、常に適用してください。現在作成中の出力に、該当するブロックをそれぞれ追加してください。

openWhiskTriggers が空でない場合、次を追加してください：

⚠ OpenWhisk トリガーが検出されました（自動移行できません）：
  <各トリガーの説明を列挙>
これらのスケジュール済みトリガーに相当する機能は、App Management にありません。

${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（OpenWhisk Triggers セクション）を読み、代替オプションを開発者に提示してください。

hasApiGateway === true の場合、次を追加してください：

⚠ OpenWhisk API Gateway のルートが検出されました（ランタイムマニフェスト内の apis: ブロック）。
これらの HTTP ルートに相当する機能は、App Management にありません。

${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（API Gateway セクション）を読み、移行オプションを開発者に提示してください。

hasSequences === true の場合、次を追加してください：

⚠ OpenWhisk シーケンスが検出されました。
アクションシーケンスに相当する機能は、App Management にありません。

${CLAUDE_SKILL_DIR}/shared/migration-warnings.md（Sequences セクション）を読み、リファクタリングのガイダンスを開発者に提示してください。

---

ステップ 2：ドメインエージェントを並行してディスパッチする

confidence !== "none" となる各ドメインについて、Agent ツールを使用して、対応するエージェントを同時にディスパッチします（1 回の並行呼び出しです）。

confidence フィールド	エージェントファイル
confidence.events !== "none"	${CLAUDE_SKILL_DIR}/agents/events.md
confidence.webhooks !== "none"	${CLAUDE_SKILL_DIR}/agents/webhooks.md
confidence.adminUiSdk !== "none"	${CLAUDE_SKILL_DIR}/agents/admin-ui-sdk.md
confidence.businessConfig !== "none"	${CLAUDE_SKILL_DIR}/agents/business-config.md

各エージェントには、次の情報を渡します。

• ProjectSnapshot JSON
• 各自の Read ツールを使用して、現在のディレクトリにある関連ファイルを読むよう指示

返されたすべての DomainResult オブジェクトを収集します。それぞれに domain、configFragment、unresolvedQuestions フィールドがあります（スキーマは ${CLAUDE_SKILL_DIR}/shared/schema.md に記載）。

---

ステップ 3：質問をまとめて確認する

すべての DomainResult から unresolvedQuestions を収集します。すべてのドメインで未解決の質問がない場合は、ステップ 4 に進みます。

すべての質問を 1 回のセッションにまとめて提示します（形式は ${CLAUDE_SKILL_DIR}/shared/questions.md に記載）。

• ドメインごとにまとめる
• default 値がある質問は、確認形式で表示します（「推奨：X」）
• ドメインをまたいで質問に順番に番号を付ける

[await]

回答を受け取るたびに、次の処理を行います。

• 対応する DomainResult の configFragment に反映する
• 質問の id を使って、更新する正確なフィールドを特定する

開発者が推奨値を受け入れた場合（Enter を押す、または「yes」と答える）、default を使用します。

特別なケース — デフォルトでスキップする質問（default が "no" の場合）： これらの質問では、必要なデータが不足しているため configFragment から除外されたオプションのセクション（例：デプロイ済みのアクションパッケージがないプロバイダーの方向）を含めるかどうかを尋ねます。開発者の回答は、次のように解釈します。

• "no"（または Enter を押す）→ セクションを configFragment から除外したままにする。何もしない
• "yes" または任意のアクション文字列 → セクションを追加する。回答にランタイムのアクション名が含まれていない場合は、その名前を尋ねてから configFragment に反映する

自律モード — 自動承認されたデフォルト値の概要：

--auto モードでは、すべての質問のデフォルト値を適用した後、次の内容を出力します。

── 自動承認されたデフォルト値 ────────────────────────────────────────
  次の質問は自動的に回答されました（--auto モード）：
  [  <domain> : <question id> = "<default value>"  ]
     ← 明示的なデフォルト値があった質問ごとに 1 行。質問がなかった場合はセクション全体を省略 →

すべてのドメインで未解決の質問がなかった場合、このセクション全体を省略します。

---

ステップ 4：app.commerce.config.ts を組み立てる

現在のディレクトリにある package.json を読み込み、メタデータを抽出します。

すべての configFragment オブジェクトをマージして、設定全体を組み立てます。

import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    id: "<derived from package.json name>",
    displayName: "<derived from package.json name>",
    version: "<from package.json version or 1.0.0>",
    description:
      "<from package.json description or 'Commerce App Builder application'>",
    upgradeMode: "auto",
  },
  // eventing: { ... }          ← from events DomainResult, if present
  // installation: { ... }      ← from webhooks DomainResult, if present
  // adminUi: { ... }           ← from admin-ui-sdk DomainResult (migrated from v1), if present
  // businessConfig: { ... }    ← from business-config DomainResult, if present
});

メタデータの決定ルール：

• id：まず extension-manifest.json を確認します。id フィールドがあり、パッケージ名のボイラープレートと異なる場合は、それを使用します（同じ正規化を適用します：小文字にし、英数字以外を - に置き換え、前後をトリミングし、最大 50 文字）。 それ以外の場合は、package.json の name を使用します。npm スコープ（@scope/）を削除します。英数字以外（- を除く）をすべて - に置き換えます。文字列全体を小文字にします。 前後のハイフンをトリミングします。最大 50 文字です。 extension-manifest.json を優先する、既知の ISK ボイラープレート名： commerce-integration-starter-kit、starter-kit、commerce-checkout-starter-kit、 aio-app-builder-template。
• displayName：まず extension-manifest.json を確認し、displayName フィールドがある場合はそれを使用します（50 文字に切り詰めます）。それ以外の場合は、id をタイトルケースにします（- をスペースに置き換えます）。 最大 50 文字です。
• version：package.json の version を使用します。デフォルトは "1.0.0" です。
• upgradeMode：開発者が自動実行を明示的に求めていない限り、"manual" を使用します（アップグレード実行が安定するまでは、現在これがデフォルトです）。"auto" は実験的なモードです。生成される post-deploy フックは desired-state の POST /installation エンドポイントを呼び出して計画されたアップグレードを開始し、その後、ライフサイクルの結果を待ちます。"manual" モードでは、同じエンドポイントがプランを作成または再利用し、実行を開始せずに返します。
• description：存在する場合は、package.json の description を使用します。 説明が 255 文字を超える場合、文の途中で切り詰めてはいけません。 代わりに説明全文を読み、重要な意味（アプリの機能、接続先のシステム、主な機能）を保ちながら、255 文字以内に収まる短い説明を書き直します。できるだけ完結した文にします。主要な目的よりも、二次的な詳細（デプロイに関する注記、網羅的な機能一覧）を先に削ります。"..." で終わらせてはいけません。書き直した説明は、意図的に作成された文章として読める必要があります。 書き直した値が適用されるのは設定のみです。Executor は init の前に元の package.json の説明を記録し、その後復元します（init は設定値を package.json に書き戻します）。 説明がない、または空の場合は、extension-manifest.json の description フィールドを確認します（同じ書き直しルールを適用します）。 どちらにも説明がない場合は、"Commerce App Builder application" を使用します。

productDependencies のコメント： ProjectSnapshot.productDependencies が null でない場合（minVersion および／または maxVersion を含む場合）： 組み立てた TypeScript に、著作権ヘッダーの直後、import { defineConfig } 行の前に、次のコメントブロックを挿入します。

// Product version constraints (no App Management equivalent — for reference only):
// Adobe Commerce compatibility: >= <minVersion>, < <maxVersion>
// Contact Adobe Commerce Marketplace for guidance on version enforcement.

maxVersion が null の場合は、< <maxVersion> の部分を省略します。minVersion が null の場合は、>= <minVersion> の部分を省略します。両方が null の場合、または productDependencies が null の場合は、コメント全体を省略します。

組み立てた TypeScript の内容をターミナルに出力します。

作成される app.commerce.config.ts は次のとおりです。

─────────────────────────────────────────────────────────
import { defineConfig } from '@adobe/aio-commerce-lib-app/config'

export default defineConfig({
  ...assembled content...
})
─────────────────────────────────────────────────────────

この内容でよろしいですか？（yes / no — no の場合は、更新が必要なセクションを指定してください）
Enter キーを押すか「yes」と入力すると、自動的に続行します。

[await]

拒否された場合の処理： 開発者が no と答えた場合は、次のように尋ねます。「どのセクションを更新しますか？（metadata / eventing / installation / adminUi / businessConfig）」

次に、そのセクションについて具体的な修正内容を尋ね、組み立てた設定を更新し、再度出力して確認を求めます。

開発者が確認するまで繰り返します。フロー全体を最初からやり直してはいけません。修正対象のセクションについてのみ、Q&A を再実行します。

---

ステップ 5：移行を実行する

以下の内容を指定して、Executor エージェント（${CLAUDE_SKILL_DIR}/agents/executor.md）を起動します。

1. 文字列としての、組み立て済みの app.commerce.config.ts TypeScript コンテンツ
2. 最終版の ProjectSnapshot JSON

Executor はすべてのファイル書き込みと CLI コマンドを実行し、移行の概要を出力します。

Executor がエラーを報告した場合は、エラーメッセージと失敗したステップを伝えてください。 変更をロールバックしようとしないでください。Executor が作成した git ブランチがロールバックポイントになります（移行を破棄するには git checkout main を実行します）。

---

メモ

• ドメインエージェント（ステップ 2）は並列で実行されます。対象となるエージェントをすべて 1 回の Agent ツール呼び出しで起動してください。
• Analyzer（ステップ 1）と Executor（ステップ 5）は順次実行されます。最初に Analyzer を実行し、最後に Executor を実行してください。
• このスキルは移行スキルのリポジトリではなく、開発者のプロジェクトディレクトリで実行されます。
• ドキュメントに関する推奨事項は Executor が作成し、以下を対象とします。
  • 5 つのパターンで検出される README.md のセクション：ISK のオンボーディングコマンド、古い環境変数の参照、古くなったアーキテクチャ図、認証情報ファミリーのセマンティックマッチング（IMS/SaaS、PaaS/OAuth1、ワークスペース）、環境セットアップの定型文（cp env.dist .env）
  • 3 つの分類にまとめられた env.dist エントリ：削除しても安全（App Management によって管理）、要手動確認（アクションのソースファイルで参照され、ファイルごとに分類）、オンボーディング専用（オンボーディングスクリプトでのみ使用）
  • ルール 9 は、他のルールに該当しない、参照されていない env.dist 変数を検出し、手動確認の対象としてフラグを付けます。
  • カテゴリ C（README）では、推奨事項のブロックを出力するために、フラグが付いたセクションが 5 つ以上必要です。
• --auto モードでは、自動的にデフォルト値が適用された Q&A の質問の概要を出力します（質問がなかった場合は省略されます）。
• productDependencies のバージョン制約は extension-manifest.json から取得され、生成された app.commerce.config.ts の import { defineConfig } 行の直前にコメントブロックとして自動挿入されます。
• ドメインエージェントは configFragment オブジェクトに内部メタデータフィールド（_directionWarning、_source）を追加する場合があります。Executor はファイルを書き込む前にこれらを削除するため、出力される TypeScript に含まれることはありません。

サポートファイル

このスキルで起動されるエージェントファイル：

• Analyzer
• Events
• Webhooks
• Admin UI SDK
• Business Config
• Executor

共有リファレンスファイル：

• Schema
• Questions format
• Migration warnings
• External references