Bucla în șase faze

La finalul capitolului poți trece un feature prin Research, Plan, Execute și Ship și știi care gate-uri sunt ale tale.

TL;DR

• Șase faze: Research, Plan, Execute, Review, Verify, Ship. Fiecare produce un artefact pe care îl poți citi și fiecare se termină la un gate.
• Planul e gate-ul unde contează cel mai mult un om. Câteva minute de citit planul te scutesc de o după-amiază de dat înapoi în Execute.
• Ship e un pull request obișnuit, cu dovezile atașate. Nu există o bandă specială pentru AI.

Ce este bucla în șase faze?¶

Fiecare fază produce un artefact și se termină la un gate.

Cele șase faze sunt Research, Plan, Execute, Review, Verify și Ship. Fiecare fază e un skill - un set împachetat de instrucțiuni pe care agentul îl încarcă atunci când faza e activă - cu un input clar, un output clar și un hand-off clar către faza următoare. Superpowers e o implementare; Spec Kit de la GitHub, framework-urile BMAD și colecțiile de skill-uri construite de echipe se sprijină pe aceeași buclă.

Bucla se sprijină pe un rezultat așteptat bine definit. Agentul poate construi aproape orice îi descrii, dar nu poate ști la care lucru te-ai referit. Research scoate la suprafață ce nu e încă hotărât, tu tranșezi, planul transformă rezultatul stabilit în verificări, iar Verify măsoară ce s-a construit față de el. Sari peste asta și „gata” e orice a decis agentul.

Feature-ul

Iată un feature urmărit prin toate fazele. E mic: adaugă un câmp priority pe recordul Wire, într-un serviciu bancar reglementat.

Priority e una dintre valorile low / normal / high / urgent, are default normal, iar flag-ul urgent declanșează un queue separat de compliance review.

Research

Research produce o notă, nu cod - iar întrebările deschise le tranșezi tu.

I-am cerut agentului să citească codebase-ul și să scrie o notă de research. A numit patru fișiere pe care nu le-aș fi găsit nici într-o oră de grep:

• recordul Wire în sine
• directorul de migrații
• serviciul queue-ului de compliance review
• emitter-ul de audit log

A ridicat și o întrebare deschisă: priority să fie enum sau text liber? Spec-ul reglementatorului folosește text liber în unele documente și enum în altele. Am ales enum. Alegerea asta nu era un detaliu - definea ținta față de care fazele de mai târziu aveau să verifice modificarea.

O notă de research are două până la patru pagini și cuprinde:

• fișierele care vor fi atinse
• convențiile pe care le urmează acele fișiere
• testele existente care acoperă zona
• concepte înrudite din alte părți ale codebase-ului
• întrebările deschise, acolo unde trebuie să decidă un om

Research e faza peste care echipele sar cel mai des, pentru că nu produce cod. Din experiența mea, e și faza cu cel mai mare levier: o notă proastă garantează un plan prost, iar una bună ancorează planul în codul real, nu în prima ipoteză a agentului.

Dacă task-ul e în afara domeniului tău, începe cu un blind spot pass: cere-i agentului să te ajute să-ți găsești unknown unknowns și spune-i pe față ce nu știi. Își calibrează răspunsul după expertiza pe care o deduce din vocabularul tău, așa că o fluență de fațadă îi ține presupunerile ascunse.

Pune nota în commit, alături de modificare. Șase luni mai târziu, când cineva se întreabă de ce e structurat codul așa, răspunsul e în repository.

Plan

Planul e gate-ul unde contezi cel mai mult.

Agentul a transformat nota într-un plan de șase task-uri:

1. Adaugă coloana în baza de date, cu default.
2. Actualizează clasa recordului Wire.
3. Actualizează serviciul wire-builder.
4. Actualizează contractul de API.
5. Actualizează logica de rutare pe compliance ca să citească noul câmp.
6. Actualizează emitter-ul de audit log.

Fiecare task atingea un fișier sau o pereche de fișiere. Task-ul cinci depindea de schimbarea de contract din task-ul patru; ordinea era corectă, iar agentul marcase dependența. Aprobat.

Un plan pe care îl poți aproba are trei proprietăți:

• Fiecare task numește fișierul, modificarea și verificarea care dovedește că a funcționat. Fiecare e dimensionat la două-cinci minute - destul de mic încât un eșec să fie recuperabil.
• Numește testele de adăugat sau de actualizat. Un plan fără teste e incomplet și se trimite înapoi.
• Spune ce înseamnă „gata” pentru întreaga modificare, nu doar per task. Ăsta e rezultatul pe care îl va verifica Verify.

Apoi îl citești tu. Respingi task-urile prea vagi, prea mari sau prost ordonate. Adaugi ce a ratat planul, scoți ce iese din scop. Abia apoi începe Execute.

Review-ul de plan ia câteva minute. Te scutește de o după-amiază întreagă atunci când planul era greșit și ai fi aflat abia în Execute - de unde e mult mai greu de dat înapoi.

Execute

Un subagent per task, un singur scriitor per fișier.

Șase subagenți au rulat în paralel, câte unul per task, fiecare constrâns la fișierul lui. S-au întors în mai puțin de trei minute. Cinci task-uri au avut teste care treceau din prima.

Al șaselea (emitter-ul de audit log) avea și el un test care trecea, dar testul era greșit: verifica vechiul format de log. Verde - și greșit. Capitolul 5 arată cum a fost prins.

Fiecare subagent lucrează în propriul context izolat: citește doar ce are nevoie, face modificarea, rulează verificarea din plan și raportează înapoi. Raționamentul confuz din task-ul unu nu poluează task-ul patru.

Izolarea nu e o soluție-minune. Regulile care o țin să funcționeze:

• Împarte doar când task-urile sunt independente pe fișier sau pe modul. Șase subagenți care editează fiecare câte un fișier - sigur. Șase care editează același feature, pe fișiere care se suprapun, sunt rețeta unor conflicte scumpe, care mănâncă exact câștigul de viteză pentru care ai paralelizat.
• Mai puțini înseamnă de obicei mai repede. Trei subagenți bine delimitați termină mai repede decât opt care se calcă pe picioare.
• Citește hand-off-urile orchestratorului cu scepticism. Orchestratorul tot ține câte un rezumat al fiecărui task, iar un rezumat imprecis al task-ului unu îl poate face pe task-ul patru să-l contrazică. Am văzut cu ochii mei șase subagenți producând editări reciproc inconsistente exact din motivul ăsta.
• Ține un fișier de note de implementare. Fiecare deviere de la plan și de ce, fiecare edge case pe care planul nu l-a menționat, fiecare decizie luată de un subagent acolo unde planul a lăsat-o deschisă. Consemnate în momentul în care se întâmplă, nu comprimate mai târziu într-un mesaj de hand-off.

Când un task eșuează, orchestratorul reîncearcă, ocolește eșecul sau se oprește și te întreabă. Cele mai multe eșecuri sunt recuperabile la a doua încercare. Un eșec blocant înseamnă că planul trebuie revizuit, iar bucla se întoarce la Plan.

Review și Verify

Review verifică diff-ul față de spec; Verify verifică comportamentul față de rezultatul așteptat.

La feature-ul wire, Review a prins testul de audit log și o migrație fără direcția de down, iar Verify a rulat suita completă plus un smoke test pe staging. Capitolul 5 se ocupă de ambele faze: cum citești un diff scris de agent și de ce o suită verde scrisă de agent e un indiciu, nu o dovadă.

Ship

Ship e un pull request obișnuit. Nu există o bandă specială pentru AI.

Agentul face commit cu un mesaj structurat, dă push pe branch și deschide un pull request a cărui descriere spune ce s-a schimbat, de ce, cum s-a verificat, ce riscuri rămân și cine e etichetat la review.

La feature-ul wire, PR-ul a venit cu nota de research, planul, rapoartele per task, ambele review-uri și dovezile din teste atașate. Un reviewer senior a petrecut unsprezece minute pe el și a pus o singură întrebare: ar trebui ca flag-ul urgent să fie vizibil în dashboard-ul de metrici? Nu mă gândisem la asta. Aprobat, merged.

PR-ul ăsta e exact artefactul pe care echipa știe deja să-l revizuiască. Agentul nu îți înlocuiește procesul de livrare; îl alimentează cu muncă mai bine formulată.

Cât costă în timp

Într-un workflow sănătos, gate-urile umane sunt limitatorul de ritm, nu agentul.

Pe un feature mic, bucla completă ia douăzeci-treizeci de minute de ceas; pe unul mediu, o oră; pe unul mare, câteva ore - muncă ce ar fi luat zile fără agent. Agentul rulează poate o treime până la jumătate din timpul ăsta; restul ești tu, citind nota, revizuind planul și aprobând diff-ul.

Feature-ul wire a luat nouăzeci de minute, de la „hai să adăugăm un câmp de prioritate” la cod în merge. Diferența o face contextul reglementat: o suită de 3.400 de teste, un smoke test pe staging și un diff de contract pentru reglementator. Mic ca scop nu înseamnă mic ca ceremonie.

Dacă un feature mic îți ia trei ore, gate-urile tale sunt supra-inginerite sau le faci într-un du-te-vino lent, nu într-o singură trecere concentrată. Agentul nu te salvează de propria cultură a ședințelor.

Când rulezi mai puțin din buclă

Sari peste o fază doar dacă poți numi ce îi face deja treaba.

Testul din Capitolul 3 îți spune când merită bucla în sine; în interiorul buclei se aplică aceeași contabilitate.

O echipă pe care am urmărit-o a lucrat cea mai mare parte a unui an cu ceea ce părea jumătate de buclă: Research-ul era un fir de comentarii, planul era trei bullet-uri în PR. A funcționat pentru că funcțiile se mutaseră în pereții echipei - o echipă mică și senioră, care își construise singură codebase-ul, o suită de CI strictă și o cultură de PR serioasă. Cele șase faze sunt funcții care trebuie să se întâmple undeva. Dacă nu poți spune unde, faza rămâne.

Când se strică

• Gate-urile sunt cereri, nu ziduri. Instrucțiunile din skill cer „teste în plan”; o impunere strictă are nevoie de un hook PreToolUse specific proiectului (Capitolul 2).
• Subagenții paraleli pe fișiere care se suprapun produc editări inconsistente. Redelimitează pe fișier sau pe modul, sau rulează task-urile în secvență.
• Sesiunile lungi derivă. Agentul răspunde din nou la întrebări deja tranșate și uită constrângeri. Asta e contaminarea contextului, iar Capitolul 6 acoperă remediul.

De făcut luni

• [ ] Alege un task care trece testul din Capitolul 3 și cere-i agentului o notă de research înainte de orice cod.
• [ ] Tranșează în scris fiecare întrebare deschisă din notă.
• [ ] Citește planul: fiecare task numește un fișier, o modificare și o verificare; testele sunt listate; există o linie „Done când”. Obiectează o dată înainte să aprobi.
• [ ] Rulează Execute cu un subagent per fișier și un fișier de note de implementare.
• [ ] Livrează-l ca PR obișnuit, cu nota și planul atașate.
• [ ] Cronometrează fiecare fază. Notează care a mâncat cel mai mult timp de ceas și care a produs cea mai multă valoare. De multe ori, nu sunt aceleași.

Mai departe

• Template: Anexa B.3, checklist-ul buclei în șase faze.
• Deep dive: Anexa D, Capitolul 4 - când merită împărțirea în subagenți, fork pe workeri vs izolare pe revieweri și blocurile de prompt ale vendorilor pentru autonomie și scop.
• Surse: Anexa C.