Blog

Mi az az AGENTS.md, és hogyan írhatod meg a sajátodat 30 perc alatt

Markdown

Az AGENTS.md formátuma, támogatása az AI-eszközökben, egy kész sablon, szabályok és gyakori hibák. Az AGENTS.md összehangolása a CLAUDE.md-vel és más utasításfájlokkal.

A teljes cikk elolvasása

Gyakorlati anyagok a vibe codingról és az ügynökökkel való munkáról: Ailoot-dokumentáció.

Az AGENTS.md egy bekezdésben

A lényeg

Az AGENTS.md egy egyszerű Markdown-fájl a projekted gyökerében, amely utasításokat tartalmaz egy AI-ügynök számára: hogyan telepítse a függőségeket, hogyan futtassa a teszteket, milyen kódstílust kövessen, és mihez ne nyúljon. A formátum nyílt, az OpenAI hozta létre 2025 augusztusában, és ugyanazon év decemberében csatlakozott a Linux Foundationhöz. Sok kódolóeszköz használhatja, de a felismerés módja kliensenként és verziónként eltér: némelyik automatikusan betölti az AGENTS.md-t, másoknál külön fájlnév- vagy fájlolvasási beállítás kell. A 2.1.277-es verzió óta (2026 szeptemberétől) a Claude Code is olvassa az AGENTS.md-t, ha a projektben nincs CLAUDE.md. Ha van CLAUDE.md, a Claude Code alapértelmezés szerint csak azt olvassa, az AGENTS.md pedig a @AGENTS.md sorral vagy szimbolikus hivatkozással illeszthető be.

Az alábbiakban a formátumot az agents.md, az OpenAI Codex dokumentációja, a JetBrains Junie, a Cursor Rules Docs, a GitHub Copilot Coding Agent changelogja és a Linux Foundation Agentic AI Foundationről szóló sajtóközleménye alapján tekintjük át. Minden adat és funkció 2026. május 30-i állapotot tükröz; a Claude Code AGENTS.md-támogatását az Anthropic dokumentációja alapján ismertetjük, a 2026. szeptember 24-i frissítéssel.

Ha nem tudod, mi ez a piacon lévő eszközállatkert, vagy miért van szükségük közös fájlra, először olvasd el a „Mivel kódoljunk 2026-ban: 8 AI-eszköz a Claude Code-tól az Antigravityig” című útmutatót. Ez a cikk kifejezetten az AGENTS.md formátumáról és a saját fájl 30 perc alatt történő megírásáról szól.

Mi az az AGENTS.md, és honnan származik?

A lényeg

Az AGENTS.md egy nyílt Markdown-fájlformátum, amelyben magad írhatsz utasításokat az AI-ügynököknek. Az OpenAI 2025 augusztusában adta ki a Codex CLI-vel együtt, és azonnal társszerzőket hívott meg: a Cursort, a Sourcegraph Ampet, a Google Jules-t és a Factoryt. Az ötlet egyszerű: „ne hozzunk létre minden eszközhöz külön, saját fájlt; állapodjunk meg egy közösben.” 2025. december 9-én az AGENTS.md az Anthropic MCP-jével és a Block goose-ával együtt a Linux Foundationhöz került az új Agentic AI Foundation három alapító projektjének egyikeként. Ugyanazon év decemberére már több mint 60 000 GitHub-adattár gyökerében szerepelt AGENTS.md.

Korábban minden AI-eszköznek saját szabályfájlja volt: az Anthropicé a CLAUDE.md, a Cursoré a .cursorrules, a GitHubé a .github/copilot-instructions.md, az Aideré az .aider.conf.yml, a JetBrainsé pedig a .junie/guidelines.md volt. Ha a csapatod három különböző ügynököt használt, az három párhuzamos, azonos tartalmú fájlt jelentett, amelyek egy héten belül eltértek egymástól.

Az OpenAI unta meg ezt elsőként. 2025 augusztusában kiadta a Codex CLI-t, és ezzel egy időben nyílt formátumként elindította az agents.md-t. A webhelyen ez olvasható:

„Tekints az AGENTS.md-re úgy, mint az ügynökök README-fájljára.”

(agents.md, fordítás angolból)

A lényeg az, hogy az AGENTS.md kiegészíti a README-t. A README embereknek szól: „mi a projekt, hogyan futtatható helyben, hogyan lehet hozzájárulni.” Az AGENTS.md az ügynöknek szól: pontos shell-parancsok, ellenőrizhető „kész” feltételek és olyan határok, mint „ehhez soha ne nyúlj.”

A webhelyről:

„Az AGENTS.md kiegészíti a README-t: olyan további, olykor részletes kontextust tartalmaz, amelyre az ügynöknek szüksége van — buildlépéseket, teszteket és olyan konvenciókat, amelyek túlzsúfolnák a README-t, vagy egyszerűen nem szükségesek az emberi közreműködőknek.”

(agents.md, fordítás angolból)

2025 szeptemberére a GitHub Copilot Coding Agent is támogatta a formátumot (changelog, 2025.08.28.). Decemberre a Cursor, a Junie, a Gemini CLI, az Aider és még egy tucat eszköz csatlakozott. 2025. december 9-én a Linux Foundation létrehozta az Agentic AI Foundationt (AAIF): három alapító projektje az OpenAI AGENTS.md-je, az Anthropic MCP-je és a Block goose-a volt. Az alapító tagok az AWS, az Anthropic, a Block, a Bloomberg, a Cloudflare, a Google, a Microsoft és az OpenAI voltak. 2026. február 24-re az alapítványnak már 146 szervezeti tagja volt, köztük a Red Hat, a ServiceNow, az Akamai, a Lenovo, a JPMorgan Chase, a Huawei, az UiPath és a Hitachi.

Ettől kezdve az AGENTS.md nem „egy újabb OpenAI-dolog” volt, hanem de facto szabvány.

Mely AI-ügynökök olvassák az AGENTS.md-t, és melyek nem?

A lényeg

Az AGENTS.md-t sok kódolóeszköz használja, köztük az alábbi táblázat kliensei. A táblázat a betöltési módokat mutatja, nem azonos natív támogatást ígér: az automatikus felismerés, a külön beállítás, a fájlnevek elsőbbsége és a beágyazott fájlok kezelése eltérhet. Az Anthropic Claude Code-ja sokáig kivétel volt: a támogatást kérő #6235-ös issue 2025 augusztusától 2026 augusztusáig nyitva maradt. A 2.1.277-es verzió óta (2026. szeptember 18-tól) a Claude Code önállóan olvassa az AGENTS.md-t, ha a projektben nincs CLAUDE.md. Ha van CLAUDE.md, alapértelmezés szerint csak azt olvassa, az AGENTS.md pedig a CLAUDE.md-ben található @AGENTS.md sorral vagy szimbolikus hivatkozással illeszthető be.

A támogatási táblázat 2026. május 30-i állapotot mutatja; a Claude Code sora 2026. szeptember 24-én frissült:

EszközOlvassa az AGENTS.md-tDátum / forrás
OpenAI Codex CLIIgen (natív formátum)2025 augusztusa, agents.md
GitHub Copilot Coding AgentIgen2025.08.28., GitHub Changelog
CursorIgen, gyökér- és beágyazott fájlokCursor Rules Docs
JetBrains JunieIgen, projekt- és globális ~/.junie/AGENTS.mdJunie Docs
Gemini CLI (Google)Igen, a .gemini/settings.json fájlon keresztül, fileName: AGENTS.md beállítássalagents.md
Jules (Google)Igen, a szabvány társszerzője2025 augusztusa
Sourcegraph AmpIgen, a szabvány társszerzője2025 augusztusa
AiderIgen, az .aider.conf.yml fájlban megadott read: AGENTS.md révénagents.md
FactoryIgen, a szabvány társszerzője2025 augusztusa
OpenCodeIgen—
ZedIgenagents.md
WarpIgenagents.md
VS CodeIgenagents.md
WindsurfIgen—
Devin (Cognition)Igen, Spec Kit Skills révén2026 áprilisa
RooCode, Kilo Code, Augment CodeIgenagents.md
Claude Code (Anthropic)Igen, ha a projektben nincs CLAUDE.mdA 2.1.277-es verzió óta (2026.09.18.), Claude Code-dokumentáció

Az Anthropic csatlakozott utolsóként a nagy szereplők közül. 2025 augusztusában a hivatalos anthropics/claude-code adattárban megnyílt a #6235-ös issue, amely az AGENTS.md támogatását kérte.

Az issue majdnem egy évig nyitva maradt, és 2026. augusztus 17-én zárták le; az AGENTS.md-támogatást hozó 2.1.277-es verzió szeptember 18-án jelent meg. Az Anthropic logikája a következő: a CLAUDE.md elsőbbséget élvez, az AGENTS.md pedig akkor olvasható, ha sem a munkamappában, sem annak szülőmappáiban nincs CLAUDE.md. A dokumentáció szerint így működik:

Mi található a projektbenMit olvas a Claude Code
Csak AGENTS.mdAGENTS.md
AGENTS.md és CLAUDE.md (vagy CLAUDE.local.md)Csak CLAUDE.md
CLAUDE.md a @AGENTS.md sorralA CLAUDE.md-t, amely beemeli az AGENTS.md-t

A bökkenő: a személyes CLAUDE.local.md is számít, és ha ilyen van, a Claude Code nem olvassa tovább az AGENTS.md-t. Ezt a viselkedést a /config menü Project instructions részében módosíthatod — például beállíthatod, hogy a Claude Code mindkét fájlt egyszerre olvassa. A 2.1.277-nél régebbi verziók automatikusan nem veszik figyelembe az AGENTS.md-t; a CLAUDE.md-ben szereplő @AGENTS.md sor továbbra is megoldást jelent.

Miben különbözik az AGENTS.md a CLAUDE.md-től és a .cursorrules-tól?

A lényeg

Technikailag semmi különleges nincs bennük: mind a négy formátum (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md) egyszerű Markdown-fájl ügynököknek szóló utasításokkal. A különbség az, hogy ki olvassa őket, és hol találhatók. Az AGENTS.md több kliens közös utasításait tárolhatja, miközben a kliensenkénti felismerést vagy konfigurációt külön tartjuk. A CLAUDE.md csak a Claude Code-hoz készült, viszont hozzáférést ad a fejlett funkciókhoz: útvonalhoz kötött szabályokhoz, személyes felülírásokra szolgáló CLAUDE.local.md-hez, más fájlok beemelésére szolgáló @import-hoz, valamint projekt-, felhasználói és helyi hierarchiához. A .cursorrules elavult a Cursorban — az új rendszer a .cursor/rules/*.mdc fájlokat használja, automatikus hozzárendeléssel fájltípus alapján. A .github/copilot-instructions.md csak a webes Copilothoz szükséges.

A négy formátum összehasonlítása 2026. május 30-i állapot szerint:

FormátumKi olvassa?Hol található?ErősségGyengeség
AGENTS.mdTöbb kliens; a betöltés klienstől/verziótól függRepógyökér és beágyazott fájlok a kliens szabályai szerintKözös utasítástartalom, kliensenként beállított betöltésselA felismerést, hierarchiát és elsőbbséget minden kliensnél külön ellenőrizni kell
CLAUDE.mdCsak Claude CodeGyökér + ~/.claude/CLAUDE.md + CLAUDE.local.mdHierarchia, útvonalhoz kötött szabályok, @import, skills, hooksCsak Claude. Nem működik Cursorban / Codexben / Copilotban
.cursor/rules/*.mdcCsak Cursor.cursor/rules/<rule>.mdcAutomatikus hozzárendelés fájltípus szerint (TS, Python, konkrét útvonalak)Csak Cursor, nem szabványos .mdc szintaxis
.github/copilot-instructions.mdGitHub Copilot (webes + klasszikus).github/Közvetlenül a GitHub.com böngészőjében működikCsak Copilot, megkettőzi az AGENTS.md-t

A fő gondolat: az AGENTS.md közös projektutasításokat tárolhat, miközben minden kliens betöltési módja és személyes beállításai külön konfigurációt igényelnek. A Claude Code erre a célra a CLAUDE.local.md-t használja, a Cursornál pedig vannak a felhasználóhoz tartozó helyi .mdc fájlok. Az AGENTS.md önmagában ezt nem biztosítja — más fájlokkal kell kombinálnod, vagy csapatként meg kell állapodnotok abban, hogy a személyes szabályokat Git által figyelmen kívül hagyott részekben írjátok le.

Egy másik fontos részlet a monorepók kezelése. A Codex és a Cursor is azt a szabályt alkalmazza, hogy „a legközelebbi AGENTS.md érvényesül”:

„Monorepóban minden csomagba tegyél külön AGENTS.md-t. Az ügynökök automatikusan a könyvtárfa legközelebbi fájlját olvassák, és a legközelebbi érvényesül.”

(agents.md, fordítás angolból)

Az agents.md megemlíti, hogy az OpenAI fő monorepójában 88 AGENTS.md-fájl található a különböző alcsomagokhoz. Ha monorepón dolgozol, oszd el a szabályokat a szintek között: általános szabályok a gyökérben, konkrétak az almappákban.

Mit tartalmazzon egy jó AGENTS.md?

A lényeg

Egy jó AGENTS.md vázlata 8, a legtöbb népszerű fájlban megtalálható részből áll: a projekt áttekintése, beállítási parancsok, kódstílus, tippek a fejlesztői környezethez, tesztelési útmutató, PR-irányelvek, biztonsági szempontok és korlátok (mit nem szabad tenni). Minden más opcionális. A fő szabály: minden pont legyen pontos parancs vagy konkrét példa, ne olyan általános gondolat, mint „írj tiszta kódot”.

Az agents.md webhely rugalmas formátumot kínál — „bármilyen Markdown” megfelel. A gyakorlatban azonban a jó fájlok 80%-a ugyanazt a nyolc részt tartalmazza. A fő szabály: minden pont legyen pontos parancs vagy konkrét példa. Az olyan elvont ötletet, mint „írj tiszta kódot”, az ügynök figyelmen kívül hagyja.

  1. A projekt áttekintése — 2–3 sor. Mi a projekt, kinek szól, és mi a fő célja. Marketing nélkül. Példa: „Telegram-bot egy fizetős workshop résztvevőinek betanításához. Stack: Next.js 14, Prisma, PostgreSQL. A purchases táblában létrejövő új rekord indítja el.”
  2. Beállítási parancsok — pontos shell-parancsok a helyi futtatáshoz. npm install, npm run dev, npm run build. Ne írd azt, hogy „általában így szoktuk csinálni”.
  3. Kódstílus / konvenciók — konkrét szabályok példával, ne annyi, hogy „írj tisztán”. Például: „Szigorú TypeScript, egyszeres idézőjelek, nincs default export, a komponensek neve PascalCase, a hookok neve use kezdetű.”
  4. Tippek a fejlesztői környezethez — hol találhatók a fontos dolgok. Milyen változók kellenek a .env-be, hol vannak tárolva a titkok, mely portok használatosak, és hogyan kell a helyi DB-vel dolgozni.
  5. Tesztelési útmutató — hogyan futtatható egy konkrét teszt, és mi számít „zöldnek”. Például: npm test -- --testPathPattern=user-auth; 100%-os sikeresség az elvárás.
  6. PR- és commit-irányelvek — a commitüzenetek formátuma, PR előtti ellenőrzőlista (tesztek, linter, dokumentáció), valamint az, hogy ki hagyja jóvá.
  7. Biztonsági szempontok — mi nem történhet meg soha. „Soha ne commitold a .env-et. A titkok kizárólag a Vaultban legyenek. Ne jelenítsd meg a felhasználók személyes adatait a naplókban.”
  8. Korlátok / Soha ne tedd ezt — tilalmak alternatívával együtt. „Ne használd a git push --force parancsot a main ágon. Ha vissza kell vonnod valamit, használd a git revert parancsot, vagy a git reset-et egy feature branchen.”

Minden részben kövesd a „parancsot az ötlet helyett” elvet. Az ügynök figyelmen kívül hagyja azt, hogy „légy óvatos a migrációkkal”. Ezt viszont követni fogja: „Az alembic upgrade head előtt futtasd az alembic check parancsot. Ha hibát jelez, ne alkalmazd a migrációt; kérdezz meg engem.”

Használatra kész AGENTS.md-sablon (másold le és alakítsd át)

A lényeg

Az alábbi sablon kiindulási alap egy szokványos webes projekthez. Másold be a repository gyökerébe, cseréld ki a <project-name> és <stack> részeket, írd be a pontos parancsokat, és töröld a számodra szükségtelen részeket. Az átalakítás 20–30 percet vesz igénybe — első alkalommal akár hosszabb ideig is.

# AGENTS.md

## A projekt áttekintése

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Beállítási parancsok

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Fejlesztői környezet

- Node 20+ (nvm-en keresztül: `nvm use 20`)
- Helyi PostgreSQL 16 a :5432-es porton (`docker-compose up postgres`)
- A Redis opcionális, csak a queue-khoz szükséges (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Soha ne olvasd be a teljes `.env` fájlt. Ha egy változóra van szükséged: `grep "^VAR=" .env`

## Kódstílus

- TypeScript strict mode
- Egyszeres idézőjelek, pontosvesszők nélkül (kivéve, ha az ESLint megköveteli őket)
- Importok: először külső, majd belső, `@/` útvonalú, végül relatív importok
- A komponensek PascalCase néven szerepelnek; a hookok neve `use` kezdetű
- Ne használj `any` típust kifejezett megjegyzés nélkül, amely megmagyarázza, „miért nem lehet típusozni”

Példa egy jó modulra:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Tesztelés

```bash
npm test                                # minden teszt
npm test -- --testPathPattern=auth      # csak az auth tesztjei
npm test -- --watch                     # watch mód
```

Commit előtt minden tesztnek sikeresen le kell futnia (zöldnek kell lennie). Ha valamelyik teszt hibás, ne commitolj; kérdezd meg, mi legyen a teendő.

## Pull request irányelvek

- Commit formátuma: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- PR előtt: `npm run build && npm test && npm run lint`
- PR-leírás = mi változik, miért, és hogyan tesztelhető
- Ne hagyd jóvá a saját PR-edet — mindig várd meg az emberi felülvizsgálatot

## Biztonság

- Titkok kizárólag a `.env`-ben és a Vaultban lehetnek, soha ne kerüljenek kódba
- Ne naplózz személyes adatokat (e-mail-címet, telefonszámot, nevet)
- Éles DB-vel való munka során csak olvasási lekérdezéseket használj, kivéve, ha erre kifejezetten felhatalmazást kaptál
- Ne rögzítsd kódba a külső szolgáltatások (Stripe, OpenAI) API-kulcsait a tesztekben

## Soha ne tedd ezt

- Ne használd a `git push --force` parancsot a main ágra. Ha vissza kell vonnod valamit, használd a `git revert` parancsot, vagy nyiss új PR-t
- Ne futtass DB-migrációt `alembic check` (vagy az ORM megfelelője) nélkül
- Ne használd az `npm install -g` parancsot vagy a `sudo`-t projektfüggőségek telepítéséhez
- Ne adj hozzá függőségeket jóváhagyás nélkül (különösen nagyokat: webpack plugineket, ORM-eket)

A sablon átlagosan 80–120 soros. Ha a fájl meghaladja a 150 sort, az annak a jele, hogy át kell szervezned: helyezz át valamit a docs/ mappába, hivatkozz valamire, vagy tömörítsd egyetlen sorba. A gyakorlatban a 100–150 soros fájlok működnek a legjobban; e határ fölött a minőségjavulás megfordul.

Melyik 5 szabály teszi igazán hasznossá az AGENTS.md-t?

A lényeg

A jó AGENTS.md öt szabályt követ: ötletek helyett parancsokat használ, alternatívákkal együtt fogalmaz meg tiltásokat, pontosan egy igazságforrást jelöl ki, ellenőrizhető teljesítési feltételeket ad, és 150 sornál rövidebb.

  1. Ötletek helyett parancsok. Az ügynök nem érti, hogy „légy óvatos a migrációkkal”. Követni fogja az alembic check parancsot az alembic upgrade head előtt. Az ügynökök parancsokkal és feltételekkel dolgoznak, nem hangulatokkal. Fogalmazd meg a legfontosabb szabályokat „tedd X-et, különben Y-t” alakban.

  2. Tiltások alternatívával. Az ügynök két-három prompt után csendben figyelmen kívül hagyja az olyan puszta tiltást, hogy „ne force pusholj”. A „ne tedd X-et; helyette tedd Y-t” párosítás működik. Példa: „ne használd a git push --force parancsot a main ágon; ha vissza kell vonnod valamit, használd a git revert parancsot, vagy nyiss új PR-t.”

  3. Pontosan egy igazságforrás. A gyökérben lévő AGENTS.md az egész projekt igazságforrása. Monorepó esetén használj beágyazott AGENTS.md-fájlokat az almappákban, a „legközelebbi érvényesül” szabályt követve. Ne legyenek egymással ellentétes utasításokat tartalmazó párhuzamos fájlok.

  4. Ellenőrizhető „kész” feltételek. A „teszteknek sikerülniük kell” haszontalan. A pontos feltétel ez: az npm test 0-s kilépési kódot ad, és nem írja ki a FAIL szót a stdoutra. „A kód legyen tiszta” — ez is haszontalan. A pontos feltétel ez: az npm run lint figyelmeztetések nélkül lefut. Az ügynök csak akkor érti, mit jelent a „kész”, ha kifejezetten leírod a feltételt.

  5. 150 sornál rövidebb fájl. 150 sor fölött romlani kezdenek a mérőszámok: az ügynök több kontextust tölt olvasással, és fontos szabályokat hagy ki. Ha nem fér bele, helyezd át a részleteket a docs/architecture.md fájlba, és hivatkozz rá az AGENTS.md-ből; a fájlban csak a parancsokat és korlátokat hagyd meg.

Melyik 10 hiba teszi használhatatlanná az AGENTS.md-t?

A lényeg

Az AGENTS.md működésképtelenségének fő oka a homályos megfogalmazás. Több mint 2 500 adattár vizsgálatában a GitHub Blog kimutatta, hogy a fájlok többsége azért vall kudarcot, mert túl általánosan fogalmaz. Például az, hogy „Segítőkész kódolási asszisztens vagy”, pontosan nulla hasznos információt ad az ügynöknek. Az alábbiakban bemutatjuk a 10 tipikus hibát és azok megjelenését a rossz fájlokban: a README megkettőzése, strukturálatlan próza, 30-nál több alternatíva nélküli tiltás, ellentmondó prioritások, kódba írt titkok, elavult dokumentáció és egyszerű feladatokhoz képest túlzott architekturális bonyolultság.

  1. Homályos szabályok parancsok nélkül. Az ügynök figyelmen kívül hagyja azt, hogy „légy óvatos a migrációkkal” — számára ez a mondat üres. Csak egy feltétellel kiegészített konkrét parancs működik: „Futtasd az alembic check parancsot az alembic upgrade head előtt. Ha hibát jelez, ne alkalmazd a migrációt; kérdezz meg engem.”

  2. „Tiszta kód.” Haszontalan kifejezés. Cseréld konkrét mintára: „Használj hookokat alkalmazó funkcionális komponenseket. Példa: function LoginForm() { const [email, setEmail] = useState(''); ... }”

  3. Strukturálatlan próza. Ha az AGENTS.md 300 sor próza, címsorok nélkül, az ügynök 80K kontextustokent fog irreleváns szövegrészekre fordítani, és elszalasztja a fontosakat. Használj H2/H3 címsorokat, rövid részeket és felsorolásokat.

  4. 150 sornál hosszabb fájl. E küszöb felett romlanak a minőségi mutatók. Bontsd a fájlt egy fő fájlra és a docs/ mappában található részletekre mutató hivatkozásokra.

  5. 30-nál több tiltás alternatíva nélkül. Ha a fájlban hosszú lista szerepel azzal, hogy „ne tedd X-et, ne tedd Y-t”, anélkül, hogy elmagyarázná, „mit tegyél Z helyett”, az ügynök tanácstalanul fog bolyongani.

  6. A README.md megkettőzése. Ha már leírtad a README-ben, hogyan kell telepíteni és futtatni, ne másold át az AGENTS.md-be. Ehelyett hivatkozz a README-re egy sorban, és az AGENTS.md-ben írd le azt, amire az ügynöknek szüksége van, de az emberi közreműködőknek nem.

  7. Titkok kódba írása. Az AGENTS.md nyilvános is lehet (a Gitben van). Ne írj bele valódi API-kulcsokat, tokeneket vagy jelszavakat. Csak a titkok tárolási helyére hivatkozz: „Lásd a Vaultot: secret/staging/db.”

  8. Rangsorolás nélküli, ellentmondó prioritások. A „Haladj gyorsan” + „tartsd fenn a 90%-os tesztlefedettséget” bizonytalanná teszi az ügynök számára, mit válasszon. Határozd meg kifejezetten a sorrendet: „A tesztlefedettség legyen legalább 80%, ezután következhet a sebesség. Ha ellentmondanak egymásnak, a tesztek az elsődlegesek.”

  9. Elavult dokumentáció. Az architektúra leírása REST+pollingot említ, miközben a valóság már WebSockets. Az ügynök a régi leírást követi, és tönkreteszi az architektúrát. A szabály: az architektúra változásakor ugyanabban a PR-ben frissítsd az AGENTS.md-t a kóddal együtt.

  10. Túlzott architekturális bonyolultság egyszerű feladatnál. Ha valaki két sort kér módosítani egy konfigurációban, az ügynöknek nem kell elolvasnia 14 mikroszolgáltatás teljes topológiáját. Helyezd át a „mélyebb” architektúrát a docs/architecture.md fájlba; az AGENTS.md-ben csak ennyi maradjon: „ha a feladat architekturális jellegű, olvasd el a docs/architecture.md fájlt”.

A GitHub Blog több mint 2 500 AGENTS.md-adattárról szóló tanulmánya a következő fő következtetést fogalmazza meg:

„A legtöbb ügynökfájl azért vall kudarcot, mert túl általános. A „Segítőkész kódolási asszisztens vagy” nem működik.”

(GitHub Blog, fordítás angolból)

Hogyan tartsd egy adattárban az AGENTS.md-t és a CLAUDE.md-t?

A lényeg

Három forgatókönyv van: (1) Csak Claude Code — tartsd meg a CLAUDE.md-t; AGENTS.md-re nincs szükség. (2) Csak nem Claude-eszközök (Codex, Cursor, Copilot, Junie) — használd az AGENTS.md-t egyetlen igazságforrásként. (3) Vegyes csapat Claude Code-dal és más eszközökkel — az AGENTS.md legyen az elsődleges fájl. Ha nincs külön szabályod a Claude-hoz, elhagyhatod a CLAUDE.md-t: a 2.1.277-es verzió óta a Claude Code önállóan olvassa az AGENTS.md-t. Ha vannak külön szabályaid, szimbolikus hivatkozással vagy @AGENTS.md importtal kapcsold össze a két fájlt. macOS-en és Linuxon csak akkor nevezz át, ha az AGENTS.md nem létezik. Ha mindkét fájl megvan, előbb őrizd meg és egyesítsd a szabályokat, majd rövid CLAUDE.md-burkolót használj @AGENTS.md importtal; a meglévő AGENTS.md-t soha ne írd felül. Windowson a szimbolikus hivatkozáshoz Developer Mode szükséges, ezért egyszerűbb importot használni.

A fő gyakorlati kérdés az, hogyan tartsd meg mindkét fájlt a tartalom megkettőzése nélkül. Három forgatókönyv van:

1. forgatókönyv: Csak Claude Code. Tartsd meg a CLAUDE.md-t, és használd a Claude Code összes funkcióját: ~/.claude/CLAUDE.md a felhasználói szintű utasításokhoz, CLAUDE.md a projekthez, CLAUDE.local.md a személyes felülírásokhoz, @import más fájlok beemelésére, valamint .claude/skills/ a speciális skillekhez. AGENTS.md-re nincs szükség.

2. forgatókönyv: Több kódoló kliens. A közös szabályokat tartsd az AGENTS.md-ben, majd minden klienst külön kapcsolj hozzá és ellenőrizz. A Gemini CLI beállítható kontextusfájlnevet támogat; az Aider az olvasási konfigurációján keresztül tölthet be fájlt. Ezek külön beállított betöltési módok, nem azonos automatikus felismerés.

Betöltési módMit ellenőrizz?
Automatikus AGENTS.md-felismerésA telepített kliens dokumentált gyökér-, beágyazási és elsőbbségi szabályai
Külön konfiguráció, például Gemini CLI vagy AiderA beállított fájlnév/olvasási útvonal és a kliens betöltött kontextust mutató nézete
Claude Code feltételes betöltés vagy importA telepített verzió és a fájlok elsőbbsége; lásd a Claude Code AGENTS.md-útmutatóját

Indíts új munkamenetet egy ártalmatlan tesztrepozitóriumban. Adj hozzá egy egyedi, ártalmatlan utasítást, például: „a tesztválasz tartalmazza az instructions-loaded jelölőt”, és a válasz mellett vizsgáld meg a kliens dokumentált betöltöttfájl-nézetét vagy naplóit is. Ezt minden ténylegesen használt kliensnél és verziónál ismételd meg. A modell állítása arról, hogy elolvasta a fájlt, nem független bizonyíték a betöltésre; egy sikeres ellenőrzésből ne következtess minden más eszköz támogatására.

3. forgatókönyv: Vegyes csapat (Claude Code + más eszközök). Ez a leggyakoribb összeállítás 2026-ban. A megoldás az, hogy az AGENTS.md-t teszed elsődlegessé. Ha nincsenek kizárólag a Claude Code-ra vonatkozó szabályaid, egyáltalán ne hozz létre CLAUDE.md-t: a 2.1.277-es verzió óta a Claude Code beolvassa az AGENTS.md-t, ha a projektben nincs CLAUDE.md. Ha vannak ilyen szabályaid, a CLAUDE.md legyen szimbolikus hivatkozás, vagy egy rövid burkolófájl @AGENTS.md importtal.

Bármelyik fájl módosítása előtt nézd át és mentsd mindkettőt. Ha mindkettő létezik, nem ellentmondó közös utasításaikat egyesítsd az AGENTS.md-be, a Claude-specifikusakat pedig CLAUDE.md-ben tartsd @AGENTS.md importtal. A meglévő symlinkeket őrizd meg cserélés helyett.

Rendes CLAUDE.md fájlnál csak az AGENTS.md hiányában használható e macOS/Linux shellőr, amely meglévő célt vagy symlinket nem ír felül:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Sikeres átnevezés után a CLAUDE.md az AGENTS.md-re mutató symlink. Minden AGENTS.md-t olvasó ügynök ugyanazt a tartalmat látja. A Claude Code, amely a CLAUDE.md-t olvassa, a szimbolikus hivatkozáson keresztül ugyanazt látja.

Windowson a szimbolikus hivatkozás létrehozásához Developer Mode (vagy Admin) szükséges, ami az egész csapatnak kényelmetlen lehet. Alternatíva egy rövid CLAUDE.md, amely beemeli az AGENTS.md-t:

# CLAUDE.md

@AGENTS.md

## Kifejezetten a Claude Code-hoz

- Speciális promptokhoz használd a .claude/skills/ mappát
- Skillek használatakor nézd meg a .claude/skills/INDEX.md fájlt
- Jelentősebb módosítások előtt használd a Plan Mode-ot (Shift+Tab)

A Claude Code-ban ez a szintaxis egyetlen sorral betölti az AGENTS.md-t, és alatta hozzáadja a Claude Code-specifikus kiegészítéseket. Ha később el akarod távolítani az AGENTS.md-t, egyszerűen töröld az importot. Ez a sor nem eredményez kétszeri beolvasást: a Claude Code dokumentációja szerint nem tölti be ugyanazt az AGENTS.md-t kétszer, még akkor sem, ha önállóan is be tudja olvasni.

A több eszközt használó csapatok kanonikus elrendezése 2026-ban:

repo-root/
├── AGENTS.md                              # igazságforrás, ≤150 sor
├── CLAUDE.md                              # csak Claude-specifikus szabályok esetén: szimbolikus hivatkozás → AGENTS.md VAGY @AGENTS.md + kiegészítések
├── .cursor/rules/                         # csak Cursorra érvényes célzott felülírások
├── .github/copilot-instructions.md        # „Lásd az AGENTS.md-t”, ha használatban van
└── docs/architecture.md                   # az AGENTS.md által hivatkozott részletes architektúra

A CLAUDE.md-ről bővebben a „Hogyan konfiguráld megfelelően a CLAUDE.md-t” című útmutatóban olvashatsz. Arról, miért van szüksége az ügynöknek egy nagy utasításfájlra, a „Mi az a Context Engineering?” című anyagból tudhatsz meg többet.

Mi változott 2026-ban: miért került az AGENTS.md a Linux Foundationhöz az AAIF révén?

A lényeg

  1. december 9-én a Linux Foundation létrehozta az Agentic AI Foundationt (AAIF), három alapító projekttel: az OpenAI AGENTS.md-jével, az Anthropic MCP-jével és a Block goose-ával. Az alapító tagok az AWS, az Anthropic, a Block, a Bloomberg, a Cloudflare, a Google, a Microsoft és az OpenAI voltak. 2026. február 24-re az alapítványnak 146 szervezeti tagja lett. Ez azt jelenti, hogy az AGENTS.md már nem „az OpenAI egyik formátuma”, hanem az MCP melletti iparági szabvány. Gyakorlati szempontból, ha olyan terméket fejlesztesz, amelynek többféle szállító ügynökeivel kell működnie, az AGENTS.md megléte a projekt gyökerében alapvető higiénia. Nélküle három vagy négy párhuzamos fájlt kell majd karbantartanod, amelyek egy hónapon belül eltérnek egymástól.

A 2026. májusi AI-kódolás fő politikai története nem egy újabb modell megjelenése volt, hanem a formátumok konszolidációja. Korábban minden szállítónak saját szabályfájlja volt, ami a szállítóknak kényelmes, a több eszközzel dolgozó csapatoknak viszont fájdalmas volt.

A 2025. december 9-i sajtóközleményben a Linux Foundation az Agentic AI Foundationt három formátumot összefogó ernyőszervezetként jelentette be:

  • AGENTS.md az OpenAI-tól — ügynököknek szóló utasításfájl-formátum
  • Model Context Protocol (MCP) az Anthropic-tól — protokoll külső eszközök ügynökökhöz csatlakoztatására
  • goose a Blocktól — nyílt forráskódú ügynökkeretrendszer

A Linux Foundation sajtóközleményéből:

„E projektek AAIF-ernyő alá vonása biztosítja, hogy olyan átláthatósággal és stabilitással fejlődhessenek, amelyet csak a nyílt irányítás képes garantálni.”

(Linux Foundation sajtóközlemény, 2025. december 9., fordítás angolból)

  1. február 24-re 146 szervezet tartozott az AAIF-hez (két hónap alatt 97 új tag). Az új Gold tagok között szerepelt a Red Hat, a ServiceNow, az Akamai, a Lenovo, a JPMorgan Chase, a Huawei, a Hitachi, az UiPath, az American Express és az Autodesk. Az Anthropic Platinum szinten van, az MCP-t támogatva. Az OpenAI Platinum szinten van, az AGENTS.md-t támogatva. A Block Platinum szinten van a goose-zal.

Ez megváltoztatja az AGENTS.md helyzetét: „OpenAI-formátumból” iparági szabvánnyá válik. 2026 tavaszán a Claude Code még a partvonalon maradt, szeptemberben azonban a 2.1.277-es verzióval megtanulta önállóan beolvasni az AGENTS.md-t. A CLAUDE.md nem tűnt el, és ha jelen van a projektben, továbbra is elsőbbséget élvez.

Gyakorlati kiindulópont az AGENTS.md-ben tárolt közös projektszabály, kiegészítve az egyes kliensek által igényelt importtal, burkolófájllal vagy külön olvasási beállítással. A Claude Code telepített verzióját és utasításfájljainak elsőbbségét ellenőrizd, mielőtt CLAUDE.md-importról vagy szimbolikus hivatkozásról döntesz. Minden kliensben igazold a betöltést; itt nincs megállapított lefedettségi százalék.

Mi következik?

Az AGENTS.md az első építőelem ahhoz, „hogyan állapodjunk meg az ügynökkel, hogy kiszámíthatóan működjön”. Következik a második építőelem — a projekt tudásmappája, amely tartalmazza az üzleti kontextust, a közönséget, a termékeket és az árakat. A harmadik építőelem a context engineering, amely mindent összekapcsol: milyen fájlokat lát az ügynök az egyes lépésekben, hogyan marad fenn az állapot a munkamenetek között, és hogyan lehet különböző modellek között váltani.

Gyakorlati anyagok: Ailoot-dokumentáció.

További anyagok és eszközök: Ailoot.

További részletek

Kérdések és válaszok: Mi az az AGENTS.md, és hogyan írhatod meg a sajátodat 30 perc alatt | Ailoot

Mi van, ha az AGENTS.md és CLAUDE.md is létezik?

Módosítás előtt mentsd és hasonlítsd össze mindkettőt. A közös szabályokat egyesítsd az AGENTS.md-be, a Claude-specifikusakat tartsd CLAUDE.md-ben @AGENTS.md importtal; ne nevezz át egyiket a másikra.

Hogyan tegyem az utasításokat igazolhatóvá?

Pontos beállítási és tesztparancsokat írj, add meg az elvárt eredményt és tiltott módosításokat. A részletes architektúrát hivatkozott dokumentumba tedd, hogy a belépőutasítás könnyen áttekinthető maradjon.

Összes cikk