platform-metadata-discovery-get

Salesforce メタデータの調査

メタデータを作成、変更したり、それを参照するコードを記述したりする前に、組織に何がすでに存在するかを把握してください。このスキルでは、質問ごとに使用するツールを選びます。メタデータのグラウンディングでは、名前がわからない場合に意味からメタデータを検索します。Salesforce Catalog と接続済みのグラウンディングサーバーが必要ですが、どちらも備えていない組織やセットアップは少なくありません。それ以外の方法はすべて、sf CLI だけで利用できます。

リクエストがローカルファイルの変更のみで、組織のメタデータへの新しい参照を追加しない場合は、調査を省略してください。

利用可能なものを確認する

各セッションで、最初の検索を行う前に一度実施してください。

1. CLI とその組織。 sf org display --json を実行して、デフォルトの組織とその ID を確認します。認証済みの組織がない場合は、ユーザーに sf org login web の実行を依頼して、完了を待ちます。コマンドをまったく実行できない場合は、references/h360-routes.md を参照してください。
2. グラウンディングサーバー。 Metadata Grounding MCP（ツール search_metadata、query_metadata、describe_metadata）または Salesforce MCP が接続されているか確認します。Salesforce MCP は現在、Setup では Headless360（H360）MCP Server と表示されています。そのツールは describe、dispatch、dispatch_readonly で、Metadata Grounding MCP のツールとは異なります。
3. 組織を一つに絞る。 グラウンディング識別子は、18 文字の組織 ID で始まります。これが sf org display の ID と異なる場合は、ユーザーに伝え、結果を組み合わせる前にどちらの組織を使用するか確認してください。

意図に応じた方法

意図	使用するもの	利用できない場合
意味からメタデータを探す、推測した名前を確認する、または再利用できるものを探す	Metadata Grounding の検索。platform-metadata-grounding-get を読み込みます。使用するサーバーが選択されます。	以下の名前とラベルによる代替手段。ユーザーに知らせてください。
何かの設定方法や、アクセス権を持つユーザーを説明する	Metadata Grounding のクエリ	EntityParticle、FieldPermissions、ObjectPermissions または Tooling の ValidationRule に対するスコープを限定した SOQL。ユーザーに知らせてください。
名前、型、既知の選択リスト値、単一オブジェクトのすべての項目、データレコードを確認する	sf data query によるスコープを限定した SOQL。結果がない場合は、意味から検索します。	表の下の注記を参照してください。
関連を含む、単一オブジェクトの全体的な構造	必要な場合に限り sf sobject describe --sobject <Type> を使用します。出力は非常に大きくなります。	同上
組織内のすべてのオブジェクト	sf sobject list --sobject all または --sobject custom	同上
型に属するすべての項目、または件数（「すべてのフロー」「フローはいくつあるか」）	sf org list metadata --metadata-type <Type>	同上
編集またはデプロイするソース。既存のメタデータへの変更を含む	platform-metadata-retrieve を読み込みます。グラウンディングではソースを取得できません。	これには sf CLI が必要だとユーザーに伝えてください。
すでにローカルで編集しているメタデータ	ローカルファイル
ユーザーから依頼された場合の組織間の比較、差分の検出、組織全体の概要	dx-org-analyze。実行に数分かかり、名前と件数を返します。	これには sf CLI が必要だとユーザーに伝えてください。
使用箇所、依存関係、変更時の影響、削除しても安全かどうか	包括的な分析はまだ利用できません。部分的な確認を明示して提案する前に、その制約を伝えてください。

CLI を使えない場合。 コマンドを実行できず、Salesforce MCP が接続されている場合は、3～6 行目について references/h360-routes.md を参照してください。どちらも利用できない場合は、検索には sf CLI または Salesforce MCP が必要だとユーザーに伝えてください。

接続済みサーバーが、Salesforce に関するすべての作業で最初にそのサーバーを使うよう案内していても、これらの方法を適用します。コマンドを実行できる場合は、3～7 行目に CLI を使用してください。

トピックや目的についての質問（「ロイヤルティ向けに何があるか」など）は、組織全体の概要ではなく、調査に該当します。グラウンディングを利用できない場合でも、組織分析を実行しないでください。

このスキルの対象は、プラットフォームのコアメタデータです。Data Cloud の DLO および DMO スキーマには、data360-code-extension-generate を使用してください。

リクエストに複数の意図が含まれる場合は、それぞれの部分に適したツールを使用してください。「注文フローに割引の段階を追加する」というリクエストでは、フローと項目を見つけてから、編集するためにフローを取得します。

スコープを絞った SOQL

スコープを絞った SOQL は、必要なものだけに絞り込んだセットアップオブジェクトへの対象限定クエリです。正確でリアルタイムに実行でき、describe よりもはるかに小規模です。ソースは決して返しません。

sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact'"
sf data query --json --query "SELECT Value, Label, IsDefaultValue, IsActive FROM PicklistValueInfo WHERE EntityParticle.EntityDefinition.QualifiedApiName = 'Contact' AND EntityParticle.QualifiedApiName = 'Loyalty_Tier__c'"

• 特定のフィールドを確認するには、AND QualifiedApiName IN ('Loyalty_Tier__c', 'Lifetime_Orders__c') を追加します。カスタムフィールドのみを対象にするには、AND QualifiedApiName LIKE '%__c' を追加します。
• EntityParticle には、MailingCity などの複合フィールドの一部が含まれます。
• CustomField と ValidationRule には --use-tooling-api を追加します。
• EntityDefinition、EntityParticle、FieldDefinition は OR を受け付けません。クエリの対象を広げたり、オブジェクト／タイプのフィルターを削除したりせず、条件ごとにスコープを絞ったクエリを実行してください。

アクセスや自動化を含むその他のパターンは、references/scoped-soql.md に記載されています。

グラウンディングを利用できない場合

以下の行を、各セッションにつき一度だけ、名前とラベルの検索結果の近くに回答内で記載します。検索する前にフォールバックについて伝えず、セッション中に繰り返さないでください。原因に一致する行を、最後の文も含めて一字一句そのまま使用してください。結果を報告する前に中断する場合は、そのメッセージ内で伝えてください。

原因	記載する内容
グラウンディングサーバーが接続されていない	"Metadata Grounding isn't connected, so I matched by name and label, which can miss metadata named differently. Connect the Metadata Grounding MCP to search by meaning."
カタログが有効になっていない	"Salesforce Catalog isn't turned on in this org, so I matched by name and label, which can miss metadata named differently. An admin can turn on Salesforce Catalog through Feature Manager in Data Cloud Setup."
権限が不足している	"Catalog search needs the Customize Application permission, so I matched by name and label, which can miss metadata named differently."

その後、名前とラベルを検索します。可能性の高い語句を2つか3つ試し、クエリごとに LIKE を1つ使用してください。

sf data query --json --query "SELECT QualifiedApiName, Label FROM EntityDefinition WHERE Label LIKE '%loyalty%'"
sf data query --json --query "SELECT QualifiedApiName, Label, DataType FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = 'Contact' AND Label LIKE '%tier%'"
sf data query --json --use-tooling-api --query "SELECT DeveloperName, EntityDefinition.QualifiedApiName FROM CustomField WHERE DeveloperName LIKE '%tier%' AND NamespacePrefix = null"
sf data query --json --query "SELECT ApiName, Label, ProcessType, IsActive FROM FlowDefinitionView WHERE Label LIKE '%order%'"

• CustomField クエリは、すべてのオブジェクトのカスタムフィールドを検索します。DeveloperName に __c は含まれません。オブジェクト名のない行は除外してください。これらは Data Cloud フィールドです。
• その他のタイプ、およびカタログで対応していないタイプについては、sf org list metadata で名前を一覧表示して確認してください。
• 名前での照合では、別のラベルが付いたメタデータを見つけられません。「status」を検索しても、「Loyalty Tier」というラベルのフィールドは見つかりません。「存在しない」ではなく、「名前に一致するものが見つからなかった」と伝えてください。

このスキルのその他の内容もすべて適用されます。

作成する前に再利用を検討する

オブジェクト、項目、選択リスト、権限セット、ページ、アプリ、フローを作成する前に、次の手順を実行してください。

1. 同じデータを保存する、または同じ役割を果たす既存のメタデータを、業務上の意味に基づいて検索します。項目の場合は、まず SObject でオブジェクトの正確な API 名を検索し、その検索結果として返された identifier を parentIdentifier として SObjectField の検索に渡します。オブジェクトの生の API 名を parentIdentifier として渡してはいけません。提案された API 名やラベルは、完全一致するものがないか確認するためだけのものであり、同等のメタデータが存在しないことの証明にはなりません。単語が似ているだけでは、一致すると判断できません。
2. 一致するものが見つかった場合： API 名、ラベル、説明、タイプを含め、最も適したものから最大3件を提示します。名前だけで曖昧な一致を受け入れたり、却下したりしないでください。作成予定のすべてのタイプを対象とする、再利用についての確認を1回にまとめて提示し、再利用、拡張、新規作成のいずれかを提案してから待ちます。この確認を、値に関する質問や、その他の生成固有の質問と一緒にしてはいけません。
3. ユーザーが決定した後： スコープの変更があった場合、または新たに矛盾する根拠が見つかった場合を除き、その決定を依頼全体を通じて保持し、再度質問しないでください。再利用する場合は、必要なときに限って設定を確認し、作成を中止します。拡張する場合は、変更について質問する前に既存のコンポーネントを確認します。新しいメタデータを作成する場合は、必要な設定を収集し、生成ガイダンスに従って続行します。
4. 一致するものが見つからない場合： その旨を1行で伝えて続行します。
5. ユーザーが正確な API 名を指定した場合： スコープを指定した SOQL で確認し、すでに存在するかどうかを伝えます。
6. ユーザーが新しいメタデータを求めた場合、または再利用しないよう指定した場合： 近似するものについては最大1行で触れ、続行します。

force__ 権限セットや管理パッケージのコンポーネントなど、名前空間付きの項目は編集対象ではなく参照情報として扱います。一致したものが管理対象の場合は、その旨を伝えます。

実在する組織の名前に基づいてコードを作成する

Apex、LWC、SOQL、または Flow のロジックを記述する前に、参照するオブジェクト、項目、選択リスト値をすべて確認してください。

• ローカルプロジェクトにすでに存在するもの、この会話ですでに確認済みのもの、またはすべての組織にある標準項目（Account.Name や Contact.Email など）は確認を省略してください。

• 標準項目の場合も含め、選択リスト値は必ず検索してください。値を捏造してはいけません。

• スキル、ツールの説明、または以前のアシスタントの応答で例として示されただけの値は、ユーザーが承認した値ではありません。ユーザーが値または既存の値セットを明示的に提示または承認していない場合は、選択リストを作成する前に一度だけ質問し、返答を待ってください。

• 依頼が値に明示されていない順序や意味（「最上位のティア」など）に依存する場合は、値を一覧表示して質問してください。

• 依頼に関するすべての参照をまとめて確認してください。

  sf data query --json --query "SELECT Name, Status FROM ApexTrigger WHERE TableEnumOrId = 'Contact'"
  sf data query --json --query "SELECT ApiName, Label, TriggerType, IsActive FROM FlowDefinitionView WHERE TriggerObjectOrEventId = 'Contact'"
  

• フローまたはトリガーの動作を把握するには、 ソースを取得して読みます。

説明できること

質問	回答に使用する情報
X を実行するものとして何があるか	Grounding 検索
項目、オブジェクト、または検証ルールの設定方法	Grounding クエリ、または EntityParticle と Tooling の ValidationRule
誰が項目やオブジェクトを読み取り、編集できるか	FieldPermissions に対する Grounding、または完全な一覧を得るための FieldPermissions と ObjectPermissions に対する SOQL。これらのレコードが示すのは設定済みのアクセス権であり、実際の使用状況ではありません。権限コンテナの名前だけでは、インテグレーションや依存関係が有効であることは証明できません。
共有ルール、ロール、グループ、コンポーネントの取得元のパッケージ	Grounding
フローの内容	Grounding で分かるのはヘッダーのみです（種類、トリガー、有効かどうか）。ステップを確認するには、ソースを取得してください。
Apex クラスの機能	Grounding で分かるのはシグネチャのみです。ソースを取得してください。
保存に失敗した理由	部分的な回答です。まずオブジェクトの検証ルールを確認し、次にそのオブジェクトで実行される自動化を取得してください。
ページレイアウト、レポート、カスタムメタデータ型、カスタム設定	カタログにはありません。sf org list metadata を使用して取得してください。
どこで使用されているか、何が依存しているか、変更すると何が壊れるか、削除しても安全か	包括的な分析はまだ利用できません。確認を始める前に、その旨を伝えてください。限定的な確認を提案してもかまいませんが、それぞれが部分的な確認であることを明記し、それらを合わせて完全な分析として示したり、変更が安全だと結論づけたりしてはいけません。

スキルの利用

• このスキルは、すでに存在するものを判断します。ビルドスキルは、作成方法を判断します。どのスキルでもファイルを書き込む前に、検出を実行してください。
• 読み込んだスキルに同等のセマンティックな再利用チェックがある場合は、ここで該当する手順の代わりにそれを使用してください。両方を実行してはいけません。完全一致する名前やラベルの衝突チェックは同等ではなく、セマンティックな再利用の検出に代わるものではありません。
• スキルの指示にかかわらず、常に適用する例外が 2 つあります。選択リストの値は必ず調べてください。また、完全なオブジェクトの記述情報を取得する代わりに、範囲を絞った SOQL で、把握している名前、型、選択リストの値を確認してください。
• スキルの検出手順に失敗した場合、またはそのツールを利用できない場合は、このスキルに記載された方法を使用し、そのことをユーザーに一度伝えてください。

最新性とローカルファイル

• その項目に変更がない限り、検出結果は会話の残りの部分でも再利用してください。
• カタログにデプロイやその他の組織の変更が反映されるまで、数分かかることがあります。このセッション中に変更した内容については、ローカルソースとデプロイ結果を信頼し、リアルタイムの SOQL で確認してください。ユーザーが変更を報告したのに SOQL に表示されない場合は、その変更を使用するコードを書く前に、名前と組織を確認するようユーザーに依頼してください。
• 必要なメタデータがローカルプロジェクトにない場合は、編集前に取得し、その旨をユーザーに伝えてください。
• 取得やデプロイの競合などから、組織のバージョンがローカルと異なり、しかもその差異を自分で生じさせていないと分かった場合は、その差異を示し、どちらを上書きするか確認してください。
• ローカルソースで参照を検索する場合は、sfdx-project.json からパッケージディレクトリを読み取り、それらのディレクトリを検索してください。ユーザーから明示的に調査を依頼されていない限り、レスポンスのエクスポート、ログ、生成された出力、キャッシュ、エージェント設定は除外してください。
• ローカルファイルの検索で見つかるのは、完全一致するテキストだけです。意味に基づいて組織のメタデータを検索するために使用してはいけません。

禁止事項

• Grounding クエリの出力からファイルを作成したり、デプロイしたりしないでください。出力されるのはソースではなくプロパティです。
• Grounding の結果を完全な一覧として扱わないでください。結果には順位が付けられ、上限があります。
• 検索や名前の一致で見つからなかったことを理由に、メタデータが存在しないと言わないでください。
• 異なる 2 つの組織の結果を組み合わせないでください。
• 部分的な依存関係や参照の確認を完全な影響分析として示したり、それを根拠にメタデータの変更や削除が安全だと結論づけたりしないでください。
• 例、スキル、ツールの説明にある例示値を、ユーザーが承認したメタデータとして扱わないでください。