data-export

/digital-marketing-pro:data-export

スクリプトの場所。 ホストが ${CLAUDE_PLUGIN_ROOT} を設定していない場合、スクリプトは skills/ と並ぶこのプラグインの scripts/ フォルダーにあります。Python 3.10 以降で実行してください。python を使用し、python が見つからない場合（macOS、多くの Linux システム）は python3 を使用します。

目的

分析、レポート作成、または他のツールとの連携のために、マーケティングデータ（指標、連絡先、キャンペーン結果、パフォーマンススナップショット）を外部データストアにエクスポートします。データウェアハウスと高度な分析には BigQuery、ステークホルダーとの共有やコラボレーションには Google Sheets、カスタムデータベースやアプリケーションとの連携には Supabase をサポートしています。生のマーケティングデータを、完全なスキーマドキュメントを備えた、後続処理ですぐに使える整然とした構造化テーブル形式に変換します。共有先に連絡先データをエクスポートする際は PII をマスキングし、プライバシー規制への準拠を確保します。

外部分析、クライアント向けレポート、またはデータウェアハウスとの連携のために、マーケティングシステムからデータを移動するには、このコマンドを使用します。特定のオーディエンスセグメントをエクスポートする場合は、まず /digital-marketing-pro:segment-audience を使ってセグメントを作成し、次にこのコマンドでメンバーデータをエクスポートしてください。

実行ゲート（必須 — 省略不可）

1. ライブシステムに触れる前に、受信者／支出／変更／コンプライアンスを含む完全なプレビューを 実行サマリー として提示します。
2. ユーザーは yes（またはそれに相当する明示的な承認）を入力する必要があります。それ以外の入力（曖昧、暗示的、一部のみの承認、または承認なし）はすべて実行をキャンセルします。
3. 曖昧な入力に基づいて処理を進めてはいけません。失敗した実行を自動で再試行してはいけません。再実行の前に人による確認が必要です。
4. ユーザーが yes と入力した後に限り、次を記録します。python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action create-approval --data '{"type":"data-export","platform":"<platform>","content_summary":"<one line from the Execution Summary>","risk_level":"<tier>"}' を実行してから、python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action approve --id {approval_id} を実行します。どちらかのコマンドでエラーが発生した場合は、処理を中止してエラーを報告します。別のツールで回避してはいけません。この記録は、この操作の承認手順が実行されたことを証明しますが、誰が yes と入力したかは証明できません。
5. 実行します。connector_executor.py を通じて送信する書き込みには --approval-id が必要で、一致する未使用かつ有効期限内の記録がある場合にのみ実行されます（/digital-marketing-pro:execute-action を参照）。接続済み MCP サーバーのツールを通じた書き込みには、このコードチェックは適用されません。その場合は、入力された yes とホストの権限確認プロンプトに依存します。その後、python "${CLAUDE_PLUGIN_ROOT}/scripts/approval-manager.py" --brand {slug} --action mark-executed --id {approval_id} --data '{"execution_result":"success"}' を実行します（失敗した場合は failure を指定します）。

必要な入力

ユーザーは次の情報を提供する必要があります（または入力を促されます）。

• データの種類：エクスポートするデータ（指標（KPI、チャネルのパフォーマンス、ファネル指標）、連絡先（CRM レコード、セグメント、リードリスト）、キャンペーン（構成、設定、ターゲティング、クリエイティブ）、パフォーマンス（日次／週次スナップショット、トレンドデータ、前年比較）、またはカスタムクエリ（ユーザーが定義する特定のフィールドとフィルター））
• エクスポート先：エクスポート先（BigQuery（プロジェクト、データセット、テーブル名）、Google Sheets（既存のスプレッドシート ID、または指定した名前で新規作成）、または Supabase（プロジェクト参照、スキーマ、テーブル名））
• 日付範囲：エクスポートの対象期間（特定の開始日と終了日、相対期間（過去 7／30／90／365 日）、四半期初日から現在まで、年初から現在まで、または利用可能なすべての履歴データ）
• フィルター（任意）：エクスポート対象を絞り込む条件（特定のチャネル、キャンペーン、オーディエンスセグメント、地域市場、デバイスタイプ、パフォーマンスのしきい値（例：ROAS が 2.0 を超えるキャンペーンのみ）、またはカスタムフィールドの値）
• フォーマットの設定：列の並び順の優先度（ディメンションを先、または指標を先）、命名規則（snake_case、camelCase、Title Case）、日付形式（ISO 8601、MM/DD/YYYY、YYYY-MM-DD）、通貨の書式（記号、コード、小数点以下の桁数）、タイムスタンプのタイムゾーン、計算フィールド（パーセンテージ、比率、期間ごとの差分）を含めるかどうか
• 追加または置換：既存の出力先テーブル／シートに新しいデータを追加するか、内容全体を置き換えるか。定期的なエクスポートでは、追加することでデータの重複を防ぎ、置き換えることでクリーンなスナップショットを確保できるため、これは重要です
• スキーマの設定（任意）：カスタム列の定義、データ型、変換（例：「氏名を first_name と last_name に分割する」、「すべての通貨を USD に変換する」、「日次データを週次に集計する」、「チャネルを列にピボットする」など）
• スケジュール（任意）：今回限りのエクスポートか、定期的なエクスポートテンプレートとして保存するか。定期的に行う場合は、頻度（日次、週次、月次）と条件付きトリガー（例：新しいデータがある場合のみエクスポートする）を指定します
• アクセス権限（任意）：Google Sheets の場合は、誰にアクセス権を付与するか（特定のメールアドレス、ドメイン全体、公開リンク）。BigQuery の場合は、クエリへのアクセスが必要なサービスアカウントまたはユーザー。Supabase の場合は、読み取りアクセスが必要な API キーまたはロール
• PII の取り扱い（任意）：個人を特定できる情報をマスキング、ハッシュ化、または匿名化するかどうか。連絡先データを共有の出力先やセキュリティの低い環境にエクスポートする場合に関連します
• 比較基準（任意）：トレンド分析のため、現在のエクスポートに過去の期間のデータを含めるかどうか（例：今月と先月のデータを並べて含める、または期間ごとの差分の列を追加する）
• 集計行の設定（任意）：エクスポートの末尾に集計行（合計、平均、加重平均）を含めるかどうか。追加の計算をせずにすぐ参照できます
• 完了時の通知（任意）：エクスポート完了時に通知を送信するかどうか（ダウンロードリンク付きのメール、概要統計を含む Slack メッセージ、またはエクスポートしたデータを参照する CRM のアクティビティログエントリ）

プロセス

1. ブランドのコンテキストを読み込む：~/.claude-marketing/brands/_active-brand.json を読み込んでアクティブなスラッグを確認し、次に ~/.claude-marketing/brands/{slug}/profile.json を読み込みます。ブランドのトーン、対象市場向けのコンプライアンスルール（skills/context-engine/compliance-rules.md）、業界のコンテキストを適用します。ガイドラインも確認してください。~/.claude-marketing/brands/{slug}/guidelines/_manifest.json が存在する場合は、制限事項と関連するカテゴリファイルを読み込みます。~/.claude-marketing/sops/ にエージェンシーの SOP がないか確認します。ブランドが設定されていない場合は、「最初にブランドを設定しますか（/digital-marketing-pro:brand-setup）？」と尋ねます。または、デフォルト設定で続行します。
2. 利用可能なソースからデータを収集する：ローカルストレージ（~/.claude-marketing/brands/{slug}/campaigns/（campaign-tracker.py --action list-campaigns 経由）、~/.claude-marketing/brands/{slug}/executions/（execution-tracker.py --action get-history 経由）、~/.claude-marketing/brands/{slug}/performance/ のスナップショット、インサイトファイル、セグメントのエクスポート）と、要求されたデータの種類および日付範囲に基づく接続済み MCP（Google Analytics、広告プラットフォーム、CRM、メールプラットフォーム）からデータを収集します。必要に応じて複数のソースのデータを統合し、ソースの優先順位に従って競合を解決します。
3. データを表形式に変換する：収集したすべてのデータをフラットな表形式に正規化します。ネストされた JSON オブジェクトを列に展開し、日付形式とタイムゾーンを統一し、通貨の値を要求された通貨単位に正規化し、列名の規則を適用し、派生フィールド（CTR、ROAS、CPA、コンバージョン率、期間比の変化率）を計算し、フィールドの種類に応じて一貫した方法（空文字列、「N/A」、または 0）で null 値を処理します。
4. フィルターと並べ替えを適用する：ユーザーが指定した条件（日付範囲、チャネル、キャンペーン、セグメント、カスタム条件）に基づいてレコードを絞り込みます。最も関連性の高い軸で並べ替えます（デフォルトは日付の降順。指定がある場合はそれに従います）。重複行を削除し、結合したデータセット間の参照整合性を検証します。
5. データ品質を検証する：変換後のデータセットについて、完全性と正確性を確認します。列ごとの欠損値（null の割合）、外れ値の検出（標準偏差の 3 倍を超える値）、日付の連続性（日次データに予期しない空白がないか）、参照整合性（キャンペーン ID とキャンペーン名が一致しているか、チャネル名が統一されているか）、行数の妥当性（日付範囲に対して行数が大幅に多い、または少ない場合に警告）を確認します。
6. 出力先への接続とスキーマを確認する：出力先へのアクセスを確認します。BigQuery のデータセットへの書き込み権限とクォータ、Google Sheets API へのアクセスとシートのサイズ制限、または Supabase の接続認証情報とテーブル権限を確認します。出力先のテーブルまたはシートが存在することを確認します（存在しない場合は適切なスキーマで作成します）。既存データに追加する場合は、スキーマの互換性（列名、データ型、並び順が一致していること）を検証します。
7. 承認ゲートを作成する：データのエクスポートはリスクが低いものとして評価します。エクスポートのプレビューには、総行数、データ型を含む列スキーマ、データの先頭 5 行を表形式で表示したもの、出力先の詳細（URL／パス）、追加／置換モード、推定ファイルサイズ、対応が必要なデータ品質に関する警告を含めます。
8. 承認後、出力先 MCP 経由でエクスポートする：適切な MCP を通じてデータを対象プラットフォームに送信します。BigQuery は BigQuery MCP 経由（小規模データセットにはストリーミング挿入、大規模データセットにはロードジョブ）、Google Sheets は Google Sheets MCP 経由（書式設定を含む一括更新）、Supabase は Supabase MCP 経由（競合解決を伴う upsert）で処理します。大規模なデータセットではページネーションを処理し、プラットフォームにデータが到達していないことを確実に確認できた場合（接続拒否、DNS エラー、または 429 レート制限の拒否）に限り、書き込みを再試行します。タイムアウト後や応答が失われた後は、まずプラットフォームでレコードを検索します（タイムアウト後に BigQuery のストリーミング挿入を再試行すると行が重複するため、すでに存在する行数を数えます）。不足分のみを再送信します。指定があればアクセス権限を適用します。
9. PII の処理ルールを適用する：PII の処理が指定されている場合は、連絡先データのフィールドを適切に処理します。メールアドレスのマスキング（j***@example.com）、電話番号のハッシュ化（SHA-256）、氏名の匿名化、または PII 列の完全な削除を行います。監査用に、変更したフィールドと適用した処理方法を記録します。
10. Google Sheets の書式を適用する（該当する場合）：Google Sheets にエクスポートする場合は、プロフェッショナルな書式を適用します。ヘッダー行を固定し、列幅を自動調整し、数値形式（通貨、パーセンテージ、整数）を適用し、KPI に条件付き書式（目標を上回る場合は緑、下回る場合は赤）を設定し、数式やグラフで簡単に参照できるよう名前付き範囲を作成します。
11. エクスポートの整合性を検証する：エクスポート完了後、出力先でデータの整合性を確認します。行数がソースと一致することを確認し、ソースデータと照らし合わせてサンプル値を 5 件抜き取り検査し、スキーマ（列名、データ型、書式）が正しく適用されていることを検証します。Google Sheets の場合は、ヘッダー、列幅、数値形式、条件付き書式が正しく表示されることも確認します。
12. 実行を記録し、テンプレートを保存する：エクスポートの詳細（タイムスタンプ、データの種類、使用したソース、行数、列数、出力先の URL／パス、適用した PII 処理、所要時間、データ品質スコア、警告）を ~/.claude-marketing/brands/{slug}/logs/data-export-log.json に記録します。スケジュール設定をユーザーが要求した場合は、エクスポート設定を再利用可能なテンプレートとして ~/.claude-marketing/brands/{slug}/templates/exports/ に保存します。

出力

以下を含む、構造化されたデータエクスポートレポートです。

• エクスポートの確認：宛先の URL または ID — BigQuery の完全修飾テーブルパス（project.dataset.table）、アクセスレベルを明記した Google Sheets の共有可能な URL、または接続の詳細を含む Supabase のテーブル参照 — 直接アクセスできるリンクを添付します
• 行数の検証：ソースと宛先の行数を比較し、一致を確認します。エクスポート中にスキップされた行があれば、具体的な理由（null キー、スキーマ違反、サイズ制限）と、転送されたデータの合計量も記載します
• 列スキーマ（データディクショナリ）：列の一覧、データ型、人が読んで理解できる説明、サンプル値、ソースシステム、計算式（派生フィールドの場合）、null 率をすべて記載します。エクスポートされたデータを利用するすべての人向けのドキュメントとして機能します
• データ品質の概要：列ごとの完全性スコア（null 以外の値の割合）、値とコンテキストを示した外れ値のフラグ、日付範囲のカバレッジ確認、参照整合性の結果、全体的なデータ品質評価（完全性と一貫性に基づく A／B／C）
• 先頭 5 行のプレビュー：宛先で表示されたエクスポートデータのサンプルです。書式、列の順序、数値の精度、日付の書式、データの正確性を目視で確認できます
• エクスポートメタデータ：タイムスタンプ、合計所要時間、使用したデータソース（ソースごとのレコード数を含む）、適用したフィルター、追記／置換モード、完了した処理ステップ
• アクセスと共有の詳細：エクスポートデータへのアクセス権を持つユーザーです。Google Sheets の場合は共有設定と閲覧者／編集者の一覧、BigQuery の場合は承認済みユーザー／サービスアカウント、Supabase の場合は API アクセス設定を記載します
• PII の取り扱い監査：変更またはマスキングしたフィールド、フィールドごとの取り扱い方法（マスキング、ハッシュ化、匿名化、削除）、適用した PII の取り扱いに関するコンプライアンス上の根拠
• 適用した Google Sheets の書式設定（該当する場合）：固定した行／列、条件付き書式のルール、作成した名前付き範囲、数値書式のパターン、追加したグラフやサマリー行など、書式設定の詳細
• 実行ログ：エクスポート処理のタイムスタンプ付き記録です。ソースと宛先への API 呼び出し、バッチサイズ、応答ステータス、再試行（プラットフォームに到達しなかったことが確実な書き込みに限る）、レート制限による待機、各ステップの処理時間を記録します
• 前回のエクスポートとの比較（定期実行の場合）：前回のエクスポートからの行数の増減、新規または削除された列、データの鮮度の比較、上流のデータ変更を示す可能性があるスキーマドリフトの警告
• ソースデータの鮮度：ソースごとの最新データポイントのタイムスタンプです。エクスポートに入手可能な最新データが反映されているか、分析の正確性に影響する古いデータを含むソースがあるかを確認できます
• 宛先のヘルスチェック：エクスポート後の宛先の検証です。BigQuery のテーブルサイズとクエリコストの推定値、Google Sheets の行数／セル数の使用状況と上限との比較、Supabase のストレージ使用量と API のレート状況を確認します
• 再利用可能なエクスポートテンプレート（要求された場合）：定期エクスポート用に保存した設定ファイルのパスです。データの種類、フィルター、宛先、スキーマ、スケジュール頻度、PII の取り扱いルール、およびこのエクスポートを同じ内容で単一コマンドから再実行するために必要なすべてのパラメーターを含みます

使用するエージェント

• analytics-analyst — プラットフォーム全体でのデータ収集、変換ロジック、スキーマ設計、派生指標の計算、データ品質の検証、外れ値の検出、エクスポートの検証、宛先のヘルスモニタリング
• crm-manager — CRM ソースデータの抽出、連絡先データのコンプライアンスチェック、PII の取り扱いとマスキングのルール、CRM レコードのエクスポートにおけるフィールドマッピング
• execution-coordinator — エクスポート承認ワークフロー、宛先への接続確認、バッチ実行の管理、プラットフォームに到達しなかったことが確実な書き込みに限った再試行、完了通知の送信