dx-org-analyze

ツールの制限

すべての sf CLI コマンドと Python スクリプトの実行には、Bash ツールのみを使用してください。 sf コマンドには必ず --json を指定してください。mcp__salesforce_dx__* ツールは使用しないでください。

評価／テスト用の出力成果物： 出力ディレクトリが利用可能な場合は、結果をそこに書き込んでください。スキルの実行後、（1）ユーザーが出力パスを指定している場合は、すぐにそこへ書き込んでください。（2）それ以外の場合は、評価用ディレクトリを検出するために [ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' を実行してください。（3）完全な JSON の結果を <output-dir>/dx-org-analyze-result.json に、Markdown レポートを <output-dir>/dx-org-analyze-result.md に書き込んでください。

---

データアクセスの優先順位

組織データをクエリする場合は、必ず次の優先順位に従ってください。

1. SF CLI コマンド — 優先して使用します。sf org list metadata-types、sf org list metadata、sf org display、sf data query、sf limits api display などを使用してください。
2. 直接の REST／Tooling API 呼び出し — 最後の手段としてのみ使用し、SF CLI でデータを取得できない場合に限ります。

この優先順位を決して回避しないでください。操作に対応する SF CLI コマンドがある場合は、直接 API を呼び出すほうが簡単でも、そのコマンドを使用してください。

---

認証ルール

• すべての認証は SF CLI を経由する必要があります（sf org login web、sf org login jwt、sf org login access-token）。
• ユーザーからユーザー名とパスワード、生のセッション ID、アクセストークンを直接受け取らないでください。
• 収集スクリプトは、sf org display --json を通じてのみアクセストークンを取得します。

---

ワークフロー

ステップ 0：認証済み組織を一覧表示する

認証済みの組織をすべて検出するには、次のコマンドを実行します。

sf org list --json --skip-connection-status

JSON 出力を解析してください。すべてのバケット（devHubs、nonScratchOrgs、scratchOrgs、sandboxes、other）から組織を収集します。認証済み組織を読みやすい表にして提示してください。

#	エイリアス	ユーザー名	インスタンス URL	組織 ID	種類

認証済み組織が 2 つ未満で、少なくとも 1 つ利用可能な場合は、単一組織のイントロスペクトモード（下記の「イントロスペクトワークフロー」を参照）を提案してください。認証済み組織がない場合は、処理を中止して次のように案内してください。

認証済み組織が少なくとも 1 つ必要です。認証するには sf org login web --alias <name> を実行してください。

ユーザーが単一組織のイントロスペクションまたはインベントリを明示的に求めている場合は、利用可能な組織数にかかわらず、イントロスペクトワークフローを使用してください。

ステップ 1：ユーザーが 2 つの組織を選択する

一覧から 2 つの組織を選ぶようユーザーに尋ねてください。暗黙的な組織やデフォルト組織は使用せず、両方の組織を明示的に指定してもらってください。

比較する組織を 2 つ選択してください。どちらがソース（参照／期待状態）で、どちらがターゲット（比較対象）ですか？

次の指定方法を受け付けてください：エイリアス、ユーザー名、または一覧の番号。選択された各組織を、具体的なユーザー名に解決してください。組織にエイリアスがない場合は、ユーザーに割り当てを依頼してください。次のように確認してください。

比較対象：

• ソース：<alias>（<username>）
• ターゲット：<alias>（<username>）

ステップ 2：接続を検証する

各組織に対し、機密情報を公開しない軽量なクエリを実行して、接続可能であることを確認してください。

sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json

クエリが成功した場合（終了コードが 0 で、レコードが返された場合）、組織は接続されています。INVALID_SESSION_ID または認証エラーで失敗した場合は、次のようにしてください。

sf org login web --alias <alias>

ステップ 3：データを収集する（組織ごと）

一意の実行 ID を生成し、各組織に対して収集スクリプトを実行してください。

RUN_ID=$(date +%Y%m%d-%H%M%S)

python3 ./scripts/collect_org_data.py \
  --org-alias "$SOURCE_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-source

python3 ./scripts/collect_org_data.py \
  --org-alias "$TARGET_ORG" \
  --output /tmp/dx-org-comparison-${RUN_ID}-target

終了コード： 0 = 成功、1 = 致命的なエラー（stderr をユーザーに報告）、2 = セッションの有効期限切れ（ステップ 2 で再認証して再試行）。

収集スクリプトが取得するデータの詳細については、references/collection-details.md を参照してください。

ステップ 4：差分を計算してレポートを作成する

python3 ./scripts/compute_diff.py \
  --org-a /tmp/dx-org-comparison-${RUN_ID}-source \
  --org-b /tmp/dx-org-comparison-${RUN_ID}-target \
  --output /tmp/dx-org-comparison-${RUN_ID} \
  --format both \
  --org-a-label "Source" \
  --org-b-label "Target"

共有コンポーネントの詳細な一覧表示をユーザーが希望する場合は、--show-shared を使用してください。

ステップ 5：結果を提示する

/tmp/dx-org-comparison-${RUN_ID}.md を読み込み、結果をユーザーに提示してください。ユーザーが追加の質問をした場合は、データの検索に /tmp/dx-org-comparison-${RUN_ID}.json を使用してください。その後、出力ディレクトリを解決し、両方のファイルをそこにコピーしてください。

OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
  OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
  OUTPUT_DIR="force-app/main/adk-eval-output"
fi

if [ -n "$OUTPUT_DIR" ]; then
  cp /tmp/dx-org-comparison-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
  cp /tmp/dx-org-comparison-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi

---

イントロスペクトワークフロー（単一組織モード）

ユーザーが単一組織の設定を調査したい場合、または認証済みの組織が1つだけの場合は、このワークフローを使用します。

イントロスペクト ステップ 1：接続を検証する

sf data query --target-org <alias-or-username> --query "SELECT Id FROM Organization LIMIT 1" --json

イントロスペクト ステップ 2：データを収集する

RUN_ID=$(date +%Y%m%d-%H%M%S)

python3 ./scripts/collect_org_data.py \
  --org-alias "$ORG" \
  --output /tmp/dx-org-analysis-${RUN_ID}

イントロスペクト ステップ 3：レポートを生成する

python3 ./scripts/introspect_org.py \
  --org /tmp/dx-org-analysis-${RUN_ID} \
  --output /tmp/dx-org-analysis-${RUN_ID} \
  --format both \
  --label "OrgName"

イントロスペクト ステップ 4：結果を提示する

/tmp/dx-org-analysis-${RUN_ID}.md を読み込み、ユーザーに提示します。レポートには、メタデータの一覧、組織の設定、組織の制限、インストール済みパッケージ、ライセンス、システム権限、詳細なデータレコードが含まれます。その後、出力ディレクトリを特定し、両方のファイルをそこにコピーします。

OUTPUT_DIR=""
if [ -n "$USER_OUTPUT_PATH" ]; then
  OUTPUT_DIR="$USER_OUTPUT_PATH"
elif [ -d "force-app/main/adk-eval-output" ]; then
  OUTPUT_DIR="force-app/main/adk-eval-output"
fi

if [ -n "$OUTPUT_DIR" ]; then
  cp /tmp/dx-org-analysis-${RUN_ID}.json "$OUTPUT_DIR/dx-org-analyze-result.json"
  cp /tmp/dx-org-analysis-${RUN_ID}.md "$OUTPUT_DIR/dx-org-analyze-result.md"
fi

---

レポートの構成

生成されるレポートには、次の項目が含まれます。

1. ドリフトスコア — 重大度レベル（LOW/MODERATE/HIGH/CRITICAL）を含む、重み付けされた総合スコア（メタデータ60％、権限30％、プロファイル10％）
2. 概要統計 — 詳細データからの「一致」「相違」列を含む、メタデータタイプごとの件数
3. タイプ別メタデータコンポーネント — タイプごとのソースのみ、ターゲットのみ、共有
4. プロファイル — 共有、ソースのみ、ターゲットのみ
5. インストール済みパッケージ — バージョンの比較、ソースのみ、ターゲットのみ
6. パッケージコンポーネント — 名前空間ごとにグループ化された、名前空間付きコンポーネント
7. 組織の権限 — カテゴリ別の有効／無効の差分、および値の差分
8. システム権限 — PermissionSet の PermissionsXxx フィールド、権限セットごとの差分
9. 組織の値と制限 — Identity、Storage、API、Feature Limits ごとのグループ
10. ライセンス — ユーザー、権限セット、パッケージのライセンス数量の差分
11. 詳細データ — Apex、Flows、Validation Rules、Custom Fields などのコンテンツレベルの差分

---

ルール／制約

制約	理由
sf コマンドでは常に --json を使用する	信頼性の高い解析のための構造化出力
組織はエイリアスではなくユーザー名に解決する	エイリアスは曖昧な場合がありますが、ユーザー名は一意です
期限切れおよび切断された組織はスキップする	アクセスできない組織からメタデータをクエリできません
読み取り専用 — デプロイや変更は決して行わない	このスキルは比較のみを行い、いずれの組織も変更しません
SF CLI 認証のみを使用する	すべての認証は SF CLI の認証情報ストアを通じて行います
両方の組織を明示的に指定する	名前のない組織や暗黙のデフォルト組織は決して比較しません

---

トラブルシューティング

問題	解決方法
「<alias> に該当する組織が見つかりません」	組織が認証されていません — sf org login web --alias <name> を実行します
認証済み組織が2つ未満	比較する前に、追加の組織を認証します
「INVALID_SESSION_ID」または認証エラー	セッションの有効期限が切れています — sf org login web --alias <name> を再実行します
収集スクリプトがコード2で終了する	セッションの有効期限が切れています — 再認証して再試行します
メタデータ一覧の取得中に API 制限エラーが発生する	詳細度を下げて高速に処理するには、--skip-deep-data を使用します
エディションの違い（DE 対 EE）	多くの差異は設定のドリフトではなく、エディションに起因します
大規模な組織で詳細データの処理がタイムアウトする	--skip-deep-data フラグを使用し、対象を絞った後続処理で完全な詳細データを実行します

---

スキル間の連携

必要な作業	委任先
組織から特定のメタデータを取得する	platform-metadata-retrieve
メタデータを組織にデプロイする	platform-metadata-deploy
比較用のスクラッチ組織を作成する	dx-org-manage
比較後にデフォルト組織を切り替える	dx-org-switch

---

参照ファイル一覧

ファイル	読むタイミング
references/collection-details.md	収集スクリプトが収集する内容と方法の詳細を確認するとき
references/report-format.md	ドリフトスコアの計算式とレポート各セクションの詳細を確認するとき
scripts/collect_org_data.py	データ収集スクリプト（組織ごと）
scripts/compute_diff.py	差分計算およびレポート生成スクリプト
scripts/introspect_org.py	単一組織のイントロスペクトレポートスクリプト