Claude Code とBigQuery SQLとビュー定義のドラフトとデータガバナンス（概念）

Google Cloud の BigQuery を中心としたデータ基盤において、最大の課題は「SQLのブラックボックス化」と「ガバナンスの欠如」です。場当たり的に作成されたビュー（View）が増殖し、どのテーブルが正解なのか分からない、あるいは修正による影響範囲が不明といった「データ負債」に悩む企業は少なくありません。

本記事では、Anthropic が提供するコーディングエージェント Claude Code を活用し、BigQuery の SQL ビュー定義やストアドプロシージャをリポジトリ管理下に置き、高度なデータガバナンスを実現するための実務フローを解説します。単なる SQL 生成にとどまらない、CLI 経由でのリポジトリ編集とプルリクエスト運用の真髄に迫ります。

Claude Code で BigQuery SQL の「統制」を自動化する新機軸

従来の BigQuery 運用では、コンソール画面（GUI）上で SQL を書き、そのまま保存するスタイルが一般的でした。しかし、この方法では「なぜそのロジックになったのか」という履歴が残らず、データガバナンスの観点から非常に脆弱です。

なぜ SQL 管理に Claude Code が必要なのか

Claude Code は、ローカルのリポジトリを直接操作できる CLI エージェントです。これを BigQuery 運用に持ち込む最大のメリットは、「ビジネスロジックの自然言語による翻訳」と「コード規約の強制」を同時に行える点にあります。

• リポジトリベースの管理: すべての SQL を .sql ファイルとして Git 管理し、Claude Code にそのコンテキストを理解させる。
• 高速なリファクタリング: 「この古いビューを、新しい命名規則に基づいて書き換え、カラム説明を docstring として追加して」といった指示が CLI 上で完結する。
• 高度な推論: 複雑な結合ロジックを含む SQL に対して、データガバナンス方針に沿った最適化を提案する。

データガバナンスと「コードとしてのデータ定義」

データガバナンスとは、データの信頼性、安全性、可用性を維持するための仕組みです。SQL ビュー定義をコード（GitHub/GitLab）として管理し、Claude Code をその「門番（ゲートキーパー）」として機能させることで、人為的なミスを大幅に削減できます。これは、現代的なデータスタックにおいて モダンデータスタック を構築する上での核心部分と言えます。

実装：Claude Code を用いた SQL リポジトリの構築と Skills 活用

実務で Claude Code を活用するには、まず適切なリポジトリ構造を定義し、Claude Code が従うべき「ルール」を覚えさせる必要があります。

リポジトリ構成：SQLファイルを「アセット」として扱う

以下のようなディレクトリ構成を推奨します。Claude Code はディレクトリ構造をスキャンし、各ファイルの役割を把握します。

my-bq-project/
├── .claude/
│   └── CLAUDE.md          # プロジェクト固有の規約（命名規則、型定義）
├── definitions/
│   ├── staging/           # 生データに近いクレンジング層
│   ├── marts/             # ビジネスロジックを反映したデータマート層
│   └── views/             # 外部公開用ビュー定義
├── scripts/
│   └── bq_dry_run.py      # Claude Codeが使用する検証スクリプト
└── README.md

CLAUDE.md への「命名規則・データ型定義」の注入

Claude Code の挙動を制御する鍵は CLAUDE.md です。ここに BigQuery 特有の制約や、自社のデータガバナンス方針を明文化します。

CLAUDE.md の記述例:

– SQLは BigQuery 標準 SQL（GoogleSQL）で記述すること。

– テーブル名は snake_case、カラム名は snake_case とする。

– すべての SELECT 文には、末尾にカラムの説明をコメントとして付与すること。

– 金額を扱うカラムは必ず NUMERIC 型または BIGNUMERIC 型を使用し、浮動小数点誤差を避けること。

このように設定することで、Claude Code は claude make me a new view for sales と命じられた際、自動的に規約に沿った NUMERIC 型のキャストを含む SQL を生成します。

運用フロー：BigQuery ビュー定義のドラフト生成とプルリクエスト運用

実際の開発現場では、エンジニアが Claude Code を立ち上げ、対話形式で SQL を構築していきます。

スキーマ情報を読み取り、Claude Code でビューを起票する

Claude Code に bq show --format=prettyjson dataset.table の結果を読み込ませることで、正確なスキーマに基づいたビュー定義のドラフトを作成させます。

実務ステップ:

1. スキーマ取得: ローカルで bq show コマンドを実行し、結果を schema.json に保存。
2. 指示: claude "schema.json を読み取って、daily_active_users を計算するビューを marts/ に作成して。規約は CLAUDE.md に従って。"
3. 生成: Claude Code がリポジトリ内に marts/daily_active_users.sql を書き出す。

ローカル実行と dry-run による検証フロー

生成された SQL が即座に本番環境へ反映されることはありません。Claude Code の Skills （外部コマンド実行能力）を活用し、BigQuery の dry-run 機能を呼び出すスクリプトを実行させます。

Claude Code 上での対話例

> 生成した SQL を dry-run して、課金見積もりとエラーがないか確認して。
> [Claude Code が scripts/bq_dry_run.py を実行]
> 結果：エラーなし。クエリサイズ：1.2GB。実行可能です。

このプロセスを経てから git commit し、プルリクエストを作成します。Claude Code は claude "この変更内容を要約して PR を作成して" という指示だけで、GitHub CLI 等と連携してプルリクエストの起票まで完結させることができます。これは CAPIとBigQueryを連携させた高度なアーキテクチャ の運用においても、ロジックの透明性を保つために極めて有効です。

データガバナンスの自動化：CLAUDE.md とメタデータ管理

ガバナンスの維持において最も困難なのは「ドキュメントの更新」です。Claude Code はこれを「コードとドキュメントの同時編集」という形で解決します。

カラム定義の自動ドキュメント化（AGENTS.md の活用）

AGENTS.md を活用して、特定のデータ管理タスクに特化した「サブエージェント」的役割を定義できます。例えば、「データカタログ更新エージェント」としての挙動を定義し、SQL の変更があった際に自動的に Markdown 形式のデータ辞書を更新させることが可能です。

非エンジニアとの役割分担：SQLの「清書」をエージェントに任せる

アナリストやマーケターが作成した「動くが汚い SQL」を、エンジニアが Claude Code を通して「プロダクション品質」に変換します。

• アナリスト: コンソールで試行錯誤し、SQL の「核」を作る。
• エンジニア: その SQL をリポジトリに貼り付け、Claude Code に "この SQL を CLAUDE.md の規約に合わせてリファクタリングし、依存関係を整理して" と指示。
• 成果物: 命名規則が統一され、コメントが充実し、パフォーマンスが最適化された SQL。

このフローにより、属人化しやすい SQL 資産が組織の共有資産へと昇華されます。これは SFA・CRM・MAを横断するデータ連携 において、各ツールの仕様変更に伴う SQL 修正を迅速に行うためにも不可欠な体制です。

比較表：Claude Code と既存ツール（Dataform/dbt）の使い分け

BigQuery の SQL 管理には Dataform や dbt などの専用ツールも存在します。これらと Claude Code の違いを整理しました。

結論として、「複雑なパイプラインは dbt で、日々のビュー作成や既存 SQL の品質向上・ドキュメント整備は Claude Code で」 という組み合わせが、2026年現在の実務における最適解です。

トラブルシューティング：Claude Code で BigQuery を扱う際の注意点

Claude Code は強力ですが、BigQuery 特有の仕様に起因する注意点があります。

クォータ制限とコンテキスト・ウィンドウの管理

大規模なデータセットで数百ものテーブル定義を一度に読み込ませると、コンテキスト・ウィンドウを圧迫し、推論精度が低下します。

• 対策: claude ignore を活用し、関連のない SQL ファイルを読み込み対象から外す。
• 対策: 必要なスキーマ情報だけを一時ファイルとして抽出し、Claude Code に明示的に渡す。

セキュリティ：認証情報の取り扱いと承認フローの厳守

Claude Code に gcloud コマンド等の実行を許可する場合、誤ってデータを削除するリスクがゼロではありません。

• 原則: 破壊的な操作（DROP TABLE 等）は Claude Code に直接実行させず、必ず生成された SQL を人間が確認してから git push する。
• 権限分離: Claude Code を実行するローカル環境の Google Cloud 認証情報は、本番環境への直接書き込み権限を制限し、CI/CD 経由でデプロイする構成にする。

まとめ：データ基盤の負債を Claude Code で解消する

BigQuery の SQL 管理に Claude Code を導入することは、単なる効率化ではありません。それは、「自然言語によるビジネス要求」と「厳格なデータガバナンス」をシームレスに繋ぐ新しい開発体験の構築です。

CLAUDE.md に自社のガバナンス方針を刻み込み、Claude Code という強力なパートナーと共に SQL リポジトリを磨き上げることで、変化に強いデータ基盤を実現してください。まずは、既存の複雑なビューを 1 つ、Claude Code に読み込ませて「リファクタリング」を依頼することから始めてみてはいかがでしょうか。

データ基盤の全体設計や、他の SaaS との高度な連携については、以下の関連記事も併せて参照してください。

• freee会計の「経営可視化・高度連携」フェーズ。会計データを羅針盤に変えるBIとAPI連携術
• SaaSコストとオンプレ負債を断つ。バックオフィス＆インフラの「標的」と現実的剥がし方
• WebトラッキングとID連携の実践ガイド。ITP対策・LINEログインを用いたセキュアな名寄せアーキテクチャ