CLAUDE.md: osvědčené postupy a komentovaný příklad

CLAUDE.md je nejdražší soubor ve vašem repozitáři. Ne v bajtech. V opakování. Cokoli do něj dáte, se načte do kontextu Clauda na začátku každého sezení a pak jede s každou jednotlivou zprávou, kterou pošlete. Nafouklý CLAUDE.md je daň, kterou platíte stokrát denně, aniž si toho všimnete.

Ve SkillProof testujeme nastavení Clauda profesionálně a přečetli jsme už víc souborů CLAUDE.md, než bychom rádi přiznali. Většina z nich dělá stejnou chybu: berou soubor jako skládku všeho, co kdy autor chtěl, aby Claude věděl. Filozofie psaní kódu, preference tónu, kompletní style guide, tři odstavce o opatrnosti. Všechno načtené, pořád, pro každý požadavek — včetně toho, kdy jste Clauda požádali o přejmenování proměnné.

Tento návod je náš pokus to napravit. K čemu CLAUDE.md doopravdy je, kompletní komentovaný příklad k převzetí, co přesunout do skilů a aritmetika, která vysvětluje, proč na tom vůbec záleží.

Co je CLAUDE.md a kdy se načítá

CLAUDE.md je soubor projektové paměti Claude Code. Když spustíte sezení v adresáři, Claude Code prochází od pracovního adresáře nahoru, hledá soubory CLAUDE.md a co najde, načte do systémového kontextu. Načte se i váš globální soubor v ~/.claude/CLAUDE.md, a to v každém projektu. Soubory v podadresářích se načtou, když Claude pracuje se soubory v těchto podadresářích.

Část, která lidem uniká: není to jednorázové čtení. Jazykové modely jsou bezstavové, takže celý kontext včetně vašeho CLAUDE.md se posílá s každým požadavkem v konverzaci. Položte v sezení čtyřicet otázek a soubor se přenese čtyřicetkrát. Prompt caching zmírňuje dolarové náklady — ke konkrétním číslům se dostaneme — ale nic nezmírní náklady na pozornost. Každý token v CLAUDE.md je token, který soupeří s vaším skutečným kódem o pozornost modelu.

To je cena. A kupuje vám něco reálného: Claude začíná každé sezení s tím, že už zná vaše build příkazy, zvláštnosti architektury i miny ve vašem kódu. Nikdo nemusí podeváté vkládat „používáme pnpm, ne npm". Otázka nikdy nezní, jestli CLAUDE.md mít. Otázka zní, co si v něm místo zaslouží.

Zlaté pravidlo: fakta do CLAUDE.md, chování do skilů

Tady je teze celého článku a jediný filtr, který opraví většinu špatných souborů:

CLAUDE.md je pro fakta o tomto projektu. Skilly jsou pro znovupoužitelné chování.

Fakt o tomto projektu: „ceny se ukládají jako celé centy." To Claude neuhodne. Žádná míra obecné inteligence to nevyčaruje ze vzduchu a chyba v tom poškozuje data. Patří to do CLAUDE.md, trvale načtené, protože je to relevantní pro téměř každou změnu, která se dotýká peněz.

Znovupoužitelné chování: „při code review zkontroluj nejdřív ošetření chyb, pak bezpečnost, pak pojmenování." To není fakt o vašem projektu. Je to postup, platí pro každý projekt, na který kdy sáhnete, a je relevantní jen tehdy, když skutečně děláte review. Dejte to do CLAUDE.md a platíte za to při každé commit zprávě, každé úpravě CSS, každém „co dělá tahle funkce". Dejte to do skilu a stojí vás to jeden řádek metadat až do chvíle, kdy review opravdu probíhá — v tu chvíli se kompletní instrukce načtou na vyžádání.

Většina lidí cpe všechno do CLAUDE.md, protože je to soubor, o kterém vědí. Je přímo tady, evidentně funguje a náklady jsou neviditelné, protože žádná faktura nikdy neříká „tento měsíc jste za svůj style guide zaplatili 4 000krát". Ale náklady jsou reálné a rozdělení je téměř mechanické, jakmile si u každé instrukce položíte dvě otázky. Platí to jen pro tento projekt? Je to relevantní pro většinu požadavků? Dvě ano: CLAUDE.md. Cokoli jiného: skill, nebo koš.

Existuje i druhý důvod pro toto rozdělení, který s tokeny nesouvisí. Instrukce ve stále načteném souboru si navzájem konkurují. Viděli jsme CLAUDE.md o 2 000 slovech, kde skutečně důležité pravidlo („nikdy nespouštěj db:push proti stagingu") sedělo v jedenáctém odstavci, pod přednáškou o čistém kódu. Claude prochází dlouhé seznamy instrukcí stejně jako lidé: ostré položky se ředí vatou kolem nich. Krátké soubory se poslouchají. Dlouhé soubory se skenují po diagonále.

Komentovaný příklad CLAUDE.md pro středně velkou webovou aplikaci

Tady je kompletní příklad pro fiktivní, ale realistický e-shop v Next.js. Komentáře vysvětlují, proč si každá sekce zaslouží trvalé místo v kontextu. Má zhruba 350 slov, asi 500 tokenů, a troufáme si tvrdit, že nic v něm není ke škrtnutí.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Všimněte si, co tam chybí. Žádné „piš čistý, udržovatelný kód". Žádné instrukce k tónu. Žádné vysvětlování, co je Next.js. Žádná lint pravidla, která linter už mechanicky vynucuje. Každý řádek je buď příkaz, který Claude spustí, fakt, který nedokáže odvodit, nebo hranice, jejíž překročení stojí skutečné peníze nebo skutečné hodiny.

Co přesunout do skilů

Pokud má váš současný CLAUDE.md 1 500 slov, přebytek obvykle spadá do několika rozpoznatelných kategorií a každá z nich má domov ve tvaru skilu. Pár příkladů z našeho vlastního katalogu — všechny jsme před zařazením nainstalovali a otestovali na čistých strojích:

Git ceremonie. Pojmenování větví, formát commit zpráv, šablony popisů PR, kdy squashovat. To je chování, je identické napříč vašimi projekty a je relevantní jen ve chvíli, kdy skutečně commitujete. Skill git-workflow, který jsme testovali, pokrývá přesně tento rozsah, a jeho vytažení z CLAUDE.md obvykle ušetří 200 až 400 slov trvale načteného textu.

Checklisty pro review. Instrukce typu „když požádám o review, zkontroluj X a pak Y" jsou klasický squatter v CLAUDE.md. Jsou dlouhé, jsou procedurální a 95 % času spí. code-review-checklist načítá svůj checklist jen ve chvíli, kdy review probíhá, což je celý smysl formátu skilů.

Disciplína při debugování. Instrukce jako „nejdřív reprodukuj, vyslov hypotézu, po opravě ověř" popisují metodiku, ne váš projekt. systematic-debugging tuto metodiku zabalí a drží se mimo kontext, dokud zrovna nehoníte chybu.

Obecné pravidlo: pokud byste odstavec mohli zkopírovat do CLAUDE.md jiného projektu bez úprav, není to fakt o vašem projektu a nemá tam co dělat. Vytáhněte ho. Napsání vlastního skilu zabere s naším návodem asi dvacet minut a je to nejvýnosnějších dvacet minut, jaké má k dispozici kdokoli, jehož CLAUDE.md přesáhl jednu obrazovku.

Anti-patterny, které vídáme pořád dokola

Procházíme hodně setupů a stejných pět selhání se opakuje ve smyčce.

Román. CLAUDE.md o 3 000 slovech, který se čte jako inženýrská příručka. Někdo měl špatnou zkušenost, přidal odstavec, měl další, přidal další a nikdy nic nesmazal. Soubor jen roste. Kromě tokenových nákladů takové soubory pohřbívají dvě pravidla, na kterých skutečně záleží, pod dvaceti, na kterých ne — a Claudova poslušnost vůči všem klesá společně.

Zastaralé příkazy. Soubor říká npm run test:unit, skript byl před osmi měsíci přejmenován na pnpm test, a Claude teď sebevědomě spouští příkaz, který selže, přečte si chybu, pohrabe se v package.json a vzpamatuje se. Každé sezení. Platíte za špatnou dokumentaci a pak platíte znovu za to, že ji Claude obchází. Špatný CLAUDE.md je horší než žádný, protože Claude mu věří.

Duplikovaná lint pravidla. „Používej jednoduché uvozovky. Žádné nepoužité proměnné. Maximální délka řádku 100." Vaše konfigurace ESLintu to už vynucuje mechanicky, s lepším pokrytím, než jaké kdy zvládne pozornost LLM. Opakovat strojově vynucovaná pravidla v próze je čiré plýtvání. Jediná výjimka: pravidla, která tooling nezachytí, jako „neimportuj ze src/legacy" — ta si zápis skutečně zaslouží.

Sekce „buď nápomocný". „Piš čistý kód. Před změnami pečlivě přemýšlej. Buď důkladný, ale stručný." Nějakou variantu vidíme asi v polovině souborů, které procházíme, a nedělá nic. Claude se už snaží. Instrukce založené na vibech bez testovatelného obsahu jsou první věc ke smazání a jejich jediný měřitelný efekt jsou tokeny, které spálí.

Autobiografie. Dlouhé popisy toho, co produkt dělá, kdo jsou uživatelé, mise firmy. Občas jeden produktový fakt pro rozhodování o kódu opravdu záleží („naši uživatelé jsou na pomalém venkovském připojení, velikost bundlu je reálné omezení"). Tu jednu větu si nechte. Pitch deck škrtněte.

Tokenová matematika

Udělejme si aritmetiku, kterou lidé přeskakují, protože právě čísla z nás udělala minimalisty.

CLAUDE.md o 3 000 slovech je zhruba 4 000 tokenů. Jede s každým požadavkem, takže pracovní sezení o 40 zprávách ho přenese 40krát: 160 000 tokenů vstupu v jednom sezení, které jsou váš paměťový soubor, ne váš kód ani konverzace. Pracujte pět sezení denně a přesouváte 800 000 tokenů CLAUDE.md za den. Za měsíc o 22 dnech asi 17,6 milionu.

Prompt caching zachrání většinu dolarových nákladů a měli bychom být upřímní. Kešovaný vstup na Sonnetu stojí desetinu základní ceny, takže těch 17,6 M tokenů vyjde na pár dolarů měsíčně, pokud cache zůstává teplá, spíš 50 $, pokud ne. Otravné, ne zničující.

Náklad, který kešování nezachrání, je kontext. Kontextové okno Claude Code je konečné a dlouhá sezení už tak končí kompakcí, kdy se konverzace shrne a detaily se ztratí. Trvalý rezident o 4 000 tokenech znamená, že na kompakci narazíte dřív, každé sezení, navždy. A degraduje pozornost ještě před jakýmkoli tvrdým limitem: modely prokazatelně dodržují instrukce lépe, když jich soupeří méně. Rozdíl mezi souborem o 500 tokenech a souborem o 4 000 tokenech není 3 500 tokenů. Je to otázka, jestli modelu vaše pravidlo „nikdy nesahej na staging" ještě leží na srdci u zprávy číslo 35.

Prožeňte stejná čísla osekaným příkladem výše: 500 tokenů, 40 zpráv, pět sezení, 22 dní. Asi 2,2 M tokenů měsíčně, osmina nafouklé verze, a důležitá pravidla stojí v nepřeplněné místnosti. Širší playbook na snižování nákladů jsme sepsali v našem průvodci tokenovými náklady a osekání CLAUDE.md je v něm trvale nejlevnější výhra.

Projektový vs. globální: rozdělení ~/.claude/CLAUDE.md

Máte dva soubory a věci se kazí, když obsah skončí ve špatném z nich.

~/.claude/CLAUDE.md je globální. Načítá se v každém projektu, takže smí obsahovat jen věci pravdivé všude: „na všech osobních projektech používám pnpm", „odpovídej anglicky, i když mé prompty jsou občas rusky", „nikdy necommituj bez vyzvání". Držte ho pod deseti řádky. Každý řádek se tu násobí napříč veškerou vaší prací, takže jeho rozpočet má být nejpřísnější.

<project>/CLAUDE.md je projektový soubor, commitnutý v gitu, sdílený s kolegy a CI. Fakta o tomto kódu, ve tvaru příkladu výše. Protože je sdílený, osobní preference do něj nepatří; na to je CLAUDE.local.md nebo globální soubor.

Soubory CLAUDE.md v podadresářích jsou nedoceněná střední vrstva. packages/api/CLAUDE.md s fakty specifickými pro API se načte, jen když Claude na daný balíček sáhne. Pokud má kořenový soubor vašeho monorepa sekce platné pro jeden workspace, jejich posunutí o úroveň níž je úspora tokenů zdarma s nulovou ztrátou informace.

Jednu mylnou představu stojí za to zabít: umístění věci do více těchto souborů nezpůsobí, že ji Claude bude dodržovat víc. Způsobí to, že soubor bude delší. Vyberte každému faktu jeden domov.

Jak soubor udržovat čerstvý

CLAUDE.md hnije rychleji než běžná dokumentace, protože když je špatně, nic viditelně nespadne. Testy selhávají hlasitě. Zastaralý paměťový soubor jen potichu svádí model na scestí, model se potichu vzpamatuje a vy potichu platíte za obojí.

Náš rituál je nudný a zabere deset minut měsíčně. Otevřete soubor. Každý příkaz skutečně spusťte. U každého uvedeného faktu se zeptejte, jestli je pořád pravdivý a jestli kvůli němu Claude tento měsíc něco pokazil. Smažte aspoň jeden řádek; vždycky nějaký je, a pokud ho nemůžete najít, polevila vaše laťka pro „zasloužit si místo". Pak zkontrolujte délku: jedna obrazovka je cíl, dvě obrazovky strop, a za ním už needitujete, ale extrahujete do skilů.

Nejlepší spouštěč aktualizací ale není kalendář. Je to okamžik, kdy Claude udělá něco špatně, protože ho soubor zmátl. Opravte soubor jedním dechem s kódem. Zacházejte s chybami v CLAUDE.md jako s bugy, protože mají stejné chování recidivy: neopravené se příští sezení stanou znovu.

FAQ

Jak dlouhý má CLAUDE.md být?

Pod 500 slov pro většinu projektů, pod 1 000 pro opravdu složité monorepo. Náš pracovní test: pokud se nevejde na jednu obrazovku, něco v něm je chování převlečené za fakt — a to něco patří do skilu. Příklad v tomto článku má asi 350 slov a pokrývá reálnou středně velkou aplikaci.

Jaký je rozdíl mezi CLAUDE.md a skilem?

Způsob načítání. CLAUDE.md se načítá celý, vždy, pro každý požadavek. Skill vystavuje jen jednořádkový popis, dokud mu úkol neodpovídá, a pak se načte na vyžádání. CLAUDE.md má tedy držet fakta, která potřebujete neustále, a skilly postupy, které potřebujete občas. Mechaniku pokrývá náš průvodce skilly.

Mám CLAUDE.md commitovat do gitu?

Ano. Je to sdílená dokumentace a sezení vašich kolegů s Claudem těží ze stejných faktů jako ta vaše. Osobní preference držte v CLAUDE.local.md (v gitignore) nebo v globálním souboru, místo abyste je vnucovali týmu.

Můžu používat vnořené soubory CLAUDE.md v podadresářích?

Ano, a v monorepech byste měli. Claude Code načte soubor podadresáře, když pracuje s tamními soubory. Kořenový soubor dostane fakta platná pro celé repo, packages/api/CLAUDE.md fakta o API a projekty s jedním balíčkem mohou vnořování úplně přeskočit.

Změní osekání CLAUDE.md skutečně chování Clauda, nebo jen náklady?

Obojí, a chování je větší výhra. Dodržování instrukcí degraduje s jejich počtem; krátký soubor s pěti ostrými pravidly se poslouchá spolehlivěji než dlouhý se třiceti. Úspora tokenů je ta měřitelná část — naše žebříčky efektivity sledují, které skilly tam pomáhají nejvíc — ale zlepšení poslušnosti je to, čeho si všimnete jako první.

Jeden názor na závěr: nejlepší soubory CLAUDE.md, jaké jsme viděli, byly všechny editované mazáním. Nikdo nenapíše skvělý první den. Napíšete průměrný, sledujete, kde Claude klopýtá, přidáte fakt, který by tomu zabránil, a škrtnete řádek vaty, abyste ho zaplatili. Šest týdnů tohohle porazí jakoukoli šablonu, včetně té naší.