Un projet dbt bien structuré fonctionne comme une base de connaissances partagée qui fournit du contexte à chaque outil IA d’une stack de données. Les modèles, les tests, la documentation et les définitions sémantiques sont les informations structurées que les agents IA consomment. Mieux un projet dbt est organisé et documenté, mieux chaque outil IA de la stack performe.
Ce que les projets dbt exposent à l’IA
Un projet dbt contient plusieurs types d’informations que les outils IA peuvent lire et utiliser :
Le SQL des modèles — la logique de transformation elle-même. Un agent IA qui lit les modèles base comprend le schéma source, les types de champs et les patterns de déduplication. Un agent qui lit les modèles intermédiaires comprend les relations entre entités et la logique métier. C’est le fondement qui rend la réplication de patterns possible — l’agent apprend les conventions à partir du code.
Le YAML de schéma — descriptions de modèles et colonnes, définitions de tests, et déclarations de sources. C’est la couche de métadonnées. Quand un modèle a une description comme “Une ligne par client, au moment de sa première commande. Granularité : customer_id” et des descriptions de colonnes précisant ce que chaque champ représente, un agent IA peut faire des hypothèses correctes sur la façon de rejoindre ou de construire sur ce modèle. Sans cela, l’agent devine.
Les tests — les assertions sur ce qui est vrai dans les données. Un modèle avec des tests not_null et unique sur sa clé primaire indique à un agent IA quelque chose d’important : cette colonne ne devrait jamais être nulle, et les doublons sont un bug. Un modèle avec des tests accepted_values sur une colonne de statut indique à l’agent quelles valeurs sont valides. Les tests encodent la connaissance des attentes de qualité des données que le SQL lui-même ne rend pas toujours explicite.
Les définitions sémantiques — modèles sémantiques MetricFlow, définitions de dimensions et YAML de métriques. C’est la couche de connaissance de plus haut niveau : que signifie “revenu” dans cette organisation ? Quelle est la granularité du modèle de sessions ? Comment les clients se rapportent-ils aux commandes et aux produits ? Quand cette couche existe et est bien maintenue, les outils IA peuvent répondre aux questions métier avec précision plutôt que de faire des hypothèses structurelles qui produisent des sorties plausibles en apparence.
La connexion MCP
Le serveur MCP dbt rend cette connaissance consommable par tout outil IA qui supporte le Model Context Protocol. Au lieu qu’un agent lise directement les fichiers du projet, le serveur MCP les expose comme outils structurés : lister les modèles, obtenir le SQL d’un modèle, interroger la couche sémantique, exécuter des commandes.
Cela importe pour la cohérence cross-outils. Claude Code peut lire les fichiers du projet directement car il s’exécute dans le terminal. Mais un outil IA qui n’a pas d’accès au système de fichiers — ou un agent de monitoring s’exécutant sur une machine distante — peut toujours accéder à la connaissance du projet dbt via MCP.
OpenClaw a un support MCP via son pont mcporter. Cela signifie que le même contexte de projet dbt qui informe les sessions de développement Claude Code peut également informer les tâches de monitoring et de reporting d’OpenClaw. Quand OpenClaw exécute dbt test à 7 heures du matin et doit expliquer ce que teste le test en échec, il peut interroger le serveur MCP pour la description du modèle et la documentation des colonnes. Le résumé d’échec qu’il envoie à Slack est plus riche car il a accès à la couche de connaissance documentée du projet.
La couche des compétences
Les Agent Skills de dbt Labs sont le complément de la documentation au niveau du projet. Les fichiers de compétences enseignent aux agents IA les conventions générales de dbt — ce qui appartient à quelle couche, comment nommer les choses, quels tests ajouter par défaut. La documentation du projet enseigne aux agents la connaissance spécifique du projet — ce qu’est la dimension date, où vit la logique de revenus, sur quelles colonnes il est sûr de joindre.
Les deux couches sont additives. Les compétences préviennent les erreurs génériques. La documentation du projet prévient les erreurs spécifiques au projet. Ensemble, elles donnent à un agent IA un meilleur contexte que l’un ou l’autre seul.
L’insight clé est que les deux couches sont des fichiers Markdown. Ils sont lisibles par un humain, versionables, et agnostiques aux outils. Les mêmes fichiers de compétences qui améliorent la production dbt de Claude Code peuvent améliorer les suggestions de Cursor et, théoriquement, de tout autre outil qui les charge comme contexte. Le même YAML de schéma qui documente le projet pour les humains est machine-readable par chaque outil IA de la stack.
La documentation comme infrastructure
La documentation dbt est de l’infrastructure IA. Une colonne non documentée est une colonne sur laquelle l’agent fait des hypothèses. Un modèle non documenté est un modèle dont l’agent devine la granularité. Un schéma source non documenté est une source que l’agent mappe incorrectement.
La qualité de la documentation détermine l’utilité de l’IA couvre cela plus en détail, mais le pattern issu de la recherche est clair : Tiger Data a constaté qu’ajouter des catalogues sémantiques au SQL généré par IA améliorait la précision de 27 %. L’amélioration ne venait pas d’un meilleur modèle, mais d’une meilleure documentation de ce que signifient les tables et colonnes. L’IA était la même. La connaissance disponible était plus riche.
L’investissement en documentation se cumule : chaque heure passée à documenter les modèles améliore la sortie IA à travers chaque outil qui lit le projet. La structure et la documentation du projet sont du travail d’ingénierie, pas une surcharge.
Effets de la documentation sur la sortie IA
Avec un projet bien documenté, un agent IA chargé de construire un modèle intermédiaire qui joint les commandes aux clients peut lire le schéma existant base__shopify__orders, localiser dim_customers et sa granularité à partir de sa description, identifier que les métriques de valeur vie client sont déjà calculées dans int__customers__lifetime_value, et suivre les conventions de nommage du projet. Le modèle qu’il produit suit les conventions, évite de recréer la logique existante, et joint correctement.
Sans documentation, le même agent suppose la granularité, peut joindre sur la mauvaise clé, peut recréer la logique existante, et peut nommer ou placer le modèle incorrectement — des erreurs qui ne sont pas toujours immédiatement évidentes.
Les échecs SQL IA les plus courants sont des échecs de jugement issus d’un contexte manquant. Un projet dbt bien documenté est la principale atténuation.
La boucle de révision
Les projets dbt mieux documentés produisent une meilleure sortie IA. Quand cette sortie est révisée et corrigée, elle devient du code plus précis, qui est plus facile à documenter clairement, ce qui améliore encore la sortie IA. La boucle se rompt si la sortie IA n’est pas révisée. Un agent qui produit silencieusement des modèles incorrects — inner joins là où des left joins sont nécessaires, mauvaise granularité, hypothèses non documentées intégrées dans la logique métier — génère une dette technique qui rend la documentation future plus difficile. L’étape de révision confirme si l’IA a correctement compris le contexte du projet ; quand ce n’est pas le cas, c’est un signal pour améliorer la documentation.