Regeln, Abläufe und Sub-Agenten: Aufteilung eines AI-Agent-Plugins für dbt
Warum eine große Anweisungsdatei fehlschlug und wie AGENTS.md, eine spezifikationsgesteuerte Fähigkeit, Sub-Agenten, Hooks sowie Jira MCP jeweils eine Aufgabe in einem dbt-Ablauf übernahmen.
Quellen: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
Eine einzige Anweisungsdatei kann weder ein Regelwerk noch einen Prozess sowie die tägliche Arbeit enthalten, ohne bei allen drei Aspekten Fehler aufzutreten. So verhielt sich die erste Version eines dbt-Agent-Arbeitsablaufs, und die Gründe für die Aufteilung sagen viel darüber aus, wie Anweisungen für KI-Agenten organisiert werden sollten.
Ein wenig Kontext: Ein KI-Agent, dem die Erstellung von dbt-Modellen übertragen wurde, kann Code zurückgeben, der zwar kompiliert wird, alle Tests besteht und dennoch falsche Werte liefert. Anstatt dem Gedächtnis des Agents zu vertrauen, wurde der Prozess in sieben strenge Kontrollpunkte umgewandelt, die direkt im Repository selbst gespeichert sind. Diese Kontrollpunkte haben seitdem echte Fehler aufgedeckt, die allein durch Tests übersehen worden wären. Der Fokus liegt hier auf dem Mechanismus, der diese Kontrollpunkte aufrechterhält: Regeln, Workflow, Unteragenten, Hooks sowie die Integration mit Jira. Das Plugin verfügt über drei Ebenen – nämlich ständig aktive Regeln, einen vom Benutzer gestarteten Workflow sowie isolierte Unteragenten für die aufwändigen Schritte. Zudem gibt es Hooks, die eine konsistente Sitzung gewährleisten, sowie MCP zur Kommunikation außerhalb des Repositoriums. Kein Bestandteil übernimmt die Aufgabe eines anderen.
Zuerst das Vokabular
- Agent. Ein KI-System, das Dateien öffnen, Befehle ausführen und mehrere Schritte unabhängig voneinander durchführen kann, sodass es mehr tut als nur Fragen beantworten.
- Regeldatei (
AGENTS.md). Standardeinstellungen, die der Agent automatisch lädt, wenn eine Sitzung beginnt. Es handelt sich um einen offenen Standard, der in verschiedenen Tools funktioniert und nicht an einen bestimmten Anbieter gebunden ist. Man kann sich darunter ein Mitarbeiterhandbuch vorstellen, das von allen bereits bekannt sein sollte. - Fähigkeit (Workflow). Anweisungen, die nur dann geladen werden, wenn eine bestimmte Art von Aufgabe anfällt – ähnlich wie ein Rezept, das hervorgeholt wird, wenn ein bestimmtes Gericht bestellt wird.
- Unteragent. Eine separate Kopie des Agents, die für eine bestimmte Aufgabe in ihrem eigenen privaten Kontext gestartet wird und nach Abschluss eine Zusammenfassung zurückgibt.
Was anfangs schiefging
Der früheste, auf Spezifikationen basierende Workflow entbehrte den meisten dieser Elemente. Es handelte sich um eine einzige Markdown-Datei im Wurzelverzeichnis des Repositoriums, die die Regeln sowie den Ablauf enthielt und versuchte, den Agenten Schritt für Schritt durch den Prozess zu führen. Es gab keine Unteragenten, Hooks oder feste Barrieren, nur eine vorgeschlagene Reihenfolge.
Eine Weile hielt das durch. Sobald eine Sitzung jedoch zu lang wurde, fielen die Regeln ganz oben im Dateiinhalt bereits bei etwa dem dritten Implementierungs Schritt aus dem aktiven Kontext heraus, und der Agent begann, ohne es zu erwähnen, improvisierend zu handeln. Entdeckung, Spezifikation und Implementierung teilten sich ein und dasselbe Fenster, wodurch die ältesten Anweisungen als Erste betroffen waren.
Auch Teams in anderen Lagern stoßen auf dasselbe Problem. Ein Muster, das in der Praxis bei einem weiter entwickelten Team beobachtet wurde, trennte Regeln, Workflow und Ausführung voneinander und nutzte Sitzungshooks, damit eine Komprimierung des Kontexts keine Anweisungen mitten in einer Aufgabe stillschweigend entfernen konnte. Die Erkenntnis daraus war, „die Anweisungen des Agents“ nicht länger als eine Einheit zu betrachten. Es gibt drei davon, jede mit einer anderen Lebensdauer und einer anderen Aufgabe.
Drei Ebenen, jeweils ein Verantwortlicher
- Ebene eins: die ständigen Regeln:
AGENTS.md, immer vorhanden - Schicht zwei, der Prozess: die vom Benutzer gestartete
spec-driven-Fähigkeit - Schicht drei, umfangreiche Schritte: Unter-Agenten, die bei Bedarf erstellt werden
Regeln
Die Regeldatei enthält die zwingend erforderlichen Engineering-Regeln sowie ein Projektprofil, das die Einstellungen jedes Teams festhält: Namenskonventionen, Materialisierungen, die Basis-Branch, das CI-System usw. Ein Hook lädt die Datei zu Beginn jeder Sitzung, wodurch keine Abhängigkeit davon entsteht, dass sich der Agent daran erinnern muss, nachzusehen. Sie steht bereits vor der ersten Nachricht im Kontext zur Verfügung. Da das Profil getrennt ist, können andere Teams den Plugin ohne Fork übernehmen.
Ablauf
Der Prozess ist als Fähigkeit kodiert, die der Agent auf Anfrage des Benutzers aufruft. Er wird durch Ausdrücke wie „Bug X beheben“ oder „Funktion Y entwickeln“ ausgelöst oder explizit über den Befehl /dbt-spec-driven:spec-driven in Cortex Code. Er leitet je nach Absicht (Funktion, Bug, Refactoring, eigenständige Überprüfung oder eigenständige Dokumentation) weiter und koordiniert die entsprechenden Phasen.
Eine Designentscheidung ist besonders wichtig: Die Fähigkeit wiederholt niemals die Regeln. Sie verweist stattdessen auf AGENTS.md. Diese Wahl löste den größten Teil des ursprünglichen Kontextproblems, da keine doppelten Kopien einer Regel an zwei Orten aus dem Einklang geraten.
Unteragenten
Fünf Aufgaben verbrauchen so viel Kontext, dass ihre Ausführung im Hauptthread die eigentliche Arbeit behindern würde: discovery, test-author, output-validator, peer-reviewer und ci-interpreter. Jede von ihnen startet in ihrem eigenen Kontext, erledigt eine einzige Aufgabe und gibt einen strukturierten Bericht mit nur den relevanten Informationen zurück.
Die zugrundeliegende Erkenntnis ist, dass Kontext ein begrenztes Budget und kein endloser Speicher ist. Nehmen wir discovery: Dabei kann es darum gehen, Dutzende von Modelldateien zu lesen und deren Abstammung nachzuvollziehen. Würde dies im Hauptthread stattfinden, würde bereits vor Beginn der Implementierung die Hälfte des Budgets für Dateien aufgebraucht, die zu diesem Zeitpunkt niemand benötigt. Discovery eignet sich außerdem gut für kleine, günstige Modelle, da das Lesen und Zusammenfassen weniger Rechenleistung erfordert.
Hooks
Die Datei hooks/hooks.json aktiviert drei Hooks, wobei keine Zusammenarbeit mehrerer Agenten erforderlich ist. Einer lädt AGENTS.md zu Beginn der Sitzung. Ein anderer warnt vor der Komprimierung des Kontexts, damit nichts Wichtiges leise verschwindet – was genau der Fehler der ersten Version war. Ein weiterer fügt beim Verlassen der Sitzung eine Notiz hinzu.
Jeder Hook wird als Paar aus bash- und PowerShell-Versionen bereitgestellt. Cortex verwendet die Variante, die zum Betriebssystem passt, während die andere Variante leise fehlschlägt. Ein Team, das unterschiedliche Betriebssysteme verwendet, benötigt keine benutzerbezogene Konfiguration.
MCP-Verbindung zu Jira
Alles das klappt nicht, wenn „die Spezifikation wieder in das Ticket einfügen“ bedeutet, dass jemand den Text manuell zwischen einer Terminalanzeige und Jira kopiert. Zwei MCP-Server verbinden den Workflow miteinander.
Der Atlassian MCP ist unverzichtbar. Der discovery-Sub-Agent verwendet ihn, um das Ticket beim Öffnen einer Sitzung zu lesen, und die Specify-Phase nutzt ihn, um nummerierte Anforderungen wieder in dieses Ticket einzuspeisen. Die Spezifikation befindet sich somit neben der Arbeit, nicht in einer Chat-Geschichte, die wieder verschwindet.
Der Notion MCP spielt derzeit eine kleinere Rolle. Er wird eingesetzt, wenn etwas eine Dokumentation an einem dauerhafteren Ort benötigt als in einer PR-Beschreibung oder im Repository – beispielsweise ein End-to-End-Flow. Im Allgemeinen ermöglicht MCP es, dass Regeln, Workflows und Sub-Agents auf alles außerhalb des Repositoriums zugreifen können. Heute ist das ein Ticket, morgen könnte es eine BI-Plattform oder ein Teams-Kanal sein.
Das Gesamtbild
Der Benutzer fragt, warum die Fähigkeitswege und Arbeiter zur Seite laufen. Jeder Arbeiter gibt einen Bericht zurück und lädt seine Dateien nicht in den Hauptthread. Hooks und MCP umschließen das Bild, ohne sich darin zu befinden: Sie laden Regeln, warnen vor der Komprimierung und erreichen Jira.
Was verbessert wurde
- Der Hauptthread konzentriert sich weiterhin auf Entscheidungen und wird nicht durch die Ausgabe von Dutzenden von Dateien belastet.
- Die Regeln verschwinden nicht mehr, da es genau eine Kopie gibt.
- Die Zwischensitzungskomprimierung kann ohne vorherige Warnung nichts verlieren.
Die allgemeine Erkenntnis gilt weit über dbt hinaus. Jeder, der einen KI-Agenten gegen ein echtes Repository einsetzt, wird wahrscheinlich eine Variante von „eine Datei macht alles“ haben, und diese neigt dazu, auf dieselbe Weise zu versagen: Je länger die Sitzung dauert, desto mehr werden die frühesten Anweisungen beiseitegedrängt.