Claude Code DBT: How We Use It to Write dbt Models

What is Claude Code DBT and Why Does It Matter?

Claude Code DBT refers to the integration of Anthropic’s agentic command-line interface (CLI) with dbt (data build tool) projects to automate the development, refactoring, and documentation of analytics engineering workflows. Unlike standard autocomplete tools, this setup allows an AI agent to understand your entire project structure, execute terminal commands, and perform complex multi-step transformations within your data warehouse.

In our experience building data stacks for mid-market companies, the bottleneck is rarely writing the SQL itself. The friction lies in the "connective tissue": creating the schema.yml files, ensuring naming conventions match the style guide, and writing the boilerplate staging models for thirty new tables. Using claude code dbt shifts the role of the analytics engineer from a manual coder to a reviewer and architect. By leveraging the agent's ability to read your manifest files and project hierarchy, we reduce the time spent on boilerplate by roughly 60%.

Setting up your environment for claude code dbt integration

To use claude code dbt effectively, you need to treat the AI as a collaborator that has direct access to your local development environment. Because Claude Code is a terminal-based agent, it can interact with your dbt project files, run dbt commands, and even check your git status.

First, ensure you have the Claude Code CLI installed and authenticated. In our internal builds, we use the following setup:

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Navigate to your dbt project root
cd my-bigquery-dbt-project

# Initialize Claude
claude

Once inside the Claude interface, the agent has access to your file system. However, the true power comes from providing it with context. We recommend ensuring your dbt_project.yml is well-structured and your profiles.yml is configured correctly. The agent can then execute commands like dbt run or dbt test to validate the code it just wrote. This creates a closed-loop system where the AI writes code, tests it, sees the error, and iterates until it passes. This is a core component of what we teach in our Data Foundation (dbt, Terraform, BigQuery) track.

Automating dbt model creation with agentic workflows

The most common use case for claude code dbt is generating staging models. If you are using a source-to-staging pattern, you likely have dozens of tables that follow a predictable structure: selecting columns, renaming them for consistency, and casting data types.

Instead of doing this manually, you can provide a high-level instruction to the agent:

"Create staging models for all tables in the stripe_raw schema. Follow our project style: use lowercase, rename id to charge_id, and ensure all timestamps are cast to UTC."

The agent will then:

1. Examine your src_stripe.yml to identify the tables.
2. Create new .sql files in models/staging/stripe/.
3. Write the boilerplate CTEs.
4. Update or create the corresponding schema.yml with basic documentation.

This is fundamentally different from using a web-based LLM. Because the agent is in your CLI, it doesn't just give you a code snippet to copy-paste; it builds the files and verifies the directory structure. For teams looking to scale their infrastructure rapidly, this type of automation is a prerequisite for high-velocity analytics. If you are wondering if your team is ready for this level of automation, our AI Readiness Diagnostic helps identify gaps in your current data stack.

Leveraging claude code dbt mcp for deeper context

One of the most powerful features of this ecosystem is the Model Context Protocol (MCP). Using a claude code dbt mcp server allows the agent to pull in metadata that lives outside of your static text files. For example, an MCP server can connect to your BigQuery or Snowflake instance and pull the actual schema and column descriptions from the information schema.

When the agent has access to the actual data types and samples from your warehouse, the code quality improves significantly. It stops guessing whether a column is a string or a JSON object and starts writing valid SQL on the first try.

Example: Using MCP for column descriptions

When we use an MCP server with Claude, we can ask: "Find all columns in the orders table that don't have descriptions in our dbt project and suggest descriptions based on the actual data values."

The agent will:

• Query the database (via MCP).
• Compare the database schema to your local schema.yml.
• Draft descriptions that reflect the actual data (e.g., "Contains ISO 4217 currency codes").

This level of integration ensures that your documentation doesn't just exist but is actually accurate.

Refactoring legacy SQL using claude code dbt

Many of our clients come to us with "SQL spaghetti"—massive, 500-line scripts that were written before they adopted dbt. Moving these into a modular dbt structure is often the first step in a data transformation project.

We use claude code dbt to handle the heavy lifting of refactoring. The process usually follows these steps:

1. Decomposition: We ask the agent to break the large script into logical CTEs (Common Table Expressions).
2. Modularity: We instruct the agent to identify which parts of the script should be moved into upstream staging or intermediate models.
3. Refactoring: The agent rewrites the code to use the {{ ref() }} function instead of hardcoded table names.
4. Validation: We have the agent run the new models and compare the row counts and values against the original legacy script to ensure parity.

For example, a prompt might look like: "Refactor legacy_marketing_query.sql into a dbt model. Move the customer logic into a new intermediate model called int_customers_joined. Replace all references to raw.users with {{ ref('stg_users') }}."

This prevents the human error that usually occurs during manual refactoring, such as missing a join condition or mislabeling a column in a deep CTE.

Best practices for dbt development with AI agents

While claude code dbt is powerful, it requires a specific set of standards to remain effective. Without clear rules, the agent might produce code that technically runs but doesn't follow your team's internal conventions.

1. Maintain a strict .claudecodeconf

You can provide instructions that the agent reads every time it starts. We include our SQL style guide here (e.g., "Always use trailing commas," "Put the comma at the start of the line," "Use 4 spaces for indentation").

2. Use small, incremental prompts

Rather than asking the agent to "Build the entire marketing attribution model," ask it to "Build the staging models for HubSpot sources." Smaller tasks allow you to verify the output before the agent moves on to more complex logic.

3. Verify with dbt compile

Always have the agent run dbt compile after generating code. This ensures that the Jinja templates are valid and that all ref() calls point to existing models. If the compilation fails, the agent can see the error message and self-correct immediately.

4. Human review is mandatory

We treat AI-generated dbt models as "Draft PRs." An analytics engineer should always review the logic, especially for complex transformations like sessionization or attribution windowing. The AI excels at the structure; the human excels at the business logic.

Comparing Claude Code to other AI coding assistants

When deciding how to implement AI in your data workflow, it is helpful to understand how Claude Code differs from tools like GitHub Copilot or Cursor.

The reason we prefer claude code dbt for analytics engineering is the terminal integration. Analytics engineering is not just about writing code; it is about the cycle of write-run-test-debug. Because Claude Code can execute dbt run and see the logs, it can fix its own bugs. An IDE-based autocomplete tool cannot see that your Snowflake warehouse is suspended or that a specific test failed because of a null value in a column.

We cover these tool comparisons in detail during our Learn AI Bootcamp, where we help teams choose the right stack for their specific needs.

Managing dbt YAML documentation at scale

If there is one task every analytics engineer dislikes, it is writing YAML. It is repetitive, error-prone, and boring. This is exactly where claude code dbt provides the highest return on investment.

We use the agent to "backfill" documentation. By pointing the agent at a folder of models, we can say: "Generate descriptions for every column in these five models. Use the context from the SQL logic to explain what the transformations are doing."

The agent is surprisingly good at this. If it sees a column being calculated as datediff(last_purchase, first_purchase), it will correctly document the column as "The number of days between the customer's first and most recent purchase." This turns a task that would take a human two hours into a three-minute automated process.

Handling dbt tests and data quality

Beyond documentation, you can use the agent to improve your testing coverage. Most teams stop at unique and not_null tests because writing custom data tests is time-consuming.

With claude code dbt, you can ask: "Based on the logic in fct_orders, what are three custom data tests we should add to ensure the revenue calculations are correct?"

The agent might suggest:

1. Checking that gross_revenue is always greater than or equal to net_revenue.
2. Ensuring order_date is never in the future.
3. Validating that every order_id in this table exists in stg_orders.

It can then write the YAML for these tests or even create the singular test SQL files in the tests/ directory. This proactive approach to data quality is what separates average data teams from those that the business truly trusts. For a deeper look at this, we recommend reading our post on why data pipelines break.

Frequently Asked Questions About Claude Code DBT

Can Claude Code run dbt commands against my production database?

Claude Code runs with the permissions of your local environment. If your local terminal is configured with production credentials, the agent can technically run commands against production. However, we strongly recommend only giving the agent access to a development or staging schema to prevent accidental data loss or cost overruns.

Does using claude code dbt require an MCP server?

No, it does not require an MCP server to function. It can work perfectly well by reading your local .sql and .yml files. However, adding an MCP server for your specific database (like BigQuery or Postgres) provides the agent with "live" metadata, which significantly increases the accuracy of its suggestions.

Is my code sent to Anthropic when using Claude Code?

Yes, the files the agent needs to read to answer your prompts are sent to Anthropic's servers for processing. If you work in a highly regulated industry with strict data residency requirements, you should review your company's AI policy before using CLI-based agents. Anthropic provides specific privacy tiers for enterprise customers that exclude data from training.

How does Claude Code handle complex Jinja macros in dbt?

Because Claude is trained on a vast library of open-source dbt projects, it understands Jinja syntax well. It can write and debug macros, including complex logic like dynamic column generation or warehouse-specific cross-database macros. We find it particularly useful for migrating macros between warehouses (e.g., from Redshift to Snowflake).

Ready to modernize your data workflow?

Implementing claude code dbt is just one part of building a world-class data foundation. If you are a data leader looking to accelerate your team's output while maintaining high standards of data quality, we can help.

Our AI Readiness Diagnostic is the best way to start. We will analyze your current stack, identify bottlenecks in your development workflow, and provide a roadmap for integrating agentic AI into your analytics engineering practice. Whether you need to refactor legacy code or build a new foundation from scratch, our team provides the practitioner-level expertise to get you into production safely and efficiently.

Book a free consultation with our team to talk through your specific data architecture and how AI agents can unblock your roadmap.