Kapitola 3 · Kontext · 8 min čtení

Předej Claudovi kontext projektu

Claude si nepamatuje. Každá konverzace začíná z nuly. Dobrý CLAUDE.md mu dává zkratky, které by si jinak musel objevit znova — a díky tomu každý prompt dopadá lépe.

Proč je kontext důležitější než model

Kvalita modelu se komoditizuje. Rozdíl dělá to, čím ho krmíš. Slabší model s dobrým kontextem obvykle porazí silnější bez kontextu.

Tři typy selhání, které poznáš:

1. „Dal mi kód, co ignoruje naše konvence" → neřekl jsi mu, jaké konvence máte
2. „Navrhl knihovnu, kterou nepoužíváme" → nevyjmenoval jsi, které používáte
3. „Pořád se ptá na věci, na které jsem už odpověděl" → nezapsal sis to

CLAUDE.md je místo, kam si to zapíšeš jednou. Až na to, že ho nepíšeš ty. Píše ho Claude.

Nech Claude napsat návrh

V projektu spusť:

/init

Claude proskenuje repo a navrhne CLAUDE.md s tím, co našel — stack, struktura, běžné skripty, zjevné konvence. Pro novější interaktivní průchod, který navíc navrhne skilly a hooky, nastav před spuštěním CLAUDE_CODE_NEW_INIT=1.

Výstup je startovní bod, ne hotový dokument. Teď požádej Claude, ať ho dolaďuje:

Znovu si přečti CLAUDE.md a přidej tři konvence, které používáme — strict TypeScript bez any, testy vedle souboru, který pokrývají, databázové migrace jako číslované SQL soubory. Sekce nech krátké.

A pak:

Znovu si přečti CLAUDE.md a přidej sekci Ne s pravidly, která pořád objevujeme znova — nesahej do app/legacy/, neinstaluj nové balíčky bez ptaní, nespouštěj migrace automaticky.

Claude soubor upraví a ukáže ti diff. Zkontroluj, potvrď, commitni. Dokument vyrostl tak, že jsi o pravidla požádal, ne tak, že jsi je do souboru natypoval.

Jak to obvykle vypadá

Pokud tě zajímá tvar — takhle obvykle vypadá to, co Claude napíše. Nepiš to sám, nech Claude, ať to sepíše z tvých odpovědí.

# CLAUDE.md

## Projekt
Interní nástroj pro onboarding zákazníků. 3k DAU, Postgres + Node, deploy na Vercelu.

## Konvence
- TypeScript strict mode. Žádné `any` bez komentáře.
- Testy bydlí u souboru: `foo.ts` + `foo.test.ts`.
- Databázové migrace jsou číslované SQL soubory v `/db/migrations/`.

## Ne
- Neinstaluj nové npm balíčky bez ptaní.
- Nesahej do `app/legacy/` — to je zamražené, čeká na rewrite.
- Nespouštěj migrace automaticky.

## Užitečné příkazy
- `pnpm dev` — lokální server na :3000
- `pnpm test` — vitest, watch mode
- `pnpm db:seed` — reset lokální DB na fixture stav

Cíl: pod 200 řádků na soubor. Delší soubory spotřebovávají víc kontextu a snižují, jak dobře se jich Claude drží. Hlubší reference je v kapitole 8.4.

Aktualizuj podle toho, co se učíš

Když tě Claude opraví, nemusíš zastavovat a ručně editovat CLAUDE.md. Stačí začít další zprávu znakem #:

#migrace musí být reverzibilní — ke každému up napiš i down

To je memory-add prefix. Claude vezme text za #, rozhodne, do jakého rozsahu patří (projekt / uživatel / lokální), a přidá ho do správného CLAUDE.md. Zůstal jsi ve flow, pravidlo se zachytilo.

Rozsah: managed, uživatel, projekt, lokální

Při startu sezení se načítají až čtyři vrstvy, všechny se zřetězí dohromady. Pozdější vítězí, když si pravidla odporují:

• Managed politika — nasazená přes MDM v enterprise prostředí. Lokálně ji nepřebíš. Objeví se jen na spravovaných strojích.
• Uživatel — ~/.claude/CLAUDE.md — o tobě: preference editoru, shell návyky, tón. Načítá se pro každý projekt.
• Projekt — ./CLAUDE.md nebo ./.claude/CLAUDE.md — o tomhle codebase: konvence, příkazy, ne. Commitnuté, sdílené s týmem.
• Lokální — ./CLAUDE.local.md — o tobě v tomhle projektu: lokální cesty, tajné klíče, rozdělaná práce. Gitignorované.

Vnořené CLAUDE.md soubory v podadresářích se načítají líně — jenom když Claude sahá do souboru uvnitř toho podadresáře. Užitečné pro monorepa. Alternativa: .claude/rules/*.md s paths: frontmatter, které se aktivují, jenom když se dotýkáš odpovídajících souborů.

→ Anthropic memory docs ↗ — kanonická reference.

Nech z něj mapu, ne manuál

Kontext je vzácný. CLAUDE.md, který se snaží říct všechno, vytlačí přesně to, s čím měl pomáhat — úkol, kód, relevantní dokumenty.

Ryan Lopopolo ↗ z OpenAI to po zkušenostech se stavbou produkčního systému převážně přes Codex pojmenoval přímo: drž svůj AGENTS.md / CLAUDE.md kolem 100 řádků a ber ho jako obsah, ne encyklopedii. Jeho formulace: Claude má být „mapa, ne tisícistránkový manuál.“ Skutečné znalosti žijí jinde — ve strukturovaných dokumentech, které si agent otevře, až když je potřebuje.

Jak to vypadá jako sekce tvého CLAUDE.md:

## Kde hledat
- Architektonická rozhodnutí — `docs/adr/`
- Runbooky — `docs/runbooks/`
- Refundy (flow) — `docs/runbooks/refunds.md`
- Style guide — `docs/style-guide.md`
- Hlubší API reference — `docs/api.md`

Claude teď mapu načte v každé session, aniž by četl celou encyklopedii. Když úkol zmíní refundy, otevře runbook. Když je úkol nový endpoint, přečte si style guide. Každý dokument napíšeš jednou, ve svém souboru, ve své velikosti — a mapa zůstane krátká.

Praxe: pokračuj se svou ukázkou

Procházíš lab popořadě? Vezmi, co tě tahle kapitola naučila, k ukázce, se kterou jsi začal v kapitole 2 — nebo rovnou ke svému vlastnímu codebase, kde to sedne hlouběji.

1. Otevři v Claudu složku projektu — samples/dotnet-core (Varianta A), samples/python-react (Varianta B), nebo svoje vlastní repo. Ukázkové složky mají starter CLAUDE.md; tvoje repo ho mít nemusí. Každopádně se podívej, co tam je, než do toho šáhneš.
2. Pusť /init. Claude navrhne aktualizovaný CLAUDE.md podle toho, co vidí. Srovnej návrh s tím, co máš — co mu uniklo, co přidal nad rámec, co je fakt lepší. Přijmi, co sedí, zbytek oprav.
3. Použij prefix # a přidej jedno dvě pravidla, která vylezla v kapitole 2, nebo která pořád opakuješ týmu — „chybové odpovědi vracej s polem error“, „než přidáš endpoint, přidej k němu test.“ Sleduj, v jakém scope každé z nich přistane; project scope chceš pro pravidla platná pro celý codebase.
4. Přidej sekci Kde hledat — jeden dva ukazatele na reálné cíle. Pokud tvoje repo má runbooky, ADR složku, nebo style guide, ukaž tam. Pokud ne, ukaž na místo, kam patří (docs/runbooks/, docs/adr/). Ten ukazatel je závazek.

Když to funguje: tvůj CLAUDE.md je tvůj — krátký, vyhraněný a odkazuje na hlubší docs, pro které vy oba skutečně půjdete. Praxe v další kapitole používá plan mode na přidání další funkce.