AGENTS.md: instrucțiunile pe care le citește agentul din proiect

Corectezi agentul a treia oară în aceeași săptămână: a rulat testele cu comanda greșită, a adăugat o bibliotecă pe care echipa a scos-o acum un an, a scris migrarea în directorul greșit. Nu e o problemă de model. Este exact contextul pe care un coleg nou l-ar primi în prima zi și pe care nimeni nu l-a scris nicăieri. Fișierul care rezolvă asta are un nume, un format deschis și e citit deja de majoritatea uneltelor: AGENTS.md.

Articolul de față e despre ce scrii în el, ce lasă în urmă fiecare unealtă și — partea pe care o ratează majoritatea echipelor — ce nu poate face un fișier de instrucțiuni, oricât de bine l-ai scrie.

Ce este AGENTS.md

Site-ul oficial îl descrie drept „un format simplu și deschis pentru ghidarea agenților de programare", gândit ca „un loc dedicat și previzibil în care oferi contextul și instrucțiunile". Formatul e Markdown obișnuit: „folosește orice titluri vrei; agentul pur și simplu parcurge textul pe care îl oferi". Nu există câmpuri obligatorii — dacă ai citit pe undeva că sunt două câmpuri necesare, e o confuzie cu alt format.

Originea e o colaborare între mai multe echipe din ecosistem — Codex de la OpenAI, Amp, Jules de la Google, Cursor și Factory — iar formatul este acum administrat de Agentic AI Foundation, sub Linux Foundation. Adoptarea declarată: peste 60.000 de proiecte open-source.

Distincția utilă e cea față de README.md: „fișierele README sunt pentru oameni: ghiduri rapide, descrieri de proiect și reguli de contribuție", în timp ce AGENTS.md conține „contextul suplimentar, uneori detaliat, de care au nevoie agenții de programare". Cu alte cuvinte: ce ai explica unui coleg în prima zi, dar într-o formă pe care o citește o mașină la fiecare sesiune.

Disciplina din spate — ce intră în context, ce rămâne pe dinafară, cum eviți ca instrucțiunile să se contrazică între ele — e tratată pe larg în cursul Context Engineering și memorie pentru agenți AI. Fișierul e doar suprafața vizibilă a acestei discipline.

Cine îl citește, de fapt

Aici apar cele mai multe presupuneri greșite. Situația reală, din documentațiile oficiale, în septembrie 2026:

GitHub Copilot citește trei tipuri de fișiere: .github/copilot-instructions.md pentru tot depozitul, fișiere NAME.instructions.md în .github/instructions/ pentru anumite căi și, pentru agenți, AGENTS.md, CLAUDE.md sau GEMINI.md, plasate oriunde în depozit. Precedența declarată: instrucțiunile personale au prioritatea cea mai mare, urmate de cele ale depozitului și, la final, de cele ale organizației. Pentru fișierele de agent, „cel mai apropiat AGENTS.md din arborele de directoare are prioritate".

Cursor folosește regulile din .cursor/rules (fișiere .mdc, versionate în depozit) și acceptă AGENTS.md ca alternativă, inclusiv în subdirectoare: fișierele imbricate „se aplică automat când se lucrează cu fișiere din acel director sau din copiii lui", iar instrucțiunile se combină ierarhic, cu precedență pentru cele mai specifice. Un detaliu care irită la prima încercare: un fișier .md simplu pus în .cursor/rules e ignorat, pentru că nu are frontmatter.

Claude Code citește CLAUDE.md, nu AGENTS.md. Documentația oficială spune exact asta și dă soluția: dacă depozitul tău folosește deja AGENTS.md pentru alți agenți, creezi un CLAUDE.md care îl importă, ca ambele unelte să citească aceleași instrucțiuni fără duplicare:

@AGENTS.md

## Claude Code

Folosește modul plan pentru modificări sub `src/billing/`.

Alternativa, dacă nu ai nevoie de instrucțiuni suplimentare: un symlink, ln -s AGENTS.md CLAUDE.md. Pe Windows, symlink-ul cere privilegii de administrator sau modul dezvoltator, deci importul e varianta practică. Tot documentația notează că /init citește regulile Cursor din .cursor/rules/ sau .cursorrules și pe cele Copilot din .github/copilot-instructions.md și le încorporează în fișierul generat.

Concluzia operativă pentru o echipă mixtă, în care unii folosesc Copilot, alții Cursor, alții Claude Code: o singură sursă de adevăr — AGENTS.md — și fișiere-punte subțiri pentru uneltele care citesc alt nume. Duplicarea instrucțiunilor în trei fișiere e garanția că peste două luni vor spune lucruri diferite.

Comparația uneltelor în sine, cu punctele lor tari și slabe, e în articolul despre Claude Code, Cursor și GitHub Copilot.

Ce pui în el

Regula de selecție e simplă și se aplică fiecărei linii: dacă scoți linia, agentul face o greșeală pe care altfel nu ar fi făcut-o? Dacă nu, linia consumă context degeaba.

Ce merită scris:

• Comenzile exacte: cum se instalează dependențele, cum se rulează testele, cum se face verificarea de tipuri, cum se generează migrarea. Nu „rulează testele", ci comanda pe care o rulezi tu.
• Convențiile care diferă de implicit: indentare, convenții de denumire, biblioteca de acces la date, formatul mesajelor de commit.
• Structura: unde stau handlerele, unde stau testele, ce e generat automat și nu se editează manual.
• Capcanele proiectului: „migrările nu se rulează local pe baza de producție", „directorul legacy/ nu se refactorizează", „cheile de test sunt în .env.example, nu în .env".
• Ce nu are voie să facă: dependențe noi fără aprobare, modificări în modulele de plăți, scrierea în fișiere generate.

Ce nu merită scris — și aici documentația Claude Code e explicită, pentru că verificarea /doctor propune exact aceste tăieri: conținutul pe care agentul îl poate deduce singur din codul sursă, cum ar fi structura de directoare, lista de dependențe sau prezentarea generală a arhitecturii. Se păstrează, în schimb, capcanele, rațiunile din spatele deciziilor și convențiile care diferă de comportamentul implicit al uneltelor.

Specificitatea se măsoară în verificabilitate. Documentația dă perechile care spun totul: „folosește indentare de 2 spații" în loc de „formatează corect codul"; „rulează npm test înainte de commit" în loc de „testează modificările"; „handlerele de API stau în src/api/handlers/" în loc de „ține fișierele organizate".

Lungimea: toate cele trei documentații spun același lucru

Nu e o chestiune de stil, ci de context consumat și de rată de respectare:

Cea mai bună tehnică de reducere e cea din documentația Cursor: nu copia ghidul de stil în fișier, trimite la el. Iar dacă instrucțiunile cresc oricum, ambele ecosisteme oferă aceeași ieșire — reguli încărcate doar când agentul atinge anumite fișiere. În Claude Code sunt fișierele din .claude/rules/ cu câmpul paths în frontmatter; în Cursor, regulile atașate pe tipare de fișiere.

Monorepo: fișiere imbricate, nu un fișier uriaș

Site-ul oficial descrie tiparul: „pune un alt AGENTS.md în fiecare pachet. Agenții citesc automat cel mai apropiat fișier din arborele de directoare, deci cel mai apropiat are prioritate". Exemplul citat acolo: depozitul principal al OpenAI avea, la momentul scrierii, 88 de fișiere AGENTS.md.

Aceeași logică la Cursor și la Copilot. În Claude Code, fișierele din directoarele superioare se încarcă la pornire, iar cele din subdirectoare se încarcă la cerere, când agentul citește fișiere de acolo; toate sunt concatenate, nu se suprascriu, în ordine de la rădăcină spre directorul curent. Pentru monorepo-urile mari există și supapa inversă, claudeMdExcludes, care sare peste fișierele altor echipe.

Recomandarea practică: în rădăcină pui ce e valabil peste tot (comenzi, convenții, reguli de securitate), iar în fiecare pachet doar ce e specific lui. Un fișier de 400 de linii în rădăcină, care descrie zece pachete, e mai rău decât zece fișiere de 40.

Partea pe care o ratează toată lumea: nu e configurație

Documentația Claude Code e neobișnuit de directă aici: fișierele de instrucțiuni sunt tratate „ca context, nu ca o configurație impusă", iar conținutul e livrat ca mesaj după promptul de sistem, deci „nu există nicio garanție de conformare strictă", mai ales pentru instrucțiuni vagi sau contradictorii. Pentru a bloca o acțiune indiferent de ce decide modelul, documentația trimite la un hook care rulează înainte de folosirea uneltei.

Tradus în reguli de echipă:

• „Nu adăuga dependențe noi" în AGENTS.md = o preferință respectată de cele mai multe ori.
• Verificarea în integrarea continuă care eșuează când apare o dependență neaprobată = o regulă.
• „Nu citi fișierele .env" = o preferință.
• O regulă de permisiuni care blochează citirea acelei căi = o regulă.

Ambele sunt necesare, dar nu sunt interschimbabile. Ce trebuie garantat se pune în permisiuni, hooks și în pipeline; în fișierul de instrucțiuni rămâne ghidajul care face agentul util, nu bariera care îl oprește. Clasele de risc din codul produs și verificările deterministe care le prind sunt tratate separat în ghidul despre cod generat de AI în producție, iar lucrul pe depozite reale cu permisiuni și hooks e subiectul cursului Claude Code Mastery.

Un schelet de pornire

Structura de mai jos acoperă ce folosește un agent în 90% din sarcini. Completeaz-o cu valorile tale reale și oprește-te când ai terminat — nu umple secțiuni de dragul simetriei.

# Proiect

Aplicație [ce face], [limbaj/framework], bază de date [X].

## Comenzi

- Instalare: `...`
- Rulare locală: `...`
- Teste: `...`  (rulează-le înainte de orice commit)
- Verificare de tipuri și linting: `...`
- Migrări: `...`

## Convenții

- [convenție care diferă de implicit]
- [bibliotecă preferată și alternativa interzisă]
- Mesaje de commit: [format]

## Structură

- `src/...` — [ce conține]
- `tests/...` — [ce conține]
- `generated/` — generat automat, nu se editează

## Reguli

- Nu adăuga dependențe noi fără aprobare într-un pull request separat.
- Nu modifica modulele de autentificare și de plăți fără cerere explicită.
- Datele de test sunt sintetice; nu copia date din producție.

## Capcane cunoscute

- [greșeala pe care a făcut-o deja cineva, o dată]

Momentul potrivit pentru a adăuga o linie e definit tot în documentație: când agentul face aceeași greșeală a doua oară, când o revizuire de cod prinde ceva ce ar fi trebuit să știe, când tastezi aceeași corecție ca sesiunea trecută sau când un coleg nou ar avea nevoie de aceeași explicație. Nu scrie fișierul dintr-o singură ședință de brainstorming. Îl crești din corecții reale.

Patru greșeli care fac fișierul inutil

Preferințele personale în fișierul echipei. Editorul tău, aliasurile tale și calea ta locală nu au ce căuta într-un fișier versionat. Toate uneltele au un loc separat pentru ele: instrucțiuni la nivel de utilizator, valabile în toate proiectele tale, respectiv un fișier local ignorat de sistemul de versionare. Documentația Claude Code numește explicit CLAUDE.local.md, cu recomandarea de a-l adăuga în .gitignore.

Instrucțiuni pentru o singură sarcină. „Când migrezi modulul de facturare, fă X" e o procedură, nu o convenție. Ocupă context în fiecare sesiune, deși e relevantă o dată pe trimestru. Astfel de proceduri se mută în mecanismele care se încarcă la cerere.

Reguli care se contrazic. Două fișiere care spun lucruri diferite despre același comportament duc la o alegere arbitrară. Apare inevitabil în monorepo-uri, unde fișierul din rădăcină și cel din pachet au fost scrise de echipe diferite, la un an distanță. O curățare trimestrială rezolvă problema mai bine decât orice instrucțiune suplimentară.

Copierea documentației existente. Ghidul de stil, lista de comenzi din package.json și descrierea arhitecturii sunt deja în depozit. Documentația Cursor o spune direct: referențiază fișierele în loc să le copiezi conținutul. Copiile devin, în plus, a doua sursă de adevăr care se învechește.

Cum verifici că funcționează

Trei semnale, în ordinea utilității:

1. Fișierul chiar s-a încărcat. În Claude Code, comanda /context arată fișierele de memorie încărcate în sesiune. Dacă fișierul nu apare acolo, nu e o problemă de conținut, ci de amplasare.
2. Corecțiile repetate scad. Ține o săptămână o listă cu ce corectezi manual. Fiecare intrare care apare a doua oară e o linie lipsă din fișier.
3. Rata de trecere prin integrarea continuă crește. Documentația GitHub formulează chiar acesta ca scop al fișierului de instrucțiuni: reducerea probabilității ca un pull request generat să fie respins pentru că nu trece verificările automate. E metrica cea mai onestă, pentru că se măsoară singură.

Ce nu e o metrică: lungimea fișierului, numărul de reguli sau senzația că „acum agentul mă înțelege". Ultima se schimbă de la o sesiune la alta.

Întrebări frecvente

Î: Claude Code citește AGENTS.md? R: Nu. Documentația oficială spune că Claude Code citește CLAUDE.md, nu AGENTS.md. Soluția recomandată, dacă depozitul folosește deja AGENTS.md, e un CLAUDE.md care îl importă cu sintaxa @AGENTS.md, sub care poți adăuga instrucțiuni specifice. Un symlink funcționează la fel, dacă nu ai nevoie de conținut suplimentar, dar pe Windows cere privilegii speciale.

Î: Ce lungime ar trebui să aibă fișierul? R: Documentațiile converg: sub 200 de linii pentru Claude Code, cel mult două pagini pentru Copilot, sub 500 de linii pentru regulile Cursor. Testul practic pentru fiecare linie e dacă absența ei ar produce o greșeală reală. Pentru instrucțiuni voluminoase, folosește reguli care se încarcă doar când agentul lucrează cu anumite fișiere.

Î: Ce fac într-un monorepo? R: Fișiere imbricate. Toate cele trei ecosisteme aplică aceeași regulă — cel mai apropiat fișier din arbore are prioritate — deci pui în rădăcină ce e valabil peste tot și în fiecare pachet doar specificul lui. Depozitul principal al OpenAI avea 88 de astfel de fișiere la momentul documentării formatului.

Î: E suficient AGENTS.md ca să împiedic agentul să facă ceva periculos? R: Nu. Instrucțiunile sunt context, nu configurație impusă: documentația Claude Code precizează explicit că nu există garanția unei conformări stricte. Interdicțiile care contează se implementează ca reguli de permisiuni, hooks care rulează înainte de acțiune și verificări blocante în integrarea continuă.

Î: Cine scrie și cine întreține fișierul? R: Echipa, la fel ca pe orice fișier versionat: modificările trec prin pull request și prin revizuire. Practic, cel mai bun ritm e adăugarea unei linii atunci când o corecție apare a doua oară, plus o curățare periodică a instrucțiunilor contradictorii — două reguli care se bat cap în cap fac agentul să aleagă arbitrar.

Concluzie

AGENTS.md nu e o tehnologie, ci o convenție: locul previzibil în care scrii ce ar trebui să știe oricine intră în proiect, într-o formă pe care o citesc și uneltele. Formatul e Markdown simplu, e administrat de o fundație neutră și e recunoscut de majoritatea agenților, cu excepția notabilă a Claude Code, care cere o punte de o linie.

Valoarea vine din disciplină, nu din format: linii verificabile, sub 200, crescute din corecții reale, imbricate pe pachete și curățate de contradicții. Iar tot ce trebuie garantat — nu doar sugerat — se mută în permisiuni, hooks și verificări automate.

Surse: agents.md — formatul oficial · Claude Code — CLAUDE.md și memoria proiectului · Documentația GitHub — instrucțiuni pentru depozit · Cursor — reguli de proiect și AGENTS.md

Articol informativ, publicat la 18 septembrie 2026. Uneltele de programare asistată evoluează rapid, iar numele fișierelor și regulile de precedență se pot modifica — verifică documentația oficială a fiecărei unelte la data implementării.