Cum pregătim codul pentru agenți AI: context, reguli și medii de test

Seria II: De la infrastructură la proiecte agentice în producție. Episodul 07 din 20.

În episodul anterior am transformat obiectivul unei funcționalități în sarcini verificabile. Următoarea problemă apare imediat: chiar și o sarcină bună eșuează dacă agentul nu știe cum pornește proiectul, ce reguli se aplică și ce comandă dovedește că modificarea funcționează.

Decizia principală este să tratăm repository-ul drept pachetul executabil de context al proiectului. Instrucțiunile, comenzile, deciziile și datele de test trebuie păstrate aproape de cod, versionate și verificate. Un document lung trimis separat nu compensează un proiect care pornește doar pe laptopul unei singure persoane.

Repository-ul este mai mult decât cod

Un repository este spațiul versionat în care echipa păstrează codul și istoricul schimbărilor. Pentru dezvoltare cu agenți AI, el trebuie să răspundă rapid la câteva întrebări: ce face sistemul, cum se instalează, cum se rulează, ce nu avem voie să schimbăm și cum verificăm rezultatul.

În scenariul nostru ipotetic, repository-ul portalului B2B conține interfața web, API-ul pentru solicitări, serviciul de documente și testele. Agentul de dezvoltare primește sarcina de a valida încărcarea fișierelor PDF. Agentul integrat ulterior în portal, care ar putea clasifica documente, este o funcționalitate separată. El nu citește instrucțiunile de dezvoltare și nu primește acces la repository.

Un pachet minim poate avea această structură:

```text
README.md
AGENTS.md
docs/architecture/
docs/adr/
scripts/bootstrap
scripts/check
tests/fixtures/
.env.example
```

Numele exacte pot diferi. Important este ca echipa să aibă o cale oficială de pornire și una de verificare, nu cinci variante contradictorii ascunse în mesaje.

README pentru orientare, AGENTS.md pentru execuție

README-ul rămâne introducerea pentru oameni: scopul proiectului, componentele principale, cerințele și traseul de pornire. AGENTS.md este un fișier Markdown dedicat instrucțiunilor pentru agenții de programare. Formatul deschis îl descrie ca pe un README pentru agenți și recomandă includerea comenzilor de instalare, testare, convențiilor și considerațiilor de securitate.

Pentru portal, AGENTS.md ar trebui să precizeze concis:

• ce directoare corespund interfeței, API-ului și serviciului de documente;
• comenzile oficiale pentru instalare, pornire, formatare, analiză și teste;
• versiunile importante ale runtime-urilor și managerelor de pachete;
• convențiile de cod și locul în care se adaugă testele;
• zonele sensibile, precum migrațiile, autorizarea și stocarea documentelor;
• verificările obligatorii înainte de predarea unei modificări;
• când agentul trebuie să se oprească și să ceară o decizie.

Într-un monorepo, pot exista fișiere AGENTS.md mai apropiate de anumite subproiecte. Documentația formatului și GitHub precizează că instrucțiunea cea mai apropiată de fișierul modificat are prioritate. Această regulă trebuie testată în instrumentul ales, deoarece suportul diferă între produse și funcții.

Instrucțiunile nu sunt un mecanism de autorizare. Fraza „nu accesa producția” poate ghida agentul, dar izolarea reală vine din credențiale absente, permisiuni minime, rețele separate și aprobări tehnice. Un fișier Markdown nu oprește o comandă permisă de mediul de execuție.

O singură cale verificată de pornire

GitHub recomandă documentarea secvențelor pentru bootstrap, build, test, run și lint, inclusiv a versiunilor și precondițiilor, iar comenzile trebuie încercate efectiv. Pentru o echipă mică, soluția practică este să ofere două puncte stabile:

• scripts/bootstrap, care instalează sau verifică dependențele și pregătește mediul local;
• scripts/check, care rulează verificările obligatorii în ordinea acceptată de echipă.

Aceste scripturi pot apela instrumentele existente. Nu trebuie să ascundă erorile sau să continue după un pas critic eșuat. Agentul și colegul nou folosesc aceeași cale, iar integrarea continuă poate apela aceeași verificare.

Un development container poate descrie într-un fișier devcontainer.json instrumentele și setările mediului containerizat. Specificația Dev Container urmărește consistența între dezvoltarea locală și automatizările de build și test. Este o opțiune, nu o obligație. Pentru un proiect simplu, versiuni fixate și scripturi reproductibile pot fi suficiente. Pentru servicii multiple, containerul poate reduce diferențele dintre laptopuri, dar nu garantează singur reproducerea tuturor serviciilor externe.

Date de test sigure și configurații exemplu

Fișierul .env.example enumeră cheile necesare, cu valori fictive sau explicații, niciodată cu secrete reale. Tokenurile și parolele sunt injectate de mediul autorizat. Testele folosesc conturi și documente sintetice, nu copii necontrolate din producție.

Pentru funcționalitatea PDF, păstrăm fixture-uri mici: un fișier valid, unul prea mare, unul cu tip declarat greșit și metadate de utilizatori fictivi. Un fixture este un set stabil de date pregătite pentru test. Documentăm cine îl actualizează și ce verifică. Dacă un exemplu conține date cu caracter personal, îl înlocuim, nu îl „anonimizăm” superficial și îl publicăm în repository.

Agentul trebuie să poată crea baza de date locală de la zero și să ruleze testele fără acces la conturi de client. Orice dependență de un serviciu extern are o alternativă controlată: sandbox oficial, emulator, mock sau un pas explicit care oprește execuția. Astfel, imposibilitatea de a contacta producția devine o proprietate a mediului, nu o rugăminte din prompt.

ADR: de ce există o decizie

Un ADR, de la Architecture Decision Record, este o înregistrare scurtă a unei decizii arhitecturale. Modelul propus de Michael Nygard include contextul, decizia, starea și consecințele. Dacă o alegere este schimbată, vechiul ADR rămâne în istoric și este marcat ca înlocuit.

Pentru portal, un ADR poate explica de ce documentele sunt stocate în obiect storage, de ce baza de date păstrează doar referința și ce compromisuri rezultă. Agentul vede astfel motivul, nu doar forma actuală a codului. AGENTS.md spune cum lucrăm acum; ADR-ul explică de ce o alegere importantă există. Niciunul nu trebuie transformat într-un duplicat al celuilalt.

Verificarea într-un mediu curat

Înainte de a considera repository-ul pregătit, îl testăm ca pe un coleg nou:

1. clonăm într-un mediu fără cache-uri și fișiere locale ascunse;
2. rulăm instrucțiunile de bootstrap exact cum sunt scrise;
3. pornim serviciile cu configurații exemplu și date sintetice;
4. executăm verificarea completă și un scenariu cap-coadă;
5. corectăm documentația sau automatizarea, nu memoria persoanei care a intervenit.

Lucrarea SWE-agent publicată la NeurIPS 2024 arată că interfața prin care un agent navighează repository-ul și execută teste îi influențează comportamentul și performanța. Rezultatele unui sistem de cercetare nu promit aceleași performanțe într-un proiect comercial. Ele susțin însă o concluzie prudentă: mediul și instrumentele oferite agentului fac parte din sistemul pe care îl evaluăm.

Piesa adăugată proiectului este pachetul minim de context: README pentru orientare, AGENTS.md pentru execuție, ADR-uri pentru motive, scripturi pentru bootstrap și verificare, plus fixture-uri sintetice. Îl revizuim în același pull request cu schimbarea de cod care îl face inexact. În episodul următor vom compara locurile în care agentul poate lucra: IDE, terminal și mediu cloud.

Surse

• AGENTS.md, format deschis pentru instrucțiunile agenților, pentru structură, domeniu și prioritatea instrucțiunilor, consultat la 9 octombrie 2026.
• GitHub Docs, Adding repository custom instructions for GitHub Copilot, pentru contextul de repository și comenzile de build, test și validare.
• Development Containers, Overview, pentru descrierea mediilor de dezvoltare și reutilizarea lor în build și test.
• Nygard, Documenting Architecture Decisions și Yang et al., SWE-agent, NeurIPS 2024, pentru ADR-uri și rolul interfeței agentului.

Următorul pas

Vrei să pregătești un proiect existent pentru dezvoltare asistată de agenți AI? Discută cu echipa i8.