platform-metadata-deploy

platform-metadata-deploy：Salesforce DevOps 自動化の包括的ガイド

ユーザーがデプロイのオーケストレーション（ドライラン検証、対象を絞ったデプロイやマニフェストベースのデプロイ、CI/CD ワークフローに関するアドバイス、スクラッチ組織の管理、失敗のトリアージ、Salesforce メタデータの安全なロールアウト手順）を必要としている場合に、このスキルを使用します。

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

次の作業が含まれる場合は、platform-metadata-deploy を使用します。

• sf project deploy start、quick、report、または取得のワークフロー
• オブジェクト、権限セット、Apex、Flow にまたがるリリースの順序決定
• CI/CD ゲート、テストレベルの選択、デプロイレポート
• デプロイ失敗のトラブルシューティングと依存関係の順序決定

次の場合は、別のスキルに委任します。

• Apex コードの作成（このスキルではデプロイのみを行います）
• LWC コンポーネントの作成 → experience-lwc-generate
• カスタムオブジェクトや項目の作成 → platform-custom-object-generate
• Flow の構築 → automation-flow-generate
• 組織のデータ操作 → platform-data-manage
• Agentforce エージェントの作成やテスト → agentforce-generate

---

重要な運用ルール

• sf CLI v2 のみを使用します。
• ソース追跡に対応していない組織では、デプロイ／取得コマンドに --source-dir、--metadata、--manifest などの明示的なスコープが必要です。
• 実際のデプロイの前に、まず --dry-run を実行してください。
• 本番組織に対して sf project deploy start を実行してはいけません。 本番環境では、以下の検証 → クイックデプロイの手順を使用します（サーバー側の検証で有効期間 10 日間のジョブ ID が返され、明示的な確認を経て、テストを再実行せずにクイックデプロイで反映します）。
• Flow は安全にデプロイし、検証後にのみ有効化してください。
• メタデータの検証またはデプロイ後のテストデータ作成に関するガイダンスは、platform-data-manage に委任してください。

デフォルトのデプロイ順序

フェーズ	メタデータ
1	カスタムオブジェクト／項目
2	権限セット
3	Apex
4	Flow（ドラフトとして）
5	Flow の有効化／デプロイ後の検証

この順序に従うことで、依存関係や FLS に関する多くの失敗を防げます。

---

最初に確認する必要がある情報

以下を質問するか、推測します。

• 対象組織のエイリアスと環境タイプ
• デプロイ範囲：source-dir、メタデータ一覧、またはマニフェスト
• 検証のみ、デプロイ、クイックデプロイ、取得、CI/CD に関するガイダンスのどれが必要か
• 必要なテストレベルとロールバックに関する想定
• 特殊なメタデータタイプ（Flow、権限セット、エージェント、パッケージ）が含まれるか

事前チェック：

sf --version
sf org list --skip-connection-status
sf org display --target-org <alias> --json
test -f sfdx-project.json

---

推奨ワークフロー

1. 事前チェック

認証、リポジトリの構成、パッケージディレクトリ、対象スコープを確認します。

1a. 対象組織を分類する（本番環境と非本番環境の振り分け）

デプロイの前に、sf org list のレコードから対象を分類します。手順は、組織が本番環境かどうかで分岐します。sf org display から分類してはいけません。このコマンドが報告するのは通常の My Domain のみで、Sandbox／Scratch／Trial のフィールドが省略されるため、Sandbox-or-Demo Org（SDO）が本番環境と誤分類されます（forcedotcom/sf-skills#356）。sf org list のレコードには、正確な分類を示すブール値が含まれています。--skip-connection-status を指定すると、認証済みの組織ごとに OAuth トークンを更新しないローカル読み取りにできます（forcedotcom/sf-skills#349）。

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

対象の alias、username、または orgId と一致するレコードを見つけ、そのレコードから分類します（最初に一致したものを使用します）。

• Scratch — isScratch が true です。
• Sandbox — isSandbox が true、または instanceUrl に --（My Domain の Sandbox マーカー）か test.salesforce.com が含まれています。
• Trial／Developer Edition — trailExpirationDate（CLI での表記。trialExpirationDate も受け付けます）が未来の日付であるか、instanceUrl のホストに orgfarm-、.develop.my.salesforce.com、.pc-rnd.、または .scratch.my.salesforce.com が含まれています。過去の日付は該当しません。日付はログイン時にキャッシュされ、更新されないため、Trial から変換された組織には古い過去の日付が残っており、Trial ではありません。

それ以外はすべて本番環境です。上記の兆候が何もない Dev Hub（isDevHub が true）も含まれます。Dev Hub は通常、顧客自身の本番組織で有効化されているためです。一致するレコードがない場合、またはレコードに利用可能な情報（instanceUrl とフラグのいずれも）がない場合は、本番環境または非本番環境と決めつけず、不明としてユーザーに確認してから進めてください。

• 非本番環境 → ドライラン＋デプロイの手順（ステップ 2～6）。
• 本番環境 → 検証 → クイックデプロイの手順（本番環境へのデプロイ）。本番環境に対して sf project deploy start を実行してはいけません。

2. まず検証する（非本番環境）

sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json

変更セットが対象を絞っている場合は、マニフェストまたはメタデータを対象に検証します。

3. 検証が成功したら、次の安全なワークフローを提案する

検証の成功後、次に行うべき適切なアクションをユーザーに案内します。

1. 今すぐデプロイする
2. 権限セットを割り当てる
3. platform-data-manage を使ってテストデータを作成する
4. テスト／スモークチェックを実行する
5. デプロイ後の複数のステップを順番にオーケストレーションする

4. 適切な範囲のうち最小のものをデプロイする

# source-dir deploy
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json

# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json

# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json

5. 検証する

sf project deploy report --job-id <job-id> --target-org <alias> --json

続いて、テスト、Flow の状態、権限の割り当て、スモークテストの動作を検証します。

6. 明確に報告する

デプロイしたもの、失敗したもの、スキップしたもの、次に行う安全なアクションを要約します。

出力テンプレート：references/deployment-report-template.md

---

本番環境へのデプロイ（検証 → クイックデプロイ）

本番環境には sf project deploy start を使ってデプロイしません。明示的な確認のもとで、サーバー側の検証によってジョブ ID を取得し、その後、テストを再実行せずに検証済みのジョブを昇格する、2 段階の手順で行います。

P1. 本番環境に対して検証する

本番環境の検証にはテストレベルの指定が必須です。デフォルトでは RunLocalTests を使用し、ユーザーがテストを明示的に列挙した場合に限り、RunSpecifiedTests --tests <ClassName>... に切り替えてください。

sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests

スコープフラグ — 次のうち、正確に1つを使用してください：--source-dir <path>、--metadata <Type:Name>、または --manifest manifest/package.xml。

レスポンスでは、10日間有効なジョブ ID（result.id）が返されます。クイックデプロイによって、検証が昇格先の組織に属していることを証明できるように、ジョブ IDをエイリアスだけでなく、sf org display で取得した組織 ID とインスタンス URLというターゲットの不変の識別情報とともに保存してください。

mkdir -p .sfdx
ORG_JSON=$(sf org display --target-org <alias> --json)
ORG_ID=$(printf '%s' "$ORG_JSON" | jq -r '.result.id')
INSTANCE_URL=$(printf '%s' "$ORG_JSON" | jq -r '.result.instanceUrl')
printf '{"jobId":"%s","createdAt":"%s","targetOrg":"%s","orgId":"%s","instanceUrl":"%s","testLevel":"RunLocalTests"}\n' \
  "<id>" "<iso8601>" "<alias>" "$ORG_ID" "$INSTANCE_URL" > .sfdx/last-validation.json

検証に失敗した場合は、result.details.componentFailures と result.details.runTestResult.failures から原因を切り分けます。主要なコンポーネントエラーとテスト失敗を、対象を絞った修正方針とともに提示し、そこで停止してください。検証中に --ignore-errors／--ignore-warnings を使用してはいけません。

P2. クイックデプロイを厳格にゲートする

昇格する前に、以下の5項目すべてを確認してください。

1. ターゲットが本番環境である — ステップ1aの分類で再確認します。
2. 検証が存在する — .sfdx/last-validation.json を読み取るか、ジョブ IDを尋ねるか、--use-most-recent にフォールバックします。--use-most-recent は、以下の確認が既知のジョブに対して行われるように、今すぐ具体的なジョブ IDに解決してください（未解決のフラグとして先に持ち越してはいけません）。
3. 検証がこのターゲットに属している — sf org display --target-org <alias> --json を再実行し、現在の result.id（組織 ID）が .sfdx/last-validation.json に保存された orgId と一致することを必須とします。これにより、古いキャッシュによる危険を防げます。キャッシュされたジョブ IDはデプロイキャッシュから組織を解決するため、この確認がないと、バナーには組織 Bが表示されているのに、ジョブは組織 Aに昇格してしまう可能性があります。不一致がある場合、または比較に必要な orgId／instanceUrl が保存レコードにない場合は、必ず停止し、意図したターゲットに対して再検証（P1）してください。ターゲットを証明できない検証を昇格してはいけません。
4. 検証が新しい — 明示的に指定した --job-id は10日以内、--use-most-recent で解決したジョブは3日以内である必要があります。古い場合は、先に再検証（P1）してください。
5. ユーザーによる明示的な確認 — 以下のバナーを表示し、文字どおり「yes」という返答を求めます。すべてのバナーフィールドには、検証済みのレコードと直前に取得した組織データを設定し、未検証の入力から設定してはいけません。自動で確認してはいけません。

┌─ PRODUCTION DEPLOY ─────────────────────────────┐
│ Org alias:      <alias>                         │
│ Instance:       <instanceUrl>                   │
│ Edition:        <edition>                       │
│ Validation ID:  <jobId>                         │
│ Validated:      <createdAt> (X days ago)        │
│ Components:     <componentCount> queued         │
│ Tests:          <run>/<passed>/<failed>         │
└─────────────────────────────────────────────────┘
Confirm deploy to PRODUCTION? (yes/no)

sf org display --json はエディションを返しません。Organization オブジェクトの OrganizationType から <edition> を読み取ってください（例：Enterprise Edition）。

sf data query --query "SELECT OrganizationType FROM Organization" --target-org <alias> --json | jq -r '.result.records[0].OrganizationType'

P3. プロモートと監査

P2のバナーに表示された「yes」が承認となります。Salesforce development plugin のコンテキストでは、PreToolUse フック（sf-deploy-gate）が、本番環境への単独の deploy quick をブロックし、機械可読な確認マーカー CONFIRM_PROD=1 がコマンドに含まれている場合に限り許可します。ユーザーが今示した確認を伝えるため、このマーカーを出力してください。これは独立したバイパスではないため、明示的な「yes」の後に限って追加し、決してその前に追加しないでください。

# plugin context: CONFIRM_PROD=1 relays P2's confirmation to the safety hook
CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json

プラグインの外（単独の CLI、ヘッドレス／MCP）にはこのようなフックがありません。同じコマンドをマーカーなしで実行してください。

Quick deploy は固有のジョブ ID を持つ新しいデプロイを開始します。検証 ID は再利用しません。応答を取得して新しい ID を抽出し、ポーリング、レポート、監査ファイル名にはその IDを使用してください。追跡用に検証 ID も別途保持します。応答にデプロイ ID が含まれていない場合は停止してください。

QUICK_RESULT=$(CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json)
QUICK_DEPLOY_ID=$(printf '%s' "$QUICK_RESULT" | jq -r '.result.id')
[ -n "$QUICK_DEPLOY_ID" ] && [ "$QUICK_DEPLOY_ID" != "null" ] || { echo "No quick-deploy ID returned — do not report the validation ID as the deploy; investigate."; exit 1; }

Quick deploy は検証済みのコンポーネントをプロモートし、テストを再実行しません。監査証跡として、（検証ではなく）quick-deploy 操作のレポートを保存してから、デプロイ後の検証（重要なパスのスモークテスト、Setup → Deployment Status の監視、問題が再発した場合に備えたロールバック計画の準備）を案内してください。

mkdir -p .sfdx/deploy-history
sf project deploy report --job-id "$QUICK_DEPLOY_ID" --target-org <alias> --json > ".sfdx/deploy-history/${QUICK_DEPLOY_ID}.json"

Quick deploy がタイムアウトするか進行中のままの場合は、検証 IDではなくquick-deploy IDを使ってポーリングしてください。

明示的な確認の後に CONFIRM_PROD=1 を追加するのが承認された手順であり、「ゲートの回避」ではありません。ただし、ユーザーが確認していない拒否を決して上書きしないでください。また、別の理由による拒否も決して上書きしないでください。対象の不一致（P2 のチェック 3）、破壊的なデプロイ、または不明／未解決の組織が該当します。こうした拒否を提示し、停止してください。

---

重大度の高い失敗パターン

エラー／症状	考えられる原因	基本的な修正方針
FIELD_CUSTOM_VALIDATION_EXCEPTION	検証ルールまたは不正なテストデータ	データまたはルールのタイミングを調整する
INVALID_CROSS_REFERENCE_KEY	依存関係の欠落	参照先のメタデータを先に含める
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY	トリガー／Flow／検証による副作用	自動化のスタックと失敗しているロジックを調査する
デプロイ中にテストが失敗する	コードの不具合または脆弱なテスト	対象を絞ったテストを実行し、根本原因を修正してから再検証する
権限セットにフィールド／オブジェクトが見つからない	順序が誤っている	権限セットより先にオブジェクト／フィールドをデプロイする
Flow が無効／バージョンが競合する	依存関係または有効化の問題	Draft としてデプロイして検証した後、有効化する

ワークフロー全体については、references/orchestration.md と references/trigger-deployment-safety.md を参照してください。

---

CI/CD のガイダンス

パイプラインの基本的な構成：

1. 認証する
2. リポジトリ／組織の状態を検証する
3. 静的解析を行う
4. ドライランでデプロイする
5. テストとカバレッジのゲートを実施する
6. デプロイする
7. 検証して通知する

• 組織のポリシーとリリースのリスクが許容する場合は、Apex の比重が高いデプロイで --test-level RunRelevantTests の使用を検討してください。
• これに、@IsTest(testFor=...) や @IsTest(isCritical=true) などの最新の Apex テストアノテーションを組み合わせてください。

静的解析では、廃止された sf scanner ではなく、Code Analyzer v5（sf code-analyzer）を使用します。

詳しいリファレンス：references/deployment-workflows.md

---

Agentforce のデプロイに関する注意

エージェントに関するデプロイ／公開の順序付けを調整するにはこのスキルを使用し、作成時の判断にはエージェント固有のスキルを使用してください。

• agentforce-generate：.agent の作成、Agent Builder、Prompt Builder、メタデータ設定

Agent: 疑似メタデータ、公開／有効化、組織間の同期など、エージェントの DevOps に関する詳細については、以下を参照してください。

• references/agent-deployment-guide.md

---

スキル間の連携

必要な作業	委任先	理由
カスタムオブジェクト／項目の作成	platform-custom-object-generate	デプロイ前にオブジェクトと項目を定義します
デプロイ後のテスト実行	platform-apex-test-run	デプロイ後のテスト実行とカバレッジ確認
Flow の作成／修復	automation-flow-generate	Flow の作成と有効化に関するガイダンス
テストデータまたは初期レコード	platform-data-manage	describe を先に行うデータの設定とクリーンアップ
エージェントの作成と公開準備	agentforce-generate	エージェント固有の正確性

---

リファレンスマップ

まずはこちら

• references/orchestration.md
• references/deployment-workflows.md
• references/deployment-report-template.md

専門的なデプロイ安全対策

• references/trigger-deployment-safety.md
• references/agent-deployment-guide.md
• references/deploy.sh

アセットテンプレート

• assets/package.xml — 一般的なメタデータタイプを網羅するマニフェストテンプレート
• assets/destructiveChanges.xml — 対象の組織からメタデータを削除するためのテンプレート

---

スコアガイド

スコア	意味
90+	優れたデプロイ計画と実行ガイダンス
75–89	良好なデプロイガイダンス。確認事項は軽微
60–74	デプロイリスクへの対応が部分的
< 60	信頼性が不十分。ロールアウト前に計画を強化してください

---

完了時の形式

Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>