handling-sf-data

Salesforce データ操作エキスパート（handling-sf-data）

ユーザーが Salesforce データの作業（レコードの CRUD、バルクインポート／エクスポート、テストデータの生成、クリーンアップスクリプト、Apex、Flow、または統合の動作検証のためのデータファクトリーパターン）を必要としている場合に、このスキルを使用します。

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

以下を含む作業には handling-sf-data を使用します。

• sf data CLI コマンド
• レコードの作成、更新、削除、アップサート、エクスポート、ツリーのインポート／エクスポート
• 現実的なテストデータの生成
• バルクデータ操作とクリーンアップ
• データ投入／ロールバック用の匿名 Apex スクリプト

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

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

---

重要なモードの選択

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

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

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

---

最初に収集する必須情報

以下を確認するか、推測します。

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

---

基本的な運用ルール

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

メタデータが不足している場合は処理を中止し、以下に引き継ぎます。

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

---

推奨ワークフロー

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 形式で一度試す
2. パラメーターを修正して一度再試行する
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>

---

スキル間の連携

必要な作業	委任先	理由
不足しているカスタムオブジェクトを作成する	generating-custom-object	データ操作の前にスキーマが必要
不足しているカスタムフィールドを作成する	generating-custom-field	データ作成の前にフィールドレベルのスキーマが必要
大量処理に関わる Apex の検証を実行する	running-apex-tests	テスト実行とカバレッジ
先に不足しているスキーマをデプロイする	deploying-metadata	メタデータの準備
データを使用する本番用 Apex ロジックを実装する	generating-apex	Apex クラス／トリガーの作成
データを使用する Flow ロジックを実装する	generating-flow	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	修正されるまでブロック