A fájdalompont: miért bukik el az AI mindig ugyanott a kódolásnál

Aki Cursorral, Windsurffel vagy Claude Code-dal dolgozik, szinte biztosan átélt már egy tipikus összeomlást: az AI kiad egy egész kódrészletet, bemásolod, futtatod – buildelési hiba, piros tesztek, rossz helyre telepített függőségek. A probléma nem az AI intelligenciájában van, hanem abban, hogy egyáltalán nem ismeri a projekted „íratlan szabályait”.

Az AGENTS.md pontosan erre való: egy Markdown fájl a projekt gyökerében, kifejezetten az AI-nak szólva – hogyan buildeljen, hogyan teszteljen, milyen konvenciókat kövessen. A README.md embereknek készül, tele projektbemutatóval, hozzájárulási útmutatóval, márkatörténettel. Amikor az AI ezt olvassa, olyan, mint egy új alkalmazott, akit az első napon a céges szórólappal dobnak be, és azonnal kódot kell írnia – tudja, mivel foglalkozik a cég, de nem tudja, mi a build parancs, hogyan futnak a tesztek, milyen ESLint szabályok vannak. Az eredmény: minden beszélgetésben újra meg újra javítgatnod kell: „pnpm-et használj, nem npm-et”, „a tesztek a packages/web alatt vannak”, „ne felejtsd el a lintet”. Ezt százszor elismétled, a projekt akkor is kaotikus marad.

A szabadúszó munka során a veszteség még közvetlenebb: elvállalsz egy Next.js + Prisma megbízást, a Cursorral gyorsítanál, de az AI npm install-t futtat, a pnpm workspace konfig teljesen használhatatlan lesz; nem tudja, hol van az adatbázis séma, a generált migration fájl azonnal elszáll. Az ügyfél sürget, te három órát debugolsz AI-generált kódot – a pénz keserűen jön.

Az AI a projekt íratlan szabályait nem ismeri – 3 tipikus bukás: ① Rossz csomagkezelő (a projekt pnpm-et használ, az AI alapértelmezetten npm install-t futtat), a függőségek rossz helyre kerülnek, a workspace konfig felmondja a szolgálatot; ② Nem találja a teszt belépési pontot (a tesztek a packages/web alatt vannak, az AI a gyökérben futtatja a pnpm test-et, „tesztfájl nem található” hibát dob); ③ Következetlen kódstílus (a projekt ESLint + Prettier kombinációt használ, az AI generált kód behúzása, idézőjelei mind rosszak, a CI azonnal megbukik).

A lehetőség: az AGENTS.md szétválasztja az „emberi” és a „gépi” dokumentációt

A GitHubon nyílt forráskódú projekt, az AGENTS.md (repo: github.com/agentsmd/agents.md, 2026.08.25-ig kb. 24 000 csillag) pontosan ezt a problémát oldja meg. Az alapötlet pofonegyszerű: a projekt gyökerébe teszel egy Markdown fájlt, ami kifejezetten az AI-nak mondja meg, hogyan buildeljen, hogyan teszteljen, milyen kódstílust kövessen.

Ez nem a README helyettesítője, hanem kiegészítője. A README emberi közreműködőknek szolgál, az AGENTS.md az AI ágenseknek. A kettő szerepe tiszta, nem zavarják egymást.

A forrásposzt szerint az AGENTS.md-et több tízezer nyílt forráskódú projekt adoptálta (a pontos szám egyelőre nem ellenőrzött), és a főbb AI kódoló eszközök – VS Code, Cursor, Windsurf, Aider, GitHub Copilot – mind támogatják (megerősített tény); a közösségi visszajelzések alapján az OpenAI Codex, Google Jules és más eszközök is támogatják (⚠️ nem ellenőrzött). Ha most nem tanulod meg, az AI dialektusban fog hozzád beszélni.

Első út: írj egy minimálisan használható AGENTS.md-t

A költség minimális. Hozz létre egy új fájlt, írj három szekciót – kész.

Előzetes tudás: a példák pnpm-et használnak (npm-hez képest kevesebb lemezterületet eszik, támogatja a monorepo workspace-t), a turbo monorepo feladat-orchestrátor, a --filter paraméterrel csak egy adott alcsomagra hatunk, így nem zavarjuk az egész repot.

Első szekció „Dev environment tips”: mondd meg az AI-nak, milyen csomagkezelőt használsz, hogyan ugorjon alcsomagba, hogyan hozzon létre új modult. A hivatalos példa:

• pnpm dlx turbo run where <project_name> – egyből a megadott alcsomag könyvtárába ugrik, nem kell ls-sel turkálni
• pnpm install --filter <project_name> – csak egy adott alcsomag függőségeit telepíti, az egész monorepót nem piszkálja
• pnpm create vite@latest <project_name> -- --template react-ts – új TypeScript ellenőrzéses React + Vite alcsomagot hoz létre

Ezeket a parancsokat az AI magától nem találja ki, de ha leírod, pontosan követi.

Második szekció „Testing instructions”: mondd meg, hogyan fussanak a tesztek, hol van a CI pipeline, commit előtt milyen ellenőrzések kötelezőek. A hivatalos példa:

• pnpm turbo run test --filter <project_name> – az adott alcsomag összes ellenőrzését futtatja
• pnpm vitest run -t "<test name>" – csak egy adott nevű tesztet futtat
• „Fix any test or type errors until the whole suite is green” – amíg nem zöld minden, nem áll le
• „Add or update tests for the code you change, even if nobody asked” – ez a kulcsmondat, enélkül az AI gyakran lusta lesz tesztet írni

Harmadik szekció „PR instructions”: szabályozd a commit cím formátumát, kötelezővé tedd a lint és a teszt futtatását. A hivatalos példa: Title format: [<project_name>] <Title>, valamint „Always run pnpm lint and pnpm test before committing”.

Ez a három szekció együtt 50 sor alatt van, mégis érezhetően megdobja az AI által generált kód elsőre sikeres átfutási arányát (közösségi visszajelzés, pontos szám nem igazolt).

Második út: beágyazás nagy monorepókban

Ha vállalati szintű projekten dolgozol, a kódbázis monorepo struktúrájú (több kapcsolódó projekt egy Git repóban – frontend, backend, megosztott kód mind külön alkönyvtár), egyetlen AGENTS.md nem elég. Az AGENTS.md támogatja a beágyazást: minden alkönyvtárba tehetsz egy saját AGENTS.md-t, az AI automatikusan a „legközelebbit” olvassa be.

Gyakorlati megoldás: a gyökér AGENTS.md-be kerülnek a globális szabályok (csomagkezelő, CI folyamat, biztonsági előírások), majd a packages/web/, packages/api/, packages/shared/ mindegyikébe egy-egy, az adott alcsomagra jellemző build parancsokkal, teszt belépési pontokkal, speciális függőségekkel. Például a frontend csomagnál: „komponenskönyvtár shadcn, stílus Tailwind, ikonok lucide-react”; a backend csomagnál: „adatbázis migration Prisma, API útvonalak az src/routes alatt, hitelesítés JWT”.

Amikor az AI egy alkönyvtárban dolgozik, automatikusan betölti a legközelebbi AGENTS.md-t, ami elsőbbséget élvez a gyökérrel szemben. Ez azt jelenti, hogy ugyanabban a projektben a frontend AI asszisztens és a backend AI asszisztens teljesen más utasításokat kap – nem keverednek össze.

Harmadik út: tedd differenciáló értékesítési előnnyé a szabadúszó munkában

Az AI-alapú szabadúszó piac már vörös óceán – mindenki tud Curortort használni, de a szállítás minősége nagyon változó. Ha az ajánlatodba beírod: „Ehhez a projekthez AGENTS.md szabványdokumentumot konfiguráltam, az AI-támogatott fejlesztés a projekt konvencióit követi”, az megveri azokat a versenytársakat, akik csak annyit mondanak: „AI-val írok kódot”.

Konkrét taktika: a megbízás átvétele után szánj 30 percet az ügyfél projektjének megértésére, majd írj egy testre szabott AGENTS.md-t. Ez a dokumentum maga is a szállítmány része – az ügyfél a jövőben saját AI-jával is gördülékenyebben tudja majd karbantartani a kódot.

Az AGENTS.md konfigurációs szolgáltatást csomagban árazd (a helyi piachoz igazítva): alap csomag ~25 000 Ft (egy fájl konfiguráció + README leírás), vállalati csomag ~150 000 Ft (monorepo beágyazás + biztonsági előírások + csapattréning). Szállítmány: ① testre szabott AGENTS.md fájl ② 30 nap Telegram/email konzultáció ③ 10 perces képernyőfelvétel tréning. Akinek való: az ügyfél már fizet Cursor/Windsurf előfizetést, de nem hozza ki belőle a maximumot. Akinek nem: aki még mindig tisztán manuális fejlesztésben dolgozik, és nem vezetett be AI eszközt.

Esettanulmány: az AGENTS.md kompatibilitási árkánya

Az AGENTS.md MIT licenc alatt áll (megerősített), közösségi karbantartású (a pontos irányítási struktúra nem ismert), honlap: agents.md.

A kompatibilitás a legnagyobb árkánya: megerősített tény, hogy a VS Code, Cursor, Windsurf, Aider, GitHub Copilot mind támogatja az AGENTS.md olvasását; a közösségi visszajelzések alapján az OpenAI Codex, Claude Code, Gemini CLI, Google Jules is támogatja (⚠️ nem ellenőrzött). Ez azt jelenti, hogy egy fájlt megírsz, és az összes főbb AI asszisztens használja – nem kell eszközönként külön konfigurációt írni.

Más megoldásokkal összehasonlítva: a Cursor .cursorrules fájlja csak a Cursorban működik, Windsurfre váltva használhatatlan; a Claude Code CLAUDE.md fájlja csak a Claude-ot szolgálja; a GitHub Copilot utasításrendszere megint egy másik. Az AGENTS.md „egyszer írod, mindenhol fut” tulajdonsága az oka annak, hogy rövid idő alatt széles körben elterjedt.

Eszközváltás költsége nulla. Ma Curortort használsz, holnap Windsurfre váltasz – az AGENTS.md-t változtatás nélkül viszed magaddal, nem kell újraírni a szabályokat.

Cselekvési felhívás: ma este készítsd el a gépi kézikönyvet a projektedhez

5 perces teendőlista: ① Nyisd meg a projekt gyökerét ② Hozz létre AGENTS.md fájlt ③ Másold be a hivatalos sablont (github.com/agentsmd/agents.md) ④ Töltsd ki a három parancsot (build, teszt, lint) ⑤ Következő AI kódolásnál figyeld meg a hatást.

Ha monorepót használsz, ma este szánj plusz 20 percet minden alcsomagra egy-egy beágyazott konfigurációra. Holnap reggel az lesz az első tapasztalatod, hogy az AI generált kódot nem kell újra meg újra javítgatnod.

Az AGENTS.md jelenleg a legjobb ROI-jú AI programozási konfiguráció – 30 perc befektetés havonta több óra debug időt spórol meg.