platform-flexipage-generate

このスキルを使用する場面

次の作業が必要な場合にこのスキルを使用します。

• Lightning ページ（RecordPage、AppPage、HomePage）を作成する
• FlexiPage メタデータ XML を生成する
• 既存の FlexiPages にコンポーネントを追加する
• FlexiPage のデプロイエラーをトラブルシューティングする
• FlexiPage の構造とコンポーネントの設定を理解する
• ページレイアウトまたは Lightning ページのカスタマイズを行う
• ANY *.flexipage-meta.xml ファイルを編集または更新する

仕様

概要

重要：新しい FlexiPages を作成する場合は、必ず CLI テンプレートコマンドから開始してください。 FlexiPage XML を一から作成してはいけません。CLI を使うことで、有効な構造、適切な領域、正しいコンポーネント設定を確保でき、デプロイエラーを防げます。

CLI によるブートストラップを使用してコンポーネントを検出・設定し、Lightning ページ（RecordPage、AppPage、HomePage）を生成します。

---

クイックスタートのワークフロー

ステップ 1：CLI でブートストラップする

新しいページでは必須：この手順は省略できません。 新しい FlexiPage を作成するときは、必ず CLI テンプレートコマンドを使用してください。CLI は、有効な XML 構造、適切な領域、正しいメタデータを生成し、よくあるデプロイエラーを防ぎます。既存の FlexiPage ファイルを編集する場合に限り、この手順を省略できます。

<packageDirectory> = sfdx-project.json の packageDirectories[0] にある path の値（例：force-app）。コマンドを実行する前に、プロジェクトファイルから値を読み取ってください。

sf template generate flexipage \
  --name <PageName> \
  --template <RecordPage|AppPage|HomePage> \
  --sobject <SObject> \
  --primary-field <Field1> \
  --secondary-fields <Field2,Field3> \
  --detail-fields <Field4,Field5,Field6,Field7> \
  --output-dir <packageDirectory>/main/default/flexipages

重要： sf template generate flexipage コマンドが失敗した場合は、作業を中止してください。

1. テンプレートプラグインをインストールします。

   sf plugins install templates
   

2. sf template generate flexipage コマンドを再実行します。
3. FlexiPage XML ファイルが作成されたことを確認します。

テンプレートコマンドが成功するまで、ステップ 2 に進まないでください。生成された XML は、ワークフロー全体に必要です。

テンプレート固有の要件

RecordPage：

• --sobject が必要です（例：Account、Custom_Object__c）
• フィールドパラメーターが必要です。
  • --primary-field：最も重要な識別フィールド（例：Name）
  • --secondary-fields：レコードの概要（推奨 4～6 個、最大 12 個）
  • --detail-fields：必須フィールドを含むレコードの詳細情報（例：Name）

AppPage：

• 追加要件はありません

HomePage：

• 追加要件はありません

フィールド選択のルール

• フィールドの存在を確認する：コマンドで指定する前に、MCP ツールまたは describe コマンドを使ってオブジェクトで使用可能なフィールドを確認します。
• 複合フィールドを優先する：使用できる場合は、FirstName／LastName ではなく Name、BillingStreet／BillingCity／BillingState ではなく BillingAddress、MailingAddress などを使用します。
• 必須フィールドを detail-fields に含める：--primary-field または --secondary-fields にも使用している場合であっても、オブジェクトの必須フィールド（Name など）は必ず --detail-fields パラメーターに含めます。

得られるもの

• 正しい構造の有効な FlexiPage XML
• 事前設定済みの領域と基本コンポーネント
• 適切なフィールド参照とファセット構造
• そのままデプロイでき、さらに拡張することも可能

ステップ 2：ベースページをデプロイする

ページと依存関係を検証するため、ドライランでデプロイします（sfdx-project.json のデフォルトのパッケージディレクトリを使用してください）。

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

重要： 先に進む前に、デプロイエラーをすべて修正してください。ページの検証が正常に完了する必要があります。

ステップ 3：コンポーネントを動的に追加する（要求された場合）

ベースページのデプロイが正常に完了した後、ユーザーが追加のコンポーネントを求めている場合は、以下のコンポーネントを動的に追加するワークフローに従ってください。コンポーネントの追加はすべて、検出と推論のパイプラインを経由する必要があります。記憶だけを頼りにコンポーネント XML を記述してはいけません。

---

重要な XML ルール

すべての XML エンコードルール、項目の参照形式、リージョン／ファセットの種類、fieldInstance の構造、一意識別子の要件、およびよくあるデプロイエラーの解決方法については、references/xml_rules.md をお読みください。

主なルール（簡単な確認用）：

• <value> タグ内の HTML をエンコードします。順序は &、<、>、"、' です。
• 項目の参照形式は Record.{FieldApiName} です（Object.Field は使用しません）。
• すべての <identifier> とリージョンの <name> は、ファイル全体で一意にします。
• 同じファセットに複数のコンポーネントを配置する場合は、複数の <itemInstances> を持つ 1 つのリージョンにまとめます。

---

識別子、リージョン、コンテナ

識別子の生成アルゴリズム、ファセットの命名パターン（名前付きと UUID）、リージョンの選択ルール、コンテナコンポーネントのファセット構造については、references/identifiers_and_regions.md をお読みください。

---

コンポーネント固有のヒント

dynamicHighlights（RecordPage ヘッダー）

場所： header リージョンのみです。完全な構造については、references/record_flexipage_dynamicHighlights.md を参照してください。 CLI は --primary-field と --secondary-fields から Facet を自動生成します。

fieldSection

用途： 項目を列に表示します。3 階層構造です：リージョン → 列ファセット → 項目ファセット。 完全な構造と XML の例については、references/flexipage_fieldSection.md を参照してください。 重要： columns プロパティの値は数値ではなく、Facet 名です。

richText

エンコードルールと XML 構造については、references/flexipage_richText.md を参照してください。 識別子：flexipage_richText または flexipage_richText_{N}

---

必須のメタデータ構造

<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
   <flexiPageRegions>
      
   </flexiPageRegions>
   <masterLabel>Page Label</masterLabel>
   <template>
      <name>flexipage:recordHomeTemplateDesktop</name>
   </template>
   <type>RecordPage</type>
   <sobjectType>Object__c</sobjectType> 
</FlexiPage>

ページの種類：

• RecordPage - <sobjectType> が必要です
• AppPage - sobjectType は不要です
• HomePage - sobjectType は不要です

---

検証チェックリスト

構造（新しいページ）

• CLI で初期化します。FlexiPage XML を一から作成しないでください

識別子とリージョン

• すべての <identifier> の値が、ファイル全体で一意です
• すべてのリージョン／ファセットの <name> の値が、ファイル全体で一意です
• 同じファセット内の複数のコンポーネントは、複数の <itemInstances> を持つ 1 つのリージョンにまとめられています

項目インスタンス

• すべての項目参照が Record.{Field} 形式です
• 各 fieldInstance に uiBehavior を持つ fieldInstanceProperties があります
• 各 fieldInstance が個別の <itemInstances> ラッパーに含まれています

種類とエンコード

• テンプレートのリージョンでは <type>Region</type> を、コンポーネントのファセットでは <type>Facet</type> を使用しています
• HTML／XML を含むプロパティ値がエンティティエンコードされています
• 不要な <mode> タグがありません（コンポーネントのパターンで必要な場合にのみ使用）
• ページ名に __c サフィックスがありません
• 各 Facet が、ちょうど 1 つのコンポーネントプロパティから参照されています

---

クイックリファレンス：CLI コマンド

CLI の完全な例（RecordPage、AppPage、HomePage）と利用可能なオプションについては、references/cli_commands.md をお読みください。

---

コンポーネントの動的な追加

必須のワークフロー： FlexiPage にコンポーネントを追加する場合は、すべてこのワークフローに従う必要があります。記憶を頼りにコンポーネント XML を記述したり、調査を省略したりしないでください。標準の OOTB コンポーネント、カスタム LWC コンポーネント、その他すべての種類のコンポーネントに適用されます。

概要

ユーザーがコンポーネントを要求した場合（例：「関連リストの取引先責任者とレポートを追加して」）、次のパイプラインに従います。

1. Parse Intent → identify ALL requested components
2. Discover ALL → batch components through 3-tier discovery
3. Infer Properties → run 3-step inference for EACH discovered component
4. Generate XML → produce valid XML for all components together
5. Validate → check identifiers, regions, property completeness

重要なルール： 最初にすべてのコンポーネントをまとめて調査します（スキャン 1 回、MCP 呼び出し 1 回）。その後、各コンポーネントのプロパティを推定します。コンポーネントごとに調査手順を実行したり、調査と推定を交互に行ったりしないでください。

手順 1：ユーザーの意図を解析する

ユーザーの発言から、要求されたすべてのコンポーネントを抽出します。例：

• 「レポートと関連する取引先責任者を含む取引先ページを作成して」→ 2 つのコンポーネント：レポート、関連リスト
• 「活動、Chatter、ケースの DRL を追加して」→ 3 つのコンポーネント：活動、Chatter、動的関連リスト

ステップ 2：3 層コンポーネントの検出

次の層に進む前に、すべてのコンポーネントについて各層を完了してください。コンポーネントごとに層 1 → 2 → 3 の順で実行しないでください。

層	ソース	タイミング	呼び出し
1	ローカルワークスペースのスキャン	必ず最初に実行 — すべてのコンポーネントが対象	0（ローカルのみ）
2	discoverUiComponents MCP アクション	層 1 の後も未解決のすべてのコンポーネントを対象に 1 回だけ呼び出す	1
3	新しい LWC バンドルの生成	層 2 の後も未解決のコンポーネントのみ対象（ユーザーの確認後）	0

すべてのコンポーネントについて層 1 が完了したら、未解決のものだけを集め、単一の MCP 呼び出しで層 2 に渡してください。層 2 の後も未解決のコンポーネントのみが層 3 に進みます。

詳細については、以下の ローカルワークスペーススキャナー と MCP アクションの統合 のセクションを参照してください。

ステップ 3：プロパティの推定（コンポーネントごと）

検出された各コンポーネントについて、次の 3 ステップの戦略でプロパティを推定します。

1. スキーマを取得するか、ソースを読む — 層 2（組織）のコンポーネントでは getUiComponentSchemas を呼び出し、層 1（ローカル）のコンポーネントではソースから @api プロパティを抽出します
2. コンポーネントの指示を適用する — references/<name>.md が存在する場合は読み込み、その推定ルールに従います
3. 残りを解決する — 適切なデフォルト値 → LLM による推定 → ユーザーへの質問（最後の手段）

詳しくは、以下の ハイブリッドプロパティ推定戦略 を参照してください。

ステップ 4：XML を生成する

次のことはできません。

• XML ファイルのトップレベル構造を変更すること
• 3 層コンポーネントの検出で解決されていないコンポーネントを記憶から追加すること
• 拡張を加えること

XML を書き込む前に references/xml_rules.md を読んでください。 そこに定義されているすべての要素名と構造のルールに従ってください。

解決済みのすべてのコンポーネントについて <itemInstances> XML を生成します。

• すべてのプロパティに <componentInstanceProperties> を使用します（<properties> は使用しません）
• 全体を通して一意の識別子を割り当てます（references/identifiers_and_regions.md を参照）
• 適切なリージョン（header、main、sidebar、または facets）に挿入します
• 各コンポーネントの指示ファイルまたはスキーマにある XML 構造に従います

ステップ 5：検証

FlexiPage 全体について、以下を確認します。

• 識別子の一意性（ファイル全体に重複がないこと）
• リージョンの妥当性（コンポーネントが正しいリージョンにあること）
• プロパティの完全性（必須プロパティがすべて設定されていること）
• XML エンコーディング（HTML の値がエンティティエンコードされていること）
• 要素名の正確性（references/xml_rules.md §6 を参照）

ドライランでデプロイします（sfdx-project.json のデフォルトのパッケージディレクトリを使用します）。

sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json

---

MCP アクションの統合

入出力の例とパラメーター表の詳細については、references/mcp_action_examples.md を読んでください。

execute_metadata_action を介した 2 つの MCP アクション：

アクション	目的	タイミング
DISCOVER_UI_COMPONENTS	ページタイプに対応するコンポーネントを検索する	層 2 の検出 — 未解決のすべてのコンポーネントを対象に 1 回だけ呼び出す
GET_UI_COMPONENT_SCHEMAS	プロパティスキーマを取得する	プロパティ推定のステップ 1（層 2 の組織コンポーネントのみ）

主な規約：

• コンポーネント定義の形式：MCP 呼び出しでは namespace/blockName（スラッシュ区切り）、XML では namespace:blockName（コロン区切り）
• RECORD_PAGE では entityName を含む pageContext が必須です
• getUiComponentSchemas は部分的な失敗に対応しています — 各コンポーネントの success ブール値を確認してください

---

ローカルワークスペーススキャナー

MCP 呼び出しを行う前に、ローカルの SFDX プロジェクトをスキャンしてカスタム LWC コンポーネントを検索します（層 1 の検出）。

アルゴリズム

コンポーネントのクエリごとにスキャナーを実行します（ローカルスキャン — ネットワーク呼び出しなし）。

scripts/scan-lwc-components.sh "<query>" [packageDirectory]

このスクリプトは <packageDirectory>/**/lwc/*/ をスキャンし、camelCase のコンポーネント名をトークン化して、ユーザーの意図を表すキーワードとの一致度を採点し、信頼度の階層を含む一致結果の JSON 配列を返します。

• 高信頼度（≥70%）： 自動選択し、ユーザーに確認する
• 中信頼度（40-69%）： ユーザーが選択できるよう、順位付きリストを提示する
• 低信頼度（<40%）： スキップして層 2 に進む

いずれかのコンポーネントを層 2 に進める前に、すべてのコンポーネントについて層 1 を実行してください。層 1 で未解決のコンポーネントをすべて集め、単一の MCP 呼び出しで層 2 に渡してください。

曖昧さの解消

中程度の信頼度（40～69％）の候補、または信頼度の高い候補が複数ある場合：

1. 各候補の .js-meta.xml を読み、<description> と <targetConfigs> を確認します
2. コンポーネント名と説明を添えて、順位付けしたリストをユーザーに提示します
3. ユーザーが選択するか、「該当する候補はない」と伝えます（→ Tier 2 に進みます）

スキップする場合

次の場合はローカルスキャンをスキップします：

• ユーザーが組織レベルのコンポーネントを明示的に指定している場合（「標準のレポートコンポーネントを使う」など）
• ユーザーの意図が既知の標準コンポーネント（DRL、richText など）に明確に対応する場合
• ワークスペースに <packageDirectory> ディレクトリが存在しない場合

---

ハイブリッドなプロパティ推論戦略

検出した各コンポーネントについて、次の3ステップを順番に適用してプロパティを設定します。

ステップ 1：最新スキーマの取得（条件付き）

コンポーネントがローカルマシンに存在しない場合（つまり、Tier 2 で組織から検出されたコンポーネントの場合）に限り、getUiComponentSchemas を呼び出します。ローカルコンポーネント（Tier 1）の場合は、代わりにソースコードから @api プロパティを直接抽出します。

呼び出す場合：

• Tier 2（組織での検出）：必ず呼び出します — スキーマがプロパティ情報の唯一の取得元です
• Tier 1（ローカル）：スキップします — コンポーネントの .js ソースファイルから @api プロパティを読み取ります
• Tier 3（生成）：スキップします — ソースを作成したばかりなので、プロパティはすでに把握しています

ステップ 2：コンポーネントの指示を適用（存在する場合）

bash scripts/resolve-component-instructions.sh <namespace:component> を実行します。ファイルが存在する場合は指示ファイルのパスが返され、存在しない場合は空文字列が返されます。

例：

• record_flexipage:dynamicHighlights → references/record_flexipage_dynamicHighlights.md
• flexipage:fieldSection → references/flexipage_fieldSection.md
• c:expenseTracker → （空 — ファイルなし）

ファイルが返された場合：読み込んで、その推論ルール、XML パターン、デフォルト値に従います。 空の場合：ステップ 3 に進みます。

指示ファイルはスキーマを補完します。ユーザーの意図から値を導き出す方法を示します。スキーマ内のプロパティで、指示ファイルに記載されていないものはステップ 3 で解決します。

ステップ 3：残りのプロパティを解決

まだ解決されていないプロパティには、次の優先順位で適用します。

3a. スマートなデフォルト値のヒューリスティック：

プロパティのパターン	デフォルト値
recordId	{!recordId}
objectApiName / sObjectName	ページの <sobjectType> 値
show* / visible* / display*	true
hide* / hidden* / disabled*	false
接頭辞のない Boolean	false
スキーマで "default" が指定されている	スキーマのデフォルト値を使用

3b. LLM による推論： コンポーネントのスキーマ、ユーザーの意図、ページのコンテキストを使って、妥当な値を推論します。例：ユーザーが「上位の商談を表示するレポート」と言った場合、reportName が商談レポートを参照するように推論します。

3c. ユーザーへの質問（最後の手段）： 推論できない、必須かつ重要なプロパティについてのみユーザーに質問します。ユーザーが「スキップ」と言った場合は、コンポーネント全体を省略します。

Tier 固有の動作

Tier	追加ステップ	スキーマ呼び出し	指示
Tier 1（ローカル）	ソースから @api プロパティを抽出	なし（ソースを使用）	存在する場合
Tier 2（組織）	—	あり	存在する場合
Tier 3（生成）	生成直後のソースから @api を抽出	なし（作成直後）	なし

---

新しい LWC の生成（Tier 3）

コンポーネントがローカル（Tier 1）にも組織内（Tier 2）にも見つからない場合は、新しい LWC の生成を提案します。

トリガー条件

• Tier 1 と Tier 2 の両方で見つからなかったか、ユーザーがすべての候補を却下した
• ユーザーが明示的に「スキップ」または「作成しない」と伝えていない

確認

作成前に必ず確認します。コンポーネント名を説明します。ユーザーが断った場合はスキップし、ほかのコンポーネントの処理を続けます。

生成後

LWC バンドルの作成後：

1. ただちに Tier 1 のローカルコンポーネントとして扱います
2. 生成したソースから @api プロパティを抽出します
3. recordId と objectApiName にスマートなデフォルト値を適用します
4. c:{componentName} を componentName として FlexiPage XML を生成します

命名規則

• ユーザーの意図から導きます：「customer health score」→ customerHealthScore
• camelCase を使用し、JS クラス名にハイフンやアンダースコアは使用しません
• フォルダー名はクラス名と一致させます（先頭の文字は小文字）：customerHealthScore/

---

参照ファイル一覧

ファイル	読むタイミング
references/xml_rules.md	FlexiPage XML を新規作成または編集する前 — エンコーディング、フィールド参照、識別子、デプロイエラー
references/identifiers_and_regions.md	コンポーネントを追加するとき — 識別子のアルゴリズム、Facet の命名、リージョンの選択、コンテナのパターン
references/cli_commands.md	新しいページをブートストラップするとき — RecordPage、AppPage、HomePage の CLI の完全な例
references/mcp_action_examples.md	MCP アクションを呼び出すとき — discoverUiComponents と getUiComponentSchemas の完全な入出力 JSON
references/flexipage_fieldSection.md	列を含む Field Section を追加するとき
references/record_flexipage_dynamicHighlights.md	Dynamic Highlights パネルを追加するとき
references/flexipage_richText.md	Rich Text コンポーネントを追加するとき
scripts/scan-lwc-components.sh	Tier 1 のローカルワークスペースのスキャン — LWC コンポーネント名をトークン化し、ユーザーのクエリとの一致度をスコアリングします
scripts/resolve-component-instructions.sh	プロパティ推論のステップ 2 — コンポーネント定義から説明ファイルのパスを解決します

新しいコンポーネントのパターンを追加するには： 既存のファイルの構成に従って references/<namespace>_<componentName>.md を作成します。このスキルは、プロパティ推論のステップ 2 でファイルを自動的に確認します。

---

動的コンポーネントの検証ルール

動的に追加したコンポーネントの XML を生成した後、デプロイ前に以下のすべてを検証します。

識別子の一意性

• FlexiPage ファイル全体からすべての <identifier> 値を抽出します
• 重複がないことを確認します
• 競合がある場合：サフィックスを自動で増分します（_2、_3 など）

リージョンの妥当性

• コンポーネントを種類に応じた正しいリージョンに配置します：
  • record_flexipage:dynamicHighlights → header のみ
  • flexipage:fieldSection → main またはタブの Facet
  • flexipage:richText → 任意のリージョン

プロパティの充足性

• スキーマで必須とされるすべてのプロパティに値が設定されています
• すべての値が期待される型（String、Boolean、valueList、Integer）と一致しています
• <value> タグ内に生の HTML が含まれていません（エンティティエンコードが必要です）

構造の整合性

• コンポーネントのプロパティから参照されるすべての Facet が、<flexiPageRegions> ブロックとして存在します
• 孤立した Facet がありません（各 Facet はちょうど 1 つのコンポーネントから参照されています）
• 同じリージョンに複数のコンポーネントを配置する場合、複数の <itemInstances> を含む <flexiPageRegions> ブロックを 1 つだけ使用します

コンポーネント間の整合性

• 複数のコンポーネントを追加する場合：すべての新しいコンポーネント間で識別子が一意です
• コンポーネント間で Facet の UUID が重複していません
• 単一配置が必要なコンポーネント（dynamicHighlights、recordDetailPanelMobile）が重複していません