Claude Codeで Snowflake + dbtプロジェクトをAI駆動で開発できるよう検証した話
はじめに
SnowflakeをDWHとしたデータ分析基盤の導入を求める新規顧客案件が始まるたびに、Snowflakeのデータベース・ロール・ウェアハウスのDDLを書き、dbtプロジェクトのディレクトリ構成を整え、Bronze/Silver/Gold層のモデルを作成するのですが、ベストプラクティスに沿った基本的な設計はどの顧客でも同じ構成を提供するものです。
そこで、毎回行われる初期環境の開発作業を、Claude Codeを使って「AI駆動のテンプレートシステム」として自動化することができないかチャレンジしてみました。
この記事で分かること
- Claude Codeの CLAUDE.md と Skills を活用したAI駆動開発の設計アプローチ
- Snowflake + dbt project on snowflakeのテンプレートをどのような設計判断で構築したか
- AIとの協働で設計を進める際の実践的なTips
対象読者
- Snowflake / dbt を使ったデータ基盤の構築経験がある方
- Claude Codeを業務に活用してみたい方
- 繰り返し発生するインフラ構築作業を効率化したい方
1. 課題: 案件ごとに繰り返される構築作業
私たちのチームでは、顧客ごとにSnowflake DWH環境とdbtプロジェクト(dbt project on snowflake)を構築しています。案件が変わっても、基本的なアーキテクチャは共通です。
- Snowflake側: データベース、ロール階層、ウェアハウス、S3インテグレーション、スキーマ、テーブルDDL
- dbt側: プロジェクト設定、Bronze/Silver/Gold層のモデル、Loadマクロ、Snapshot定義、テスト
しかし、これらを毎回手作業で構築リソースを開発すると以下の問題が発生します：
- 時間がかかる: 1案件あたり約1週間の初期構築期間
- 品質のばらつき: 担当者によって命名規則やエラーハンドリングの実装が異なる
- 知見の属人化: 「あの案件ではこうした」というノウハウが個人に閉じる
「テンプレートを作ればいい」という発想自体は以前からありましたが、テンプレートのメンテナンスコストや、案件固有のパラメータ適用の手間を考えると、なかなか着手できずにいました。
2. アプローチ: Claude Code × CLAUDE.md × Skills
Claude Codeとは
Claude Code はAnthropicが提供するCLIツールで、ターミナル上でClaudeと対話しながらコードの読み書き・実行ができます。特に以下の機能がこの取り組みの核になりました：
- CLAUDE.md: プロジェクトルートに配置する指示書。Claudeがこのファイルを読み、プロジェクト固有のルールや規約に従って動作する
- Skills (SKILL.md): 再利用可能なタスク定義。
/skill-nameで呼び出せるコマンドとして機能する
全体構成
構築したテンプレートシステムの全体像は以下のとおりです：
snowflake_dbt_project_template/
├── CLAUDE.md # プロジェクト全体の指示書（マップ）
├── templates/
│ ├── dbt_project/ # dbtテンプレート
│ │ └── CLAUDE.md # dbt固有の規約
│ ├── snowflake_ddl/ # Snowflake DDLテンプレート
│ │ └── CLAUDE.md # DDL固有の規約
│ └── requests/ # 入力テンプレート
└── .claude/skills/ # AIスキル定義
├── init-project/
├── add-table/
├── add-gold-model/
├── generate-task/
└── review-table/
設計思想: 「マップ」と「詳細地図」の分離
CLAUDE.mdは1つの巨大なファイルにすべてを書くのではなく、階層的に分離しました：
- ルートCLAUDE.md = マップ（全体像、生成フロー、命名規則）
- dbt CLAUDE.md = 詳細地図（Bronze/Silver/Gold各層の開発規約）
- Snowflake DDL CLAUDE.md = 詳細地図（DDLの規約、ロール階層、FUTURE GRANTSパターン）
こうすることで、Claudeが必要な情報に効率よくアクセスでき、かつ各ファイルのメンテナンスも独立して行えます。
3. 設計判断: アーキテクチャの要点
テンプレートに組み込んだ主要な設計判断を紹介します。
メダリオンアーキテクチャ
[Source] → Bronze(BRZ) → Silver(SLV) → Gold(GLD)
│ │ │
生データ クレンジング済 ビジネス用
view table/incr table
各層の役割と materialization 戦略を明確にテンプレート化しました。
環境切替: 1つのコードベースで prd/stg/dev
dbtの target.name を活用した3層の環境切替メカニズムを採用しました：
- profiles.yml: target（prd/stg/dev）ごとにデータベース名を切り替え
- dbt_project.yml:
+schema: brzのように環境中立なスキーマ名を設定 - generate_schema_name マクロ:
target.name+custom_schema_nameで動的にスキーマ名を組み立て
これにより、モデルのディレクトリ名やソース参照は環境中立（brz/, slv/, gld/）のまま、デプロイ先を --target オプションで切り替えられます。
Silver層: 3つのマテリアライゼーション戦略
テーブルの性質に応じて3パターンを使い分けます：
| パターン | 対象 | materialized | 変更履歴 |
|---|---|---|---|
| table + snapshot | マスタ（履歴あり） | table（洗い替え） | SCD Type 2 |
| table のみ | マスタ（履歴なし） | table（洗い替え） | なし |
| incremental | トランザクション | incremental（MERGE） | なし |
Loadマクロのエラーハンドリング
S3からのデータロードで起こりうるエラーに対して、データ種別ごとに異なるハンドリングを設計しました：
| チェック | MERGE（差分） | TRUNCATE/INSERT（洗い替え） |
|---|---|---|
| ファイル未存在 | エラー | エラー |
| レコード0件 | 正常スキップ | エラー（0件で洗い替えはデータ消失リスク） |
洗い替えパターンで0件ロードをエラーにしたのは、TRUNCATEした後に0件INSERTするとデータが消失するためです。これはAIとの対話の中で「この場合どうなるか？」を議論して決まった設計です。
4. スキル体系: 5つのコマンドで案件を構築
構築したスキルの全体像です。各スキルは /skill-name で呼び出せます。
案件開始 → テーブル追加 → Gold層追加 → タスク生成 → レビュー
│ │ │ │ │
/init-project /add-table /add-gold-model /generate-task /review-table
各スキルの役割
| スキル | 入力 | 出力 | 自動化度 |
|---|---|---|---|
/init-project |
案件パラメータ（YAML） | Snowflake DDL + dbtプロジェクト一式 | 完全自動 |
/add-table |
テーブルリスト + カラム定義（CSV） | DDL + Bronze + Silver + Snapshot | ほぼ完全自動 |
/add-gold-model |
ビジネス要件（CSV） | Gold層モデルの雛形 | 雛形生成 → 人が補完 |
/generate-task |
（自動検出） | Snowflake Task SQL（DAG定義） | 完全自動 |
/review-table |
テーブル名 | レビューレポート | 完全自動 |
入力テンプレートの工夫
各スキルの入力はCSVまたはYAMLのテンプレートファイルとして定義しました：
- ヘッダー情報（案件名、ソースシステム等）はYAML形式でkey-value
- カラム定義はCSV形式でExcelからコピペしやすく
- デフォルト参照先を設定し、引数なしでも実行可能
入力項目の設計もAIとの対話で「何が不足しているか」を洗い出しながら決めました。例えば、当初なかった「Silver変換後の型」や「snapshot戦略」の列は、テスト実行中の指摘で追加されたものです。
5. 一気通貫テストの実行
テンプレートの完成後、3パターンのテーブルを使って一気通貫テストを実施しました。
※記事内ではプロジェクトの仮名を”testpj”としています。
テストデータ
| テーブル | パターン | 特徴 |
|---|---|---|
| CUSTOMERS | master + 履歴あり | snapshot（timestamp戦略）、SCD Type 2 |
| PRODUCTS | master + 履歴なし | BOOLEAN変換あり、snapshotなし |
| ORDERS | transaction + 差分 | incremental（MERGE）、FK2つ |
実行フロー
/init-project
→ testpj_dbt_project/ + testpj_snowflake_ddl/ を生成
/add-table（3テーブル）
→ DDL 3本 + Bronze source 3本 + Loadマクロ 6本(yml+sql)
+ Silver model 6本(sql+yml) + Snapshot 2本(sql+yml)
/add-gold-model（2モデル）
→ daily_sales（集計モデル）+ customer_summary（snapshot参照モデル）
/generate-task
→ Silver → Snapshot → Gold の DAG定義を自動生成
/review-table（3テーブル）
→ 全チェック項目パス
1つの案件で生成されたファイル数は 約40ファイル です。これを手作業で作るのと比較すると、品質の均一性と速度の両面で大きな改善が見込めます。
6. Claude Codeとの協働で得た学び
CLAUDE.md は「指示書」ではなく「対話の起点」
CLAUDE.mdを最初から完璧に書こうとする必要はありません。まずは大まかな方針を書き、実際にClaude Codeと対話しながら「これは書いておくべきだ」と気づいた規約を追記していく進め方が有効でした。
例えば、Loadマクロのエラーハンドリングや Snapshot での LOAD_TIME 除外は、Claude Codeとの設計対話で「この場合はどうなりますか？」という質問から生まれた設計判断です。
Skills の粒度は「1文で依頼できる単位」
スキルの粒度を決める際の基準は「人が1文で依頼できるか」です。
- 良い例: 「このテーブルを追加して」→
/add-table - 粒度が細かすぎ: 「source YAMLを作って」→
/add-tableに統合すべき - 粒度が大きすぎ: 「環境構築やって」→ 何をチェックするか曖昧
レビュースキルは「生成」とセットで作る
/add-table と /review-table をセットで作ったことで、生成→レビュー→修正のサイクルが回せました。人がレビューする前にAIがセルフチェックすることで、明らかな漏れ（ファイル不足、命名不一致、テスト定義漏れ）は事前に解消できます。
ゼロからの構築でも「実案件の見本」が役に立つ
今回のテンプレート開発の最中では、過去の実案件で構築したリソース群をリファレンスとしてリポジトリに配置し、Claude Codeが参照できるようにしました。テンプレートの設計中に「このパターンはどう実装すべきか？」と迷った際、実案件のコードを具体例として示せたことで、設計判断のスピードと精度が大きく向上しました。リファレンスはテンプレート完成後に削除しましたが、ゼロからAI駆動で開発する際の「地に足のついた出発点」として非常に有効でした。
まとめ
Claude Code の CLAUDE.md と Skills を活用して、Snowflake + dbt のプロジェクトをAI駆動で開発しました。
成果
- 5つのスキルで案件構築の全フローをカバー
- 3つのCLAUDE.mdで設計規約を階層的に管理
- 入力テンプレート（CSV/YAML）で誰でも同じ品質で開発可能
- レビュースキルでセルフチェックを自動化
今後の展望
- アクセス制御設計やロール設計を詳細に構築できるスキルの追加
/run-guide、/recoveryなど運用系スキルの追加- 複数ソースシステム対応の検証
- 実案件での適用とフィードバックの蓄積
テンプレートそのものよりも、Claude Codeとの協働で設計を進めるプロセス が最も価値のある成果だと感じています。AIに「作って」と丸投げするのではなく、設計判断を一つずつ対話で詰めていくアプローチは、他のプロジェクトにも応用できるはずです。
