Problema: de ce AI-ul dă greș mereu în același loc

Oricine a folosit Cursor, Windsurf sau Claude Code pentru un proiect a trăit același moment de frustrare: AI-ul scoate un bloc întreg de cod, îl copiezi, îl rulezi — build-ul crăpă, testele sunt roșii, dependențele ajung în folderul greșit. Problema nu e inteligența AI-ului, ci faptul că habar n-are de „regulile nescrise” ale proiectului tău.

AGENTS.md e un fișier Markdown plasat în rădăcina proiectului, scris special pentru AI: îi spune cum să facă build-ul, cum să ruleze testele, ce convenții de cod respectă. README.md e pentru oameni — istoria proiectului, ghid de contribuție, povești despre brand. Când AI-ul citește chestiile astea, e ca un angajat nou care primește în prima zi un pliant de marketing și e pus imediat să scrie cod — știe ce face compania, dar nu știe comanda de build, nu știe cum rulează testele, habar n-are de regulile ESLint. Rezultatul: corectezi în conversație iar și iar — „folosește pnpm, nu npm”, „testele sunt în packages/web”, „nu uita să rulezi lint”. Corectezi de o sută de ori, proiectul tot e varză.

În freelance, pierderea e directă: ai luat un contract extern pe Next.js + Prisma, folosești Cursor ca să accelerezi, iar AI-ul instalează cu npm install, distrugând configurația de workspace din pnpm. Nu știe unde e schema bazei de date, fișierele de migration generate explodează. Clientul presează, tu pierzi trei ore depanând codul generat de AI — bani câștigați cu noduri în stomac.

Trei scenarii clasice în care AI-ul calcă strâmb: ① Manager de pachete greșit (proiectul folosește pnpm, AI-ul default-ează pe npm install), dependențele ajung în altă parte, workspace-ul moare; ② Testele nu sunt găsite (testele stau în packages/web, AI-ul rulează pnpm test din rădăcină și primește „no test files found”); ③ Stil de cod inconsistent (proiectul folosește ESLint + Prettier, codul generat are indentare și ghilimele greșite, CI-ul pică).

Oportunitatea: AGENTS.md separă net documentația pentru oameni de cea pentru mașini

Proiectul open-source AGENTS.md de pe GitHub (repo github.com/agentsmd/agents.md, ~24.000 de stele la 2026-08-25) rezolvă exact problema asta. Ideea e simplă: pui un fișier Markdown în rădăcina proiectului, prin care îi spui AI-ului cum să construiască, cum să testeze, ce stil de cod să respecte.

Nu înlocuiește README-ul, îl completează. README-ul servește contributorilor umani, AGENTS.md servește agenților AI. Responsabilități clare, fără suprapuneri.

Potrivit sursei, AGENTS.md a fost adoptat de zeci de mii de proiecte open-source (cifrele exacte rămân de verificat), acoperind VS Code, Cursor, Windsurf, Aider, GitHub Copilot și alte unelte majore de programare AI (confirmat); conform feedback-ului din comunitate, OpenAI Codex și Google Jules oferă și ele suport (⚠️ neconfirmat). Dacă nu înveți acum, lași AI-ul să-ți vorbească pe dialect propriu.

Traseul 1: Scrie un AGENTS.md minim utilizabil

Costul e aproape zero. Fișier nou, trei secțiuni și gata.

Context rapid: exemplele de mai jos folosesc pnpm (mai economic la disc decât npm, suportă workspace-uri monorepo), turbo e orchestratorul de task-uri pentru monorepo, parametrul --filter țintește un singur sub-pachet fără să atingă restul repo-ului.

Secțiunea 1 — „Dev environment tips”: îi spui AI-ului ce manager de pachete folosești, cum navighezi între sub-pachete, cum creezi un modul nou. Din exemplul oficial:

• pnpm dlx turbo run where <project_name> — sare direct în directorul sub-pachetului dorit, fără ls prin zeci de foldere
• pnpm install --filter <project_name> — instalează dependențele doar pentru un sub-pachet, fără să atingă întregul monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — creează un sub-pachet React + Vite cu verificare TypeScript

Comenzile astea AI-ul nu le ghicește singur, dar scrise în fișier le execută întocmai.

Secțiunea 2 — „Testing instructions”: cum rulezi testele, unde e planul CI, ce verificări rulezi înainte de commit. Exemplul oficial include:

• pnpm turbo run test --filter <project_name> — rulează toate verificările pentru un sub-pachet
• pnpm vitest run -t "<test name>" — rulează un singur test care se potrivește cu numele
• „Fix any test or type errors until the whole suite is green” — nu te opri până nu e totul verde
• „Add or update tests for the code you change, even if nobody asked” — linia asta e cheia; fără ea, AI-ul sare frecvent peste teste

Secțiunea 3 — „PR instructions”: formatul titlului de commit, obligativitatea lint-ului și testelor. Exemplul oficial: Title format: [<project_name>] <Title> și „Always run pnpm lint and pnpm test before committing”.

Cele trei secțiuni ocupă sub 50 de linii, dar rata de „first-time-right” a codului generat crește vizibil (conform feedback-ului din comunitate, cifrele exacte rămân de verificat).

Traseul 2: Implementează AGENTS.md imbricat într-un monorepo mare

Dacă lucrezi la proiecte enterprise cu structură monorepo (mai multe proiecte conexe în același repo Git — frontend, backend, cod partajat, fiecare în sub-directorul lui), un singur AGENTS.md nu ajunge. AGENTS.md suportă imbricarea: pui câte un fișier în fiecare sub-director, iar AI-ul citește automat „cel mai apropiat” de el.

Cum se face concret: AGENTS.md din rădăcină conține regulile globale (manager de pachete, flux CI, note de securitate), apoi pui câte unul în packages/web/, packages/api/, packages/shared/ cu comenzile specifice acelui sub-pachet, intrările de test, dependențele speciale. De exemplu, pachetul frontend scrie „biblioteca de componente e shadcn, stilizarea cu Tailwind, iconițe cu lucide-react”; pachetul backend scrie „migration-urile cu Prisma, rutele API în src/routes, autentificare cu JWT”.

Când AI-ul lucrează într-un sub-director, încarcă automat AGENTS.md-ul cel mai apropiat, cu prioritate față de cel din rădăcină. Rezultatul: asistentul AI pentru frontend și cel pentru backend primesc instrucțiuni complet diferite, fără să se contamineze reciproc.

Traseul 3: Transformă-l în avantaj competitiv pe freelance

Piața de freelance cu AI e deja un câmp de luptă — toată lumea știe să deschidă Cursor, dar calitatea livrabilelor variază enorm. Dacă în ofertă scrii o propoziție de genul „Proiectul include configurare AGENTS.md, dezvoltarea asistată de AI respectă standardele proiectului”, câștigi mai ușor decât concurența care zice doar „folosesc AI pentru cod”.

Tactica concretă: după ce semnezi contractul, alocă 30 de minute ca să înțelegi structura proiectului clientului, apoi scrie un AGENTS.md personalizat. Documentul ăsta e parte din livrabil — clientul îl păstrează, iar mentenanța viitoare cu AI devine mult mai lină.

Pune serviciul de configurare AGENTS.md ca linie separată pe lista de prețuri (adaptată la piața locală): varianta de bază ~70 EUR (configurare pentru un singur fișier + README explicativ), varianta enterprise ~400 EUR (configurare imbricată monorepo + politici de securitate + training de echipă). Ce primește clientul: ① fișierul AGENTS.md personalizat ② 30 de zile de suport pe chat ③ un screencast de 10 minute cu instruire. Se potrivește pentru: clienți care au deja abonament Cursor/Windsurf dar nu le iese treaba. Nu se potrivește pentru: clienți care încă lucrează exclusiv manual, fără unelte AI.

Studiu de caz: zidul de apărare al compatibilității AGENTS.md

AGENTS.md e licențiat MIT (confirmat), întreținut de comunitate (structura de guvernare rămâne de verificat), site oficial agents.md.

Compatibilitatea e cel mai mare avantaj competitiv: confirmat că VS Code, Cursor, Windsurf, Aider și GitHub Copilot citesc AGENTS.md; conform feedback-ului din comunitate, OpenAI Codex, Claude Code, Gemini CLI și Google Jules oferă și ele suport (⚠️ neconfirmat). Scrii un singur fișier, îl folosesc toate uneltele majore — nu mai trebuie configurații separate pentru fiecare.

Compară cu alternativele: .cursorrules din Cursor merge doar în Cursor, în Windsurf nu face nimic; CLAUDE.md din Claude Code servește doar Claude; sistemul de instrucțiuni din GitHub Copilot e altă poveste. Principiul „scrie o dată, rulează peste tot” e motivul pentru care AGENTS.md a fost adoptat atât de rapid.

Costul de migrare între unelte dispare. Azi lucrezi în Cursor, mâine treci pe Windsurf — AGENTS.md se refolosește fără rescrieri.

Apel la acțiune: pune-i proiectului un manual pentru mașină în seara asta

Checklist de 5 minute: ① Deschide rădăcina proiectului ② Creează AGENTS.md ③ Copiază șablonul oficial (github.com/agentsmd/agents.md) ④ Completează trei comenzi (build, test, lint) ⑤ La următoarea sesiune cu AI, observă diferența.

Dacă lucrezi în monorepo, alocă încă 20 de minute diseară pentru configurări imbricate în fiecare sub-pachet. Mâine, când deschizi laptopul, codul generat de AI nu mai are nevoie de corecturi repetate.

AGENTS.md are cel mai bun raport timp-investit / timp-economisit din tot ce ține de configurarea AI pentru programare — 30 de minute investite, câteva ore de depanare economisite în fiecare lună.