AGENTS.md: projektutasítások, amiket betart az agent

Mi ez, és hol tart a szabvány

Az AGENTS.md a saját meghatározása szerint „README az agenteknek": egy kijelölt, kiszámítható hely a repóban, ahol a projekt kontextusát és szabályait odaadod a kódoló agentnek.

Négy dolgot érdemes tudni az állapotáról 2026 szeptemberében:

• Van mögötte szervezet. A formátumot a Linux Foundation alá tartozó Agentic AI Foundation gondozza, 2025 decembere óta. Az alapító tagok között ott van a legtöbb nagy modellfejlesztő és felhőszolgáltató.
• Elterjedt. Több mint 60 000 nyílt forrású projekt használja, és nagyjából 26 eszköz olvassa.
• Nincs formátuma. „Sima Markdown. Használj bármilyen címsort, az agent egyszerűen elolvassa a szöveget." Kötelező mező nincs, és verziószámozott, normatív specifikáció sem.
• A hely kötött: a repó gyökerében. Beágyazott csomagoknál mindegyikbe kerülhet egy saját.

Az, hogy nincs formátuma, egyszerre a szabvány ereje és gyengesége. Erő, mert öt perc alatt bevezethető. Gyengeség, mert semmi nem mondja meg, mi kerüljön bele — és ettől lesz a legtöbb ilyen fájl használhatatlanul hosszú.

Melyik eszköz melyik fájlt olvassa

Itt van a leggyakoribb buktató, és érdemes szó szerint idézni a gyártói dokumentációt: az egyik nagy terminálos agent a saját fájlját olvassa, az AGENTS.md-t nem.

A megoldás egyszerű, és ezt érdemes bevezetni: egy forrás legyen, a többi hivatkozzon rá. Vagy importtal a másik fájlból, vagy szimbolikus linkkel. Windowson a szimbolikus linkhez rendszergazdai vagy fejlesztői mód kell — ott az import az út.

A precedencia is különbözik. Az egyik eszköznél a személyes utasítás a legerősebb, utána a repó, végül a szervezeti. A másiknál a fájlok nem írják felül egymást, hanem összefűződnek, a gyökértől a munkakönyvtár felé haladva.

Mit tudunk mérésből — és mit nem

Van erről egy 2026-os, konferencián publikált kísérlet, és a módszertana szokatlanul tiszta.

Tíz repó, 124 pull request, párosított összehasonlítás: ugyanaz a feladat, ugyanaz a repóállapot, ugyanaz a kódbázis — egyszer projektutasítás-fájllal, egyszer nélküle. Izolált konténerek, friss checkout a megfelelő commiton. Csak kis változtatások: legfeljebb száz sor, legfeljebb öt fájl.

És most a korlát, ami nélkül ez az egész félrevezető: a helyességet nem mérték. A szerzők annyit erősítettek meg ötven feladat kézi mintáján, hogy „nem üres, nem triviális, a feladathoz illeszkedő kódváltozás" született. A korrektség átfogó kiértékelését jövőbeli munkára hagyták.

Vagyis amit a projektutasítás ma bizonyítottan tud: gyorsabb és olcsóbb lesz tőle az agent, nagyjából egyötöddel. Hogy jobb kódot ír tőle, azt nem bizonyította senki. Ez nem érv ellene — de érv az ellen, hogy minőségbiztosítási eszköznek tekintsd.

Mekkora legyen?

A három nagy gyártó három különböző számot ajánl, és ez önmagában is tanulságos:

• 200 sor alatt fájlonként. Indoklás szó szerint: „a hosszabb fájlok több kontextust fogyasztanak, és csökkentik a betartást."
• 500 sor alatt szabályonként, több komponálható szabályra bontva.
• Két oldal alatt.

A legszigorúbb — 200 sor — mindháromnak megfelel. Kezdd ott.

És van rá független kutatás is, ami megmondja, hol a valódi határ. Egy 2026-os kísérletben öt modellen vizsgálták, mi történik, ha egyre több egyidejű szabályt adnak: 10, 20, 40, 80, 120, 160 szabály, négy különböző formátumban, kétféle elhelyezéssel, modellenként 960 hívással.

Az eredmény: minden modellnél, minden formátumban, nyolcvan szabálynál a „tökéletes válasz" aránya nullára esett. Nem romlott — nullára esett. Százhatvan szabálynál minden modell, minden feltételben nullán állt.

Egy 200 soros fájl nagyjából 30–60 valódi szabályt tartalmaz. Ez épp a határ alatt van — és most már tudod, miért ott van a határ.

Miért nem parancs, hanem javaslat

Ezt a gyártói dokumentáció maga mondja ki, és érdemes komolyan venni:

A projektutasítás-fájl tartalma a rendszerprompt után, felhasználói üzenetként érkezik, nem a rendszerprompt részeként. A modell elolvassa és igyekszik követni, de a szigorú megfelelésre nincs garancia — különösen homályos vagy ellentmondó utasításoknál.

Három gyakorlati következmény:

• Ellentmondó szabályt ne hagyj benne. Ha két szabály ütközik, a modell „önkényesen választhat egyet".
• A túlírt fájl az ellenkezőjét éri el. A dokumentáció szó szerint: a felpuffadt utasításfájl miatt a modell figyelmen kívül hagyja a valódi utasításaidat.
• A kiemeléssel is lehet visszaélni. Ha egy sort következetesen kihagy, tegyél rá hangsúlyt — de „ha sok sort emelsz ki, egyik sem tűnik ki".

Van egy öntesztelő kérdés minden sorra, ami a legjobb szűrő: „Ha ezt kitörölném, hibázna tőle?" Ha nem — töröld.

Ami kötelező, az ne utasítás legyen

Ez a cikk legfontosabb technikai tanácsa, és megint a gyártó fogalmazza meg a legpontosabban:

A projektutasításokkal ellentétben, amelyek tanácsadó jellegűek, a hookok determinisztikusak, és garantálják, hogy a művelet megtörténik.

Vagyis: ha azt akarod, hogy minden commit előtt lefusson a formázó, azt ne írd bele az utasításfájlba. Kösd rá hookként, vagy tedd be a CI-be. Az utasításfájl arra való, hogy a modell értse a projektet — nem arra, hogy kényszerítsd.

A szerkezet, ami skálázódik

1. EGY fájl a repó gyökerében, 200 SOR ALATT.
   Ami mindenre igaz: a projekt célja, a fő parancsok
   (build, teszt, lint), a nem nyilvánvaló konvenciók.

2. AMI CSAK EGY RÉSZRE IGAZ -> útvonalhoz kötött szabály.
   Az API-ra vonatkozó szabály csak akkor töltődjön be,
   amikor az agent API-fájlhoz nyúl. Mindhárom nagy
   eszköznek van erre saját formátuma.

3. AMI KÖTELEZŐ -> hook vagy CI, nem utasítás.

4. AMI ELLENTMOND -> töröld az egyiket. Nem a modell
   dolga eldönteni, melyiket gondoltad komolyan.

5. TÖBB AGENT -> EGY forrás + import vagy symlink.
   Ne tarts karban három fájlt ugyanazzal a tartalommal.

6. FELÜLVIZSGÁLAT negyedévente: minden sorra
   "ha kitörölném, hibázna tőle?"

A 37 oldalas szabályzat, amit senki nem tart be

Van erre egy 2026-os mérés, ami nem kódolásról szól, de pontosan ide tartozik.

Tíz kitalált cég, öt üzleti terület, 65 feladat, és mindegyikhez egy valódi formátumú vállalati szabályzat: 20–124 oldal, medián 37 oldal, PDF-ben, Wordben, HTML-ben. A feladatokhoz összesen 824 programozottan ellenőrizhető elfogadási kritérium tartozott — kötelező és tiltott műveletek.

A szigorú eredmény: a legjobb modell 36,2%-ot ért el, a frontvonalbeli modellek többsége 25% alatt.

És a legbeszédesebb részlet: ha megengedünk feladatonként egyetlen elbukott kritériumot, a pontszámok nagyjából megduplázódnak. Az agentek tehát egy szabályzat által vezérelt munka nagy részét elvégzik — de pont a kritikus kontrollokat hagyják ki.

Ez a legjobb érv amellett, hogy a projektutasítás nem helyettesíti az ellenőrzést. Egy harminchét oldalas szabályzatot a legjobb modell is az esetek kétharmadában megsért legalább egy ponton. Hogy mit érdemes emiatt kézzel átnézni, arról a generált kód átvizsgálása poszt szól.

Tipikus félreértések

• „Az AGENTS.md-t minden eszköz olvassa." Nem. Az egyik nagy agent kifejezetten a saját fájlját olvassa. Egy forrást tarts karban, a többi hivatkozzon rá.
• „Minél részletesebb, annál jobban betartja." Nyolcvan egyidejű szabálynál a tökéletes betartás aránya nullára esik. A túlírt fájl miatt a valódi utasításaid vesznek el.
• „Ha beleírom, akkor meg is csinálja." Tanácsadó jellegű, felhasználói üzenetként érkezik, és a szigorú megfelelésre nincs garancia. Ami kötelező, az hook vagy CI.
• „Jobb kódot ír tőle." A mérés 20% token- és időmegtakarítást mutatott. A helyességet nem mérték.
• „Ha mindent kiemelek, mindent betart." „Ha sok sort emelsz ki, egyik sem tűnik ki."

Amit érdemes elvinni

A projektutasítás gyorsabbá és olcsóbbá teszi az agentet, nem pontosabbá. Egy fájl legyen, a repó gyökerében, kétszáz sor alatt; ami csak a kód egy részére vonatkozik, az útvonalhoz kötött szabályba menjen; ami kötelező, az hookba vagy CI-be. És minden sorra tedd fel a kérdést: ha kitörölném, hibázna tőle?

Az első éles feladat kiszabásáról az első feladat egy agenttel poszt szól; arról pedig, hogy hol fusson mindez, a fejlesztői környezet választása poszt.