Accueil / Articles

Règles, flux de travail et sous-agents : Séparation d’un plugin d’agent IA pour dbt

Pourquoi un grand fichier d’instructions a échoué, et comment AGENTS.md, une compétence basée sur des spécifications, les sous-agents, les hooks et Jira MCP ont chacun assumé une tâche dans un flux de travail dbt.

Éditeur : REACTAPP.TOP6 min de lecture1298 mots

Sources: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into

Un seul fichier d’instructions ne peut pas contenir à la fois un règlement, un processus et les tâches quotidiennes sans compromettre l’un ou l’autre de ces éléments. C’est ainsi que se comportait la première version d’un flux de travail dbt agent, et les raisons de sa division en parties révèlent beaucoup sur la manière d’organiser les instructions destinées aux agents IA.

Quelques éléments de contexte. Un agent IA chargé d’écrire des modèles dbt peut produire du code qui se compile, passe tous les tests, mais donne malgré tout des résultats erronés. Plutôt que de faire confiance à la mémoire de l’agent, le processus a été transformé en sept contrôles stricts stockés directement dans le répertoire, et ces contrôles ont depuis permis de détecter de véritables défauts que les seuls tests n’auraient pas pu repérer. Ici, l’accent est mis sur le mécanisme qui garantit le bon fonctionnement de ces contrôles : des règles, un flux de travail, des sous-agents, des hooks ainsi qu’une intégration avec Jira. Le plugin comporte trois niveaux : des règles actives en permanence, un flux de travail déclenché par l’utilisateur, des sous-agents isolés pour les étapes complexes, des hooks qui maintiennent la cohérence de la session, ainsi que MCP pour interagir en dehors du répertoire. Aucune composante ne double le travail d’une autre.

Le vocabulaire d’abord

  • Agent. Un système d’IA capable d’ouvrir des fichiers, d’exécuter des commandes et de réaliser plusieurs étapes de manière indépendante, ce qui lui permet de faire plus que simplement répondre aux questions.
  • Fichier de règles (AGENTS.md). Règles permanentes que l’agent charge automatiquement au démarrage d’une session. Il s’agit d’une norme ouverte fonctionnant avec différents outils, sans être liée à un fournisseur particulier. On peut l’imaginer comme un manuel du personnel que tout le monde est censé connaître déjà.
  • Compétence (flux de travail). Instructions chargées uniquement lorsque ce type de tâche apparaît, un peu comme une recette qui est utilisée lorsque l’on commande un plat spécifique.
  • Sous-agent. Une copie distincte de l’agent lancée pour une tâche donnée dans son propre contexte privé, qui fournit un résumé une fois le travail terminé.
  • Hook. Un script lié à un moment précis d’une session qui s’exécute automatiquement, quel que soit le choix de l’agent. On peut l’imaginer comme un système anti-incendie : il se déclenche dès la première apparition de fumée sans demander l’avis de quiconque.
  • MCP (Model Context Protocol). Un standard publié par Anthropic qui définit la manière dont un agent accède à des outils externes, afin que personne n’ait à créer des solutions sur mesure pour chaque outil. On le compare à un port USB-C pour les applications d’intelligence artificielle, car tout ce qui respecte ce standard peut y être connecté.
  • Qu’est-ce qui a mal tourné au début

    Le premier flux de travail basé sur des spécifications manquait de la plupart de ces éléments. Il s’agissait d’un seul fichier Markdown situé dans la racine du répertoire, contenant les règles et le processus, et qui tentait de guider l’agent étape par étape. Il n’y avait ni sous-agents, ni hooks, ni contrôles stricts, seulement une séquence suggérée.

    Pendant un certain temps, cela a fonctionné. Cependant, une fois que une session devenait longue, les règles situées en haut du fichier sortaient du contexte actif vers la troisième étape d’implémentation, et l’agent commençait à improviser sans le dire. La découverte, la spécification et l’implémentation partageaient la même fenêtre, et les instructions les plus anciennes étaient les premières à être affectées.

    Les équipes travaillant dans d’autres entrepôts rencontrent le même problème. Un modèle observé dans la pratique, chez une équipe plus avancée, séparait les règles, le flux de travail et l’exécution, et utilisait des points d’ancrage de session afin que la compression du contexte ne puisse pas supprimer silencieusement des instructions au milieu d’une tâche. La leçon à retenir était de cesser de considérer « les instructions de l’agent » comme un tout unique. Il y en a trois, chacune ayant une durée de vie et une fonction différentes.

    Trois niveaux, un responsable par niveau

    • Niveau un : les règles permanentes : AGENTS.md, présentes en permanence
    • Couche deux, le processus : la compétence spec-driven, initiée par l’utilisateur
    • Couche trois, étapes complexes : des sous-agents créés selon les besoins

    Règles

    Le fichier des règles contient les règles d’ingénierie obligatoires, ainsi qu’un profil de projet qui définit les paramètres de chaque équipe : conventions de nommage, méthodes de matérialisation, branche de base, système CI, etc. Un mécanisme de chargement lit ce fichier au début de chaque session, ce qui élimine toute dépendance quant au fait que l’agent se souvienne de le consulter. Il est donc disponible avant même le premier message. Comme le profil est séparé, d’autres équipes peuvent utiliser ce plugin sans avoir à le forkner.

    Flux de travail

    Le processus est codé en tant que compétence que l’agent invoque à la demande de l’utilisateur. Il est déclenché par des phrases telles que « corriger le bug X » ou « développer la fonctionnalité Y », ou explicitement via une commande /dbt-spec-driven:spec-driven dans Cortex Code. Il dirige l’exécution en fonction de l’intention (fonctionnalité, bug, refonte, revue indépendante ou documentation indépendante) et orchestre les phases nécessaires.

    Une décision de conception est particulièrement importante : la compétence ne réénonce jamais les règles. Elle renvoie plutôt vers AGENTS.md. Ce choix a résolu la plupart des problèmes liés au contexte initial, car aucune copie redondante d’une règle ne peut devenir désynchronisée en deux endroits différents.

    Sous-agents

    Cinq tâches consomment tellement de contexte que leur exécution dans le thread principal empêcherait d’effectuer le travail réel : discovery, test-author, output-validator, peer-reviewer et ci-interpreter. Chacune d’elles démarre dans son propre contexte, effectue une seule opération puis renvoie un rapport structuré ne contenant que les informations essentielles.

    L’idée fondamentale est que le contexte représente un budget limité et non un espace de travail infini. Prenons l’exemple de la découverte : elle peut nécessiter la lecture d’une dizaine de fichiers de modèle ainsi que l’analyse de leur filiation. Si cette opération a lieu dans le thread principal, la moitié du budget est déjà utilisée avant même le début de l’implémentation, pour des fichiers dont personne n’a encore besoin. La découverte convient également bien à un modèle de petite taille et peu coûteux, car la lecture et la synthèse exigent moins de capacités de raisonnement.

    Hooks

    Le fichier hooks/hooks.json déclenche trois fonctions d’ancrage sans nécessiter de coopération de la part des agents. L’une charge AGENTS.md au démarrage de la session. Une autre émet une alerte avant la compression du contexte, afin qu’aucun élément important ne disparaisse silencieusement, ce qui était précisément le problème de la première version. La dernière ajoute une note de session à la fin.

    Chaque fonction d’ancrage est fournie sous forme de variantes correspondant à Bash et PowerShell. Cortex exécute celle qui correspond au système d’exploitation, tandis que l’autre échoue silencieusement. Une équipe utilisant des systèmes d’exploitation différents n’a pas besoin de configuration par utilisateur.

    Connexion MCP à Jira

    Tout cela devient inutile si « envoyer la spécification vers le ticket » signifie que quelqu’un doit copier manuellement du texte entre un terminal et Jira. Deux serveurs MCP relient alors le flux de travail.

    Le Atlassian MCP est indispensable. Le sous-agent discovery l’utilise pour lire le ticket lors de l’ouverture d’une session, et la phase de spécification l’utilise pour publier des exigences numérotées sur ce même ticket. La spécification se trouve donc à côté du travail, et non dans un historique de chat qui disparaît.

    Le Notion MCP joue pour l’instant un rôle plus limité. Il est utilisé lorsque quelque chose mérite d’être documenté dans un endroit plus durable qu’une description de PR ou le répertoire de code, comme un flux bout en bout. En général, c’est le MCP qui permet aux règles, aux workflows et aux sous-agents d’accéder à n’importe quel élément en dehors du répertoire de code. Aujourd’hui, il s’agit d’un ticket, mais demain ce pourrait être une plateforme BI ou un canal Teams.

    Le tableau d’ensemble

    L’utilisateur pose une question, les chemins liés aux compétences et les travailleurs s’exécutent en arrière-plan. Chaque travailleur renvoie un rapport sans déposer ses fichiers dans le thread principal. Les hooks et MCP entourent l’ensemble sans s’y intégrer : ils chargent les règles, avertissent avant la compression et transmettent les données à Jira.

    Qu’est-ce qui a été amélioré

    • Le thread principal reste concentré sur les décisions et n’est pas alourdi par des dizaines de fichiers contenant des résultats de recherche.
    • Les règles ne s’éloignent plus, car il n’existe qu’une seule copie d’elles.
    • La compression en cours de session ne peut rien perdre sans avertissement préalable.

    Cette leçon s’applique bien au-delà de dbt. Toute personne utilisant un agent IA sur un répertoire réel aura probablement une version du principe « un seul fichier pour tout », et cela entraîne généralement les mêmes problèmes : plus la session dure, plus les instructions initiales sont écrasées.