2026-04-08-ad-ops-tooling-overview — curumi-ops

Databeat + スプシ + CLI 設計

日付: 2026-04-08 目的: curumi-ops（Web アプリ）を廃止し、「Databeat + スプシ + CLI」で広告運用業務を完結させる ゴール: 運用者が判断とクライアントコミュニケーションだけに集中できる状態を作る

背景

残る課題

Databeat + スプシで定常業務は回るが、以下の課題がある：

週次レポートの「データ集め」に時間がかかる — 施策の背景・目標値・アクション履歴等のコンテキストがバラバラに存在
非定型な問い合わせに時間がかかる — 「直近3ヶ月のCPA推移」「先週CPAが急騰した理由は？」等

方針

定常業務 = スプシで完結。CLI + AI で非定型な補完。

現在の仕組み（Databeat + スプシ）

データの流れ

各媒体（Google / Meta / TikTok / Yahoo 等）
  ↓ Databeat が自動収集
BigQuery（perfs-440904）
  ├── rawテーブル（自動生成・カスタマイズ不可）
  │     google_ads_{account_id}/campaign, adgroup, ad, keyword, ...
  │     facebook_ads_{account_id}/campaign, adgroup, ad, ...
  │
  └── 出力フィード（SQL カスタマイズ可）
        output_feed_table_* （約40本の VIEW）
        → 各 VIEW に対応する��プシのシートにデータを自動出力

Databeat の特性

BQ の rawテーブルは自動生成。 テーブル構造・カラムは Databeat が決める。カスタマイズ不可
出力フィードで SQL をカスタマイズ → 必要なデータを整形してスプシに抽出。これが現在の運用の基盤
出力フィードの限界: 単一の SQL → 単一のシートへの出力。複数ソースの横断や、施策コンテキストとの突合はできない

現在のスプシ構成

Google Sheets — 業務の中心
  ├── rawデータシート群（Databeat 出力フィード）  ← 運用者がデータを確認する場所
  ├── プロモーション補足情報      ← KPI目標・クライアント特性（手入力）
  └── アクション履歴              ← 施策記録（手入力）

CLI で補うもの

Databeat の出力フィードでは難しい「複数ソースの横断 + AI 分析」を CLI が担う。

既存（Databeat 出力フィード）:
  BQ rawテーブル → SQL → スプシ（数値の整形・抽出）

CLI が追加するレイヤー:
  BQ（数値） + スプシ（KPI目標・アクション履歴・クライアント特性）
    → AI が横断分析 → レポート下書きをスプシに書き込み

CLI は出力フィードを置き換えない。 出力フィードはそのまま稼働し続ける。CLI は出力フィードではカバーできない「分析・レポート生成」を追加する位置づけ。

全体構成

Databeat（SaaS）— データ集約
  ├── 全媒体 → BigQuery rawテーブル（自動生成）
  └── 出力フィード（カスタム SQL）→ スプシにデータ出力（既存・稼働中）

Google Sheets — 業務の中心
  ├── rawデータ（Databeat 出力フィード）  ← 既存のまま
  ├── プロモーション補足情報              ← KPI目標・クライアント特性
  ├── アクション履歴                      ← 施策記録
  └── 週次レポート下書き                  ← CLI が書き込み、運用者が加筆【新規】

adbuddy-cli（TypeScript/Bun）— レポート補助【新規】
  ├── adb report   → BQ + Sheets → AI分析 → スプシに下書き
  └── adb ask      → BQ + Sheets → AI分析 → stdout（将来）

設計原則

既存の仕組み（Databeat 出力フィード + スプシ）を壊さない。CLI は追加レイヤー
定常業務はスプシで完結。ツールを増やさない。運用者の作業場所を統一
データ取得は BigQuery に一本化。CLI は BQ からデータを読む（出力フィードと同じ rawテーブルを参照）
スプシには「Databeat にないもの」だけ追加管理。対応表や数値データを二重管理しない

Databeat BQ スキーマ（2026-04-08 調査結果）

BQ プロジェクト: perfs-440904

データセット構成

perfs-440904
  ├── databeat                        ← システム（マスタ + 集約データ）
  ├── udf                             ← ユーザー定義関数
  ├── google_ads_1270800500           ← 媒体名_アカウントID（16アカウント）
  ├── google_ads_1632871505
  ├── ...
  ├── facebook_ads_581009382830044    ← 9アカウント
  └── ...

databeat データセットの核心テーブル

テーブル/VIEW	用途	CLI での使い方
`databeat_attribute`	Promotion × Account の N:M マッピング	プロモーション一覧・アカウント特定
`campaign_summary_report`	日次 × Promotion × Campaign の集約データ	レポートのメインデータソース
`campaign_summary` (VIEW)	上記 + 属性 + 予算 + 目標達成率	`adb report` のメインクエリ先
`databeat_period_attribute`	月次予算・目標設定	現状未入力（0.0）。スプシで代替
`output_feed_table_*` (VIEW)	Databeat → スプシ自動連携用	CLI では使わない（Databeat の機能）

Databeat のプロモーション構造

Databeat は BQ 上に「プロモーション」概念を持ち、媒体アカウントとの N:M マッピングを databeat_attribute テーブルで管理している。

databeat.databeat_attribute:
  PromotionId (UUID)     → プロモーション単位の一意キー
  PromotionName          → "ブラス様_全体", "ルナビューティー様_池袋" 等
  AccountId (UUID)       → Databeat 内部アカウントID
  AccountName            → "ブラス様_結婚式場", "ルナドクター様_美容事業_Google"
  ServiceName            → "Google Ads" / "Facebook Ads" / "TikTok Ads" 等
  ServiceAccountId       → 媒体のアカウントID（BQ データセット名に対応）

実データ例：

Promotion「ブラス様_全体」
  ├── ブラス様_結婚式場（Google Ads: 215-710-0762）
  ├── ブラス様_Meta（Facebook Ads: 660386785372414）
  └── ブラス様_TikTok（TikTok Ads: 7545389763659235329）

Promotion「ルナビューティー様_池袋」  ─┐
Promotion「ルナビューティー様_指名」   ├── 同一 Google Ads アカウント（127-080-0500）
Promotion「ルナビューティー様_ハイコックス」 ─┘

スプシに対応表を手作りする必要はない。 Databeat が自動管理。

個別アカウントデータセットのテーブル（Google Ads の例）

24テーブル。日次パーティション（MONTH）。

テーブル	粒度	用途
`campaign`	日次 × キャンペーン	基本分析（メイン）
`adgroup`	日次 × 広告グループ	グループ別ドリルダウン
`ad` / `ad_asset`	日次 × 広告	クリエイティブ比較
`keyword`	日次 × キーワード	KW分析 + 品質スコア
`search_query`	日次 × 検索語句	検索意図の変化検出
`campaign_hourly`	時間帯別	時間帯シフト分析
`age_range` / `gender`	デモグラ	ターゲット層分析
`geo`	地域別	エリア分析
`final_url`	LP別	LP×CVR比較
`campaign_conversion`	CV詳細	CV種別内訳

campaign テーブルの主要カラム：

Date, CampaignId, CampaignName, CampaignStatus, BiddingStrategyType
ExternalCustomerId, AccountDescriptiveName
Impressions, Clicks, Cost, Conversions, ConversionValue
CostPerConversion, Ctr, AverageCpc, SearchImpressionShare

スプシテンプレート設計

スプシは「Databeat にないもの」だけを管理する。 既存の rawデータシート（Databeat 連携）はそのまま。

シート1: プロモーション補足情報

Databeat の PromotionId に紐づくビジネスコンテキスト。

列	内容	記入例
promotion_id	主キー。 Databeat の PromotionId（UUID）	`45eaa4a4-71bc-44ce-...`
プロモーション名	表示用（正は Databeat）	ブラス様_全体
CPA目標	目標CPA	¥3,000
CV目標	月間目標CV数	100件
月予算	月間予算上限	¥500,000
クライアント特性メモ	CPA重視、ブランド重視等	CPA重視。LP改修中

シート2: アクション履歴

列	内容
日付	施策実施日
promotion_id	Databeat の PromotionId
施策内容	LP変更、入札変更、クリエイティブ追加等
意図	なぜその施策を行ったか
結果メモ	施策後の所感・数値変化

シート3: 週次レポート下書き

CLI が書き込む先。運用者が加筆修正してクライアントに出す。

列	内容
draft_id	一意キー。 `{promotion_id}_{period_start}` 形式
生成日	CLI 実行日時
promotion_id	Databeat の PromotionId
プロモーション名	表示用（Databeat から自動補完）
期間	対象週
数値サマリ	主要KPIの今週/先週/前週比/目標達成率
変動分析	AI が生成した変動要因の仮説
改善提案	AI が生成した次のアクション案
運用者コメント	運用者が加筆する欄（空欄で出力）
ステータス	`draft` / `edited` / `sent`

再実行時の挙動:

draft → 上書き（upsert）。まだ人間が触っていないので安全
edited or sent → 上書きしない。_v2 で新規追加
なし → 新規追加（append）

adbuddy-cli 設計

コマンド体系

adb report "ブラス様_全体" --period last-week
# → campaign_summary から全アカウント集約データを取得してレポート

adb report --all --period last-week
# → 全プロモーションのレポートを一括生成

adb ask "ブラス様のCPAが先週急に上がった理由は？"
# → BQ + Sheets を横断して自然言語で問い合わせ（将来）

内部アーキテクチャ

CLI エントリポイント
  ├── data/bigquery.ts    — BigQuery への接続・クエリ実行
  ├── data/sheets.ts      — Google Sheets の読み書き
  ├── ai/analyze.ts       — Claude API でデータ分析・レポート生成
  └── commands/
      ├── report.ts       — レポート下書き生成 → スプシ書き込み
      ├── ask.ts          — 自然言語での問い合わせ
      └── query.ts        — データ取得

`report` コマンドの処理フロー

1. PromotionName（or PromotionId）で databeat_attribute からプロモーションを特定
2. campaign_summary VIEW から当該 PromotionId の対象期間データを取得（全媒体集約済み）
3. スプシのプロモーション補足情報から KPI目標・クライアント特性を取得
4. スプシのアクション履歴から promotion_id の直近施策を取得
5. 上記をすべて Claude に渡し、プロモーション単位のレポート下書きを生成
6. スプシの「週次レポート下書き」シートに書き込み

データソースの使い分け

用途	データソース
`adb report`（レポート）	`campaign_summary` VIEW のみ（プロモーション×キャンペーン粒度で十分）
`adb ask`（深掘り分析）	質問内容に応じて個別データセット（adgroup, keyword, search_query 等）まで深掘り

技術スタック

要素	技術
ランタイム	Bun
言語	TypeScript
BigQuery	`@google-cloud/bigquery`
Sheets	`googleapis`
AI	`@anthropic-ai/sdk`（Claude API、Opus）
CLI フレームワーク	最小限（引数パースのみ）

curumi-ops の廃止

実運用に入っていないため、移行計画は不要。

機能	判断	移行先
広告データ同期（Google/Meta）	廃止	Databeat
campaign_assignments（紐付け）	廃止	Databeat の `databeat_attribute`
会社・商材管理	廃止	スプシのプロモーション補足情報
週次レポート生成	CLI に置き換え	`adb report`
タイムライン	廃止	スプシのアクション履歴
Marp スライド生成	凍結	必要になったら CLI サブコマンドで復活
Share of Model / ナレッジ管理	凍結	不要であれば廃止

即時実行可能:

Cloudflare Worker を停止（外部利用者なし）
cron ジョブを停止（既に無効化済み）
リポジトリはアーカイブ（削除はしない。設計資産の参照用に残す）
Turso DB は当面維持（参照用。不要になったら削除）

Phase 計画

Phase 0: スプシテンプレート整備

プロモーション補足情報・アクション履歴・レポート下書きシートのテンプレートを作成
Databeat の databeat_attribute から PromotionId/PromotionName を取得してセット

Phase 1: BigQuery 接続 ✅ データ粒度調査完了（2026-04-08）

GCP 認証の設定
campaign_summary VIEW からのデータ取得が動く状態にする
databeat_attribute からプロモーション一覧を取得できる状態にする

Phase 2: Sheets 接続

CLI がスプシのプロモーション補足情報・アクション履歴を読み書きできる状態にする

Phase 3: レポート下書き生成

campaign_summary VIEW + スプシ（KPI目標・アクション履歴）を Claude に渡してレポート下書きを生成
adb report → スプシに書き込み

Phase 4: 運用定着と改善

プロンプトの改善（レポート品質の向上）
cron での定期実行
adb ask の実装

やらないこと

Web UI（スプシで十分）
広告データの独自同期（Databeat に任せる）
媒体への書き込み操作
レポートの自動送信（人間が確認してから出す）

運用自動化（google-ads-ops / Meta） は別ドキュメント: docs/strategy/2026-04-08-automation-roadmap.md