sf-datacloud

sf-datacloud：Salesforce Data Cloud オーケストレーター

単一の独立したコマンドファミリーではなく、製品レベルの Data Cloud ワークフロー（パイプラインの設定、フェーズをまたぐトラブルシューティング、データスペース、データキット、またはタスクが Connect、Prepare、Harmonize、Segment、Act、Retrieve のどれに該当するかの判断）に関するガイダンスが必要な場合は、このスキルを使用してください。

このスキルは、実行時に外部の sf data360 コマンドサーフェスを使用しながら、意図的に sf-skills のスタイルに準拠しています。このプラグインは、このリポジトリに同梱されていません。

---

このスキルが担当するタスク

次の作業には sf-datacloud を使用してください。

• 複数フェーズにまたがる Data Cloud の設定や修復
• データスペース（sf data360 data-space *）
• データキット（sf data360 data-kit *）
• ヘルスチェック（sf data360 doctor）
• CRM から統合プロファイルまでのパイプライン設計
• 取り込み → 調和 → セグメンテーション → アクティベーションへの進め方の判断
• 根本原因がまだ明らかでない、フェーズをまたぐトラブルシューティング

ユーザーが1つの領域に絞っている場合は、フェーズ固有のスキルに委任してください。

フェーズ	使用するスキル	一般的な対象範囲
Connect	sf-datacloud-connect	接続、コネクタ、ソースの検出
Prepare	sf-datacloud-prepare	データストリーム、DLO、変換、DocAI
Harmonize	sf-datacloud-harmonize	DMO、マッピング、ID 解決、データグラフ
Segment	sf-datacloud-segment	セグメント、計算済みインサイト
Act	sf-datacloud-act	アクティベーション、アクティベーションターゲット、データアクション
Retrieve	sf-datacloud-retrieve	SQL、検索インデックス、ベクトル検索、非同期クエリ

ユーザーが次の作業を行っている場合は、このスキルファミリー以外に委任してください。

• セッショントレーシング／STDM テレメトリの抽出 → sf-ai-agentforce-observability
• CRM SOQL のみの作成 → sf-soql
• CRM ソースデータの読み込み → sf-data
• 不足している CRM スキーマの作成 → sf-metadata
• 後続の Apex または Flow ロジックの実装 → sf-apex、sf-flow

---

最初に確認する必須コンテキスト

次の情報を確認するか、推測してください。

• 対象の組織エイリアス
• プラグインがすでにインストールされ、リンクされているか
• ユーザーが求めているのは設計ガイダンス、読み取り専用の調査、ライブ環境への変更のどれか
• 関連するデータソース：CRM オブジェクト、外部データベース、ファイル取り込み、ナレッジなど
• 目標：統合プロファイル、セグメント、アクティベーション、ベクトル検索、分析、トラブルシューティングのいずれか
• ユーザーがデフォルトのデータスペースとカスタムデータスペースのどちらで作業しているか
• scripts/diagnose-org.mjs で組織がすでに分類されているか
• 現在失敗しているコマンドファミリーがあるか

プラグインが利用可能か、組織の準備が整っているか不明な場合は、まず次を確認してください。

• references/plugin-setup.md
• references/feature-readiness.md
• scripts/verify-plugin.sh
• scripts/diagnose-org.mjs
• scripts/bootstrap-plugin.sh

---

基本的な運用ルール

• 外部の sf data360 プラグインランタイムを使用し、コマンドレイヤーを再実装したり、同梱したりしないでください。
• タスクの範囲が絞り込めたら、フェーズ固有の最小限のスキルを優先してください。
• 変更を伴う作業の前に、準備状況を分類してください。失敗したコマンドを一つだけ見て推測するより、scripts/diagnose-org.mjs を優先してください。
• sf data360 コマンドでは、デバッグに標準エラー出力が必要な場合を除き、2>/dev/null を付けてリンク済みプラグインの警告を抑制してください。
• Data Cloud SQL と CRM SOQL を区別してください。
• sf data360 doctor を製品全体の準備状況を確認する手段として扱わないでください。現在のアップストリームコマンドが確認するのは、検索インデックスの範囲のみです。
• query describe をテナント全体の汎用プローブとして扱わないでください。より広範な準備状況を確認した後、既知の DMO／DLO テーブルに対してのみ使用してください。
• 重要な場合は、Data Cloud 固有の API バージョン回避策を維持してください。
• 組織固有のワークショップ用ペイロードより、汎用的で再利用可能な JSON 定義ファイルを優先してください。

---

推奨ワークフロー

1. ランタイムと認証を確認する

次の項目を確認します。

• sf がインストールされている
• コミュニティ版 Data Cloud プラグインがリンクされている
• 対象の組織が認証済みである

推奨する確認コマンド：

sf data360 man
sf org display -o <alias>
bash ~/.claude/skills/sf-datacloud/scripts/verify-plugin.sh <alias>

sf data360 doctor は全般的なヘルスシグナルとして扱い、唯一の判定基準にしないでください。一部しかプロビジョニングされていない組織では、コネクター、DMO、セグメントなどの読み取り専用コマンドが引き続き動作していても、失敗することがあります。

2. 変更を加える前に準備状況を分類する

まず、共通の分類スクリプトを実行します。

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --json

テーブル名が実在すると確認できてから、クエリプレーンのプローブを使用してください。

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json

分類スクリプトを使って、次の状態を区別します。

• 有効だが空のモジュール
• 機能が制限されているモジュール
• クエリプレーンの問題
• ランタイム／認証の失敗

3. 読み取り専用コマンドで既存の状態を確認する

分類後、対象を絞って調査します。

sf data360 doctor -o <org> 2>/dev/null
sf data360 data-space list -o <org> 2>/dev/null
sf data360 data-stream list -o <org> 2>/dev/null
sf data360 dmo list -o <org> 2>/dev/null
sf data360 identity-resolution list -o <org> 2>/dev/null
sf data360 segment list -o <org> 2>/dev/null
sf data360 activation platforms -o <org> 2>/dev/null

4. フェーズを特定する

タスクを次のように振り分けます。

• ソース／コネクターの問題 → Connect
• 取り込み／DLO／ストリームの問題 → Prepare
• マッピング／IR／統合プロファイルの問題 → Harmonize
• オーディエンスまたはインサイトの問題 → Segment
• 下流へのプッシュの問題 → Act
• SQL／検索／インデックスの問題 → Retrieve

5. 可能な場合は決定性の高い成果物を選ぶ

一度限りの手動操作より、JSON 定義ファイルと再現可能なスクリプトを優先してください。汎用テンプレートは次の場所にあります。

• assets/definitions/data-stream.template.json
• assets/definitions/dmo.template.json
• assets/definitions/mapping.template.json
• assets/definitions/relationship.template.json
• assets/definitions/identity-resolution.template.json
• assets/definitions/data-graph.template.json
• assets/definitions/calculated-insight.template.json
• assets/definitions/segment.template.json
• assets/definitions/activation-target.template.json
• assets/definitions/activation.template.json
• assets/definitions/data-action-target.template.json
• assets/definitions/data-action.template.json
• assets/definitions/search-index.template.json

6. 各フェーズの後に検証する

一般的な検証項目：

• ストリーム／DLO が存在する
• DMO／マッピングが存在する
• ID 解決の実行が完了している
• 統合レコードまたはセグメント数が正しい
• アクティベーション／検索インデックスのステータスが正常である

---

特に注意すべき点

• connection list には --connector-type が必要です。
• 完全なカタログが必要な場合は dmo list --all が便利ですが、準備状況の確認には、最初のページのみを表示する dmo list で十分なことが多く、処理もはるかに高速です。
• セグメントの作成では --api-version 64.0 が必要な場合があります。
• segment members は不透明な ID を返します。人が読める詳細を取得するには、SQL の結合を使用してください。
• 一部の読み取り専用コマンドが引き続き動作していても、プロビジョニングが不完全な組織では sf data360 doctor が失敗することがあります。その場合は、対象を絞ったスモークテストに切り替えてください。
• Couldn't find CDP tenant ID や DataModelEntity ... not found などの query describe エラーは、クエリプレーンに関する手掛かりであり、製品全体が無効であることを自動的に示すものではありません。
• 多くの長時間実行ジョブは、コマンドがすぐに戻る場合でも、実際には非同期で動作します。
• Data Cloud の一部の操作では、CLI ランタイムの外部で UI による設定が引き続き必要です。

---

出力形式

完了時には、次の順序で報告してください。

1. タスクの分類
2. 実行時のステータス
3. 準備状況の分類
4. 該当するフェーズ
5. 使用したコマンドまたは成果物
6. 検証結果
7. 次に推奨されるステップ

推奨形式：

Data Cloud task: <setup / inspect / troubleshoot / migrate>
Runtime: <plugin ready / missing / partially verified>
Readiness: <ready / ready_empty / partial / feature_gated / blocked>
Phases: <connect / prepare / harmonize / segment / act / retrieve>
Artifacts: <json files, commands, scripts>
Verification: <passed / partial / blocked>
Next step: <next phase, setup guidance, or cross-skill handoff>

---

スキル間の連携

必要な作業	委任先	理由
CRM のソースデータの読み込みまたはクリーンアップ	sf-data	取り込み前にソースレコードを登録または修正します
不足している CRM スキーマの作成	sf-metadata	Data Cloud では既存のオブジェクト／項目が必要です
権限またはバンドルのデプロイ	sf-deploy	環境を準備します
Data Cloud の出力を使用した Apex の記述	sf-apex	コードを実装します
セグメンテーション／アクティベーション後の Flow 自動化	sf-flow	宣言的なオーケストレーションを行います
セッションのトレース／STDM／parquet の分析	sf-ai-agentforce-observability	Data Cloud の別のユースケースです

---

リファレンスマップ

まずはこちら

• README.md
• references/plugin-setup.md
• references/feature-readiness.md
• UPSTREAM.md

フェーズ別スキル

• sf-datacloud-connect
• sf-datacloud-prepare
• sf-datacloud-harmonize
• sf-datacloud-segment
• sf-datacloud-act
• sf-datacloud-retrieve

決定論的ヘルパー

• scripts/bootstrap-plugin.sh
• scripts/verify-plugin.sh
• scripts/diagnose-org.mjs
• assets/definitions/