eugenemind.com
← Înapoi la blog

24 octombrie 2026 · 10 min. de citit

AGENTS.md pentru Codex și Claude Code. Ce scriem în instrucțiuni și ce mutăm în Skills

#codex #claude-code #coding-agents #agents-md #context-engineering #skills

Un agent AI poate să înțeleagă destul de bine codul și totuși să propună o soluție nepotrivită pentru proiect.

Să presupunem că trebuie modificată interfața unei biblioteci interne. În locul unei schimbări mici, agentul introduce metode marcate deprecated, straturi de compatibilitate și un întreg plan de migrare. Biblioteca este însă folosită doar de câteva aplicații, iar toate pot fi actualizate în același timp.

Se întâmplă și invers. Agentul modifică un API public fără să țină cont că dezvoltatorii din afara echipei depind de el.

Nu înseamnă neapărat că modelul scrie cod prost. Unele constrângeri ale proiectului pur și simplu nu pot fi deduse din surse. De aici vine interesul pentru AGENTS.md. Mi-ar plăcea ca agentul să cunoască dinainte particularitățile importante ale repository-ului, fără să fie nevoie să întreținem încă un document uriaș.

Cum funcționează AGENTS.md

În esență, AGENTS.md este un fișier Markdown obișnuit. Putem descrie scopul proiectului, limitele sale și convențiile de care agentul trebuie să țină cont atunci când modifică codul.

Diferența este că instrumente precum Codex și Claude Code pot găsi aceste fișiere și pot folosi conținutul lor drept instrucțiuni suplimentare pentru model. Astfel, nu trebuie să repetăm aceleași reguli în fiecare prompt.

De obicei, AGENTS.md se află în rădăcina repository-ului. Dacă este nevoie, putem adăuga fișiere mai specifice în anumite module.

De exemplu:

MyApp/
├── AGENTS.md
├── Sources/
├── Features/
└── MyAppUI/
    └── AGENTS.md

Fișierul din rădăcină descrie constrângerile generale ale aplicației. Cel din MyAppUI conține reguli valabile pentru biblioteca respectivă.

Atât Codex, cât și Claude Code acceptă AGENTS.md, dar mecanismele de încărcare diferă puțin. Codex ține cont de ierarhia fișierelor în raport cu directorul de lucru. Claude Code poate folosi AGENTS.md, păstrând în același timp propriul format CLAUDE.md.

Dacă în proiect există ambele fișiere, merită verificate setările și regulile de prioritate. Acest lucru contează mai ales când membrii echipei folosesc agenți AI diferiți.

Totuși, AGENTS.md nu este un linter. Modelul primește instrucțiunile, dar nimic nu garantează că le va respecta pe toate. În plus, conținutul ocupă spațiu în context și poate crește consumul de tokenuri.

Mecanismul este simplu. Oferim agentului câteva informații despre proiect înainte să înceapă lucrul, iar el le folosește împreună cu cererea curentă și cu ceea ce găsește în cod.

Întrebarea mai dificilă este ce informații merită puse acolo.

Ce merită scris în AGENTS.md

Agenții moderni pot deja să exploreze un repository. Pot deschide Package.swift, găsi testele, inspecta dependențele și înțelege relațiile dintre componente.

De aceea, n-aș folosi AGENTS.md ca să descriu în detaliu tot ce există în proiect. Mai ales când informațiile pot fi găsite ușor în cod.

Mai utile sunt lucrurile care s-ar putea să nu apară deloc în surse.

Să ne imaginăm un repository separat, MySDK. Este o bibliotecă Swift publică, distribuită dezvoltatorilor externi prin Swift Package Manager.

În acest caz, AGENTS.md poate începe cu doar câteva rânduri:

# Project

MySDK is a public Swift SDK distributed
through Swift Package Manager.

Third-party applications depend on its public API.

## Constraints

- Preserve public API compatibility.
- Do not introduce breaking changes without approval.
- Keep the SDK independent of application-specific code.

Nu e nimic complicat aici. Dar când agentul modifică o metodă publică, are deja un motiv să se gândească la compatibilitate.

Dacă MySDK ar fi o bibliotecă internă, regulile ar putea fi diferite.

De exemplu, echipa controlează toate aplicațiile care folosesc SDK-ul și le lansează coordonat. Uneori este mai simplu să modifici interfața și să actualizezi consumatorii decât să păstrezi vechiul API doar pentru compatibilitate.

Desigur, nu toate bibliotecile interne funcționează așa. Dacă există zeci de aplicații cu cicluri de lansare independente, cerințele de compatibilitate pot fi aproape la fel de stricte ca pentru un SDK public.

Tocmai aceste diferențe merită documentate.

Agentul poate vedea cum este implementată o metodă. Îi este mult mai greu să deducă cât de liber o poate modifica.

La fel stau lucrurile și cu arhitectura. Dacă proiectul are constrângeri stabile, care nu sunt evidente din cod, are sens să le explicăm. O listă completă cu toate clasele, ecranele și dependențele actuale este mult mai puțin utilă.

Iar lungimea fișierului nu este singura problemă.

De ce instrucțiunile lungi pot încurca

AGENTS.md poate ajunge foarte ușor în aceeași situație ca documentația tradițională a proiectului.

La început este un fișier scurt, cu câteva reguli. Apoi agentul face o greșeală și cineva adaugă o instrucțiune. Peste o săptămână introduce o abstracție inutilă, așa că apare încă o regulă. În timp se adună secțiuni despre teste, tratarea erorilor, denumiri și refactorizare.

În final, documentul ajunge la câteva sute de rânduri.

Problema este că agentul poate primi o mare parte din aceste instrucțiuni chiar și atunci când sarcina nu are nicio legătură cu ele.

Merită să ne uităm și la cercetările pe această temă.

În februarie 2026, cercetătorii de la ETH Zürich au publicat Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

Au analizat influența instrucțiunilor din repository asupra agenților de programare. În condițiile experimentelor, fișierele generate automat au redus ușor rata de succes, iar cele scrise de dezvoltatori au adus doar îmbunătățiri modeste. Costurile de inferență au crescut cu aproximativ 20% sau mai mult.

Agenții chiar au urmat instrucțiunile. Au explorat mai mult codul, au efectuat operații suplimentare și au rulat mai multe verificări. Dar aceste activități nu au dus întotdeauna la rezultate mai bune.

Un alt studiu, On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents, publicat în ianuarie 2026, a raportat o reducere de 28,64% a timpului median de finalizare a sarcinilor.

Metodologiile au fost diferite, deci rezultatele nu pot fi comparate direct. Totuși, ele arată că simpla prezență a unui AGENTS.md nu garantează o îmbunătățire.

În ianuarie 2026, Matt Pocock a propus și el o curățenie în fișierele AGENTS.md și CLAUDE.md. Recomandarea era să eliminăm contradicțiile, sfaturile evidente și regulile care nu trebuie încărcate pentru fiecare sarcină.

E greu să nu fii de acord când vezi instrucțiuni de acest fel:

## Guidelines

- Write clean code.
- Follow SOLID principles.
- Use meaningful names.
- Avoid bugs.

Toate sunt recomandări corecte, dar nu spun aproape nimic despre proiectul concret.

Pe de altă parte, nici n-aș elimina complet contextul proiectului. Câteva rânduri despre scopul repository-ului și limitele API-ului public pot fi mai utile decât pagini întregi de recomandări generale.

Mai există un motiv să evităm instrucțiunile prea detaliate. Cu timpul, devin învechite.

Să presupunem că descriem în AGENTS.md arhitectura aplicației, navigația, ecranele principale și locul în care se află serviciile.

După câteva luni, unele module sunt rescrise, navigația se schimbă, iar anumite componente sunt mutate într-un Swift Package separat.

Codul este altul, dar fișierul de instrucțiuni rămâne neschimbat.

Acum agentul primește o descriere învechită și s-ar putea să se bazeze pe ea în loc să studieze implementarea actuală.

Situația este și mai neplăcută în aplicațiile mari, cu arhitecturi diferite. Un modul folosește SwiftUI, altul UIKit, iar un al treilea are propria soluție de navigație.

Dacă impunem în AGENTS.md din rădăcină o singură arhitectură pentru întreaga aplicație, putem crea mai multe probleme decât rezolvăm.

Aș prefera instrucțiuni scurte și suficient de stabile încât să nu necesite actualizare după fiecare refactorizare.

Instrucțiuni separate pentru module

Să revenim la MyApp.

Să presupunem că aplicația este destul de mare încât să aibă propria bibliotecă de componente UI, MyAppUI.

MyApp/
├── AGENTS.md
├── App/
├── Features/
│   ├── Checkout/
│   └── Vouchers/
└── Packages/
    ├── MyAppUI/
    │   └── AGENTS.md
    └── MyAnalytics/
        └── AGENTS.md

În AGENTS.md din rădăcină putem descrie aplicația și câteva constrângeri generale.

În MyAppUI putem preciza că aceste componente sunt reutilizabile și nu trebuie să depindă de anumite ecrane ale aplicației.

# MyAppUI

This package contains reusable UI components
used across multiple application features.

## Constraints

- Keep components independent of feature-specific logic.
- Avoid dependencies on application navigation.
- Preserve existing component APIs unless a change is approved.

Pentru MyAnalytics, regulile vor fi altele. De exemplu, modulul nu ar trebui să depindă de UI sau să conțină logica de business a unor funcționalități individuale.

Avantajul este că instrucțiunile rămân lângă partea de proiect la care se referă. Dacă regulile pentru MyAppUI se schimbă, nu trebuie rescris fișierul principal al aplicației.

Totuși, n-aș crea un AGENTS.md în fiecare director. Un fișier separat are sens doar când există constrângeri locale importante. Altfel, înlocuim un document mare cu zece documente mici, care necesită la fel de multă întreținere.

Același principiu se aplică și repository-urilor separate.

Dacă MyApp, MyAppUI și MySDK sunt proiecte independente, fiecare poate avea propriul AGENTS.md. Scopurile și constrângerile lor sunt diferite.

Dar nu mi-ar plăcea să copiez aceleași reguli detaliate de testare sau refactorizare în toate trei. Mai devreme sau mai târziu, copiile vor începe să difere.

Aici intră în discuție Skills.

Ce merită mutat în Skills

Să presupunem că proiectele Swift ale echipei urmează aceleași reguli pentru unit testing. Există convenții pentru fixtures, mocks, teste asincrone și Swift Testing.

Am putea descrie toate acestea pe câteva pagini în AGENTS.md.

Dar de ce ar trebui agentul să citească instrucțiuni detaliate despre testare când modifică doar o componentă UI?

Pentru astfel de proceduri, Skills sunt mai potrivite.

.agents/
└── skills/
    ├── swift-testing/
    │   └── SKILL.md
    ├── api-compatibility/
    │   └── SKILL.md
    └── code-quality/
        └── SKILL.md

Un Skill conține metadate care explică în ce situații este util, împreună cu instrucțiunile detaliate. Agentul poate identifica Skill-ul relevant după descriere și îi poate încărca apoi conținutul atunci când are nevoie.

Astfel, procedurile întregi nu mai trebuie să ocupe permanent spațiu în context.

De exemplu, swift-testing poate descrie regulile de testare ale echipei. code-quality poate acoperi lizibilitatea, tratarea erorilor și refactorizarea. Iar api-compatibility poate conține pașii pentru verificarea interfețelor publice.

În funcție de instrument și de modul de instalare, același Skill poate fi reutilizat în mai multe repository-uri.

Există însă o limită importantă între AGENTS.md și Skills.

Dacă repository-ul conține un SDK public, agentul trebuie să știe că păstrarea compatibilității API este obligatorie, indiferent dacă a decis sau nu să încarce un Skill dedicat.

De aceea, aș lăsa această constrângere în AGENTS.md și aș muta procedura detaliată de verificare într-un Skill.

Mecanismul nu este perfect. Agentul poate să nu aleagă Skill-ul potrivit, iar instrumentele diferă în felul în care le descoperă și le încarcă. Totuși, separarea contextului permanent de procedurile specifice unei sarcini mi se pare o idee bună.

Cine ar trebui să scrie AGENTS.md

Ar trebui să-i cerem agentului să genereze singur AGENTS.md?

Pare convenabil. Poate analiza repository-ul, identifica anumite tipare arhitecturale și pregăti un draft în câteva minute.

Dar există o problemă. Agentul vede codul existent fără să știe întotdeauna ce decizii mai consideră echipa corecte și ce a rămas dintr-o arhitectură veche.

Să presupunem că proiectul are multe clase al căror nume se termină în Manager. Modelul poate concluziona că este o convenție de denumire și o poate transforma într-o regulă.

De fapt, echipa poate încerca de mult timp să renunțe la astfel de nume.

Același lucru se întâmplă cu singleton-urile, tiparele arhitecturale și împărțirea în module. Faptul că o soluție există în repository nu înseamnă că trebuie repetată.

Aș folosi fără probleme AI pentru un draft. De exemplu, i-aș cere să propună posibile constrângeri și să indice codul sau documentația pe care se bazează fiecare propunere.

Dar aș verifica și edita personal textul final.

Nici n-aș adăuga o regulă după fiecare sarcină ratată. Dacă agentul introduce o abstracție inutilă, mai întâi trebuie înțeles motivul. Poate este suficient un prompt mai clar sau o trimitere la o implementare existentă.

Merită actualizat AGENTS.md atunci când aceeași greșeală se repetă din cauza unei constrângeri stabile a proiectului, pe care agentul chiar trebuie să o cunoască dinainte.

Concluzii

AGENTS.md funcționează cel mai bine când e scurt și descrie doar scopul repository-ului și constrângerile care nu se văd în cod. Procedurile detaliate merită mutate în Skills, iar o ciornă generată de AI trebuie verificată de un om.

Merită verificat și dacă ajută cu adevărat. Ajunge să compari câteva sarcini tipice cu și fără instrucțiuni. Dacă nu există nicio diferență, nu are rost să întreții fișierul.

Lecturi suplimentare

Articole similare