CLAUDE.md-től a skillekig

A legtöbben beállítások nélkül kezdenek Claude Code-dal dolgozni. Az AI-eszközök ma már többnyire jó kódot írnak. Felmérik a jelenlegi kódot, és megpróbálnak ahhoz igazodni. Ez kezdetben elfogadható, de ha már vannak bevett szokások, szabályok vagy céges elvárások, szinte minden munkamenetben ugyanazokat kell majd ismételgetned.

Első lépések

Az AI-val végzett fejlesztésben ma már a legtöbb gondot nem a hibás kód okozza. A probléma az, hogy a kód nem az elvárásoknak megfelelően készül. Nem oda kerül, ahova te tennéd, a tesztek sem úgy néznek ki, ahogy megszoktad, és még a commitüzenet is idegen, vagy legalábbis sokkal hosszabb, mint szeretnéd.

Egy új kollégánál sem az a megoldás, hogy útmutatás nélkül elkezd dolgozni, majd mindent utólag kijavíttatsz vele. Eredményesebb, ha előre megkapja a szabályokat és eszközöket, amikkel a munkáját könnyebben és pontosabban el tudja végezni. A Claude Code-nál ugyanez működik, csak nem mindegy, mit írsz le, hova és milyen formában.

Erre való a CLAUDE.md. Ez egy Markdown-fájl, amelyben leírhatod a projektben betartandó szabályokat. Azt is megadhatod, hogy mi hol található a projektben, és melyik eszközt mikor és hogyan kell használni.

A legegyszerűbb mindent a CLAUDE.md-be írni, hiszen az mindig ott van, minden munkamenetben automatikusan betöltődik. Ez jól működik. Vannak olyan projektek, ahol ennél nem kell messzebbre menni.

Beleírhatod például, hogyan kell futtatni a tesztet, a lintert és a projektet, mi hol van a mappaszerkezetben, mely konvenciókat kell mindig betartani, és meddig mehet el a Claude Code (például ne hozzon létre olyan fájlt, amit nem kértél).

Amit viszont nem érdemes beleírni:

• Buzdítást. A „írj minőségi kódot” vagy „ne hibázz” nem szabály, mert nincs mihez mérni.
• Kitalált problémák megoldását. Csak növeli a tokenhasználatot, és rossz irányba elviheti a munkamenetet.
• Titkot, kulcsot, belső címet. Ez a fájl általában verziókezelve van, és minden beszélgetés elején be is töltődik.

Tipp. A CLAUDE.md állhat egyetlen sorból is, ami betölti az AGENTS.md-t:

@AGENTS.md

Az AGENTS.md nem Claude-specifikus, hanem közös formátum: ugyanazt használhatja a Codex, a Cursor és több más eszköz is. Így egy fájlt kell karbantartani, és aki más eszközzel dolgozik ugyanazon a projekten, ugyanazokat a szabályokat kapja.

Csökkentsük a zajt

A CLAUDE.md-től függetlenül érdemes megemlíteni a settings.json-t. Sok beállítás kerülhet ide, de talán az egyik legfontosabb az, hogy mit futtathat a Claude Code kérdés nélkül. A CLAUDE.md-vel ellentétben ezeket a beállításokat nem a modell értelmezi, hanem a Claude Code érvényesíti. Ez nemcsak biztonsági kérdés, hanem a figyelmed beosztásáról is szól. Ha sok engedélykérést kapsz a Claude Code-tól, akkor egy idő után már el sem fogod olvasni, amit kérdez, csak jóváhagyod a következőt is. A veszély az, hogy így azt az engedélykérést is jóváhagyhatod, amelyiket nem kellene (kapcsolódó olvasmány a témában).

{
  "permissions": {
    "allow": ["Bash(uv run pytest)", "Bash(uv run ruff check)"],
    "deny": ["Read(./.envrc)"]
  }
}

Engedélyezd előre a helyi, visszafordítható parancsokat az allow listában. De ne kerüljön bele semmi, ami töröl, nehezen visszafordítható vagy kifelé kommunikál. Ha pedig van olyan, amit tiltani szeretnél, azt a deny listában rögzítheted. A fenti példában ez a .envrc, amely érzékeny beállításokat is tartalmazhat.

Egy pontosítás a fenti deny sorhoz: ez a beépített Read eszközt és a felismert Bash-parancsokat (cat, head, tail, sed) tiltja. Egy önálló script viszont, ami maga nyitja meg a fájlt, még mindig hozzáférhet. A Read szabály tehát nem az operációs rendszer által kikényszerített védelem. Ehhez sandbox kell.

Telik az idő

Minél tovább dolgozol egy projekten, annál nagyobb lesz a CLAUDE.md. Ez természetes, hiszen egyre pontosabban meg tudod mondani, hogy mit és hogyan szeretnél. A CLAUDE.md-ből minden szabály betöltődik, akár szükség van rá az adott feladatnál, akár nincs. Minél több szabály kerül egyszerre a kontextusba, annál könnyebben vesznek el köztük a fontos utasítások.

Ilyenek a tesztekkel kapcsolatos szabályok. Teljesen felesleges elővenni őket, ha az alkalmazás kinézetével foglalkozol.

Itt nem az számít, mennyire fontos egy szabály, hanem az, hogy milyen gyakran van rá szükség. Ami minden feladatnál kell, marad a CLAUDE.md-ben. Ami csak bizonyos feladatoknál, az kikerülhet egy skillbe.

Mi az a skill?

Egy .claude/skills/<név>/SKILL.md fájl. A neve alapértelmezetten a könyvtár neve, a leírása (description) opcionális. Ha hiányzik, az első bekezdés szolgál helyette. A név és a leírás mindig ott van a kontextusban, a törzs viszont csak akkor töltődik be, amikor valaki ténylegesen meghívja. A Claude Code automatikusan is meghívhatja, ha egy feladat szempontjából relevánsnak ítéli, vagy te magad is, direktben, a /<név> paranccsal.

Ennek a bontásnak van egy nagy előnye is. A skill maga lehet részletesebb, mint a CLAUDE.md, mert a törzse csak akkor töltődik be, amikor használod.

Fontos, hogy a skill leírásából kiderüljön, mikor van rá szükség. Ne összefoglalót írj, hanem útbaigazítást:

rossz:  Testing conventions: test organization, structure, fixtures.
jó:     Use when writing, modifying, or running tests: test organization,
        structure, fixtures, and how to run them.

Az első egy tartalomjegyzék, a második egy feltétel.

Mi kerül a kontextusba?

A projekt gyökerében lévő CLAUDE.md teljes tartalma tényleg bekerül a kontextusba minden munkamenet elején. Az alkönyvtárakban lévő CLAUDE.md fájlok viszont csak akkor kerülnek a kontextusba, amikor a Claude Code ott olvas egy fájlt. A skillek esetén csak a nevük és az egysoros leírásuk kerül a kontextusba. A teljes tartalmuk csak akkor töltődik be, amikor a Claude Code ténylegesen meghívja a skillt. Emiatt kevesebb tokent használnak fel. Nem azért, mert kevesebb tudást tartalmaznak, hanem mert a teljes tartalmuk csak használatkor kerül a kontextusba.

Path-scoped rules

Van még egy kevésbé ismert megoldás is. Ha egy szabály nem a feladat típusától, hanem az érintett fájloktól függ, mondjuk csak akkor számít, ha épp a tests/ mappa alatt dolgozol, erre valók a path-scoped rule-ok.

Mi az a rule?

Egy .claude/rules/ alá tett Markdown-fájl, amelynek a front matter részében egy paths: minta határozza meg, mely fájlokhoz tartozik (pl. tests/**/*.py). Csak akkor kerül a kontextusba, amikor a Claude ténylegesen beolvas egy, a mintára illő fájlt.

Mi kerüljön a skillbe?

A skillbe ugyanúgy bármi kerülhet, ami a CLAUDE.md-be kerülhet. A skill alapvetően az adott munkafolyamat szabályait írja le. Ahol van értelme, oda egy jó és egy rossz példa is kerülhet.

A skillbe sem kell mindent beleírni. Ha valamire csak ritkán van szükség, akkor azt külön Markdown-fájlba teheted. Ilyen lehet például egy kiadási teendőlista. A skillben elég leírni, hogy mikor kell ezt a fájlt elolvasni.

Ha egy folyamatban nincs mit eldönteni, akkor érdemes scriptet írni hozzá. A változásnapló formázását például jobb egy scripttel elvégezni, mint minden alkalommal újra leírni a szabályait. A skillnek ilyenkor csak azt kell előírnia, hogy a Claude futtassa a scriptet.

Csak akkor bontsd tovább a skillt, ha a leválasztott részre ritkábban van szükség, mint a skill többi részére. Ha mindig együtt használod őket, a bontás csak több fájlt eredményez.

Nem mindegy, hogyan fogalmazol

Számít, hogyan fogalmazol meg egy szabályt. Ezt a saját bőrömön tapasztaltam meg, amikor egy-egy megfogalmazás más eredményt hozott, mint amire számítottam.

Az egyik szabály így szólt:

Check .claude/skills/ before writing code and follow the matching skill.

A „check” ugyanis teljesíthető úgy is, hogy a Claude csak elolvassa a fájlokat. Ebben az esetben elolvasta és követte a tartalmukat, de a skilleket nem hívta meg. Szigorúan véve megnézte. A javítás: Before writing code, invoke the matching skill with the Skill tool: reading the SKILL.md file instead does not count.

Egy másik szabály azt kérte, hogy kérdezzen vissza egy bizonyos esetben:

Ha a változás olyan fogalmat vezet be, amely egyik meglévő részhez sem tartozik, ne magadtól nevezd el. Javasolj két-három nevet, kérdezz rá, és csak utána hozd létre a fájlt.

Egy teljesen új fogalom bevezetésénél volt rá példa, hogy a Claude tényleg megállt és rákérdezett, de volt, hogy úgy gondolta, hogy ez nem új fogalom, ezért magától nevezte el a fájlt, kérdés nélkül.

Az eredmény nem determinisztikus. Ugyanarra a kérésre nem biztos, hogy mindig ugyanazt kapod, akkor sem, ha a szabály egyértelmű. Ezért érdemes pontosan behatárolni, mit bízol a modellre. Ahol nincs mit eldönteni, használj inkább előre megírt scriptet.

Kezdd kicsiben

Nem feltétlenül kell megtervezni az egészet. A legtöbb szabály, amit előre kitalálsz, lehet, hogy sosem fog kelleni, viszont ott lesz mindenki útjában.

Először írd le, hogyan kell futtatni a projektet, és mi hol van benne. Utána csak figyelj. Ha valamit már másodszor kérsz a Claude-tól, kérd meg, hogy fogalmazza meg szabályként. Így legközelebb nem kell újra elmondanod.

Végül mindig arról döntesz, hol legyen a szabály. Ami minden feladatnál kell, marad a CLAUDE.md-ben. Ami csak egy feladattípusnál, az egy skillbe kerülhet. Ha egy szabály csak bizonyos fájloknál számít, a .claude/rules/ alá kerülhet. Amit pedig nem kell minden alkalommal újragondolni, azt érdemes scriptre bízni.

Jó konfigurációval a Claude ugyanott keresi a szabályokat, ugyanazzal a paranccsal ellenőrzi magát, és ugyanúgy rögzíti a munka eredményét. Ettől a munkafolyamat kiszámíthatóbbá és következetesebbé válik.

A cikk 2026 augusztusában készült. Ez a terület gyorsan változik. Ha eltérést találsz, akkor érdemes a dokumentációt is megnézni.