Întâi harta: review-ul de arhitectură

La finalul capitolului poți produce o hartă corectată a unui codebase pe care nu și-l mai amintește nimeni și poți folosi rularea ca diagnostic inițial pentru următorul pas.

TL;DR

• Folosește o investigație bine delimitată ca să schițezi docs/architecture.md, apoi verifică harta față de cod și realitatea de business.
• În cazul de mai jos, agentul a lucrat 18 minute, iar corecția expertului a luat circa 45. Acuratețea și timpul de review depind de acces, scop și cunoașterea domeniului.
• Aceeași rulare e un diagnostic inițial. O hartă incoerentă cere să oprești schimbările autonome și să investighezi modelul, accesul, contextul și codebase-ul (Capitolul 8).

Workflow-ul

Pune agentul să citească întâi codul, apoi corectează ce a scris și dă commit rezultatului.

Multe echipe dețin un codebase care se potrivește unei singure descrieri: autorul a plecat, README-ul descrie un build care nu mai merge, codul aduce bani și nimeni nu vrea să-l atingă. Agentul poate scurta prima investigație, dar o hartă nu înseamnă că ai devenit productiv sau că ai înțeles business-ul. Cazul de mai jos a cerut minute de lucru de agent și review de la un expert de domeniu; alte repository-uri cer mai mult.

Promptul cere nouă secțiuni, de la scop și model de date până la riscuri și necunoscute, cu citări fișier:linie peste tot; textul complet e în Anexa B.1. Alege secțiunile și profunzimea de care are nevoie investigația. Un document poate părea complet și totuși să interpreteze greșit partea esențială de business. Dacă codebase-ul depășește un singur context window, investigațiile independente pe module pot justifica subagenți, iar orchestratorul asamblează bucățile și verifică granițele comune.

Cazul

Agentul n-a decis că rewrite-ul nu era necesar. A dat experților de domeniu suficientă structură ca să decidă mai repede.

O echipă de banking deținea un sistem de onboarding pentru clienți: cam șaizeci de mii de linii de Java, scrise între 2018 și 2024 de o distribuție rotativă de contractori. Echipa fusese asamblată în 2024 din trei achiziții și nimeni nu fusese de față la build-ul original. README-ul descria o arhitectură din 2020, iar documentația enumera doi dintre cei trei pași ai build-ului. Echipa lua în calcul un rewrite complet, estimat la optsprezece luni, pentru că „nimeni nu îl înțelege suficient de bine ca să-l întrețină cu încredere.”

Am cerut cincisprezece minute și un terminal. Am lipit promptul de review cu două adăugiri: domeniul (onboarding de clienți, banking reglementat) și cererea de a marca tot ce arată a fi sensibil din punctul de vedere al conformității. Optsprezece minute mai târziu aveam un document de treisprezece pagini, greșit în trei locuri:

• A numit serviciul de deduplicare „serviciu de căutare”, pentru că implementarea folosea infrastructura de search. Scopul lui de business era să prevină crearea de dubluri ale înregistrărilor de clienți.
• A descris cu deplină încredere, în detaliu, un job programat. La o privire mai atentă, era cod comentat, nerulat în producție de trei ani.
• A ratat faptul că o dependență third-party era deprecated și avea un security advisory. Agentul nu avea acces la baza de date de advisories, așa că am adăugat eu informația.

Documentul corectat a intrat în repository, iar echipa a ales muncă țintită în locul propunerii de rewrite amplu. Au înlocuit două module în trimestrul următor, inclusiv dependența deprecated. Propunerea de optsprezece luni și înlocuirea de trei luni descriu calendare, nu totaluri comparabile de muncă. Fără ipotezele inițiale despre numărul de oameni și un scenariu contrafactual credibil, relatarea nu stabilește om-luni economisite și nu izolează efectul agentului de judecata experților.

Corectează harta

Harta agentului e o ciornă, iar estimarea de 45 de minute presupune un reviewer care cunoaște domeniul.

Nu mai văzusem niciodată codebase-ul ăla, dar construisem sisteme de onboarding și înainte, așa că știam cum arată de obicei un serviciu de deduplicare și un path de conformitate în banking reglementat. Greșelile agentului mi-au sărit în ochi. Un reviewer nou și pe codebase, și pe domeniu n-are un asemenea reper: identificările greșite continuă să pară plauzibile, nu poate spune pe care să le semnaleze, iar corecția durează ore, nu 45 de minute. Workflow-ul funcționează în continuare; partea umană costă mai mult.

Verifică harta față de cinci lucruri:

• Scopul modulelor, raportat la realitatea de business, nu la infrastructura de implementare.
• Orice e descris ca activ, dar ar putea fi mort sau comentat.
• Faptele despre dependențe și advisories pe care agentul nu le vede.
• Path-urile sensibile din punctul de vedere al conformității.
• Fiecare ambiguitate semnalată chiar de agent.

Dă-i commit

Documentul corectat e punctul de intrare pentru orice lucrare ulterioară.

Pune-l la docs/architecture.md. Membrii noi ai echipei îl citesc primii, inginerii seniori îl consultă înainte să atingă o parte nefamiliară, iar agentul îl deschide la cerere, când un task atinge un modul pe care nu l-a văzut, în loc să re-derive arhitectura. AGENTS.md conține o trimitere către fișier, nu structura codebase-ului (Capitolul 6).

Șterge pe bază de dovezi¶

O eliminare e o afirmație; dovedește-o înainte ca agentul să șteargă ceva.

Harta face și curățenia mai sigură, adică exact munca pe care o vinde Slopfix din Prolog. Pentru fiecare candidat, strânge referințele statice, folosirea la runtime (log-uri, metrici, feature flags, job-uri programate), orice fallback păstrat pentru incidente și confirmarea owner-ului. Apoi deschide câte un pull request mic pentru fiecare eliminare, cu dovezile atașate, iar review-ul îl face echipa care deține codul. Relatarea OpenAI despre propria curățenie făcută cu modelele GPT-6, peste 1.400 de pull request-uri acceptate la merge care au șters mai mult de 800.000 de linii, numește capcanele: reflection care păcălește analiza statică, o rută nefolosită păstrată ca să atenueze incidente viitoare și propuneri care au adăugat mai multă complexitate decât au eliminat.

Review-ul ca diagnostic

O hartă incoerentă e un motiv să oprești schimbările autonome și să investighezi cauza. Rularea e un diagnostic inițial, nu un verdict despre codebase.

• Hartă coerentă, corecție rezonabilă: o informație utilă pentru următorul task bine delimitat. Nu dovedește înțelegerea comportamentului sau pregătirea pentru producție.
• Output incoerent: verifică accesul lipsă, contextul incomplet, aria investigației și potrivirea modelului înainte să pui eșecul pe seama codului încâlcit. Dacă echipa tot nu poate evalua rezultatul, păstrează munca respectivă condusă de oameni și folosește grila din Capitolul 8.

Alocă un timp limitat primei investigații, apoi decide dacă încă o trecere ar putea lămuri o necunoscută concretă. Kill signals din Capitolul 8 sunt grila sistematică; o singură hartă nu o înlocuiește.

Când se strică

• Output nerevizuit. Citările și structura îngrijită nu transformă o ciornă în documentație corectă.
• Un reviewer fără cunoaștere de domeniu nu poate spune pe care dintre greșelile plauzibile să le semnaleze. Bugetează ore.
• Harta se învechește. Rerulează review-ul ori de câte ori codebase-ul se schimbă substanțial.

De făcut luni

• [ ] Pe un codebase slab înțeles, alege părțile relevante din Anexa B.1, numește domeniul și alocă un timp limitat primei treceri.
• [ ] Corectează output-ul după cele cinci verificări de mai sus.
• [ ] Salvează-l ca docs/architecture.md, dă-i commit și adaugă în AGENTS.md o singură linie de trimitere. Nu lipi structura în fișier.
• [ ] Evaluează dovezile: alege următorul task bine delimitat sau investighează de ce a eșuat harta. Folosește Capitolul 8 înainte să extinzi scopul.
• [ ] Notează timpul de investigație și de corecție înainte să repeți exercițiul în altă parte.

Mai departe

• Template: Anexa B.1, promptul de architecture review.
• Deep dive: Anexa D, Capitolul 7 - de ce căutarea simplă în cod bate un index vectorial aici și Understand Anything, alternativa vizuală.
• Surse: Anexa C.