dbt 導入時に最初の3週間でやるべきこと

dbt（data build tool） は「軽量で気軽に使える」と紹介されることが多いツールですが、本番運用に乗せるという視点で見ると、最初の3週間でしっかり型を作るかどうかで3年後の運用負荷が大きく変わります。今回は、私たちが新規プロジェクトで必ずやる「最初の3週間」を共有します。

Week 1：プロジェクト構成と命名規約を決める

命名規約は、最初に決めておけば誰が書いても揃いますが、後から揃え直すのは地獄です。私たちは以下の規約を必ず Day1 に決めます。

Week 2：CI（Continuous Integration） と スキーマテストを入れる

「動くdbtプロジェクト」と「壊れないdbtプロジェクト」を分けるのは、CI/CDとスキーマテストの有無です。GitHub Actions で PR ごとに dbt build を走らせ、テスト失敗時はマージ不可にします。

name: dbt CIon: pull_requestjobs:  dbt-build:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: actions/setup-python@v5        with: { python-version: '3.11' }      - run: pip install dbt-bigquery      - run: dbt deps      - name: Run dbt build (差分のみ)        run: dbt build --select state:modified+ --defer --state ./prod-manifest        env:          DBT_BIGQUERY_KEY: ${{ secrets.DBT_BIGQUERY_KEY }}

重要なのは `state:modified+` での差分実行。プロジェクト全体を毎回ビルドすると CI が10分以上かかるようになり、誰も PR を出さなくなります。差分実行で1〜2分に抑えるのがコツ。

Week 3：ドキュメント自動生成と運用への引き渡し

dbt の隠れた最強機能は、ドキュメントの自動生成です。`description:` を schema.yml に書いておけば、`dbt docs generate` でER図付きのドキュメントが自動的に出来上がります。Week 3 では、これを運用フローに組み込みます。

Claude Code で dbt 規約を一括チェック

この dbt プロジェクトの命名規約違反を全部見つけて修正リストにしてください。

## 規約
- staging: stg_<source>__<table>
- intermediate: int_<noun>_<verb>
- fact mart: fct_<noun>
- dim mart: dim_<noun>
- 日付カラム: <event>_at (TIMESTAMP) / <event>_date (DATE)
- boolean カラム: is_<state> または has_<thing>

## 出力
- ファイル名と違反内容のテーブル
- 一括 rename PR の案（必要なら）

## 規約違反リスト

| ファイル | 違反 | 提案 |
|---|---|---|
| models/staging/sf_opps.sql | プレフィクス無し | stg_salesforce__opportunities |
| models/marts/sales/order.sql | fct/dim区別無し | fct_orders |
| models/marts/finance/customer.sql | dim_ 無し | dim_customer |
| カラム created (TIMESTAMP) × 8テーブル | _at suffix 無し | created_at に変更 |
| カラム active (BOOLEAN) × 5モデル | is_ prefix 無し | is_active に変更 |

## 一括 PR 案
`scripts/rename_models.sh` を生成しました。dry-run で5件のテーブル名・15件のカラム参照が更新されます。確認後、実行します。

3週間チェックリスト

• □ ディレクトリ構成（staging / intermediate / marts / analyses）を採用した
• □ 命名規約を README に明文化した
• □ 全モデルが規約に準拠している（Claude Code でチェック）
• □ GitHub Actions で差分CIが動いている
• □ schema.yml の description にビジネスルールを書いた
• □ dbt docs を社内に共有した

次回予告

EP.04 では、「夜中に止まるパイプライン」を撲滅する監視設計を、Datadog/Cloud Monitoring の実例とともに解説します。