platform-data-manage

Salesforce Data Operations Expert（platform-data-manage）

ユーザーがSalesforce データの操作を必要としている場合に、このスキルを使用します。対象は、レコードの CRUD、一括インポート／エクスポート、テストデータの生成、クリーンアップスクリプト、Apex、Flow、またはインテグレーションの動作検証用のデータファクトリーパターンです。

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

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

• sf data CLI コマンド
• レコードの作成、更新、削除、アップサート、エクスポート、またはツリーインポート／エクスポート
• 実際に即したテストデータの生成
• 一括データ操作とクリーンアップ
• データのシード／ロールバック用の匿名 Apex スクリプト

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

• SOQL のみを書く場合 → platform-soql-query
• Apex テストを実行または修復する場合 → platform-apex-test-run
• 最初にメタデータをデプロイする場合 → platform-metadata-deploy
• カスタムオブジェクト／項目を作成または変更する場合 → platform-custom-object-generate または platform-custom-field-generate

---

重要：モードの選択

ユーザーが希望するモードを確認します。

モード	使用する状況
スクリプト生成	まだ組織に変更を加えず、再利用可能な .apex、CSV、または JSON アセットが必要な場合
リモート実行	実際の組織で今すぐレコードを作成／変更したい場合

ユーザーがスクリプトのみを必要としている可能性がある場合は、リモート実行を前提にしないでください。

---

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

以下について質問するか、推測します。

• 対象オブジェクト
• リモート実行が必要な場合は組織のエイリアス
• 操作の種類：クエリ、作成、更新、削除、アップサート、インポート、エクスポート、クリーンアップ
• 想定されるデータ量
• テストデータ、移行データ、または一時的なトラブルシューティング用データのいずれか
• 先に存在している必要がある親子関係

---

基本的な運用ルール

• ユーザーがローカルでのスクリプト生成を明示的に希望しない限り、platform-data-manage はリモート組織のデータを操作します。
• データを作成する前に、オブジェクトと項目が存在している必要があります。
• 自動化テストで一括処理の動作が重要な場合は、251 件以上のレコードを優先します。
• 大規模または大量のデータセットを作成する前に、クリーンアップを計画します。追跡されていないレコードは実行のたびに蓄積し、組織の状態を汚染します。
• テストレコードには、個人を特定できない合成データを使用します。実際の PII はコンプライアンス上のリスクとなり、一括インポート後に安全に削除できません。
• 単純な CRUD には CLI を優先し、サーバー側のオーケストレーションが本当に必要な場合に匿名 Apex を使用します。

メタデータが不足している場合は、作業を中止して次に引き継ぎます。

• 不足しているスキーマを作成するには platform-custom-object-generate または platform-custom-field-generate を使用し、データ操作を再試行する前に platform-metadata-deploy でデプロイします。

---

推奨ワークフロー

1. 前提条件を確認する

オブジェクト／項目の利用可否、組織の認証、必要な親レコードを確認します。

2. スキーマが不確かな場合は、describe を先に実行して事前検証する

レコードを作成または更新する前に、オブジェクトの describe データを使用して以下を検証します。

• 必須項目
• 作成可能な項目と作成不可能な項目
• 選択リストの値
• リレーション項目と親レコードの要件

項目、選択リストの値、作成可能性の制約を調べるための sf sobject describe コマンドと jq フィルターパターンについては、references/sf-cli-data-commands.md を参照してください。

3. 要件を満たす最小限の方法を選択する

必要な作業	デフォルトの方法
少量の一時的な CRUD	sf data の単一レコードコマンド
大規模なインポート／エクスポート	sf data ... bulk による Bulk API 2.0
親子関係を含むシードデータセット	ツリーインポート／エクスポート
再利用可能なテストデータセット	ファクトリー／匿名 Apex スクリプト
元に戻せる実験	クリーンアップスクリプトまたはセーブポイントを使用する方法

4. アセットを実行または生成する

適している場合は、assets/ 内の組み込みテンプレートを使用します。

• assets/factories/
• assets/bulk/
• assets/cleanup/
• assets/soql/
• assets/csv/
• assets/json/

5. 結果を検証する

作成または更新の後に、件数、リレーション、レコード ID を確認します。

6. 回数を制限した再試行戦略を適用する

作成に失敗した場合：

1. 主要な CLI 形式で 1 回試します
2. パラメーターを修正して 1 回再試行します
3. describe を再実行して、前提を検証します
4. 別の手段に切り替えるか、手動での回避策を提示します

失敗する同じコマンドを延々と繰り返さないでください。

7. クリーンアップ手順を提示する

データを作成した場合は、正確なクリーンアップコマンドまたはロールバック用アセットを提示します。

---

重要度の高いルール

一括処理の安全性

• 大量データには一括操作を使用します
• 適切な場合は、251 件以上のレコードを使って自動化の影響を受けやすい動作をテストします
• 一括処理のシナリオでは、1 レコードずつ処理する方法を避けます

データの整合性

• 必須フィールドを含めます
• 作成前に選択リストの値を検証します
• 親 ID とリレーションの整合性を検証します
• 入力ペイロードに書き込み不可のフィールドを含めないようにします
• 入力ペイロードに作成不可のフィールドを含めないようにします

クリーンアップの規律

次のいずれかを優先します。

• ID による削除
• パターンによる削除
• 作成日の期間による削除
• スクリプトベースのテスト実行におけるロールバック／セーブポイントのパターン

---

よくある失敗パターン

エラー	考えられる原因	既定の修正方針
INVALID_FIELD	フィールドの API 名が誤っている、または FLS の問題	スキーマとアクセス権を確認する
REQUIRED_FIELD_MISSING	必須フィールドが省略されている	describe データから必須値を含める
INVALID_CROSS_REFERENCE_KEY	親 ID が無効	先に親を作成／検証する
FIELD_CUSTOM_VALIDATION_EXCEPTION	入力規則によってレコードがブロックされた	有効なテストデータを使うか、設定を調整する
無効な選択リスト値	describe に基づかない値を推測した	まず選択リストの値を確認する
書き込み不可フィールドのエラー	フィールドが作成不可／更新不可	ペイロードから削除する
一括処理の制限／タイムアウト	データ量に対してツールが不適切	一括処理／段階的なインポートに切り替える

---

出力形式

完了時には、次の順序で報告します。

1. 実行した操作
2. オブジェクトと件数
3. 対象組織またはローカルアーティファクトのパス
4. レコード ID／出力ファイル
5. 検証結果
6. クリーンアップ手順

推奨形式：

Data operation: <create / update / delete / export / seed>
Objects: <object + counts>
Target: <org alias or local path>
Artifacts: <record ids / csv / apex / json files>
Verification: <passed / partial / failed>
Cleanup: <exact delete or rollback guidance>

---

スキル間の連携

必要な作業	委任先	理由
不足しているカスタムオブジェクトを作成する	platform-custom-object-generate	データ操作の前にスキーマが必要です
不足しているカスタムフィールドを作成する	platform-custom-field-generate	データ作成の前にフィールドレベルのスキーマが必要です
一括処理に関わる Apex 検証を実行する	platform-apex-test-run	テストの実行とカバレッジ
まず不足しているスキーマをデプロイする	platform-metadata-deploy	メタデータの準備
データを使用する本番用 Apex ロジックを実装する	platform-apex-generate	Apex クラス／トリガーの作成
データを使用する Flow ロジックを実装する	automation-flow-generate	Flow の作成と自動化

---

リファレンスマップ

まずはこちら

• references/sf-cli-data-commands.md
• references/test-data-best-practices.md
• references/orchestration.md
• references/test-data-patterns.md
• references/test-data-factory-usage.md

クエリ／一括処理／クリーンアップ

• references/soql-relationship-guide.md
• references/relationship-query-examples.md
• references/bulk-operations-guide.md
• references/cleanup-rollback-guide.md
• references/cleanup-rollback-example.md

例／制限

• references/crud-workflow-example.md
• references/bulk-testing-example.md
• references/anonymous-apex-guide.md
• references/governor-limits-reference.md

検証スクリプト

• scripts/soql_validator.py — 実行前に SOQL クエリを検証します
• scripts/validate_data_operation.py — データ操作の事前チェック（必須項目、選択リスト値、作成可能な項目）

アセットテンプレート

• assets/factories/ — Apex テストデータファクトリースクリプト（account、contact、opportunity、lead、user など）
• assets/bulk/ — Bulk API 2.0 Apex テンプレート（200、500、10000 レコードの挿入、外部 ID による upsert）
• assets/cleanup/ — クリーンアップとロールバックスクリプト（名前、日付、パターンによる削除、トランザクションのロールバック）
• assets/soql/ — SOQL クエリテンプレート（集計、サブクエリ、親から子、子から親、多態的なクエリ）
• assets/csv/ — Account、Contact、Opportunity、カスタムオブジェクト用の CSV インポートテンプレート
• assets/json/ — JSON ツリーインポートテンプレート（account-contact、account-opportunity、完全な階層）

---

スコアガイド

スコア	意味
117+	本番環境で安全に使える、優れたデータワークフロー
104–116	軽微な改善の余地はあるものの、良好な運用
91–103	許容範囲ですが、レビューを推奨します
78–90	一部に不完全またはリスクのあるパターンがあります
< 78	修正されるまでブロックされます