Zasady, procesy pracy i podagenty: dzielenie pluginu agenta AI dla dbt
Dlaczego jeden duży plik z instrukcjami zawiodł, oraz jak AGENTS.md, umiejętność oparta na specyfikacji, oddzielone podagenty, hooki oraz Jira MCP przejęły po jednej zadaniu w procesie pracy dbt.
Źródła: Rules, Workflow, Sub-Agents: The Three Layers We Split Our AI Agent Into
Jeden plik z instrukcjami nie może zawierać zarówno zasad, procesu, jak i codziennej pracy, nie narażając przy tym żadnego z tych elementów na problemy. W ten sposób zachowywała się pierwsza wersja jednego z procesów roboczych agenta dbt, a powody jego podziału wiele mówią o tym, jak należy organizować instrukcje dla agentów AI.
Kilka informacji w tle. Agent sztucznej inteligencji, któremu zlecono napisanie modeli dbt, może zwrócić kod, który kompiluje się i przechodzi wszystkie testy, a mimo to generuje błędne wartości. Zamiast polegać na pamięci agenta, proces ten został przekształcony w siedem rygorystycznych kontrolerów umieszczonych bezpośrednio w repozytorium, a te kontrolery wykryły rzeczywiste błędy, które same testy by przeoczyły. Tutaj kluczową rolę odgrywa mechanizm utrzymujący te kontrolery w działaniu: zasady, procesy pracy, podagenty, hooki oraz integracja z Jira. Wtyczka składa się z trzech warstw: zasad działających stale, procesu uruchamianego przez użytkownika oraz izolowanych podagentów przeznaczonych do zadań wymagających większych zasobów, a także hooki zapewniających spójność sesji oraz mechanizmu MCP umożliwiającego dostęp poza repozytorium. Żadna z części nie powtarza zadań innej.
Najpierw słownictwo
- Agent. System AI, który może otwierać pliki, wykonywać polecenia i samodzielnie realizować kilka kroków, dzięki czemu robi coś więcej niż tylko odpowiada na pytania.
- Plik z zasadami (
AGENTS.md). Stałe zasady, które agent ładuje automatycznie przy rozpoczęciu sesji. Jest to otwarty standard, który działa w różnych narzędziach i nie jest związany z jednym dostawcą. Można to porównać do podręcznika pracowniczego, który wszyscy powinni już znać. - Umiejętność (przepływ pracy). Instrukcje ładowane tylko wtedy, gdy pojawia się konkretny rodzaj zadania, podobnie jak przepis, który jest wyjmowany, gdy zamawia się określone danie.
- Podagent. Odrębna kopia agenta uruchamiana do wykonania jednego zadania w swoim prywatnym kontekście, która po zakończeniu pracy zwraca podsumowanie.
Co poszło nie tak na początku
Najwcześniejszy model pracy oparty na specyfikacji nie zawierał większości z tych elementów. Był to jeden plik markdown w korzeniu repozytorium, który zawierał zasady i proces oraz próbował kierować agentem krok po kroku. Nie było podagentów, hooków ani sztywnych blokad – tylko zalecona sekwencja działań.
Przez jakiś czas to działało. Gdy jednak sesja się wydłużała, zasady znajdujące się na początku pliku traciły znaczenie w aktywnym kontekście mniej więcej przy trzecim kroku implementacji, a agent zaczynał improwizować, nie informując o tym. Proces odkrywania, specyfikacji i implementacji odbywał się w jednym oknie, więc najstarsze instrukcje były pierwszymi ofiarami.
Zespoły w innych magazynach napotykają ten sam problem. Jeden z rozwiązań stosowanych w praktyce, opracowany przez bardziej zaawansowany zespół, oddzielał zasady, procesy pracy i ich wykonywanie, a także wykorzystywał specjalne elementy sesji, aby kompresja kontekstu nie mogła po cichu usunąć instrukcji w trakcie zadania. Wniosek brzmiał, że należy przestać traktować „instrukcje agenta” jako jedną całość – istnieją trzy takie zestawy, z których każdy ma inny okres obowiązywania i inne zadanie.
Trzy warstwy, po jednym właścicielu na każdą
- Warstwa pierwsza – stałe zasady:
AGENTS.md, obecne przez cały czas - Warstwa druga, proces: umiejętność
oparta na specyfikacji, rozpoczynana przez użytkownika - Warstwa trzecia, złożone kroki: podagenty, tworzone w razie potrzeby
Reguły
Plik z regułami zawiera obowiązkowe reguły inżynieryjne dotyczące blokowania, a także Profil Projektu, który rejestruje ustawienia każdego zespołu: zasady nazywania, metody realizacji, podstawową gałąź, system CI i tak dalej. Hook ładuje ten plik na początku każdej sesji, co eliminuje konieczność, by agent pamiętał o jego sprawdzeniu. Plik jest dostępny w kontekście przed pierwszą wiadomością. Ponieważ profil jest oddzielny, inne zespoły mogą używać tego pluginu bez konieczności tworzenia forku.
Przepływ pracy
Proces jest zakodowany jako umiejętność, którą agent wykorzystuje na żądanie użytkownika. Uruchamia się przy frazach takich jak „napraw błąd X” lub „stwórz funkcję Y”, albo wyraźnie poprzez polecenie /dbt-spec-driven:spec-driven w Cortex Code. Kieruje działaniem według intencji (funkcja, błąd, refaktoryzacja, niezależna ocena lub niezależne dokumenty) i koordynuje poszczególne etapy.
Najważniejszą decyzją projektową jest to, że umiejętność nigdy nie powtarza zasad – odwołuje się do pliku AGENTS.md. Ta decyzja rozwiązała większość problemów związanych z oryginalnym kontekstem, ponieważ żadne duplikaty zasad nie mogą się rozbiec w dwóch różnych miejscach.
Podagenty
Pięć zadań wymaga tak dużo zasobów kontekstowych, że ich wykonywanie w głównej wątku ograniczyłoby możliwości realizacji prawdziwej pracy: discovery, test-author, output-validator, peer-reviewer oraz ci-interpreter. Każde z nich uruchamia się w własnym kontekście, wykonuje jedno zadanie i zwraca ustrukturyzowany raport zawierający tylko to, co istotne.
Podstawowa zasada polega na tym, że zasoby kontekstowe są ograniczonym budżetem, a nie nieskończoną przestrzenią do pracy. Weźmy na przykład proces odkrywania: może on obejmować czytanie kilkunastu plików modeli oraz analizę ich powiązań. Jeśli zostanie on przeprowadzony w głównej wątku, połowa budżetu zostanie wykorzystana jeszcze przed rozpoczęciem implementacji na plikach, których nikt wtedy nie potrzebuje. Proces odkrywania nadaje się również dobrze do małych, tanich modeli, ponieważ czytanie i podsumowywanie wymagają mniej zasobów obliczeniowych.
Hooks
Plik hooks/hooks.json uruchamia trzy haczyki, które nie wymagają współpracy żadnego agenta. Jeden ładuje plik AGENTS.md na początku sesji. Drugi ostrzega przed skompresowaniem kontekstu, dzięki czemu nic ważnego nie znika bez śladu, co było dokładnie problemem pierwszej wersji. Trzeci dodaje notatkę o sesji po jej zakończeniu.
Każdy haczyk dostępny jest w parach wersji dla bash i PowerShell. Cortex uruchamia tę wersję, która pasuje do systemu operacyjnego, a druga działa bez efektu. Zespół używający różnych systemów operacyjnych nie potrzebuje konfiguracji indywidualnej dla każdego użytkownika.
Łączenie MCP z Jira
Wszystko to przestaje działać skutecznie, jeśli „przesłanie specyfikacji z powrotem do zlecenia” oznacza ręczne kopiowanie tekstu pomiędzy terminalami a Jira. Dwa serwery MCP łączą ten proces pracy.
Atlassian MCP jest niezbędny. Podagent discovery wykorzystuje go do odczytywania zgłoszenia przy otwarciu sesji, a faza Specify używa go do dodawania numerowanych wymagań z powrotem do tego zgłoszenia. Specyfikacja znajduje się więc obok pracy, a nie w historii czatu, która znika.
Notion MCP odgrywa obecnie mniejszą rolę. Jest używany wtedy, gdy coś wymaga dokumentacji w miejscu trwalszym niż opis PR lub repozytorium, na przykład pełny proces pracy. Ogólnie rzecz biorąc, MCP umożliwia regułom, procesom pracy oraz podagentom interakcję z dowolnym elementem poza repozytorium. Dziś może to być zgłoszenie, a jutro platforma BI lub kanał w Teams.
Cały obraz
Użytkownik zadaje pytanie, a ścieżki umiejętności oraz pracownicy przechodzą na bok. Każdy pracownik zwraca raport i nie zapisuje swoich plików do głównego wątku. Hooki i MCP otaczają strukturę danych, nie znajdując się w jej wnętrzu: ładują reguły, ostrzegają przed kompresją i przekazują dane do Jira.
Co się poprawiło
- Główny wątek pozostaje skupiony na podejmowaniu decyzji i nie jest obciążony wynikami analizy dziesiątek plików.
- Reguły przestają się zmieniać, ponieważ istnieje tylko jedna ich kopia.
- Kompresja w trakcie sesji nie może nic stracić bez uprzedniego ostrzeżenia.
Uczta ta ma zastosowanie nie tylko w dbt. Każdy, kto używa agenta AI do pracy z rzeczywistym repozytorium, prawdopodobnie ma wersję „jednego pliku, który robi wszystko”, a ta zazwyczaj działa w ten sam sposób: im dłuższa sesja, tym bardziej wcześniejsze instrukcje są wypierane.