experience-lds-data-requirements-generate

LDS データ要件の生成

要件の明確化、API 名の検証、API の推奨という 3 段階のアナリストワークフローを実行し、後続の開発者が推測に頼らず Lightning Data Service（LDS）ソリューションを実装できるようにします。

使用するタイミング

• PRD、Figma のコメント、またはユーザーからの依頼で Salesforce のデータが言及されているものの、オブジェクト、項目、操作が曖昧な場合（「顧客情報を表示する」「レコードを更新する」「今後のライブを一覧表示する」など）。
• 新しいデータ要件に対応する @wire／Apex コードを書く前、または推奨内容を後続の実装ワークフローに渡す前。
• // TODO: fetch related records のような TODO を引き継ぎ、正確な仕様にまとめる必要がある場合。

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

• データ要件がすでに完全に指定されている場合（オブジェクト API 名、項目 API 名、操作の種類、範囲）。
• コンポーネントが Salesforce データにまったく触れない場合（UI のみ、外部 REST、ローカル状態）。

前提条件

• 自然言語で記述された要件（PRD の抜粋、ユーザーからの依頼、または TODO コメント）。
• カスタムオブジェクト／項目の API 名を確認するための、対象組織の「設定」→「オブジェクトマネージャー」へのアクセス。
• 現在の GraphQL／UI API／Apex の優先順位（読み取りに対応できる場合は、最初に GraphQL を検討する）を把握していること。

ナレッジベース

• references/requirements-analysis.md — 要件分析モードのフレームワーク。
• references/api-name-validation.md — オブジェクト／項目の API 名を特定するための精密モード。
• references/api-recommendation.md — GraphQL → UI API → Apex の判断フレームワーク。
• references/lds-expert.md — LDS の全般的なパターンと注意点。
• references/lds-data-consistency.md — キャッシュと整合性の保証。
• references/lds-referential-integrity.md — 親子関係と関連レコードのルール。

ワークフロー

3 つのステップを必ず順番に実行してください。呼び出し元がすでに出力を確認済みの場合を除き、ステップを省略しないでください。

ステップ 1 — データ要件を解析する（要件分析モード）

**目標：**把握している情報をすべて抽出し、先に進む前に不明点をすべて明らかにします。

すべての会話を次の文で始めます。

"データ要件「」を分析しました。理解した内容と、確認が必要な点を以下に示します…"

references/requirements-analysis.md の 4 つのアクションを適用します。

1. 操作の種類 — 読み取り、作成、更新、削除のどれですか？曖昧な動詞がある場合は、ただちに確認してください。次のように確認します。「これは 操作であると判断しました。正しいですか？」
2. データエンティティの特定 — 標準オブジェクト（確信度が高いため続行）、カスタムオブジェクトの可能性あり（「これはカスタムオブジェクト <Term>__c ですか？正確な API 名を教えてください」と質問）、または不明（オブジェクトマネージャーで API 名を確認するよう依頼）。
3. 項目の指定 — 一般的な表現（phone、address、name、status）を特定の API 名に対応付けます。候補が複数ある場合は、列挙して質問してください。
4. 範囲とコンテキスト — 1 件のレコードか複数か、ユーザー操作による実行か自動実行か、想定件数、リアルタイムかオンデマンドかを確認します。

**ステップ終了時のゲート。**次の形式にまとめます。

Clear Requirements: [confirmed facts]
Need Clarification: [numbered questions from 1.1–1.4]

すべての質問に 90％以上の確信度で回答できた場合にのみ、次へ進んでください。

Step 2 — Salesforce API 名を検証する（精度モード）

目標： コードを記述する前に、すべてのオブジェクトとフィールドの API 名を 100% 正確に確認します。

references/api-name-validation.md の検証フレームワークを適用します。

• 標準オブジェクト — Account、Contact、Lead、Opportunity、Case、User、Task、Event、Product2、Pricebook2、Order、OrderItem、Asset、Contract、Campaign は即時に確認済みとして扱います。それ以外の場合は検証を行います。
• カスタムオブジェクト — __c サフィックスを決めつけないでください。次のように尋ねます：「これは <Term>__c ですか、それとも別のカスタムオブジェクト API 名ですか？」ユーザーには、Setup → Object Manager → → Details → API Name を確認するよう案内します。
• 標準フィールド — 参照ファイルの表を使って、曖昧な参照を対応付けます。
• カスタムフィールド — __c サフィックスの確認が必要です。大文字と小文字を区別します。

確認テンプレート：

Object API Name: <OBJECT>
Field API Names: <FIELD_LIST>
Confidence Level: 100% validated

不明点が残っている場合は、停止します。未完了の確認依頼と Setup のナビゲーション手順を提示します。Step 3 に進んだり、コードを生成したりしないでください。

呼び出し元が API 名は上流ですでに検証済みであると明示している場合、または要件がレコードにまったく関係しない場合に限り、このステップをスキップします。スキップした理由を Step 4 の出力に記録します。

Step 3 — API を推奨する（ソリューションアーキテクチャモード）

目標： references/api-recommendation.md の判断フレームワークを使って、適切なデータアクセス API を選択します。

優先順位（必須）：

1. GraphQL ワイヤーアダプター（lightning/graphql） — 対応可能な読み取りでは最優先です。
2. UI API / LDS — CRUD の書き込み、メタデータ、レイアウト、選択リスト、シンプルな読み取り。
3. Apex — 代替手段としてのみ使用します。

次の 6 つの判断サブステップに沿って進めます。

1. 操作の種類（読み取り／書き込み／混在）。
2. UI API でのオブジェクトとフィールドのサポート状況。
3. リレーションの複雑さ（単一オブジェクトか複数オブジェクトか、親／子）。
4. クエリの複雑さ（フィルタリング、並べ替え、ページネーション、集計）。
5. パフォーマンスとスケーラビリティ（ラウンドトリップ、ペイロードサイズ）。
6. 特殊な要件（メタデータ、アトミックなトランザクション、ビジネスロジック、昇格された権限）。

推奨ルール：

• GraphQL — 読み取り専用で、サポート対象のオブジェクトを扱う場合。複数オブジェクトの結合、ページネーション／並べ替え／フィルタリング、集計、ラウンドトリップの最小化にも適しています。
• UI API — CRUD の書き込み、メタデータ（選択リスト、レイアウト、オブジェクト情報）、getRecordCreateDefaults と createRecord の組み合わせ、リストビューに適しています。
• Apex — UI API がオブジェクト／フィールドをサポートしていない場合、複数レコードのアトミックなトランザクション、カスタムビジネスロジック、システムコンテキストの権限が必要な場合に適しています。

「Show Your Work」テンプレートを使って提示し、GraphQL を選ばない理由／UI API を選ばない理由／Apex を選ばない理由を明示的に説明します。

引き継ぎ：

• GraphQL を推奨する場合 → Step 4 の出力に、クエリの形状（ルートオブジェクト、要求するフィールド、フィルター）を記載します。実際の lightning/graphql ワイヤーアダプターの作成は、次のステップとして呼び出し元に引き継ぎます。
• UI API を推奨する場合 → 使用する具体的な UI API アダプター（getRecord、getRelatedListRecords、createRecord、updateRecord、getRecordCreateDefaults など）と、レイアウト／選択リストに関する前提条件を記載します。
• Apex を推奨する場合 → 理由を Step 4 の出力に記載し、プロジェクトで定められた Apex ワークフローに引き継ぎます。

Step 4 — PRD にそのまま使える仕様を出力する

呼び出し元が PRD またはコンポーネントファイルのヘッダーに貼り付けられる、単一のブロックを作成します。

## Data Requirement: <CLEAR_TITLE>

### Technical Specification
- Primary Object: <OBJECT_API_NAME>
- Required Fields: <FIELD_API_NAMES>
- Relationships: <RELATED_OBJECTS_OR_LOOKUPS_OR_NONE>
- Data Scope: <SINGLE_RECORD | MULTIPLE_RECORDS | QUERY_BASED>
- Access Pattern: <READ_ONLY | READ_WRITE | WRITE_ONLY>
- Trigger: <USER_ACTION | AUTO_ON_LOAD | REACTIVE>

### Implementation Details
- Recommended LDS API: <GRAPHQL | UI_API | APEX>
- Implementation Pattern: <WIRE | IMPERATIVE>
- Rationale: <WHY THIS API, NOT THE OTHERS>
- Next step: <author the GraphQL wire adapter | author the UI API adapter call | project's Apex workflow>

Few-Shot パターン

曖昧な依頼	確認の質問
「連絡先情報を取得して」	「具体的にどの Contact フィールドが必要ですか？（Email、Phone、MailingAddress、Department など）」
「取引先データを表示して」	「どの Account フィールドが必要ですか？また、1 件のレコードと一覧のどちらを表示しますか？」
「カスタムのジムレコード」	「これはカスタムオブジェクト Gym__c ですか？具体的にどのフィールドが必要ですか？」
「レコードを更新して」	「どのオブジェクトですか？どのフィールドですか？どのレコードですか（実行時の ID）？」
「顧客情報をすべて」	「Account と Contact のどちらですか？どのフィールドですか？単一レコードですか、それともクエリですか？」

検証チェックリスト

• 元の要件に含まれる曖昧な用語がすべて、確認済みの API 名に対応付けられています。
• 操作の種類（R / C / U / D）が確認されています。
• 対象範囲（単一か複数か）とトリガー（ユーザー操作か自動か）が記載されています。
• API の推奨内容が、3 つの選択肢（GraphQL / UI API / Apex）すべてと比較して正当化されています。
• 具体的な次のアクションが記載されています。つまり、接続する特定の下流アダプター（lightning/graphql、getRecord、createRecord など）か、プロジェクトで正式に採用されている Apex ワークフローのいずれかです。
• Step 2 をスキップした場合、その理由が出力に記録されています。
• 仕様ブロックが PRD にコピー＆ペーストできる形式です。

相互参照

• スキル：
  • コンポーネントに @wire アダプターを接続する際、出力は experience-lwc-generate で使用されます。
• 下流の実装手順（現時点ではスキルに紐付いていません）：
  • GraphQL の場合 — 呼び出し元が、対象組織から取得したスキーマを使用して lightning/graphql ワイヤーアダプターを記述します。
  • UI API の場合 — 呼び出し元が、推奨される UI API アダプター（getRecord、createRecord など）を接続します。