Onboarding într-un codebase necunoscut, cu agenți AI

Prima zi pe un proiect nou: 400.000 de linii, un README scris acum doi ani, trei persoane care știu cum funcționează sistemul și care sunt toate ocupate. Întrebarea nu e „ce face codul ăsta" — răspunsul îl poți obține în cinci minute de la un agent. Întrebarea e „care dintre răspunsurile pe care le primesc sunt adevărate", iar aici se vede diferența dintre cineva care folosește un agent și cineva care îl folosește bine.

Articolul e despre primele cinci zile într-un cod pe care nu l-ai scris tu: la schimbarea jobului, la preluarea unui proiect abandonat sau când echipa ta moștenește un serviciu de la altă echipă. Nu e despre modernizarea codului moștenit — aceea e o discuție separată, tratată în ghidul despre modernizarea codului legacy cu agenți. Aici obiectivul e mai modest și mai urgent: să ajungi rapid în punctul în care poți face o modificare mică fără să strici nimic.

Prima oră: rulează-l, nu citi-l

Tentația e să deschizi codul și să începi să citești de sus în jos. E cea mai lentă metodă posibilă de a înțelege un sistem.

Ordinea care funcționează:

1. Pornește-l local. Dacă durează mai mult de o oră, notează fiecare obstacol — vei avea prima contribuție utilă la proiect chiar înainte să scrii o linie de cod.
2. Rulează testele. Care trec, care sunt sărite, cât durează. O suită care durează 40 de minute îți spune mai multe despre cultura echipei decât orice document.
3. Citește configurația de integrare continuă. Aceasta e documentația adevărată: ce se verifică la fiecare modificare, ce blochează livrarea, unde se livrează. Un README poate minți; un pipeline care rulează zilnic, nu.
4. Uită-te la istoricul ultimelor 30 de zile. Ce fișiere se modifică cel mai des? Acolo e inima sistemului și acolo vei lucra.

Abia acum merită să deschizi codul, pentru că știi ce cauți.

Modul de lucru cu un agent pe un depozit real — cum îi dai contextul, cum limitezi ce atinge, cum integrezi rezultatul în fluxul de versionare — e tratat în cursul Claude Code Mastery.

A doua oră: harta

Un agent poate citi întregul depozit mai repede decât tine, dar răspunde cu aceeași siguranță în glas și când e corect, și când inventează. Regula care rezolvă problema e una singură:

Nicio afirmație despre cod fără fișier și linie.

Formulează cererile astfel încât răspunsul să fie verificabil într-un clic. În loc de „explică-mi arhitectura", cere: „listează punctele de intrare ale aplicației și, pentru fiecare, dă-mi fișierul și linia". În loc de „cum funcționează autentificarea", cere: „arată-mi, cu fișier și linie, unde se validează sesiunea și ce se întâmplă când validarea eșuează".

Trei tehnici care cresc calitatea răspunsurilor:

Cere demonstrația, nu descrierea. „Rulează comanda care arată toate rutele înregistrate" e mai bun decât „descrie-mi rutele". Ieșirea unei comenzi nu poate fi halucinată.

Cere contrazicerea. După ce primești o explicație, întreabă: „ce dovezi din cod ar contrazice explicația asta?". Modelele au tendința să confirme ipoteza din întrebare; cererea explicită de contraexemple corectează parțial înclinația.

Folosește istoricul ca arbitru. „De ce e scris așa?" primește adesea un răspuns plauzibil și inventat. „Găsește commit-ul care a introdus linia asta și arată-mi mesajul" primește un fapt.

Disciplina de a construi și menține contextul unui agent — ce încarci, ce lași pe dinafară, cum eviți instrucțiunile contradictorii — e subiectul cursului Context Engineering și memorie pentru agenți AI.

Cele șapte întrebări care dau cel mai mult context

În ordinea în care merită puse, fiecare cu cerința de fișier și linie:

1. Unde intră o cerere și pe unde iese? Punctele de intrare și ieșire delimitează sistemul mai bine decât orice diagramă.
2. Unde se scriu datele? Fiecare loc care modifică starea persistentă. Aici sunt și cele mai mari riscuri.
3. Ce e generat automat? Cod, migrări, clienți de API, fixturi. Editarea unui fișier generat e greșeala clasică a primei săptămâni.
4. Ce e mort? Module fără referințe, rute care nu mai sunt apelate, fișiere neatinse de trei ani. Un agent poate face inventarul; tu confirmi cu istoricul și cu telemetria.
5. Care sunt vecinii? Ce servicii externe apelează sistemul și cine îl apelează pe el. Integrările sunt sursa principală de surprize.
6. Ce se rupe des? Din istoricul de incidente, din fișierele cu cele mai multe corecții, din testele marcate ca instabile.
7. Unde nu am voie să umblu fără să întreb? Plăți, autentificare, date personale, cod cu obligații contractuale. Răspunsul vine de la oameni, nu de la agent — dar întrebarea trebuie pusă în prima zi.

Cum prinzi o halucinație de arhitectură

Sunt cele mai periculoase, pentru că sună impecabil. Un model îți poate descrie un strat de servicii inexistent, un tipar pe care echipa l-a abandonat acum doi ani sau o convenție preluată din alte proiecte.

Trei verificări rapide, aplicate oricărei afirmații care ți se pare importantă:

• Există fișierul? Deschide-l. Pare banal; nu e. Căile inventate sunt cel mai frecvent tip de eroare.
• Se potrivește cu ce rulează? Dacă agentul spune că există o coadă de mesaje, caută consumatorul în configurația de rulare, nu doar în cod.
• Confirmă un al doilea traseu? O afirmație importantă trebuie să apară în două locuri independente: cod și configurație, sau cod și test.

Regula de bază rămâne cea din ghidul despre cod generat de AI în producție: ce e determinist se verifică automat, restul se verifică de om. La onboarding, „omul" ești tu, iar verificarea durează secunde dacă răspunsul vine cu fișier și linie.

Ce scrii pe măsură ce înveți

Cea mai mare risipă din onboarding e că înțelegerea rămâne în capul tău și dispare în trei luni. Soluția e să o scrii în același loc din care o va citi și agentul, și următorul coleg.

Pornește de la un fișier generat. Claude Code are pentru asta comanda /init, care analizează codul și creează un fișier de instrucțiuni cu comenzile de build, instrucțiunile de test și convențiile descoperite; dacă fișierul există deja, propune îmbunătățiri în loc să-l suprascrie. Comanda citește și regulile Cursor din .cursor/rules/ sau .cursorrules, respectiv pe cele Copilot din .github/copilot-instructions.md, și încorporează ce e relevant.

Adaugă ce nu se poate deduce. Un fișier generat conține structura; valoarea o aduci tu, cu ce ai aflat lovindu-te: „migrările se rulează manual, nu la deployment", „testele din directorul X sunt instabile, se reiau", „clientul de plăți are un timeout de 3 secunde setat în altă parte decât te aștepți". Formatul, regulile de precedență între unelte și limitele acestui fișier sunt în ghidul despre AGENTS.md.

Ține o listă separată de întrebări pentru oameni. Tot ce agentul nu poate ști: de ce s-a ales această soluție, ce clienți depind de comportamentul ciudat din modulul Y, ce nu se atinge înainte de închiderea de lună. O întrebare bine pusă la cafea economisește o zi de citit cod.

Trei tipuri de proiecte, trei abordări

Monolitul mare. Avantajul e că totul e într-un singur loc; dezavantajul, că „totul" înseamnă sute de mii de linii. Nu încerca harta completă: alege modulul în care vei lucra și cartografiază-l pe el, plus interfețele lui cu restul. Fișierele de instrucțiuni imbricate, cu unul în rădăcină și câte unul pe modul, sunt tiparul potrivit aici.

Sistemul distribuit. Codul unui serviciu se înțelege în două ore; sistemul, în două săptămâni. Întrebarea centrală se mută de la „ce face codul" la „cine apelează pe cine și ce se întâmplă când unul cade". Începe cu contractele dintre servicii, nu cu implementările, și cere agentului să extragă lista de apeluri externe din fiecare serviciu, cu fișier și linie.

Monorepo-ul cu mai multe echipe. Riscul specific e să primești contextul altei echipe și să tragi concluzii greșite. Verifică ce fișiere de instrucțiuni se încarcă efectiv în sesiunea ta și exclude ce nu te privește — uneltele au mecanisme dedicate pentru asta. La fel de important: află cine deține fiecare director, pentru că revizuirea pull request-ului tău va veni de acolo.

Ce faci când nu există teste

Cazul cel mai neplăcut: un sistem în producție, fără suită de teste, fără documentație și fără persoana care l-a scris.

Ordinea care funcționează și aici:

1. Captează comportamentul actual înainte să schimbi ceva: intrări reale și ieșirile lor, salvate ca fișiere. Devin testul tău de referință, chiar dacă nu arată ca un test clasic.
2. Scrie primul test în jurul zonei în care vei lucra, nu în jurul întregului sistem. Un test care acoperă o funcție e mai valoros decât un plan de acoperire care nu se termină niciodată.
3. Folosește agentul pentru schele, nu pentru adevăr. Poate genera rapid structura testelor și cazurile evidente; tu decizi care e comportamentul corect, pentru că modelul nu are de unde să știe ce e intenționat și ce e defect vechi.
4. Nu „repara" comportamente ciudate în prima săptămână. Unele sunt cerințe de business pe care nimeni nu le-a scris. Notează-le pe lista de întrebări pentru oameni.

Primul pull request, în ziua 3 sau 4

Criteriile unei alegeri bune:

• Mic, sub 100 de linii modificate.
• Verificabil, adică acoperit de teste existente sau ușor de testat.
• Necritic, departe de plăți, autentificare și date personale.
• Util, nu cosmetic. Un obstacol pe care l-ai întâlnit la pornirea locală e alegerea perfectă: îl repari pentru tine și pentru următorul.

Scopul nu e impresia, ci parcurgerea completă a drumului: modificare, test, revizuire, integrare, livrare. Vei descoperi pe parcurs jumătate din lucrurile pe care nimeni nu s-a gândit să ți le spună.

Ce nu delegi agentului în prima săptămână

• Refactorizări mari. Nu ai încă modelul mental care îți spune dacă rezultatul e corect.
• Modificări în zonele sensibile. Autentificare, plăți, migrări de date.
• Ștergerea codului „mort". Până nu confirmi cu telemetrie sau cu o persoană, „nereferențiat" nu înseamnă „nefolosit".
• Deciziile de convenție. Dacă observi trei stiluri diferite în cod, întreabă echipa care e cel curent; nu lăsa agentul să aleagă pentru tine.

Un plan pe cinci zile

Ritmul e realist pentru o persoană care lucrează opt ore pe zi și participă și la ședințe. Dacă proiectul e mai mare, planul nu se schimbă — se repetă pe fiecare modul.

Cum știi că ai înțeles sistemul

Testul e simplu: poți răspunde, fără să deschizi codul, la cinci întrebări.

1. Ce se întâmplă, pas cu pas, când un utilizator face acțiunea principală?
2. Unde ajung datele și cine le mai citește?
3. Ce se strică dacă serviciul extern cel mai important devine indisponibil?
4. Care sunt cele trei fișiere pe care le atinge orice modificare semnificativă?
5. Ce parte a sistemului nu ai atinge fără să întrebi pe cineva?

Dacă răspunzi la toate cinci în ziua a cincea, ai făcut un onboarding bun. Dacă răspunzi la trei, ești în grafic. Iar dacă te-ai trezit citind cod trei zile fără să rulezi nimic, merită să reiei prima oră.

Întrebări frecvente

Î: Pot să mă bazez pe explicațiile unui agent despre un cod pe care nu îl cunosc? R: Ca punct de plecare, da; ca sursă de adevăr, nu. Cere fiecare afirmație importantă cu fișier și linie, verifică-le pe cele care contează și preferă demonstrațiile — ieșirea unei comenzi sau mesajul unui commit — în locul descrierilor. Halucinațiile de arhitectură sună întotdeauna plauzibil, pentru că sunt construite din tipare comune din alte proiecte.

Î: Cât durează un onboarding rezonabil? R: Pentru un serviciu de dimensiune medie, cinci zile până la primul pull request util și două-trei săptămâni până la autonomie pe zonele obișnuite. Într-un monorepo mare, planul se aplică pe modulul în care vei lucra, nu pe tot depozitul; încercarea de a înțelege totul deodată e cea mai frecventă cauză de blocaj.

Î: Ce fac dacă nu am voie să trimit codul firmei către un serviciu extern? R: Metoda rămâne identică, doar unealta se schimbă: rulezi un model găzduit intern sau folosești funcții care păstrează codul în infrastructura proprie. Partea cu adevărat valoroasă din acest plan — ordinea pașilor, întrebările, regula citatelor, ce scrii la final — nu depinde de furnizor.

Î: Merită să generez documentație pentru tot proiectul în prima săptămână? R: Nu. Documentația generată în masă e lungă, plauzibilă și greu de verificat, iar nimeni nu o citește. Scrie puțin și verificat: comenzile reale, capcanele pe care le-ai lovit, zonele sensibile. Documentația exhaustivă e un proiect separat, cu propriile reguli de verificare.

Î: Cum transform onboarding-ul într-un avantaj pentru echipă, nu doar pentru mine? R: Prin cele două artefacte care rămân după tine: fișierul de instrucțiuni actualizat, din care câștigă orice agent folosit de orice coleg, și lista de obstacole de la pornirea locală, rezolvate sau măcar documentate. Următoarea persoană care intră în proiect va ajunge la primul pull request în două zile, nu în cinci.

Concluzie

Un agent transformă onboarding-ul dintr-un exercițiu de citit cod într-unul de pus întrebări bune și de verificat răspunsuri. Ordinea contează mai mult decât unealta: întâi rulezi sistemul, apoi îl cartografiezi cu cereri verificabile, apoi confirmi ce ai aflat, apoi scrii rezultatul acolo unde îl găsesc și ceilalți.

Rămâne, la final, un singur reflex de format: nicio afirmație despre cod fără fișier și linie. Cu el, un agent e cel mai bun coleg de onboarding pe care îl poți avea. Fără el, e o sursă rapidă de convingeri false.

Surse: Claude Code — memoria proiectului și comanda /init · agents.md — formatul de instrucțiuni pentru agenți · Documentația GitHub — instrucțiuni pentru depozit

Articol informativ, publicat la 18 septembrie 2026. Are caracter educativ. Înainte de a folosi un agent pe codul unui angajator sau al unui client, verifică politica internă și clauzele contractuale privind transmiterea codului către servicii externe.