experience-aura-lwc-migrate

Aura を LWC に移行する

PRD 主導のワークフローを使用して、既存の Salesforce Aura コンポーネントバンドルを Lightning Web Component に移行します。Aura のソースを 8 つの専門的な観点（静的参照、データ、API サーフェス、スロット、スタイル設定、デフォルト値、不明な依存関係、冗長コードのクリーンアップ）から分析し、フレームワークに依存しない PRD を作成します。これを LWC 作成スキルに引き継ぎ、Aura→LWC 完全性チェックリストに照らして検証します。

使用する場面

• Aura バンドル（.cmp、.controller.js、.helper.js、.renderer.js、.css、.design、.evt、.intf）を LWC に移植する場合。
• Aura ソースからフレームワークに依存しない PRD を作成し、姉妹チームが LWC 版を実装できるようにする場合。
• LWC への変換前に明示的なマッピングが必要なパターン（ファセット、aura:id による DOM アクセス、force:recordData、アプリケーションイベント）について、Aura コンポーネントを監査する場合。

次の場合はこのスキルを使用しないでください。

• Aura ソースがなく、Figma または PRD から新しい LWC を作成する場合（experience-lwc-generate に委任してください）。
• 既存の LWC をリファクタリングする場合（experience-lwc-generate に委任してください）。
• このスキルを使わずにすでに完了した変換の完全性を事後評価する場合、または Lightning Out Beta → 2.0 のホストページ移行を行う場合。これらをカバーするチェックイン済みのスキルは、現在ありません。

前提条件

• Aura コンポーネントバンドルのファイル（最低限 .cmp。通常はコントローラー、ヘルパー、CSS、イベント、インターフェースも含みます）。
• 移行先の LWC パス（モジュールフォルダー）。sfdx-project.json の packageDirectories から呼び出し元のモジュールツリーを特定します（通常、一覧にあるパッケージパスのいずれかの下に lwc/<name>/ サブディレクトリがあります）。
• リゾルバーを使った依存関係の検索（フェーズ 2、ステップ 7）を行うには、呼び出し元のワークスペースに @sfdc-internal/adk-knowledge パッケージがインストールされている必要があります。インストールされていない場合、このスキルは失敗せず、不明な依存関係として報告します。
• プロジェクトの後続の LWC 作成ワークフローを把握していること。このスキルは PRD をそのワークフローに引き継ぎますが、呼び出しは行いません。

基本原則

各フェーズの前と実施中に、Aura → LWC の移行原則を適用してください。変換前に理解し、構造の同等性より機能の同等性を優先し、ネイティブの Web 標準を活用し、段階的に移行し、十分にテストします。アーキテクチャ上の差異（双方向バインディングから一方向バインディングへの変更、Aura イベントから DOM イベントへの変更、aura:id から this.template.querySelector への変更など）については、references/aura-migration-guidelines.md に記載されています。

ナレッジベース

• references/aura-prd-framework.md — Aura コンポーネントからフレームワークに依存しない PRD を作成するための 14 セクションのフレームワークです。
• references/aura-migration-guidelines.md — 基本原則 + Aura と LWC のアーキテクチャ上の違い + マークアップ / JS / イベント / ライフサイクルの変換表です。
• references/aura-reference-expert.md — 静的リソース、グローバル値プロバイダー、HTML から汎用的な表現への置き換え、URL、コンポーネントの依存関係、Aura.Action ハンドラーです。
• references/aura-data-expert.md — データ要件、force:recordData、lightning:recordViewForm、Apex コントローラーです。
• references/aura-api-expert.md — API サーフェス：パブリック属性、メソッド、レイアウト、コンポーネントイベント、DOM イベントです。
• references/aura-slots-expert.md — デフォルトおよび名前付きスロット（Aura のファセット / {!v.body} → LWC スロット）です。
• references/aura-style-expert.md — CSS、SLDS、デザイントークン、動的スタイル設定です。
• references/aura-values-expert.md — デフォルト値と初期化パターンです。
• references/aura-resolver-expert.md — @sfdc-internal/adk-knowledge パッケージを使って、未知のコンポーネント、イベント、インターフェース、ライブラリを解決します。
• references/aura-redundant-code-expert.md — LWC への引き継ぎ前に、PRD から Aura のみに関わる不要なコード（コメントアウトされたコード、テレメトリー、未使用のプライベート属性 / メソッド）を取り除きます。
• WCAG 2.2 — Aura 向けのアクセシビリティレビュアー（SC 1.3.1 (ii) Tables、1.3.5 Identify Input Purpose、3.2.1 On Focus、3.2.2 On Input、3.3.2 Labels or Instructions、4.1.2 Name / Role / Value）は、後続の PR で独立した accessibility-code-review-aura スキルとして追加する予定です。それまでは、フェーズ 3 で WCAG の前文をインラインで適用します。
• references/aura-to-lwc-completeness-checklist.md — 変換後の検証基準です。

対応する PRD セクションを作成または拡充する前に、関連するリファレンスを開いてください。

ワークフロー

このスキルが対象とするのは、分析と PRD 生成のフェーズのみです。LWC バンドル、ワイヤーアダプター、テストの生成、編集、検証は行いません。このスキルが呼び出された場合、以下のフェーズ 1〜3 は必須です。フェーズ 4〜5 は、推奨される後続の作成フローを示したもので、呼び出し元への参考情報としてのガイダンスであり、このスキルでは実行されません。

フェーズ 1 — PRD の分析と作成

目標： 14 セクションのフレームワークのすべてのセクションを網羅する、YAML 形式の PRD ドラフトを作成します。

1. 呼び出し元から提供された Aura バンドルファイルを確認します。コンポーネント名、.cmp メタデータの access 属性、埋め込みまたは参照されているすべてのコンポーネントを抽出します。
2. references/aura-prd-framework.md のフレームワークを適用します。概要で access 属性を明示し、その意味（GLOBAL：名前空間をまたいで一般公開、PRIVILEGED/PUBLIC：制限付き、など）を説明します。
3. unknowns セクションにホストコンポーネント自体を記載してはいけません。循環依存が発生します。有効な未知項目がない場合は、空の配列を使用します。
4. ドラフト PRD をワークスペースに保存します（例：packages/skills/<skill>-workspace/<iteration>/PRD-draft.yaml）。

成果物： 14 セクションを網羅した PRD ドラフト（YAML）。

Phase 2 — Aura エキスパートの視点で PRD を強化する

目標： 8 つの Aura エキスパートのフレームワークを使って、各セクションを強化します。

エキスパートを記載順に適用します。各パスでは、ドラフトの PRD を読み、関連するセクションをその場で書き換えます。

1. リファレンス分析 — references/aura-reference-expert.md を staticReferences、componentCommunication、unknowns に適用します。すべての $Resource、$ContentAsset、$Label、$Browser、$Locale、/lightning/* ルート、および c:*／force:*／lightning:* 依存関係を列挙します。ブループリントに Aura 固有の文字列 $ContentAsset、$Label、$Resource、$Browser、$Locale を直接含めてはいけません。それぞれの意図を説明する記述に置き換えます。
2. データ分析 — references/aura-data-expert.md を dataRequirements に適用します。ブループリントの dataRequirements に force:recordData や lightning:recordViewForm を含めてはいけません。代わりに、基となるレコード、フィールド、オブジェクト API 名を記述します。sObjectName を objectApiName に変更します。Apex コントローラーのメソッド名、入力パラメーター、出力形式を記録します。
3. API 分析 — references/aura-api-expert.md を componentCommunication、interactions、staticReferences に適用します。すべての公開属性（型、デフォルト値、すべての使用目的を含む）、<aura:method> 宣言、イベントの発火（component.getEvent(...).fire()）、および Object 型のコールバック属性（これらは LWC カスタムイベントになります）を記述します。
4. スロット分析 — references/aura-slots-expert.md を contentRequirements に適用します。すべての {!v.body}／{#v.body} をデフォルトスロットのエントリーに変換します（LWC コンポーネントにデフォルトスロットは 1 つしか持てないため、そのスロットが存在する条件を記録します）。また、すべての <aura:attribute type="Aura.Component"> または "Aura.Component[]" を名前付きスロットのエントリーに変換します。
5. スタイル分析 — references/aura-style-expert.md を styling と dataRequirements に適用します。スタイル関連の属性を dataRequirements から styling に移動します。SLDS フック、カスタム CSS、JS によって動的に適用されるスタイルを記述します。
6. 値分析 — references/aura-values-expert.md を dataRequirements に適用します。すべての Aura 属性について、デフォルト値（型＋リテラル値、または $Label 参照の場合は名前空間＋名前）を what プロパティに記録します。
7. リゾルバー分析 — references/aura-resolver-expert.md を unknowns に適用します。不明な項目ごとに、名前空間＋名前を解析し、マッピングルールを使って node_modules/@sfdc-internal/adk-knowledge/dist/ 内の対応ファイルを検索します。解決した内容をインライン化するか、手作業での調査が必要である旨を記載します。@sfdc-internal/adk-knowledge パッケージがインストールされていない場合は、想定されるパスを記載し、不明な項目はそのまま残します。
8. 冗長コードのクリーンアップ — PRD 全体に references/aura-redundant-code-expert.md を適用します。コメントアウトされたマークアップ／JS／CSS、テレメトリー／計測コード、ほかで使用されていないプライベート属性／メソッドを削除します。これらは LWC に引き継がれません。PRD の JSON 形式は維持します。セクションに空の配列が残る場合があります。実際に変更した項目のみを記載した簡潔なレポートを作成します。

成果物： 8 つすべてのエキスパートによるパスを適用した拡張 PRD（YAML）。

フェーズ 3 — アクセシビリティの確認

目標： PRD の accessibility セクションが WCAG 2.2 の最低要件を満たしていることを確認します。

1. Aura ソースファイル（.cmp、.controller.js、.helper.js、.renderer.js、.css）に対して、WCAG 2.2 のレビュー項目をインラインで適用します。Aura の対象となる達成基準を確認します：1.3.1（ii）表、1.3.5 入力目的の特定、3.2.1 フォーカス時、3.2.2 入力時、3.3.2 ラベルまたは説明、4.1.2 名前／役割／値。（後続の PR で関連する accessibility-code-review-aura スキルが提供された場合は、そちらに引き継いでください。）
2. 各指摘を PRD の accessibility セクションに反映します。要件ごとに、満たす WCAG 達成基準と、提案する LWC の実装方法を記載します（まずセマンティック HTML を使用し、同等の結果をセマンティック HTML で実現できない場合に限り ARIA を使用します）。
3. WCAG 達成基準に直接違反する項目のみを指摘します。WCAG の対象外である改善案は提案しないでください。

成果物： 必須機能ごとに、満たす WCAG 達成基準と LWC の実装方法を記載したアクセシビリティセクションを含む PRD。

フェーズ 4 — 後続の作成（ここでは実行しない、後続作業のガイダンス）

拡張された PRD が完成したら、呼び出し元はそれを LWC 作成ワークフローに引き継ぐことができます。このスキルでは作成作業は行いません。推奨される後続手順：

• 拡張された PRD を設計入力として experience-lwc-generate に渡します。Figma／記述仕様の入力の代わりに使用します。このスキルは experience-lwc-generate を呼び出しません。呼び出し元が後続手順として実行します。
• データアクセスの判断（UIAPI／GraphQL／Apex）については、呼び出し元は LDS に特化したワークフローを参照し、PRD の dataRequirements セクションを具体的なアダプターに置き換えることができます。
• SLDS のスタイルに関する判断については、呼び出し元は SLDS デザインワークフローを参照できます。

フェーズ 5 — 後続の検証（ここでは実行しない、後続作業のガイダンス）

LWC の作成が完了したら、呼び出し元はプロジェクト標準のテストおよびレビューワークフロー（Jest カバレッジ、アクセシビリティ Jest、a11y／セキュリティ／RTL レビュー、テレメトリー、機能フラグのゲーティングなど）を使用して、移行したコンポーネントを検証できます。完成した LWC の最終評価として references/aura-to-lwc-completeness-checklist.md を適用してください。

相互参照

• experience-lwc-generate — 推奨される後続の作成ワークフローへの引き継ぎ（実行は行いません。呼び出し元がこのスキルの PRD 完成後に実行します）。

検証（PRD のみ）

• 拡張された PRD が 14 のフレームワークセクションすべてを網羅し、TODO／プレースホルダー項目を含んでいないこと。
• dataRequirements に force:recordData または lightning:recordViewForm への直接参照がなく、sObjectName キーも含まれていないこと（objectApiName に変更済みであること）。
• staticReferences およびその他のセクションに、$Resource、$Label、$ContentAsset、$Browser、$Locale などの Aura 文字列がそのまま含まれていないこと。
• すべての <aura:method> が、対応するトリガーとともに interactions に記載されていること。
• すべての {!v.body}／{#v.body} が、表示条件とともにデフォルトスロットとして contentRequirements に記載されていること。
• 不明点がすべて @sfdc-internal/adk-knowledge パッケージを通じて解決されているか、試行したナレッジファイルのパスを記載して手動対応が必要な項目としてマークされていること。