CLAUDE.md Template: dbt Projects

Overview

A CLAUDE.md file placed in your dbt project root gives build-cli persistent context about the project — dbt version, database, model structure, naming conventions, testing standards, and known data quality constraints. This article provides a ready-to-use CLAUDE.md template for dbt projects running on Snowflake, BigQuery, Redshift, or Databricks.

Copy the template below, fill in the placeholders, and commit it to your project root as CLAUDE.md.

Background

Without project context, build-cli may generate dbt models with incorrect naming conventions, missing schema.yml entries, or test patterns incompatible with your installed packages. It may also suggest hardcoded schema or table references instead of ref() and source(), or generate SQL in the wrong dialect. A well-filled CLAUDE.md prevents these issues by establishing the conventions and constraints upfront.

The template covers the most common dbt project structures (staging / intermediate / marts) and can be adapted for projects with additional layers (e.g., a raw layer or domain-specific subfolders).

Main Content

Copy this template into CLAUDE.md at your dbt project root and replace all [PLACEHOLDER] values:

## Project

**[PROJECT NAME]** — [One sentence: what this dbt project models, what domain or domain subdomain.]

## Tech stack

- Tool: dbt [VERSION]
- Database: [Snowflake / BigQuery / Redshift / Databricks / PostgreSQL]
- Profile: [dbt profile name]
- Packages: [list key packages — e.g., dbt-utils, dbt-expectations, elementary]

## Model structure

models/ staging/ # Raw source cleaning, one model per source table intermediate/ # Multi-source joins, business logic marts/ # Final consumption layer — one folder per domain

Sources are defined in `models/staging/sources.yml`.

## Conventions

- Naming: `stg_<source>__<entity>` for staging; `int_<description>` for intermediate; `<entity>` for marts
- All models have a description in `schema.yml`
- All primary keys have `not_null` + `unique` tests
- No `SELECT *` — all columns explicitly listed
- CTEs preferred over subqueries; each CTE has a comment on its purpose
- `ref()` and `source()` always — no hardcoded schema or table references

## Testing

```bash
dbt test                        # Run all tests
dbt test --select [model_name]  # Run tests for a specific model
dbt build --select [model_name]+  # Build model and its downstream dependents

Running

dbt run                         # Full run
dbt run --select [model_name]   # Single model
dbt run --select tag:[tag]      # Run by tag

Documentation

dbt docs generate && dbt docs serve

Known constraints

[Upstream sources, SLAs, fragile models, or known data quality issues to be aware of]

## Summary

- Place `CLAUDE.md` in the dbt project root to give build-cli accurate context for every session.
- The "Conventions" section is critical: it ensures generated code follows your project's naming standards and uses `ref()` / `source()` correctly.
- Fill in "Known constraints" with any data quality issues or fragile models — this prevents the AI from suggesting changes that would break fragile pipelines.
- Commit `CLAUDE.md` to version control so all team members work with consistent context.
- See the other CLAUDE.md example templates in this hub for data governance, ETL pipeline, and SQL analytics projects.