Hogyan írj olyan CLAUDE.md-t, amitől tényleg jobb lesz a kimenet

Az utóbbi időben jó pár CLAUDE.md fájlt láttam, és feltűnően sok ugyanabba a csapdába esik: mindent ide tesznek, amihez máshol nincs kedvük helyet keresni.

Kerül bele egy kis hangnem, pár csapatszabály, néhány régi emlékeztető, aztán egyszer csak már fél betanító anyag van benne. Mire Claude odaérne a lényeghez, a valóban fontos instrukciók addigra rég elvesztek.

Innen jönnek a tipikus hibák: rossz parancsot futtat, rossz rétegben javít, vagy egy apró fixből sokkal szélesebb módosítást csinál, mint amit bárki kért.

Az Anthropic dokumentációja szerint a CLAUDE.md a projekt memóriája, amit Claude a munkamenet elején automatikusan beolvas. Pont ezért kell vele takarékosan bánni. Minden ködös, általános bekezdés helyet vesz el attól a néhány helyi ténytől, amire Claude-nak tényleg szüksége van.

Az a változat működik jól, ami rövid és tárgyszerű. Claude tud kódot írni. Amit nem tud magától, az az, hogyan van összerakva a kódbázisod, melyik parancsot használjátok ténylegesen, mihez ne nyúljon, és meddig mehet el egy változtatásban.

Mi való bele

Nem szoftverfejlesztési bölcsességeket akarsz itt újra leírni. Azokat a hiányzó helyi információkat akarod pótolni, amiket Claude nem tud megbízhatóan kitalálni egy gyors kódbázis-olvasásból.

Ez általában ezt jelenti:

• a parancsok, amik tényleg működnek ebben a projektben
• a határok a rétegek között
• azok a hibák, amelyeket jobb előre kivédeni
• az együttműködési keret, amit módosítás közben elvársz

Az Anthropic ajánlása itt elég egyértelmű: legyen a fájl konkrét, tömör, jól strukturált, és lehetőleg maradjon 200 sor alatt. Ez nagyjából egybevág azzal is, amit a gyakorlatban látni. Amint ezek a fájlok elkezdenek felpuffadni, azonnal kevésbé hasznosak.

1. Kezdd a parancsokkal

Ha Claude nem tudja, hogyan kell buildelni, tesztelni, lintelni vagy típust ellenőrizni a projektet, improvizálni fog. Láttam már olyat, hogy pnpm helyett npm-mel indult el, rossz tesztparancsot futtatott, vagy olyan útvonal-formátumot használt, amit az eszközlánc egyszerűen nem fogad el.

Itt érdemes a legkonkrétabbnak lenni.

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test single: `pnpm vitest run path/to/file.test.ts`
- Test all: `pnpm test`
- Lint: `pnpm lint`
- Type check: `pnpm tsc --noEmit`

A parancsblokk inkább puskának nézzen ki, ne szabályzatnak. Ne magyarázd túl. A pontos parancs számít.

2. Adj egy térképet a kódbázishoz

Claude nulla helyi tudással indul. Ha a kódbázisodban tiszták a határok, mondd ki őket.

## Architecture
- `src/lib/services/` -> business logic
- `src/components/` -> presentational UI only
- `src/app/api/` -> API route-ok, üzleti logika nélkül
- `src/lib/store/` -> global state
- Adatbázis-hozzáférés csak server actionből vagy API route-ból

Ez a rész nem könyvtárlista akar lenni, hanem döntési térkép. Nem az a cél, hogy Claude végig tudja mondani a mappaszerkezetet, hanem az, hogy ne a rossz rétegben oldja meg a feladatot.

Az Anthropic támogat almappaszintű CLAUDE.md fájlokat is, amelyek akkor töltődnek be, amikor Claude az adott területen dolgozik. Nagyobb kódbázisoknál ez sokkal jobb minta, mint mindent a gyökérfájlba önteni.

3. Írd le azokat a szabályokat, amelyek megóvnak a drága hibáktól

Ezt a részt a legtöbben vagy kihagyják, vagy túl puha, általános mondatokkal töltik ki. Egyik sem segít sokat.

A hasznos szabály konkrét. Ne commitolj titkos kulcsot. Ne vezess be SSR-t. Futtass típusellenőrzést módosítás után. Maradj a lehető legkisebb változtatásnál. Minden sornak egy valós hibára kell rámutatnia.

## Rules
- Soha ne commitolj `.env` fájlt vagy titkos kulcsot
- Minden kódmódosítás után fusson típusellenőrzés
- Maradj a lehető legkisebb módosításnál, ne refaktorálj nem kapcsolódó fájlokat
- Csak static export, ne vezess be SSR-t
- Minden aszinkron hibautat kezelj explicit módon

Az Anthropic anyagában az is benne van, hogy a kiemelés segíthet. Ezzel egyetértek, de csak ritkán érdemes használni. Ha minden sor IMPORTANT, akkor egyik sem az.

4. Írd le azt is, hogyan történjen a munka

A coding agenttel való frusztráció jó része nem az elrontott szintaxisról szól. Inkább arról, hogy más tempóban és nagyobb lendülettel dolgozik, mint amire számítasz. Te célzott fixet kérsz, ő közben elkezd még öt kapcsolódó fájlt rendbe rakni. Te két opciót vársz, ő csöndben kiválaszt egyet.

## Workflow
- Komplexebb módosítás előtt kérdezz vissza
- Maradj a lehető legkisebb módosításnál
- Minden változtatás után futtasd a releváns teszteket
- Egy logikai változás egy commit legyen
- Ha két jó megoldás van, előbb mutasd meg mindkettőt

Ezek a sorok kevésbé a kódstílusról szólnak, inkább az együttműködésről. Mikor kérdezzen vissza? Mennyire lehet széles egy módosítás? Fusson-e teszt minden változtatás után? Magyarázza-e el a kompromisszumokat döntés előtt? Ha ez fontos, érdemes leírni.

Mit ne tegyél bele

Ha megnyitok egy CLAUDE.md-t, és az első érdemi mondat valami olyasmi, hogy "viselkedj gondolkodó senior engineerként", akkor már sejtem, hogy a fájl helyet pazarol.

Érdemes kihagyni:

• személyiségjellegű tölteléket, például hogy "viselkedj senior engineerként"
• olyan formázási szabályokat, amelyeket a linter már amúgy is kikényszerít
• hosszú bemásolt dokumentációkat
• duplikált instrukciókat a user, project és local szintek között
• bármit, amit Claude gyorsabban megtanul a kódbázis átnézéséből

Az Anthropic ma már több instrukciós szintet támogat: user, project, lokális felülírás és központilag kezelt szabályok. Emiatt nem kell mindent egyetlen gyökérfájlba önteni. A közös projektszabályok menjenek a projektfájlba. A személyes szokások a user szintre. A gépspecifikus vagy privát eltérések pedig a lokális felülírásba.

Ez a szétválasztás segít abban, hogy a fő fájl rövid és olvasható maradjon.

Egy használható template

Ez az a rövid változat, amit már tényleg érdemes lemásolni és testre szabni:

# CLAUDE.md

## Project
Rövid leírás arról, mit csinál a termék és kinek készül.

## Stack
Framework, nyelv, adatbázis, deploy környezet.

## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`

## Architecture
- `[path]` -> `[felelősség]`
- `[path]` -> `[felelősség]`
- `[path]` -> `[felelősség]`

## Rules
- `[Szabály, ami egy valós hibát előz meg]`
- `[Szabály, ami egy valós hibát előz meg]`
- IMPORTANT: `[Az a szabály, amit Claude nem törhet meg]`

## Workflow
- `[Hogyan közelítse meg a módosítást]`
- `[Mikor kérdezzen vissza]`
- `[Tesztelési elvárás]`
- `[Mit vársz a commitoktól]`

## Out of Scope
- `[Amihez ne nyúljon]`
- `[Manuálisan karbantartott fájlok vagy integrációk]`

Én minden sorra ugyanazt a gyors kérdést tenném fel: ha ezt kiveszem, nagyobb eséllyel csinál Claude rossz dolgot? Ha nem, menjen.

Mit kapsz tőle

A jó CLAUDE.md nem varázsolja okosabbá a modellt. Azt viszont eléri, hogy kevesebb legyen a felesleges bizonytalanság.

Ez pont elég ahhoz, hogy számítson. Kevesebbszer kell ugyanazt a korrekciót újra leírnod. Claude kevesebbet találgat. A fájl pedig végre azt csinálja, amire való: röviden leírja, hogyan érdemes ebben a projektben dolgozni.

Érdemes mindig akkor elővenni, amikor Claude valamit elront. Pontosítsd azt a sort, ami ezt megelőzte volna. Ami csak dísz, azt vedd ki.

Ha nemcsak egy repo instrukcióit akarod rendbe rakni, hanem azt is, hogyan működjön az AI egy valódi termékben vagy delivery workflow-ban, a következő jobb lépés általában a dedikált AI Product Strategy tanácsadás.