How Spec-Driven Development Maximizes dbt Wizard

In my last post I argued that as coding agents take over implementation, analytics engineering work moves upstream: finding the business rules, resolving the open decisions, and defining what "correct" means before anyone writes SQL. A spec is how you make that work concrete.

Since then, the obvious follow-up question keeps coming up in conversations: fine, but which agent do I point the spec at? dbt Wizard is now a very strong option for analytics engineering teams.

Here’s why I think dbt Wizard makes the case for spec-driven development stronger.

What is dbt Wizard?

dbt Wizard is dbt Labs' AI agent for dbt development. It runs either inside the dbt platform or as a terminal-native CLI you can install with your own model key, with or without a platform account.

The biggest advantage of dbt Wizard is its native metadata engine: a structured index of lineage, tests, contracts, model health, and run history, built from your dbt artifacts. This provides a series of advantages over other coding agents, such as:

• Impact analysis: Lineage is tracked at the column level, and dbt Wizard is immediately aware of downstream impacts of changes to your models
• Health checks: dbt Wizard gives you structured data on which of your models lack tests, have stale data, or failed recently, without running anything
• Data profiling: Row counts, distributions, null rates, used as context when deciding how to build a model, without materializing it first

dbt Wizard also ships with a validation loop: it checks proposed changes against the project state before making any changes. If a check fails, it adjusts and retries. In the CLI, you can set the depth of validation: light, medium, or heavy, where heavier validation includes additional steps such as checking your data against the prod environment.

dbt Wizard doesn’t know your business logic by default

dbt Wizard’s advantages are grounded on your project as it exists today, not what it’s supposed to produce.

For example, Wizard can tell you that fct_revenue has no tests on the net_revenue column, or that 14 downstream models reference it. It can’t tell you that finance nets credit memos against the original invoice period rather than the issue period, the Salesforce segment field is stale and NetSuite is the source of truth for enterprise accounts, or that Q4 net revenue has to tie to the GL within $5k.

Those rules aren't in your artifacts: they’re in a Finance spreadsheet, discussed in a meeting, or in someone's head.

This is exactly the gap I described in my last post: an AI agent can produce code that compiles, passes tests and respects your conventions, yet encodes the wrong business rule. The validation loop confirms the change is technically safe, but it has no opinion on whether the logic is correct, and dbt's own docs say as much: a passing check doesn't remove the need to review business logic.

Could this gap be addressed by a well-built specification?

Proof that dbt Wizard works even better with a spec

I tried building a proof-of-concept dbt pipeline using dbt Wizard for Velogroup, a demo company we use internally based on an SAP sample dataset:

1. I created two dbt projects, both using dbt Wizard on Sonnet 5
2. I gave both projects the same prompt: create a dbt project which allows us to analyze the financials of our business using a medallion architecture
3. In the second dbt project, I included a spec created using Maxa Autopilot, based on two transcripts of meetings with members of the Finance team.

Without the spec, dbt Wizard was still very capable

It read the source data and built 18 staging models, 4 intermediate, and 9 marts. It validated the project to ensure it compiled cleanly. The final project enabled analysis of our demo company’s P&L statement and actual vs budget variance.

However, Autopilot Spec took dbt Wizard to the next level

It read the spec before it planned anything, working through the entity files, KPI definitions, and reference docs to ground the plan. It then produced a similar number of staging, intermediate and mart models, but with key differences compared to the no-spec run:

1. It wrote tests against business figures, not just structural ones. The spec-grounded tested exact distributions from the spec: customer type mix at roughly 66% special, 31% large, under 1% medium; COGS around 75% of transaction counts against gross revenue around 18%. Those numbers came from a finance interview transcript that Autopilot ingested and carried into the spec. The pipeline now ran regression tests against the business's own stated shape of its data.
2. It answered an edge case with a decision instead of a judgement call. I asked dbt Wizard inside both projects the same question: should I filter out customers with hash symbols from the customer dimension? The spec-grounded run pointed out that doing so would delete the entire operating expense section from consolidated reporting, citing the framing from the finance workshop where that rule was established. Without the spec, this is the kind of question an agent can give you a reasonable answer which silently destroys the P&L.
3. KPI coverage wasn't close. The spec lists 21 KPIs that VeloGroup's CFO and director of finance named as the metrics they actually track. I asked Wizard to grade both pipelines against that list. The spec-built pipeline answers 17 fully out of the box, three more with a single query, and one is out of scope, effectively 20 of 20 in-scope KPIs. The no-spec pipeline could only answer 6 of the KPIs fully: the rest needed hand-written SQL which depended on knowledge living nowhere in the models. Gross margin percentage, the CFO's stated top priority, was amongst the KPIs which the no-spec pipeline could not calculate.

TL;DR:

None of those are coding failures: dbt Wizard built a clean, conventional, test-covered dbt project both times. The difference is entirely in the business context and requirements captured in the spec, and how they enriched the spec pipeline.

The real return on spec-driven development

Now that an agent can produce a validated, lineage-aware, test-covered model faster than you can schedule the meeting to define it, the spec is the bottleneck.

dbt Wizard built a clean project both times. What it couldn't do was tell me which of the two was right, and neither could I, until I had a list of 21 KPIs to grade them against.

That's the real return on a spec. Not that it makes the agent write better SQL (though it does). It's that "correct" becomes something you can check instead of something you argue about in review. A data pipeline that ties to figures the CFO stated out loud is a different kind of artifact than one that merely compiles.

Agents made implementation cheap. Specs are what make correctness checkable.

And in agentic data engineering, you want both.