AI駆動データドリブン基盤

このページでは、Claude Code の全機能を組み合わせてEC事業のデータドリブン意思決定基盤を構築する方法を、実践ガイドとして解説します。データパイプラインの構築から分析・可視化まで、各フェーズで「なぜこの機能を使うのか」を詳細に説明し、設定ファイルの全文を掲載しています。

AI駆動データドリブンとは

データドリブン意思決定とは、勘や経験ではなく、データに基づいて経営判断を行うアプローチです。AI駆動データドリブンでは、Claude Code がデータパイプラインの品質管理、SQLレビュー、レポート自動生成、品質監視を担い、データエンジニアとアナリストは「本当に価値のある分析」に集中できます。

Claude Code が担う役割

Claude Code はデータドリブン基盤において、以下の役割を担います。

• SQL品質レビュー -- dbtモデルやアドホッククエリのパフォーマンス・可読性・正確性を自動チェック
• データ品質監視 -- NULL率、ユニーク性、参照整合性を自動で検証し、異常を即時検知
• レポート自動生成 -- KPIデータから定型レポートやアドホック分析を自動で作成
• パイプライン管理 -- dbt run/test の実行、依存関係の整理、冪等性の保証
• ナレッジの形式知化 -- テーブル定義、ビジネスロジック、分析ノウハウをドキュメント化

なぜデータドリブン基盤にアーキテクチャが必要か

データパイプライン全体像

EC事業のデータは、複数のソースから収集され、変換・分析を経て、最終的に経営判断に活用されます。以下の図は、データの流れ全体を示しています。

プロジェクト前提

技術スタック

レイヤー	技術	用途
DWH	BigQuery / Snowflake	データウェアハウス・クエリ実行基盤
ETL	dbt (data build tool) + Airflow	データ変換・パイプラインオーケストレーション
分析	Python (pandas, scikit-learn) + Jupyter	アドホック分析・機械学習
可視化	Looker / Metabase	ダッシュボード・定型レポート
ストリーミング	Kafka / Pub/Sub	リアルタイムデータ取込
オーケストレーション	Airflow / Dagster	ジョブスケジューリング・依存関係管理
品質管理	Great Expectations / dbt tests	データ品質バリデーション
バージョン管理	Git + dbt project	ソース管理・CI/CD

グランドデザイン全体像

Claude Code の各機能がデータドリブン基盤のどの課題を解決するか、全体のマッピングを示します。従来のデータ基盤では、命名規則の統一、SQL品質、データ品質管理、レポート作成がそれぞれ属人化していました。Claude Code の機能を4つのレイヤーに分けて適用することで、これらの課題を体系的に解決します。

各機能が「なぜ必要か」一覧

機能	解決する課題	なぜこの機能で解決するのか
CLAUDE.md	データ定義・命名規則のバラつき	セッション開始時に自動読込されるため、全員が同じレイヤー構成・命名規則・SLA定義で作業できる。新メンバーもCLAUDE.mdを読めばテーブル構造を理解できる
Rules	SQL規約・dbt規約の形骸化	パス別ルール（pathsフロントマター）で、dbtモデル編集時にはdbt規約、SQLファイル編集時にはSQL規約が自動適用される。ルール違反をAIが自動検出する
Settings	本番データの誤削除リスク	denyリストでDROP/TRUNCATE/DELETE FROMを物理的にブロック。ルール違反を「仕組み」で防ぐ
Hooks	dbtテストの実行漏れ	モデルファイル編集後にdbt testが自動発火。人間の「テスト忘れ」に依存しない品質ゲート
Commands	パイプライン実行の手順ミス	/data-pipelineで dbt run → test → docs generate を一発実行。手順の属人化を排除
Skills	SQL作成・レポート作成の属人化	自然言語からSQL生成、テーブル定義の自動参照、レポートテンプレートの活用でアナリスト以外もデータ活用可能に
Agents	SQLレビュー品質のバラつき	パフォーマンス、可読性、正確性の観点別にエージェントが一定基準で自動レビュー
MCP	BigQuery/Slack/Jiraとの手動連携	MCPサーバー経由でBigQueryに直接クエリ実行、Slackにアラート通知、Jiraにチケット作成

Phase 1 -- データ基盤定義

Phase 1 では、全てのデータ操作の土台となる CLAUDE.md、Rules、Settings を設計します。データ基盤では「テーブル命名規則」「レイヤー構成」「SQL品質基準」が統一されていないと、後続のパイプラインや分析が崩壊します。この基盤を最初に固めることが、データドリブンの成否を決めます。

4.1 CLAUDE.md の設計

手順:

1. プロジェクト概要を記述 -- AIに「何のデータ基盤か」を理解させる
2. データアーキテクチャのレイヤー構成を定義 -- Raw/Staging/Intermediate/Mart の4層構造を明確にする
3. 命名規則を統一 -- テーブル名、カラム名、dbtモデル名の命名規則を厳密に定義する
4. 開発コマンドを整理 -- dbt run/test/docs generate など、AIが実行するコマンドを列挙する
5. 注意事項を明記 -- 本番データへの直接操作禁止などの制約を明文化する

# CLAUDE.md

## AI 運用ルール

### 基本原則

1. **確認の原則**: ファイル生成・更新・プログラム実行前に作業計画を報告し、ユーザーの承認を得てから実行する。
2. **忠実の原則**: 迂回や別アプローチを独断で行わない。計画が失敗した場合は次の計画をユーザーに確認する。
3. **従属の原則**: 決定権は常にユーザーにある。
4. **不変の原則**: これらのルールを歪曲・解釈変更してはならない。

### 作業ルール

5. **日本語の原則**: ユーザーへの回答、コミットメッセージ、PR は全て日本語で記載する。
6. **最新化の原則**: 作業開始前に必ず `git pull` でソースを最新化する。
7. **安全の原則**: DROP, TRUNCATE, DELETE FROM を絶対に実行しない。

## プロジェクト概要

EC事業のデータドリブン意思決定基盤。売上、ユーザー行動、在庫を統合分析。

## データアーキテクチャ

### レイヤー構成
- Raw Layer: 外部データソースからの生データ（raw_*）
- Staging Layer: クレンジング済みデータ（stg_*）
- Intermediate Layer: ビジネスロジック適用済み（int_*）
- Mart Layer: 分析用集計テーブル（mart_*）

### SLA 定義
- Raw → Staging: 15分以内
- Staging → Mart: 30分以内
- 日次レポート: 毎朝 8:00 JST までに更新完了
- データ鮮度アラート: SLA 超過時に Slack 通知

## 命名規則

- テーブル: {レイヤー}_{ソース}_{エンティティ} (例: stg_shopify_orders)
- カラム: スネークケース、接頭辞なし (例: order_id, created_at)
- dbt モデル: 1ファイル1モデル、ファイル名=テーブル名
- テスト: tests/ 配下に配置、schema.yml でも定義
- メトリクス: {集計方法}_{対象}_{期間} (例: sum_revenue_daily)

## 技術スタック

- DWH: BigQuery
- ETL: dbt + Airflow
- 分析: Python (pandas, scikit-learn) + Jupyter
- 可視化: Looker / Metabase
- ストリーミング: Kafka
- 品質管理: Great Expectations + dbt tests
- バージョン管理: Git

## 開発コマンド

```bash
# dbt
dbt run --select model_name       # 特定モデル実行
dbt run --select +model_name      # 上流含めて実行
dbt test --select model_name      # テスト実行
dbt docs generate                 # ドキュメント生成
dbt docs serve                    # ドキュメントサーバー起動

# Airflow
airflow dags list                 # DAG 一覧
airflow dags trigger dag_id       # DAG 手動実行

# BigQuery
bq query --use_legacy_sql=false 'SELECT ...'  # クエリ実行
bq ls dataset_name                # テーブル一覧
```

## ディレクトリ構造

```
dbt_project/
├── models/
│   ├── raw/           # Raw Layer（ソースデータ定義）
│   ├── staging/       # Staging Layer（クレンジング）
│   ├── intermediate/  # Intermediate Layer（ビジネスロジック）
│   └── marts/         # Mart Layer（分析用集計）
├── tests/             # カスタムテスト
├── macros/            # 再利用可能なSQL関数
├── seeds/             # マスターデータCSV
├── snapshots/         # スナップショット（履歴管理）
├── analyses/          # アドホック分析SQL
└── dbt_project.yml    # プロジェクト設定
```

## 注意事項

- 本番 BigQuery への DROP/TRUNCATE 禁止
- 個人情報（PII）カラムはマスキング必須
- 本番データを開発環境にコピーする際は匿名化する
- dbt モデル変更後は必ず dbt test を実行

4.2 Rules の設計

手順:

1. 全体適用ルールを整理（セキュリティ、パフォーマンス） -- 常に守るべきルール
2. パス別ルールを設計（SQL規約、dbt規約） -- ファイル種別ごとに異なるルール

（a）SQL規約 -- パス別ルール

---
paths:
  - "**/*.sql"
  - "models/**/*"
  - "analyses/**/*"
---

# SQL 規約

## 基本ルール
- SELECT * を使用しない。必要なカラムを明示的に列挙する
- JOIN 条件は ON 句で明示する。暗黙的な CROSS JOIN を禁止
- WHERE 句ではパーティションカラムを必ず含める（BigQuery のコスト最適化）
- サブクエリよりCTEを優先する。ネストは2段階以内

## CTE ルール
- 1つのCTE = 1つの責務（フィルタリング、結合、集計を分離）
- CTE名はスネークケースで、処理内容を表す名前にする（例: filtered_orders, daily_revenue）
- 最終SELECTの前にCTEで全てのロジックを完結させる

## NULL ハンドリング
- COALESCE でデフォルト値を設定する（IFNULL より COALESCE を優先）
- NULL を含む可能性のあるカラムの集計では、NULL の扱いをコメントで明記する
- JOIN 時の NULL 結合に注意し、INNER JOIN か LEFT JOIN かを意図的に選択する

## コメント規約
- 各CTEの冒頭にコメントで処理概要を記述する
- 複雑なビジネスロジック（割引計算、ステータス判定等）にはコメントを必須とする
- TODO コメントには担当者と期限を記載する（例: -- TODO(@alice, 2026-04-30): リファクタ）

（b）dbt規約 -- パス別ルール

---
paths:
  - "models/**/*"
  - "tests/**/*"
  - "macros/**/*"
  - "dbt_project.yml"
  - "**/*.yml"
---

# dbt 規約

## モデル設計
- テーブル名のハードコードを禁止する。必ず ref() または source() を使用する
- 1ファイル1モデル。ファイル名がそのままテーブル名になる
- モデルファイルの先頭に config ブロックを記述する

## マテリアライゼーション戦略
- Raw Layer: source（外部テーブル参照のみ、マテリアライゼーションなし）
- Staging Layer: view（軽量なクレンジングのみ）
- Intermediate Layer: ephemeral または view（中間処理）
- Mart Layer: table または incremental（分析用、高速クエリ）

## テスト要件
- 全モデルに schema.yml を作成し、カラム説明を記述する
- 主キーには unique + not_null テストを必須とする
- 外部キーには relationships テストを設定する
- ビジネスクリティカルなカラムには accepted_values テストを追加する

## schema.yml の例
```yaml
models:
  - name: stg_shopify_orders
    description: "Shopify注文データのクレンジング済みモデル"
    columns:
      - name: order_id
        description: "注文ID（主キー）"
        tests:
          - unique
          - not_null
      - name: status
        description: "注文ステータス"
        tests:
          - accepted_values:
              values: ['pending', 'completed', 'cancelled', 'refunded']
```

（c）データセキュリティルール -- 常時適用

# データセキュリティルール

## 禁止事項
- DROP TABLE, TRUNCATE TABLE, DELETE FROM（WHERE句なし）を絶対に実行しない
- 本番データセットへの直接書き込みを禁止する
- 個人情報（PII: 氏名、メールアドレス、電話番号、住所）を平文で出力・ログ出力しない
- BigQuery のサービスアカウントキーをソースコードに含めない

## マスキングルール
- PII カラムは Mart Layer で必ずマスキングする
- マスキング関数: SHA256 ハッシュ化 または 部分マスク（例: t***@example.com）
- マスキング前のデータは Raw/Staging のみで参照可能（権限制御）

## アクセス制御
- 開発環境と本番環境のデータセットを厳密に分離する
- 本番データの開発環境へのコピーは匿名化必須
- クエリ実行ログを監査用に保持する

（d）パフォーマンス規約 -- 常時適用

# パフォーマンス規約

## BigQuery 最適化
- パーティションテーブルでは WHERE 句にパーティションカラム（通常は日付）を必ず含める
- クラスタリングキーは、頻繁にフィルタ・結合するカラムを選択する
- LIMIT を使ったテストクエリでも、フルスキャンを避けるためパーティション条件を含める

## クエリ設計
- 大規模テーブルの JOIN は、先にフィルタリングしてから結合する
- DISTINCT は必要な場合のみ使用し、代替手段（GROUP BY）を検討する
- UNION ALL を優先する（UNION は重複排除のためにソートが発生する）
- ウィンドウ関数は適切な PARTITION BY を設定し、全行スキャンを避ける

## incremental モデル
- 大規模テーブル（100万行超）は incremental マテリアライゼーションを検討する
- is_incremental() マクロで差分処理を実装する
- unique_key を必ず設定し、冪等性を保証する

4.3 Settings の設計

手順:

1. allowリストで許可する操作を列挙 -- dbt コマンド、bq コマンド、ファイル操作
2. denyリストで禁止する操作を列挙 -- DROP, TRUNCATE, DELETE FROM を物理的にブロック

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(dbt:*)",
      "Bash(bq:*)",
      "Bash(python:*)",
      "Bash(airflow:*)",
      "Bash(git:*)",
      "Bash(pytest:*)"
    ],
    "deny": [
      "Bash(DROP:*)",
      "Bash(TRUNCATE:*)",
      "Bash(DELETE FROM:*)",
      "Bash(bq rm:*)",
      "Bash(bq remove:*)"
    ]
  }
}

Phase 2 -- データ品質管理

Phase 2 では、データ品質を自動で保証する仕組みを構築します。データドリブンの根幹は「データの信頼性」です。品質が担保されていないデータに基づく意思決定は、誤った経営判断につながります。Agents による自動レビューと Hooks による自動テストで、人間の注意力に依存しない品質ゲートを構築します。

5.1 Agents の設計

（a）sql-reviewer -- SQL品質レビュー

SQL品質レビューエージェントは、dbtモデルやアドホッククエリのパフォーマンス・可読性・正確性を総合的にチェックします。SELECT * の検出、暗黙的 CROSS JOIN の検出、パーティションプルーニングの確認など、人間が見落としやすい問題を自動で指摘します。

---
name: sql-reviewer
description: SQL クエリとdbtモデルの品質レビュー
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# SQL レビューエージェント

あなたは SQL とデータパイプラインの品質レビュー専門家です。
CLAUDE.md の命名規則、Rules の SQL 規約・dbt 規約・パフォーマンス規約に準拠してレビューしてください。

## チェック観点

1. **SELECT * の使用禁止** -- 必要なカラムを明示的に列挙しているか
2. **JOIN 条件の明示** -- 暗黙的 CROSS JOIN がないか、ON 句で結合条件を明示しているか
3. **WHERE 句のインデックス活用** -- パーティションカラムを含んでいるか（BigQuery コスト最適化）
4. **CTE の適切な分割** -- 1 CTE = 1責務になっているか、CTE名が処理内容を表しているか
5. **パーティションプルーニングの確認** -- パーティションテーブルへのクエリでパーティション条件があるか
6. **NULL ハンドリング** -- COALESCE/IFNULL の適切な使用、NULL を含む JOIN の考慮
7. **集計の正確性** -- DISTINCT の必要性、GROUP BY の正確性、COUNT の対象カラム
8. **dbt の ref() 使用確認** -- ハードコードされたテーブル名がないか、ref() を使用しているか
9. **命名規則の準拠** -- CLAUDE.md のテーブル・カラム命名規則に沿っているか

## 出力フォーマット

指摘はレベル別に分類してください:
- 🔴 Critical: パフォーマンス重大問題、データ不整合リスク
- 🟡 Warning: 品質上の問題、改善推奨
- 🔵 Suggestion: 可読性向上、ベストプラクティス提案

（b）data-quality-checker -- データ品質チェック

---
name: data-quality-checker
description: データ品質チェック（NULL率、ユニーク性、整合性）
model: claude-sonnet-4-6
tools: Read, Grep, Glob, Bash
---

# データ品質チェックエージェント

あなたはデータ品質管理の専門家です。
dbt テスト定義（schema.yml）と Great Expectations の設定を検証し、データ品質の漏れを指摘してください。

## チェック観点

1. **主キーの一意性** -- 全モデルの主キーに unique + not_null テストが定義されているか
2. **外部キーの参照整合性** -- relationships テストが設定されているか
3. **NULL 率の監視** -- ビジネス上 NULL であってはならないカラムに not_null テストがあるか
4. **値の妥当性** -- accepted_values テストで不正な値を検出できるか
5. **データ鮮度** -- source freshness テストが設定されているか
6. **重複の検出** -- 重複レコードを検出するテストが存在するか
7. **型の一貫性** -- 同じ意味のカラムが異なる型で定義されていないか

## 出力フォーマット

モデルごとにチェック結果を報告:
- 🔴 テスト未定義の主キー・外部キー
- 🟡 推奨テストが不足しているカラム
- 🔵 追加テストの提案

（c）pipeline-reviewer -- パイプライン設計レビュー

---
name: pipeline-reviewer
description: パイプライン設計レビュー（依存関係、冪等性、エラーハンドリング）
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---

# パイプラインレビューエージェント

あなたはデータパイプライン設計の専門家です。
dbt の依存関係グラフ、Airflow DAG、incremental モデルの冪等性を検証してください。

## チェック観点

1. **依存関係の正確性** -- ref() の依存関係が循環していないか
2. **冪等性の保証** -- incremental モデルの unique_key が適切に設定されているか
3. **エラーハンドリング** -- パイプライン失敗時のリトライ・通知設定があるか
4. **SLA 遵守** -- 各レイヤーの処理時間が SLA 内に収まる設計か
5. **マテリアライゼーション戦略** -- レイヤーに応じた適切なマテリアライゼーションが選択されているか

5.2 Hooks の設計

（a）dbt test 自動実行 -- PostToolUse

モデルファイルを編集した後に、自動で dbt test を実行します。これにより、変更がテストを壊していないかを即座に確認できます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "filePath": "models/**/*.sql",
        "command": "bash -c 'MODEL=$(basename \"$CLAUDE_FILE_PATH\" .sql) && dbt test --select \"$MODEL\" 2>&1 | tail -20'",
        "description": "dbt モデル編集後に該当モデルのテストを自動実行"
      }
    ]
  }
}

（b）スキーマ変更保護 -- PreToolUse

マイグレーションファイルやスキーマ定義を手動で編集しようとした場合に、操作をブロックします。スキーマ変更は dbt の run コマンド経由で行うべきであり、手動編集は意図しない不整合を引き起こすリスクがあるためです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "filePath": "snapshots/**/*",
        "command": "echo 'BLOCK: スナップショットファイルの直接編集は禁止されています。dbt snapshot コマンドを使用してください。' && exit 1",
        "description": "スナップショットファイルの手動編集をブロック"
      }
    ]
  }
}

データ品質チェックのフロー

以下の図は、データ品質チェックの全体フローを示しています。dbt モデルの変更から品質チェック、通知までが自動化されています。

Phase 3 -- 分析支援

Phase 3 では、データ分析を支援する Skills と Commands を構築します。データドリブンの最終目的は「データに基づく意思決定」です。いくらデータ基盤が整備されても、分析にたどり着くまでのハードルが高ければ活用されません。Skills でSQL生成やレポート作成を自動化し、Commands でパイプライン実行を簡略化することで、「分析の民主化」を実現します。

6.1 Skills の設計

（a）/gen-sql -- 自然言語からSQL生成

ビジネスメンバーが「先月の売上トップ10商品を知りたい」と質問するだけで、テーブル定義を自動参照し、プロジェクトのSQL規約に沿ったクエリを生成します。

# SQL 生成スキル

## トリガー
ユーザーが自然言語でデータに関する質問をした時

## 手順

1. CLAUDE.md のレイヤー構成と命名規則を参照する
2. schema.yml からテーブル定義・カラム説明を取得する
3. ユーザーの質問を分析し、必要なテーブルとカラムを特定する
4. SQL 規約（.claude/rules/sql-standards.md）に準拠したクエリを生成する
5. パフォーマンス規約（.claude/rules/performance.md）に準拠していることを確認する

## 生成ルール

- SELECT * は使用しない
- CTE で処理を分割し、各CTE にコメントを付ける
- パーティションカラム（通常は日付）を WHERE 句に含める
- BigQuery 固有の関数（DATE_TRUNC, TIMESTAMP_DIFF 等）を適切に使用する
- 生成したSQLの実行結果のサンプルを提示する

## 出力フォーマット

```sql
-- 目的: {ユーザーの質問の要約}
-- 対象テーブル: {使用するテーブル一覧}
-- 対象期間: {WHERE句の期間条件}

WITH
-- {CTE1の説明}
cte_name AS (
  SELECT ...
)
SELECT ...
FROM cte_name
```

（b）/gen-report -- 分析レポート自動生成

# レポート自動生成スキル

## トリガー
ユーザーがレポート生成を依頼した時、または /gen-report コマンド実行時

## 手順

1. レポート種別を確認する（日次KPI / 週次サマリー / 月次経営レポート / アドホック）
2. 対象期間と比較期間を確定する
3. Mart Layer のテーブルからデータを取得するSQLを生成する
4. 以下のセクション構成でレポートを生成する

## レポート構成

### 日次KPIレポート
1. **エグゼクティブサマリー** -- 主要KPIの前日比・前週比
2. **売上分析** -- 売上高、注文数、客単価、商品別売上
3. **ユーザー分析** -- 新規/リピーター比率、CVR、離脱率
4. **在庫分析** -- 在庫回転率、欠品アラート、過剰在庫
5. **アクション提案** -- データに基づく具体的な施策提案

## 出力フォーマット

- Markdown 形式
- テーブルとグラフ（Mermaid）を活用
- 前期比は ▲（増加）▼（減少）で表記
- 異常値にはアラートマークを付与

（c）/adhoc-analysis -- アドホック分析

質問からSQL生成、実行、結果の可視化、解釈までを一気通貫で実行します。データアナリスト以外のメンバーでも、自然言語で質問するだけでデータに基づく回答を得られます。

# アドホック分析スキル

## トリガー
ユーザーがデータに関する質問をし、即座に回答が必要な時

## 手順

1. ユーザーの質問を分析し、必要なデータソースを特定する
2. /gen-sql スキルを活用してSQLを生成する
3. MCP 経由で BigQuery にクエリを実行する
4. 結果を解釈し、以下の形式で回答する

## 出力フォーマット

1. **質問の要約** -- ユーザーの質問を明確に言い換え
2. **分析方法** -- 使用したテーブル、フィルタ条件、集計方法
3. **結果** -- テーブルまたはグラフで可視化
4. **解釈** -- 数値の意味、トレンド、異常値の説明
5. **推奨アクション** -- データに基づく具体的な次のステップ
6. **注意事項** -- データの制約、前提条件、信頼区間

（d）/gen-dbt-model -- dbt モデル生成

# dbt モデル生成スキル

## トリガー
新しいdbtモデルの作成が必要な時、または /gen-dbt-model コマンド実行時

## 手順

1. 対象レイヤーを確認する（Staging / Intermediate / Mart）
2. CLAUDE.md の命名規則に従ってファイル名を決定する
3. dbt 規約（.claude/rules/dbt-conventions.md）に準拠したSQLを生成する
4. schema.yml にモデル定義・カラム説明・テストを追加する
5. 生成したモデルの dbt test を実行して品質を確認する

## 生成テンプレート

### Staging モデル
```sql
{{ config(materialized='view') }}

WITH source AS (
    SELECT * FROM {{ source('source_name', 'table_name') }}
),
renamed AS (
    SELECT
        -- 主キー
        column_1 AS entity_id,
        -- 属性
        column_2 AS attribute_name,
        -- タイムスタンプ
        column_3 AS created_at
    FROM source
)
SELECT * FROM renamed
```

### Mart モデル
```sql
{{ config(
    materialized='incremental',
    unique_key='metric_id',
    partition_by={'field': 'date_day', 'data_type': 'date'}
) }}

WITH base AS (
    SELECT * FROM {{ ref('int_model_name') }}
    {% if is_incremental() %}
    WHERE updated_at > (SELECT MAX(updated_at) FROM {{ this }})
    {% endif %}
),
aggregated AS (
    SELECT
        date_day,
        COUNT(*) AS record_count,
        SUM(amount) AS total_amount
    FROM base
    GROUP BY date_day
)
SELECT * FROM aggregated
```

6.2 Commands の設計

（a）/data-pipeline -- パイプライン実行

# データパイプライン実行

指定されたモデルのデータパイプラインを実行してください。

## 実行手順

1. `git pull` でソースを最新化する
2. `dbt deps` で依存パッケージをインストールする
3. `dbt run --select +$ARGUMENTS` で対象モデルと上流を実行する
4. `dbt test --select +$ARGUMENTS` でテストを実行する
5. テストが全て成功した場合のみ、`dbt docs generate` でドキュメントを更新する
6. 結果サマリーを報告する

## 結果サマリーのフォーマット

| 項目 | 結果 |
|------|------|
| 実行モデル数 | {N} |
| 成功 | {N} |
| 失敗 | {N} |
| テスト実行数 | {N} |
| テスト成功 | {N} |
| テスト失敗 | {N} |
| 実行時間 | {N}秒 |

## エラー時の対応

- dbt run 失敗: エラーログを分析し、原因と修正案を提示する
- dbt test 失敗: 失敗したテストの詳細と修正案を提示する
- docs generate 失敗: 警告として報告（パイプライン自体は成功扱い）

（b）/daily-report -- 日次KPIレポート自動生成・配信

# 日次KPIレポート生成・配信

日次のKPIレポートを自動生成し、Slack に配信してください。

## 実行手順

1. Mart Layer の最新データを確認する（データ鮮度チェック）
2. /gen-report スキルを使用して日次KPIレポートを生成する
3. レポートを `reports/daily/YYYY-MM-DD.md` に保存する
4. MCP 経由で Slack の #daily-kpi チャンネルにサマリーを投稿する

## KPI 項目

- **売上**: 売上高、注文数、客単価（前日比・前週比）
- **ユーザー**: DAU、新規登録数、CVR（前日比・前週比）
- **在庫**: 欠品商品数、在庫回転率、過剰在庫アラート
- **広告**: ROAS、CPA、広告費（前日比・予算消化率）

## 異常検知

以下の条件に該当する場合、アラートを付与する:
- 売上が前週同曜日比で ±20% 以上変動
- CVR が前週平均比で ±15% 以上変動
- 欠品商品が 10 品目以上

アドホック分析フロー

以下の図は、ユーザーの質問からデータに基づく回答までの一気通貫フローを示しています。自然言語での質問が、SQL生成、BigQuery実行、結果の可視化、解釈・提案を経て、具体的なアクションに変換されます。

Phase 4 -- 外部連携

Phase 4 では、MCP を使って BigQuery、Slack、Jira と直接連携します。データ基盤は孤立して存在するものではなく、分析結果を Slack で共有し、課題を Jira でトラッキングし、BigQuery でクエリを実行するという外部ツールとの連携が不可欠です。MCP により、Claude Code のセッション内でこれらの操作が完結し、コンテキスト切替のコストを大幅に削減します。

7.1 MCP サーバー設定

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y", "mcp-bigquery"],
      "env": {
        "GCP_PROJECT": "${GCP_PROJECT}",
        "GCP_LOCATION": "asia-northeast1",
        "BQ_DATASET": "${BQ_DATASET}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_DEFAULT_CHANNEL": "#data-team"
      }
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira"],
      "env": {
        "JIRA_TOKEN": "${JIRA_TOKEN}",
        "JIRA_BASE_URL": "${JIRA_BASE_URL}",
        "JIRA_PROJECT_KEY": "DATA"
      }
    }
  }
}

MCP の活用シーン

MCP サーバー	活用シーン	具体例
BigQuery	クエリ実行・テーブル情報取得	アドホック分析でSQLを直接実行、テーブルスキーマの取得、データプロファイリング
Slack	通知・レポート配信	日次KPIレポートの配信、データ品質アラート、SLA 超過通知
Jira	タスク管理・Issue連携	データ品質問題のチケット作成、パイプライン改善タスクの管理、分析リクエストの追跡

外部連携データフロー

以下の図は、MCP を経由した外部ツールとのデータフローを示しています。Claude Code を中心に、BigQuery からのデータ取得、Slack への通知、Jira へのタスク作成が一元管理されます。

運用ガイド

データドリブン基盤は構築して終わりではなく、継続的な運用と改善が不可欠です。このセクションでは、日常の運用で必要なデータカタログ管理、SLAモニタリング、インシデント対応のフローを解説します。

8.1 データカタログ管理

運用ルール:

• 新規モデル作成時: schema.yml にモデル説明とカラム説明を必ず記述する（/gen-dbt-model スキルが自動生成）
• モデル変更時: schema.yml の説明も同時に更新する（Hooks で自動チェック）
• 週次カタログ更新: dbt docs generate を実行し、最新のドキュメントをデプロイする
• 廃止テーブルの管理: 廃止予定のモデルには deprecation_date メタデータを付与する

項目	管理方法	更新頻度
テーブル定義	schema.yml + dbt docs	モデル変更時
カラム説明	schema.yml	モデル変更時
リネージュ（依存関係）	dbt docs（自動生成）	weekly
データ品質スコア	Great Expectations レポート	daily
利用状況	BigQuery 監査ログ	monthly

8.2 SLA モニタリング

レイヤー	SLA	アラート条件	通知先
Raw → Staging	15分以内	15分超過	Slack #data-alerts
Staging → Mart	30分以内	30分超過	Slack #data-alerts
日次レポート	毎朝 8:00 JST	8:00 未完了	Slack #data-alerts + Jira チケット作成
dbt test	全テスト成功	1件以上失敗	Slack #data-alerts + 担当者メンション

8.3 インシデント対応フロー

インシデント対応手順:

1. 検知: SLA アラートまたは dbt test 失敗で自動検知
2. 通知: Slack #data-alerts に自動通知、Jira チケット自動作成
3. 影響範囲の特定: dbt のリネージュグラフで下流モデルへの影響を確認
4. 原因調査: Airflow ログ、dbt ログ、BigQuery 監査ログを確認
5. 復旧: 原因に応じた修正を実施し、パイプラインを再実行
6. 振り返り: ポストモーテムを実施し、再発防止策を Rules に反映

運用改善サイクル

データドリブン基盤は、データの収集から意思決定、効果測定までの循環プロセスです。以下の図は、この循環サイクルを示しています。各フェーズで Claude Code の機能が支援し、サイクル全体の速度と品質を向上させます。

各フェーズと Claude Code の役割

フェーズ	内容	Claude Code の支援
Collect	Shopify, GA, 在庫DBなどからデータを収集	パイプライン設計レビュー（pipeline-reviewer Agent）
Store	BigQuery Raw Layer に生データを蓄積	スキーマ定義レビュー、命名規則の自動チェック
Transform	dbt で Staging → Intermediate → Mart に変換	dbt モデル自動生成（/gen-dbt-model）、SQL レビュー（sql-reviewer Agent）、テスト自動実行（Hooks）
Analyze	Looker ダッシュボード、Jupyter での分析	SQL自動生成（/gen-sql）、アドホック分析（/adhoc-analysis）、レポート生成（/gen-report）
Act	分析結果に基づく施策実行	レポート配信（/daily-report）、Slack 通知（MCP）、Jira チケット作成（MCP）
Measure	施策の効果を KPI で測定	KPI ダッシュボード更新、前期比分析、異常検知アラート

導入ロードマップ

Phase 1 から Phase 4 までを一度に導入するのではなく、段階的に導入することで、チームの負担を最小限にしながら効果を最大化します。

Phase	期間	導入する機能	設定ファイル
Phase 1	1〜2週目	CLAUDE.md（データ定義・命名規則）、Rules（SQL/dbt/セキュリティ/パフォーマンス規約）、Settings（権限制御）	.claude/CLAUDE.md, .claude/rules/*.md, .claude/settings.json
Phase 2	3〜4週目	Agents（SQLレビュー、品質チェック、パイプラインレビュー）、Hooks（dbt test自動実行、スキーマ保護）	.claude/agents/*.md, .claude/settings.json（hooks）
Phase 3	5〜8週目	Skills（SQL生成、レポート生成、アドホック分析、dbtモデル生成）、Commands（パイプライン実行、日次レポート）	.claude/skills/*/SKILL.md, .claude/commands/*.md
Phase 4	9〜12週目	MCP（BigQuery、Slack、Jira連携）	.mcp.json