dbt_project_evaluator: best practice rules as native dbt checks

What it checks, and the six categories

The package highlights areas of a dbt project that are misaligned with dbt Labs' best practices, and the six categories are each a link into their own documentation section.

Modeling covers your dbt DAG for modeling best practices. Testing covers your models for testing best practices. Documentation covers your models for documentation best practices. Structure covers your dbt project for file structure and naming best practices. Performance covers how your models are persisted for performance best practices. And Governance covers your best practices for model governance features.

The mechanism is the part that makes this different from a linting tool. Each rule is a native dbt check, which the README defines as a SQL query over the dbt information schema that runs locally and returns one row per violation. Nothing is built in your warehouse, so it needs no credentials and works with every adapter supported by dbt 2.

That last point is the design decision worth dwelling on. A check that runs in the warehouse consumes compute, needs a connection string, and reports whatever the warehouse happens to be configured to return. A check that runs locally against the manifest and the dbt information schema needs nothing but a dbt install, which is what makes it viable in a pull request check where the alternative would be spinning up a warehouse just to lint.

The primary language is Python, the licence is Apache-2.0, the default branch is main, the homepage is the documentation site at dbt-labs.github.io, and the recent releases are v2.0.1 from 2026-10-19, v2.0.0 from 2026-10-16 and v1.4.1 from 2026-10-14. The last push was on 2026-10-19 and the project is not archived.

Version 2 is a rewrite of the delivery mechanism, not of the rules

The README's most prominent block is a warning for anyone arriving from the 1.x line. Using dbt v1? This README is for version 2, which requires dbt 2.0 or later. Stay on 1.x and cap the version in your packages.yml so that dbt deps does not upgrade you, with the constraint given as a version range.

That cap is the operational detail that catches people. The migration is not automatic when you add the package, because dbt deps resolves the latest matching version, and the latest is now 2.x with a different configuration model.

The reason version 2 exists is listed as five advantages.

Native means you run the rules with dbt check and configure them in dbt_project.yml like any other resource. Checked before every build means a rule set to severity: error stops a build that breaks it. Fast means about 15 seconds for a project of 1,900 models, against about 2 minutes for the 1.x dbt build. Selectable means --select and state:modified report only the violations on the resources you changed. And no warehouse needed means no credentials and no compute cost, so CI needs no secrets.

The performance comparison is the most interesting claim, because it inverts the usual reason to run checks in CI. The 1.x approach modelled the rules as dbt models and built them, which is why it took two minutes and why it needed a warehouse. The 2.x approach runs them as checks, which is why it takes fifteen seconds and needs nothing.

The coming from version 1 section is short and specific. The rules are the same, but they are checks now instead of models, so the configuration changes: severity is set with checks:, exceptions are a var instead of a seed, and the 1.x tables are gone. A script, scripts/migrate_to_v2.py, converts your exceptions seed, and a migration guide covers the rest.

Installing and running it

Installation is a package entry in packages.yml, with a version range for the 2.x line:

# packages.yml
packages:
  - package: dbt-labs/dbt_project_evaluator
    version: [">=2.0.0", "<3.0.0"]

After that the checks run before every dbt build, and on demand with dbt check. They are advisory by default, with severity: warn.

The three invocations on the command line are the whole interface:

dbt check                                                       # every check
dbt check fct_root_models                                       # one check
dbt check --select state:modified --state path/to/main/target   # only what a pull request changes

The first runs every check, the second runs one check by name, and the third runs only what a pull request changes, using the state comparison against a target directory. That third form is the one that makes the checks usable in a pull request workflow, since a full check on a large project is noise unless you narrow it to the diff.

The severity of a category or of a single check is set in dbt_project.yml:

checks:
  dbt_project_evaluator:
    structure:
      +severity: error          # block `dbt build` on violations
    documentation:
      fct_undocumented_models:
        +enabled: false         # turn off one rule

The structure of that configuration shows the granularity. A category gets a severity, so structure can block the build. A single check under a category can be disabled with +enabled: false, and the example disables fct_undocumented_models while leaving the rest of the documentation rules active. That is the difference between turning off a whole category because it does not apply to your project and turning off one rule that does not apply to one table.

The documentation site lists four more customisation routes: accepting some violations as exceptions, changing a threshold or a naming convention, excluding a package or a path, and running the checks in CI.

The agent skills, and what they are for

The package ships three skills that teach a coding agent how to run the checks, fix the violations and migrate from 1.x. You set ai_provider under flags: in your dbt_project.yml and run dbt deps to install them.

This is a recent addition and it is worth reading carefully rather than skipping. The idea is that an agent which knows the rules can fix them, which turns the evaluator from a report into a repair tool. A rule that says a model is undocumented, for example, is trivially fixable by an agent that has read the rule, because the fix is a description field in the model config.

The three skills map onto the three jobs a team would actually want an agent to do: run the checks, fix what they report, and handle the version 1 to 2 migration. The last one is the most interesting, because the migration is mechanical but tedious, and a migration script that only converts the exceptions seed does not convert the severity settings, which is the part that touches every category in your configuration.

The repository layout backs this up. There is a skills/ directory alongside checks/, macros/, overrides/ and scripts/, and a dbt_project.yml at the root that configures the package. The macros and overrides directories are where the rule implementations and their configuration live, which is the same shape a dbt package normally has, and the integration_tests_checks/ directory suggests the checks are tested against fixtures rather than against a live project.

How to evaluate it, and the questions to ask your team

The evaluation is mostly about whether your project is ready to be judged against these rules, because that is a cultural question as much as a technical one.

Start with the categories. If your project has no documentation culture, the documentation rules will report every model, and turning that category off is better than ignoring a report nobody reads. The severity mechanism lets you do this per category and per check, and the +enabled: false example in the README is exactly the case where a single rule does not fit your setup.

Then think about the enforcement mode. A rule set to severity: error stops a dbt build, which is a strong statement to make about a lint rule on day one. The safer path is to start with everything at warn, run the checks on the full project, look at the violation count, and promote to error only for the categories where you are confident the codebase is already clean. A check that blocks builds on a repository with two thousand existing violations is a check that will be disabled in a week.

The state:modified form deserves a note for CI. Because the checks can be narrowed to the resources a pull request changes, you can run them as a required status check without making every pull request wait on a full project scan. That is the design the fifteen-second figure exists to support, and it is what makes the package realistic for a repository of the size the README describes.

Two things to verify before committing. The first is your dbt version, because the package requires dbt 2.0 or later and the 1.x line is a different codebase with different configuration, so a team on dbt 1.x is a migration project rather than an install. The second is the adapter question. The checks run locally against the dbt information schema, which is why no warehouse is needed, but that also means the rules are evaluated against what dbt knows about your project rather than against what the warehouse contains, and a project with unusual table or view strategies, or custom macros may need an exception for rules that do not fit.

Editorial conclusion

Adopt dbt_project_evaluator v2 if you run dbt 2 and want best practice rules enforced as part of the build rather than reviewed by hand, since the checks run locally in about fifteen seconds, need no warehouse credentials, and can block a build when a rule is set to severity error. Do not adopt it on dbt 1.x without a migration, and do not turn on error severities for every category on day one, since a repository with existing violations will simply have its builds blocked. Before you commit, run the checks once against the whole project, count the violations per category, promote only the clean categories to error, and use the state:modified form in CI so a pull request check reports only what it changed.

Frequently asked questions

Official sources

1. dbt-labs/dbt-project-evaluator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases