mcpField
P
platform-destructive-deploy

platform-destructive-deploy

github.com/forcedotcomクラウド・DevOps1.1k2.7k 回インストール1 日前に更新
リポジトリ

platform-destructive-deploy について

破壊的変更マニフェストを使って Salesforce のメタデータ削除を管理する開発スキルです。範囲の特定、検証、実行の段階を設け、本番組織では明示的な確認を求めます。

主な機能

  1. 01メタデータ型と API 名の収集
  2. 02ローカルソースの依存関係スキャン
  3. 03破壊的変更マニフェストの作成
  4. 04削除前の検証
  5. 05本番操作での明示的な確認

活用シーン

  1. 01Salesforce メタデータコンポーネントの削除
  2. 02削除前のローカル参照確認
  3. 03削除のみのデプロイ準備
  4. 04本番環境での破壊的変更の保護

MCP 対応

Salesforce CLI のデプロイコマンドとデプロイゲートフックを使用します。説明には MCP サーバーや MCP 専用ツールの記載はありません。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill platform-destructive-deploy

インストール後、Claude Code で/platform-destructive-deployを入力して読み込まれたか確認します。

詳細

破壊的変更の処理

destructiveChanges マニフェストを使用して、Salesforce 組織のメタデータ削除を調整します。スコープ設定 → 検証 → 実行の3つのフェーズで実施し、本番環境ではより厳格なガードレールを適用します。

フェーズ 1 — 削除対象のスコープ設定

ステップ 1a — 削除するコンポーネントの収集

削除するコンポーネントをユーザーに確認するか、コンテキストから推測します。各コンポーネントについて、以下を記録します。

  • メタデータ型（例：CustomObject、CustomField、ApexClass、Flow、PermissionSet）
  • API 名（例：Project__c、Account.Status__c、MyController）
ステップ 1b — ローカル依存関係のスキャン（ベストエフォート）

マニフェストを生成する前に、ローカルプロジェクト内で各コンポーネントへの参照をスキャンします。force-app/ に対して Grep を使用します。

grep -rn "<componentApiName>" force-app/ --include='*.cls' --include='*.trigger' --include='*.xml' --include='*.js' --include='*.html'

参照が見つかった場合：

  • ユーザーに一覧を提示します
  • 先にそれらの参照を更新するか、同じ破壊的デプロイで削除することを推奨します
  • 黙って先に進まず、依存関係のリスクを明示します
ステップ 1c — destructiveChanges.xml の生成

（デプロイ前に削除する場合は）manifest/destructiveChangesPre.xml、（デプロイ後に削除する場合は）manifest/destructiveChangesPost.xml に書き込みます。標準の Salesforce メタデータ形式を使用します。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Project__c</members>
        <members>OldThing__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>Account.Status__c</members>
        <name>CustomField</name>
    </types>
    <version>62.0</version>
</Package>

sourceApiVersion の API バージョンを sfdx-project.json から使用します。

コンポーネントはメタデータ型ごとにグループ化します（型ごとに <types> ブロックを1つ使用）。名前空間付きフィールドには Object.Field 表記を使用します。

フェーズ 2 — 検証

破壊的デプロイを実行する前に、必ず検証します。

sf project deploy validate \
  --pre-destructive-changes manifest/destructiveChangesPre.xml \
  --manifest manifest/package.xml \
  --target-org <alias> \
  --test-level RunLocalTests \
  --json

（破壊的変更をデプロイ後に行う場合は、--post-destructive-changes を使用します。）

package.xml が存在しない場合は、同じ場所に空のファイルを作成します（削除のみのデプロイにもパッケージ記述子が必要です）。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>62.0</version>
</Package>

検証に失敗した場合は、エラーを提示して停止します。よくある失敗の原因：

  • 「削除できません：Apex／Flow／Layout によって参照されています」→ コンポーネントにまだ参照があります
  • 「削除できません：ライセンスに必要です」→ 管理パッケージまたはライセンスへの依存関係があります
  • 「アクセス権が不十分です」→ ユーザーに削除権限がありません

フェーズ 3 — 実行

本番環境の場合

実行前に、対象が本番環境かどうかを確認します。信頼できる確認方法はゲートの分類機能です。これはデプロイフックと同じ方法で組織を特定し（production|sandbox|scratch|trial|unknown を返します）。

"${CLAUDE_PLUGIN_ROOT}/scripts/sf-deploy-gate" bucket <alias>

unknown は組織の種類を確認できなかったことを意味します（通常、組織レコードが不完全な場合に発生します）。その旨を明確に伝えます。デプロイゲートは引き続きデプロイを許可しますが、その組織では保存時の自動デプロイはオフのままです。sf org login web で再認証すると、通常は分類が復元されます。

分類機能が production を返す場合：

  1. 破壊的変更の確認バナーを表示します（platform-quick-deploy に準拠）
  2. 削除されるすべてのコンポーネントを一覧表示します
  3. 「yes, delete from PRODUCTION」という明示的な確認を必須とします
  4. ユーザーが明示的に入力しない限り、--purge-on-delete を拒否します

PreToolUse フック（sf-deploy-gate destructive）は、本番環境に対するフラグなしの破壊的コマンドをすでにブロックします。その拒否をユーザーに伝え、回避してはいけません。

Sandbox／Scratch の場合
sf project deploy start \
  --pre-destructive-changes manifest/destructiveChangesPre.xml \
  --manifest manifest/package.xml \
  --target-org <alias> \
  --json \
  --wait 30

ユーザーが完全削除（ごみ箱をスキップ）を明示的に依頼した場合に限り、--purge-on-delete を追加します。

フェーズ 4 — 削除後のクリーンアップ

破壊的デプロイが成功した後：

  • sf project retrieve start --metadata <Type>:<Name> の実行は推奨しません（コンポーネントはすでに存在しません）。代わりに、ローカルソースのクリーンアップを提案します。 
    # Remove the now-deleted local files to keep source tracking accurate
rm -rf force-app/main/default/<path-to-component>
  • データのあるカスタムフィールドを削除する場合は、データが失われる（または完全削除されるまでごみ箱に残る）ことをユーザーに伝えます
  • 実行時のリグレッションがないことを確認するため、テストの実行を推奨します

ルール

  • 必ず先に検証します。フェーズ 2 を決して省略しません
  • 必ずローカル参照をスキャンします。確認せずに削除してはいけません
  • 必ずユーザーの明示的な確認を得て、本番環境への実行を制御します
  • ユーザーから明示的な依頼がない限り、--purge-on-delete を追加してはいけません
  • 破壊的デプロイで --ignore-errors を決して使用してはいけません
  • 必ず sfdx-project.json の API バージョンを使用し、値をハードコードしてはいけません
  • required="true" のフィールド、または RecordType の選択リスト値で使用されているフィールドをユーザーが削除する場合は、続行する前に連鎖的な影響を明示します

コメント

Markdown 対応