AGENTS.md și contextul

La finalul capitolului poți scrie un AGENTS.md în care fiecare linie își merită locul și poți rula sesiuni de agent care rămân ascuțite.

TL;DR

• AGENTS.md e infrastructură de echipă: reguli locale scurte, cu motiv clar, trecute prin review ca orice cod și deținute de un champion.
• Ține-l scurt și relevant: constrângeri locale, comenzi verificate și pointeri. Circa 200 de linii e un reper de întreținere, nu un prag universal demonstrat. Agentul citește înainte să citeze; tu verifici numele noi.
• Contextul e memorie de lucru. O unitate de muncă per sesiune, starea durabilă în fișiere; când apare deriva, diagnostichează cauza înainte de compactare sau repornire.

Ce este AGENTS.md?¶

AGENTS.md este acordul echipei cu agentul, versionat în git.

E un fișier Markdown cu instrucțiunile proiectului. Un client compatibil îl încarcă după propriile reguli de descoperire și configurare; unii clienți cer încărcare explicită. Textul consemnează ce vrea echipa să urmeze agentul și poate trece prin review într-un pull request. E stratul Memory deținut manual din Capitolul 1, nu o politică de permisiuni aplicată efectiv.

AGENTS.md vs CLAUDE.md: care e diferența?¶

Același rol, dar regulile de încărcare depind de harness și de versiune.

Un nume de fișier comun nu înseamnă reguli identice de încărcare. Rezumatul de compatibilitate de mai jos a fost verificat pe 23 octombrie 2026; verifică versiunea instalată și contextul efectiv.

Documentația primară și limitele de versiune sunt în Anexa C. Testează o instrucțiune distinctivă într-o sesiune nouă, în loc să presupui că fișierul a fost descoperit sau că are aceeași autoritate în fiecare client.

Povestea: o convenție, trei forme de sprijin

O echipă cu care am lucrat folosea un coding agent de șase luni când un senior engineer a venit la mine cu o nemulțumire. „De fiecare dată când generăm un endpoint de API, trebuie să repar validarea. Mereu aceeași corecție. Agentul pune validarea în stratul greșit.”

„De ce nu e regula scrisă undeva?”

„N-am scris-o niciodată. Doar o tot reparăm.”

Seniorul corecta repetat aceeași amplasare a validării la review-urile de endpoint-uri. Relatarea inițială includea numere de endpoint-uri și o estimare de timp, dar înregistrările review-urilor nu sunt disponibile aici, așa că ediția aceasta nu susține o economie lunară precisă.

Am documentat convenția în AGENTS.md, am adăugat un reminder în template-ul de PR și am identificat endpoint-uri corecte ca exemple de referință. Potrivit relatării, review-urile ulterioare au cerut mai puține corecții de acest fel. Intervenția a fost combinația celor trei; relatarea nu izolează contribuția instrucțiunii.

Șase reguli pentru fișier

Șase reguli, fiecare cu un test pe care îl poți aplica oricărei linii.

Regula 1: scrie reguli pe care agentul le poate verifica

O regulă pe care agentul n-o poate verifica e decor.

Varianta proastă nu specifică arhitectura. Varianta delimitată identifică o graniță de intrare, garanția ei, un mecanism și un exemplu fără să declare că serviciile pot avea încredere universală în orice input. Spring suportă și validarea metodelor de service. Un pattern portabil este: „În [scope], [granița de intrare] stabilește [garanția de input] prin [mecanism]; urmează [referința]. Alte intrări stabilesc aceeași garanție; [responsabilul] păstrează invariantele de domeniu.” Anexa B.2 e un punct de pornire specific unui proiect.

Regulile 2 și 5: motivate de context, tratate ca cod¶

O regulă își câștigă locul prin utilitate locală, iar un champion ține fișierul în formă.

• Dă-l la review ca pe cod. Reviewerul întreabă ce problemă previne și de ce agentul nu poate deduce singur regula. Un eșec real e o justificare bună; o constrângere neintuitivă de securitate, business sau compatibilitate poate intra preventiv, cu motiv și dovezi. Best practice-urile generice nu merită copiate automat.
• Ține un jurnal de greșeli. O intrare per incident real, cu regula care previne repetarea și un pointer la dovadă, commit-ul sau incidentul; B.2 are o intrare-exemplu.
• Numește un champion. O singură persoană deține fișierul și jurnalul; toată lumea editează prin pull request-uri, iar championul curatoriază. În fiecare trimestru, championul întreabă pentru fiecare intrare dacă a salvat pe cineva în ultimele trei luni și le retrage pe cele a căror problemă de fond a dispărut, cu motivul în mesajul de commit; o regulă care încă previne un eșec rar rămâne. Apoi rolul se rotește.

Regulile 3 și 4: context relevant, lungime justificată¶

Păstrează constrângerile locale, comenzile și pointerii care scutesc agentul de ghicit.

• Pattern-uri interzise, convenții și intrări de jurnal, câte o linie fiecare.
• Comenzile exacte de build și de test. Fără ele, agentul ghicește, iar uneori ghicește greșit.
• Un glosar de domeniu. În pretraining, „transfer” înseamnă o grămadă de lucruri; în banca ta înseamnă unul singur, iar un „wire” e strict cel inter-bancar.
• O linie de pointer: „Structura repository-ului și harta modulelor: docs/architecture.md. Citește-l înainte să atingi un modul pe care nu l-ai văzut în sesiunea asta.”

O hartă voluminoasă se citește mai bine la cerere, în docs/architecture.md; un pointer sau o scurtă informație de orientare poate rămâne dacă ajută task-urile reale. Studiul revizuit despre AGENTS.md nu a găsit o îmbunătățire generală a succesului pentru fișierele de context generate și a măsurat un cost de inferență cu peste 20% mai mare în setup-urile testate. Fișierele scrise de developeri au adus un câștig mediu modest, fără semnificație statistică. Studiul nu dovedește că orice fișier de instrucțiuni dăunează sau că fiecare categorie de context trebuie eliminată.

Folosește circa 200 de linii ca reper de întreținere. Nu există o prăpastie demonstrată la linia 201. Elimină redundanțele și regulile generice, mută detaliile la locul lor și păstrează regulile rare care încă previn un eșec real. Un studiu despre numărul de reguli din prompturi nu stabilește o conversie universală între reguli și linii de AGENTS.md. Verifică dacă fișierul tău ajută, pentru modelul și task-urile folosite.

Fișierul unei echipe de banking a crescut în șase luni până pe la nouă sute de linii, iar agentul a început să ignore regulile cele mai noi. L-am tăiat la nouăzeci, mutând convențiile în skill-uri care se încarcă la detecție și istoricul greșelilor din trecut în documentul de arhitectură, iar rata de conformare a sărit în sus într-o săptămână. Cazul arată utilitatea selecției și a structurii, nu validează un plafon universal de linii.

Regula 6: când agentul minte cu încredere

Agentul inventează fișiere, funcții și opțiuni, așa că obligă-l să demonstreze ce citează.

Va cita un fișier care nu există, o funcție pe care biblioteca n-a expus-o niciodată, o opțiune scoasă din uz acum trei versiuni. Output-ul arată plauzibil și e greșit; agentul potrivește pattern-uri din cod similar și nu știe că ghicește. Trei tactici mecanice:

• Citește înainte să citezi. Tot ce menționează agentul trebuie să fi fost citit în sesiunea curentă. AGENTS.md poate impune asta: „Înainte să faci referire la orice funcție, citește fișierul care o definește. Citările fără o citire prealabilă se tratează ca ciorne de verificat.”
• Dă grep după fiecare nume nou. Zero rezultate înseamnă că funcția probabil nu există sau stă într-o dependență vendored pe care agentul n-o vede. Durează câteva secunde și prinde cele mai frecvente invenții.
• Pune un hook pe citări. Dacă agentul citează un fișier și o linie, câteva linii de bash într-un hook pot verifica dacă linia există (Capitolul 2).

Igiena contextului¶

Fereastra e memoria de lucru a agentului, așa că încarcă ce cere task-ul și nimic în plus.

Tot ce e în fereastră concurează pentru aceeași atenție mărginită. Contextul învechit sau contradictoriu e una dintre cauzele pentru care o sesiune lungă poate pierde firul task-ului. Patru obiceiuri te ajută să păstrezi contextul util.

• Pointere, nu payload-uri. Pune în AGENTS.md un link spre documentele mai lungi și doar contextul stabil care ajută frecvent. Reperul de 200 de linii te îndeamnă să alegi, nu să tai instrucțiuni necesare ca să atingi un număr.
• Păstrează starea de care ai nevoie. Pentru munca de durată, notează deciziile, constrângerile, progresul și comenzile care au mers, în formatul potrivit proiectului. Un issue, un fișier existent sau o scurtă notă pot fi suficiente; nu ai nevoie de trei documente și un commit la fiecare restart.
• Folosește cele patru semne pentru diagnostic. Agentul reia întrebări rezolvate, citează un fișier învechit, uită o constrângere sau face editări tot mai neglijente. Acestea pot indica un context contaminat, dar și cerințe contradictorii, surse învechite ori acces lipsă. Verifică starea reală și corectează cauza; dacă deriva continuă, păstrează ce e necesar și pornește o sesiune curată. Fă commit după practica repo-ului, nu ca ritual de restart.
• Tratează compactarea ca pe un hand-off. Rezumarea poate omite sau deforma detalii, așa că salvează durabil deciziile, constrângerile și dovezile indispensabile. Dă-i compactorului o listă de păstrat: planul, întrebările deschise, devierile consemnate în notele de implementare, comenzile exacte care au mers. Apoi verifică dacă în contextul rezultat se află tot ce cere pasul următor.

Clientul stabilește ce rezumă, ce păstrează și ce reîncarcă; documentația Claude Code despre compactare descrie aceste diferențe. Verifică comportamentul clientului și al versiunii pe care le folosești.

Când se strică

• Fișierul e o rugăminte, nu un zid. Agentul tot poate încălca AGENTS.md. Restricțiile obligatorii cer permisiuni aplicate efectiv, izolare sau gate-uri protejate de review; un hook ajută doar pe căile pe care le acoperă (Capitolul 2).
• Intrările vechi devin folclor. O intrare fără pointer la dovadă e greu de retras, iar un cimitir de reguli e aproape la fel de inutil ca lipsa lor: echipa încetează să mai aibă încredere în vreuna.

De făcut luni

• [ ] Verifică instrucțiunile curente ale repository-ului. Adaugă o convenție lipsă documentată, o constrângere justificată sau o corecție repetată; include comenzi și pointeri unde scutesc agentul de ghicit. Nu ai o cotă de linii sau de reguli de completat.
• [ ] Găsește-ți propria poveste cu validarea: o corecție pe care o tot faci în review. Scrie-o ca o singură linie verificabilă și adaugă-o în template-ul de PR, ca reminder pentru revieweri.
• [ ] Verifică numele nefamiliare față de definițiile și sursele lor. Adaugă regula „citește înainte să citezi” dacă rezolvă o problemă observată și numește un responsabil pentru întreținerea instrucțiunilor.
• [ ] În următoarea sesiune lungă, urmărește deriva. Păstrează starea necesară pentru hand-off, apoi recuperează contextul, compactează sau repornește după caz; fă commit conform practicii repository-ului.

Mai departe

• Template-uri: Anexa B.2, scheletul AGENTS.md (conține linia de precedență); B.7, igiena contextului pe o singură pagină; B.11, punerea pe picioare a fișierului pe un repository.
• Deep dive: Anexa D, Capitolul 6 - studiul despre fișierele de context, limitele dovezilor despre numărul de reguli și de instrucțiuni, mecanica jurnalului de greșeli, măsurătorile despre compactare și cache și avertismentele de context ale HumanLayer.
• Surse: Anexa C.