Cum orchestrăm agenți AI de programare: ce am învățat construind Brigadier

La Syncra construim Brigadier (se deschide într-o filă nouă), o aplicație desktop local-first pentru sesiuni lungi de programare cu AI. E în dezvoltare, iar codul sursă e public pe GitHub.

Ideea e simplă. Vorbești cu un singur orchestrator. El planifică munca, împarte sarcinile între workeri, verifică ce primește înapoi și îți raportează. Workerii sunt agenții de programare deja instalați și autentificați pe mașina ta, pentru început Claude Code și Codex. Sub capotă există un daemon în Rust care rulează în continuare și după ce închizi fereastra, un shell desktop în Tauri și o interfață în React.

Brigadier nu e încă gata pentru uz general. Deciziile de design sunt însă destul de bine așezate ca să merite scrise, iar majoritatea se aplică oricui rulează mai mult de un agent odată.

1. Orchestratorul doar vorbește

Orchestratorul nu citește niciodată repository-ul, nu rulează comenzi și nu editează fișiere. Singurele lui unelte sunt cele pe care i le dă Brigadier: să delege o sarcină, să trimită un mesaj unui worker, să citească un raport, să-l întrebe pe utilizator, să propună un plan. Tot ce trebuie investigat merge la un worker, adesea un scout cu acces doar la citire.

E o chestiune de context. Un orchestrator care citește fișiere își umple contextul cu conținut de care nu va mai avea nevoie. Unul care schimbă doar mesaje, rapoarte și decizii rămâne destul de mic încât să țină în vedere tot planul unei sesiuni lungi. Asta ține și rolurile curate: agentul care decide ce e de făcut nu e cel care face, așa că n-are niciun interes să apere un anumit diff.

2. Workerii raportează într-un format fix

Workerii nu conversează cu orchestratorul. Ei trimit un raport structurat: un rezumat, modificările, deciziile luate, cum au verificat munca, întrebările deschise și referințe la artefacte. Raportul rămâne scurt. Constatările complete, logurile și documentele merg în artefacte pe care orchestratorul le poate deschide când are nevoie de ele.

Un format fix face rapoartele comparabile și face golurile vizibile. Un raport cu secțiunea de verificare goală spune ceva prin el însuși. Brigadier verifică rapoartele și mecanic. Un raport care numește un fișier inexistent, sau unul pe care workerul l-a lăsat într-un folder temporar, e trimis înapoi cu instrucțiuni în loc să fie acceptat.

3. Un git worktree pentru fiecare worker

Fiecare sarcină care scrie cod rulează în propriul git worktree, creat din cea mai recentă stare a branch-ului sesiunii. Workerii paraleli nu își pot suprascrie fișierele unii altora, iar un experiment eșuat se aruncă ștergând un folder. În paralel rulează doar munca pe fișiere separate.

Integrarea e strictă intenționat. Munca terminată ajunge în repo ca un commit făcut cu identitatea ta git. În checkout-ul tău, integrarea se face doar prin fast-forward. Dacă ai schimbat branch-ul, dacă branch-ul s-a mutat neașteptat sau dacă un fișier untracked ar fi suprascris, munca așteaptă în starea „ready to land” și nu se schimbă nimic. Modificările tale necomise nu sunt suprascrise niciodată.

Agenții scriu cod repede, dar nu prea le pasă unde ajunge, așa că unealta trebuie să fie cea atentă.

4. Review făcut de celălalt furnizor

Un model care își verifică propria muncă tinde să fie de acord cu sine. În Brigadier, munca e verificată de modelul altui furnizor: munca lui Claude de Codex, cea a lui Codex de Claude. Fiecare fază a unei sesiuni se încheie cu un verificator nou, care face el însuși acest review și verifică cu adevărat fiecare criteriu de finalizare.

„Cu adevărat” contează. Verificarea înseamnă type checks, lint, build-ul, suita de teste existentă și un smoke check la runtime, nu un model care spune că munca arată corect. Raportul final spune exact ce s-a verificat și cum, ca să știi ce a fost verificat și ce nu.

5. Predare în loc de compactare

Sesiunile lungi umplu contextul modelului. Soluția obișnuită e compactarea: unealta rezumă conversația pe loc și merge mai departe, pierzând tot ce a lăsat rezumatul pe dinafară.

Orchestratorul Brigadier nu compactează niciodată. Când contextul lui devine prea mare, scrie o notă de predare, iar o sesiune nouă preia lucrul pornind de la un briefing: nota, fiecare decizie luată în sesiune, tabla curentă de sarcini și ultimele mesaje, cuvânt cu cuvânt. Transcrierea completă rămâne pe disc, unde poate fi căutată. Tu vezi în continuare o singură conversație. Workerii fac la fel. Un worker care rulează de mult își predă sarcina unei sesiuni noi a aceluiași model, în același worktree, împreună cu specificația, un jurnal de progres și diff-ul curent.

În spatele acestui mecanism stă ceea ce numim Project Brain: o bază cu ce știe deja Brigadier despre un proiect, cum ar fi module, convenții și decizii anterioare, fiecare cu evidența sursei din care provine. O întrebare la care s-a răspuns o dată nu mai trebuie investigată din nou. Când fișierele din spatele unui răspuns se schimbă, răspunsul e marcat ca posibil depășit.

6. Acțiunile spre exterior rămân la oameni

Workerii nu fac niciodată push, nu publică, nu fac deploy și nu deschid pull requesturi. Când o sarcină are nevoie de unul dintre acești pași, workerul îl trece pe listă, iar tu îl pornești singur. Orchestratorul îți cere aprobarea înainte să cheltuiască bani, să folosească credențiale sau să distrugă ceva din afara muncii sesiunii.

În rest, cât de multe lucruri au nevoie de aprobarea ta decizi tu, pe trei niveluri. Ask for approval („cere aprobare”) înseamnă că aprobi fiecare plan și fiecare modificare, iar workerii rulează în sandbox-ul sistemului de operare. Approve for me („aprobă în locul meu”) îl lasă pe Brigadier să aprobe în numele tău în interiorul sandbox-ului și te întreabă doar lucrurile la care numai tu poți răspunde. Full access („acces complet”) rulează workerii ca pe propriul tău terminal, cu un avertisment vizibil cât timp e activ.

7. Nu lăsa gunoi în urmă

Agenții creează lucruri: worktree-uri, foldere temporare, fișiere de sesiune, servere de dezvoltare, browsere headless. După câteva zile de lucru cu agenți, o mașină se poate umple de orfani pe care nimeni nu-și amintește să-i fi pornit.

Brigadier ține un registru de curățenie. Înregistrează fiecare fișier, folder, proces și port creat de fiecare sesiune de agent și le șterge când sarcina se termină sau când sesiunea e arhivată ori ștearsă. La fiecare pornire rulează din nou o curățare, pentru cazul în care un crash a întrerupt-o pe cea anterioară. Șterge doar ce a înregistrat. Sesiunile de agent pornite de tine și fișierele tale nu sunt atinse niciodată.

8. Folosește uneltele pe care oamenii le au deja

Brigadier controlează uneltele de linie de comandă claude și codex exact așa cum sunt instalate pe mașina ta. Nu le citește niciodată credențialele. Nu există backend Brigadier, nici cont, nici telemetrie. Codul tău, conversațiile tale și ce află Brigadier despre proiectul tău rămân pe calculatorul tău.

Constrângerea asta a modelat mult din design. Brigadier nu se poate baza pe un server care să păstreze starea sau să recupereze o sesiune, așa că evidența e la daemon: fiecare conversație, sarcină și decizie stă în stocarea lui locală, iar orice sesiune de agent poate fi înlocuită.

Unde a ajuns

Brigadier e în dezvoltare. Codul sursă e public pe GitHub (se deschide într-o filă nouă), iar planul din repository descrie direcția: întâi macOS, apoi Windows și Linux.

Principiile depășesc o singură aplicație. Când construim funcții cu agenți în produsele clienților, aplicăm aceleași reguli: roluri înguste, rapoarte structurate, verificare pe care o poți confirma și oameni care decid tot ce iese de pe mașină.