Review-ul de arhitectură: documentare și diagnostic

În Capitolul 2 ți-am arătat cum am folosit un coding agent ca să inspectez codul sursă al altor doi coding agents, în paralel. Am numit ce am găsit acolo anatomia invariantă. Acum vreau să transform observația aceea într-un workflow pe care să-l poți aplica chiar săptămâna asta pe un codebase pe care echipa ta îl deține și abia și-l mai amintește.

Workflow-ul e simplu. Îndrepți agentul spre repository. Îi ceri să producă un review de arhitectură structurat. Salvezi output-ul ca artefact durabil. Folosești artefactul ca punct de intrare pentru orice lucrare ulterioară în acel codebase.

Mai toate echipele dețin cel puțin un codebase care se potrivește descrierii „abia și-l mai amintim”. Autorul original a plecat acum doi ani. Documentația e subțire și parțial greșită. README-ul descrie un proces de build care nu mai merge de la update-ul de dependențe din martie anul trecut. Codul rulează în producție și aduce bani. Nimeni nu vrea să-l atingă.

Înainte de agenți, să devii productiv într-un asemenea codebase dura săptămâni. Un senior engineer petrecea două-patru săptămâni citind sursa, punând întrebări, trasând fluxuri, scriind documentație internă. Înmulțește cu costul total al unui asemenea inginer și ajungi la sume de cinci cifre per codebase, per onboarding. Ori trei-patru ingineri per repository legacy de-a lungul vieții lui. Ori numărul de repository-uri legacy din organizația ta. Costul agregat e substanțial. Mai toate organizațiile îl înghit fără să-l măsoare.

Workflow-ul cu agenți coboară costul ăsta la zece-douăzeci de minute de timp de agent plus o oră de review uman. Agentul citește sursa, trasează fluxurile, identifică pattern-urile, produce documentația. Omul revizuiește, corectează, adaugă contextul pe care agentul l-a ratat, semnează. Artefactul intră în repository, versionat. Următoarea persoană care are de lucrat în codebase pornește de la artefact, nu de la zero.

E workflow-ul cu cel mai bun raport efort-câștig din tot manualul. Îl aplici o dată și investiția s-a întors.

Mai jos e promptul pe care îl folosesc, ușor editat. Al tău va arăta altfel; ăsta e ilustrativ. Promptul rămâne în engleză - așa îl folosesc în practică, și pe ăsta îl lipești ca atare.

Analyze the architecture of this codebase. Produce a structured architecture review document that covers:

1. Purpose. What does this service do? Who uses it? What business problem does it solve?
2. Top-level structure. Major modules, packages, or folders. One paragraph per major component explaining its role.
3. Data model. Primary entities, relationships, persistence. Cite specific files and line numbers.
4. Request flows. For the three most important external entry points (API endpoints, scheduled jobs, message consumers), trace the flow from entry to persistence. Cite files and lines at each step.
5. Cross-cutting concerns. Authentication, authorization, logging, error handling, configuration. How are they implemented and where do they live?
6. Dependencies. External services, databases, message brokers, third-party APIs. List with versions if discoverable.
7. Test posture. What is the test structure, what coverage exists, where are the gaps?
8. Build and deployment. How is this thing built and deployed? Cite the relevant configuration files.
9. Risks and unknowns. Code that looks fragile, areas where conventions are inconsistent, dependencies that may be deprecated, places where the codebase has accumulated patterns that suggest unresolved decisions.

Cite specific files and line numbers throughout. Where the codebase is ambiguous, say so explicitly. Where you encounter patterns the team should formalize as conventions, suggest the convention.

Promptul ăsta, lansat pe un serviciu Spring Boot de complexitate medie, produce un document de arhitectură de zece-cincisprezece pagini în mai puțin de cincisprezece minute. Documentul va fi corect cam în proporție de 70%. Restul de 30% e exact motivul pentru care review-ul uman e esențial - agentul va interpreta greșit unele pattern-uri, va rata context care trăiește în afara codebase-ului, uneori va descrie cu toată încrederea un code path scos din uz de mult. Reviewerul uman corectează toate astea. După review, documentul e solid.

Asta e varianta cu un singur agent și e suficientă pentru majoritatea serviciilor. Pe un codebase prea mare pentru un singur context window, același workflow se distribuie pe subagenți - câte unul per modul, fiecare întorcând un rezumat structurat, iar orchestratorul asamblează documentul din bucăți. E pattern-ul de analiză de arhitectură la scară din Capitolul 1, pus la treabă în producție.

Documentul corectat intră în repository. Prin convenție, îl pun la docs/architecture.md. Devine punctul de intrare pentru orice lucrare ulterioară. Membrii noi ai echipei îl citesc primii. Inginerii seniori îl consultă când modifică părți nefamiliare ale sistemului. Îl citește și agentul (îl referențiezi din AGENTS.md) când lucrează în codebase, astfel încât munca lui ulterioară e ancorată în review-ul de arhitectură, în loc să re-derive arhitectura de fiecare dată.

Workflow-ul de review de arhitectură are și o alternativă șlefuită, care merită menționată. Există un plugin numit Understand Anything care face ceva similar cu promptul de mai sus, dar cu un dashboard vizual ca output principal, în locul unui document markdown. Dashboard-ul redă codebase-ul ca un graf navigabil - vederea structurală (module, dependențe, ierarhia de fișiere) pe un tab, vederea de domeniu (concepte de business, entități, conexiuni între domenii) pe altul.

Vederea structurală e utilă pentru ingineri. Vederea de domeniu e utilă pentru manageri, pentru că prezintă codebase-ul în termeni de concepte de business, nu de căi de fișiere. Un manager care nu citește Java se poate uita la vederea de domeniu și poate vedea „aha, serviciul ăsta se ocupă de detecția fraudelor pe transferurile primite” fără să citească un rând de sursă.

Includ alternativa cu plugin de dragul completitudinii. Documentul markdown de arhitectură descris mai sus e suficient pentru majoritatea echipelor; dashboard-ul vizual e un upgrade real pentru echipele ai căror manageri sau oameni de produs au nevoie să interacționeze regulat cu structura codebase-ului. Alege după ce are nevoie echipa ta, nu după ce arată mai spectaculos.

Rulează workflow-ul de review de arhitectură întâi pe codebase-ul tău cel mai prost înțeles. Privește agentul cum produce în cincisprezece minute ce i-ar fi luat unui senior engineer o săptămână. Salvează artefactul. Referențiază-l din AGENTS.md. Treci la următorul codebase.

Asta e rețeta.

Același workflow e și un instrument de diagnostic. Aceleași cincisprezece minute de timp de agent îți spun dacă are sens, în primul rând, să adopți lucrul cu agenți pe codebase-ul respectiv.

Iată un review de arhitectură pe care l-am rulat anul trecut pentru o echipă de banking - anonimizat, dar fidel experienței.

Codebase-ul era 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 care îl deținea acum fusese asamblată în 2024 din trei achiziții diferite și niciunul dintre inginerii actuali nu fusese de față la build-ul original. Lead-ul tehnic original plecase cu doi ani în urmă. Exista un README care descria o arhitectură din 2020, doar vag asemănătoare cu codul curent. Build-ul avea trei pași, documentația enumera doi, al treilea era tribal knowledge.

Când am ajuns eu, echipa lua în calcul un rewrite complet. Estimarea era de optsprezece luni. Justificarea: „nimeni nu îl înțelege suficient de bine ca să-l întrețină cu încredere.” Ceea ce, sincer, era adevărat. Era însă și genul de justificare care duce frecvent la proiecte de rewrite ce durează de trei ori mai mult decât estimarea și produc sisteme cu toate problemele originalului, plus câteva noi.

Am cerut cincisprezece minute și un terminal. Am clonat repository-ul. Am deschis agentul. Am lipit promptul de review de arhitectură de mai devreme din acest capitol, cu două mici ajustări - am adăugat „this is a customer onboarding system in a regulated banking context”, ca să-i dau agentului domeniul, și i-am cerut explicit să marcheze tot ce arată a code path sensibil din punctul de vedere al conformității.

Optsprezece minute mai târziu, agentul produsese un document de arhitectură de treisprezece pagini. L-am citit. Nu era perfect, iar imperfecțiunile contează. Agentul identificase greșit un modul - numise serviciul de deduplicare „serviciu de căutare”, pentru că implementarea folosea infrastructura de search, dar scopul de business real era deduplicarea înregistrărilor de clienți, ca să nu se creeze dubluri. Am corectat. Agentul descrisese, tot cu deplină încredere, un „job programat” care, la o privire mai atentă, s-a dovedit a fi cod comentat, nerulat în producție de trei ani. Am corectat și asta. Agentul ratase faptul că una dintre dependențele third-party era deprecated și avea un security advisory; am adăugat eu informația, pentru că agentul nu avea acces la baza de date de advisories.

O notă despre timpul de corecție. Am petrecut cam patruzeci și cinci de minute corectând documentul ăla de treisprezece pagini. Cifra stă în picioare datorită unei condiții precise: aveam context. Nu context adânc pe acest codebase - nu-l văzusem niciodată -, ci context general pe domeniu. Construisem sisteme de onboarding de clienți și înainte. Știam cum arată de obicei un serviciu de deduplicare. Știam cum arată de obicei un path de conformitate în banking reglementat. Identificările greșite ale agentului mi-au sărit în ochi pentru că aveam un model mental cu care să le compar.

Dacă și reviewerul descoperă codebase-ul pentru prima oară - un coleg nou-angajat care n-a văzut în viața lui onboarding bancar, de exemplu -, bucla de corecție durează mai multe ore, nu patruzeci și cinci de minute. Reviewerul trebuie să citească fiecare afirmație a agentului, să se uite la codul de dedesubt și să decidă dacă afirmația e corectă, fără un reper de domeniu pe care să se sprijine. Identificările greșite ale agentului arată în continuare plauzibil; reviewerul nu poate spune pe care să le semnaleze. Ăsta e cel mai important avertisment practic legat de timpii workflow-ului de review de arhitectură: estimarea de patruzeci și cinci de minute de corecție presupune un reviewer cu cunoaștere de domeniu. Fără ea, workflow-ul funcționează în continuare, dar partea umană costă mai mult.

În cazul din banking, cunoașterea de domeniu o aveam. După vreo patruzeci și cinci de minute de corecturi, aveam un document de treisprezece pagini care descria fidel codebase-ul. Echipa l-a citit. Doi dintre ingineri mi-au spus, separat, că au învățat mai multe despre codebase din document decât din șase luni de lucru în el. Al treilea inginer a semnalat un gol în plus, pe care îl ratasem; l-am adăugat. Documentul a intrat în repository.

Echipa n-a mai făcut rewrite-ul. A folosit documentul de arhitectură ca să identifice cele două module care chiar aveau nevoie de înlocuire (dependența deprecated era unul dintre ele) și a înlocuit doar acele module în trimestrul următor. Restul codebase-ului devenise întreținabil, pentru că echipa putea citi documentul de arhitectură, găsi secțiunea relevantă și înțelege ce atinge înainte să atingă. Estimare de rewrite de optsprezece luni, redusă la o înlocuire țintită de trei luni, pe baza a cincisprezece minute de muncă de agent plus o oră de review uman. Nu agentul a decis că rewrite-ul nu era necesar. A produs suficientă structură încât experții de domeniu să poată lua decizia aia mai repede.

Cincisprezece minute de muncă de agent nu au înlocuit judecata de domeniu; au făcut-o mai ieftin de aplicat. Nu teoretic. Nu „în principiu”. „Am rulat exact workflow-ul ăsta pe exact codebase-ul ăsta, iar compania a economisit nouă om-luni de efort de rewrite pe care altfel le-ar fi cheltuit și le-ar fi regretat.”

Acum partea de diagnostic.

Workflow-ul de review de arhitectură e cel mai ieftin test posibil pentru întrebarea dacă lucrul cu agenți va funcționa pe un codebase dat. Dacă agentul poate produce un review de arhitectură coerent, cu un volum rezonabil de corecții umane, codebase-ul e într-o formă suficient de bună încât agentul să fie util și la lucrările următoare. Dacă agentul nu poate produce un review coerent - dacă codebase-ul e atât de încâlcit încât până și citirea lui produce un rezultat inutilizabil -, atunci ai aflat, la un cost foarte mic, că acest codebase e în zona roșie a disciplinei pe care urmează s-o introduc și că trebuie să repari codebase-ul înainte să încerci să folosești agentul pe el pentru modificări de producție.

Oricare dintre rezultate e valoros. Investiția e de cincisprezece minute plus o oră. Riscul e limitat. Câștigul, în cazuri ca acela din banking descris mai sus, înseamnă luni de muncă economisite.

Rulează workflow-ul săptămâna asta. Rulează-l pe cele trei-patru codebase-uri pe care echipa ta le înțelege cel mai prost. Output-ul agentului îți va spune multe despre care dintre ele sunt pregătite pentru restul manualului și care au nevoie întâi de investiție.

Asta e puntea către restul Părții a III-a. Capitolul următor - kill signals - e grila structurată de evaluare a gradului de pregătire al unui codebase. Workflow-ul de review de arhitectură îți dă testul empiric ieftin; kill signals îți dau checklist-ul sistematic. Funcționează împreună.

Partea a II-a se încheie aici. Ai metoda. Știi cum să formulezi munca într-un mod pe care agentul îl poate executa, bucla în șase faze care transformă formularea în livrare, infrastructura AGENTS.md care face metoda portabilă și workflow-ul de review de arhitectură care te face productiv într-un codebase nou într-o după-amiază - și care e, în același timp, cel mai ieftin diagnostic pe care îl ai pentru a afla dacă lucrul cu agenți va reuși pe un codebase dat.

Partea a III-a e confruntarea cu realitatea. Metoda funcționează pe multe lucruri. Nu funcționează pe toate. Următoarele trei capitole sunt despre diferența asta - grila care îți spune ce codebase-uri sunt pregătite, pattern-urile operaționale pentru cele brownfield care sunt și arcul de nouăzeci de zile prin care duci o echipă la livrare susținută cu agenți.