Claude Code for dbt Development

This hub maps the core Claude Code workflows for dbt development. The highest-leverage tasks are those with high pattern density: generating base models, writing tests, documenting columns, tracing debug paths, and refactoring column names across files. Each note stands alone, but prompting principles and CLAUDE.md configuration apply across all workflows.

Start Here

Before anything else, understand what the tool is actually good at and where it falls short:

• Claude Code Strengths and Limitations for Data Work — The capability map. What Claude Code handles natively (boilerplate, multi-file changes, pattern replication) and where it struggles (novel business logic, ambiguity, security-sensitive work).
• Claude Code ROI for Analytics Engineers — The honest setup cost: several weeks of investment before consistent value, what the savings actually look like, and which tasks get done because they stopped being painful.

Configuration

• CLAUDE.md as Project Memory — The single highest-leverage configuration. Encoding naming conventions, test requirements, SQL style, and explicit prohibitions into CLAUDE.md means Claude applies them to every prompt without being told.
• Claude Code Slash Commands for dbt — Reusable, team-shareable prompts for repeatable workflows. /generate-tests, /document-model, /test-prompt. How to build them, what to include, how to distribute them to the team.

Core Workflows

Model Generation

• Base Model Generation with Claude Code — The pattern-replication workflow for dbt base models. How to write prompts that produce convention-consistent output, what CLAUDE.md defaults to encode, and how to handle full source onboarding (15+ tables from a new connector).

Testing

• TDD with Claude Code for dbt — Test-driven development with an AI agent. Write tests first, let Claude implement to pass them, iterate on failures, refactor with confidence. The five-step workflow and why “don’t modify the tests” is the critical instruction.

Documentation

• dbt Documentation with Claude Code — The codegen-plus-Claude pattern for schema.yml. Generate the column scaffold with dbt codegen, fill descriptions and tests with Claude Code. Plus: docs blocks for consistency, lineage diagrams, and the /document-model slash command.

Debugging

• Debugging dbt with Claude Code — Let Claude face errors directly. Build errors, data quality issues, subagents for complex investigations. The “describe the problem, not the debugging steps” principle and when subagents help vs overkill.

Refactoring

• Codebase Refactoring with Claude Code — Project-wide column renames, naming convention migrations, ref() updates across dozens of files. How to include YAML files and singular tests in refactoring prompts, and why low-cost refactoring changes which work actually gets done.

Prompting

• Prompting Claude Code for dbt — What separates prompts that work from prompts that produce generic output. The four properties: specificity, explicit constraints, codebase references, and defining “done.” The session memory problem and how CLAUDE.md partially solves it.

Reading Path

If you’re getting started with Claude Code for dbt work, a useful sequence:

1. Claude Code ROI for Analytics Engineers — Calibrate expectations before investing in setup.
2. CLAUDE.md as Project Memory — Set up the configuration foundation.
3. Prompting Claude Code for dbt — Learn what makes prompts work.
4. Base Model Generation with Claude Code — First workflow to practice.
5. TDD with Claude Code for dbt — Add test coverage systematically.
6. dbt Documentation with Claude Code — The biggest time sink, now manageable.
7. Debugging dbt with Claude Code — Use when you need it.
8. Codebase Refactoring with Claude Code — Tackle the technical debt backlog.
9. Claude Code Slash Commands for dbt — Systematize the workflows that work for you.

The sequence isn’t strict. Configuration before workflows, and prompting principles before any specific task, reduces errors from misaligned expectations.