deploying-metadata

deploying-metadata：Salesforce DevOps の包括的な自動化

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

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

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

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

次の場合は、ほかのスキルに委任してください。

• Apex コードの作成 → generating-apex
• LWC コンポーネントの作成 → generating-lwc-components
• カスタムオブジェクトや項目の作成 → generating-custom-object、generating-custom-field
• Flow の構築 → generating-flow
• 組織のデータ操作 → handling-sf-data
• Agentforce エージェントの作成やテスト → developing-agentforce

---

重要な運用ルール

• sf CLI v2 のみを使用してください。
• ソース追跡を行わない組織では、デプロイ／取得コマンドに --source-dir、--metadata、--manifest などの明示的な範囲指定が必要です。
• 実際にデプロイする前に、まず --dry-run を使用してください。
• Flow は安全にデプロイし、検証後にのみ有効化してください。
• テストデータの作成方法に関する案内は、メタデータの検証またはデプロイ後に handling-sf-data に委任してください。

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

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

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

---

最初に収集する必要があるコンテキスト

次の情報を確認または推測してください。

• 対象組織のエイリアスと環境タイプ
• デプロイ範囲：source-dir、メタデータのリスト、またはマニフェスト
• 検証のみ、デプロイ、クイックデプロイ、取得、CI/CD のアドバイスのいずれが必要か
• 必要なテストレベルとロールバックへの期待
• 特別なメタデータタイプ（Flow、権限セット、エージェント、パッケージ）が含まれるか

事前チェック：

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

---

推奨ワークフロー

1. 事前確認

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

2. 最初に検証

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

変更セットの対象が絞られている場合は、マニフェストまたはメタデータの範囲を指定して検証します。

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

検証に成功した後は、次に行う適切な操作をユーザーに案内します。

1. すぐにデプロイする
2. 権限セットを割り当てる
3. handling-sf-data を使ってテストデータを作成する
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

# quick deploy after successful validation
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

5. 検証

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

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

6. 明確に報告

デプロイされたもの、失敗したもの、スキップされたもの、次に取るべき安全な操作を要約します。

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

---

重大な障害パターン

エラー／症状	考えられる原因	デフォルトの修正方針
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 テストアノテーションを組み合わせてください。作成方法については、generating-apexを参照してください。

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

詳細なリファレンス：references/deployment-workflows.md

---

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

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

• .agent の作成、Agent Builder、Prompt Builder、メタデータ設定については、developing-agentforceを参照してください。

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

• references/agent-deployment-guide.md

---

スキル間の連携

必要な作業	委任先	理由
カスタムオブジェクトの作成	generating-custom-object	デプロイ前にオブジェクトを定義する
カスタム項目の作成	generating-custom-field	デプロイ前に項目を定義する
Apex の作成／修正	generating-apex	コードの作成と修復
Flow の作成／修復	generating-flow	Flow の作成と有効化に関するガイダンス
テストデータまたはシードレコード	handling-sf-data	describe-first のデータ設定とクリーンアップ
エージェントの作成と公開準備	developing-agentforce	エージェント固有の正確性

---

リファレンスマップ

まずはこちら

• 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>