Většina vývojářů přistupuje k dokumentaci v Claude Code stejně jako k dokumentaci obecně — píší ji pro lidi. Nebo vůbec, případně ji odbudou. To je chyba. docs/ v kontextu Claude Code je znalostní báze pro agenta, ne veřejná dokumentace projektu. Čím dříve toto rozlišení pochopíte, tím lépe bude Claude rozumět vašemu projektu a tím méně času budeš trávit opakovaným vysvětlováním již vysvětleného.
A to si přiznejme, je něco, co začátečníky v Claude Code prudí hodně. Ale jde o nepochopení. LLM si prostě z principu nic “nepamatuje”. Vždycky začíná znovu. Pokud chceme, aby si něco “pamatoval”, musíme mu tyto informace přidávat jako kontext. A k tomu má právě Claude Code celou řadu přístupů, kdy to dělá za vás. Jen musíme vědět, jak mu s tím pomoci.
Základní princip: kontext na vyžádání
Claude Code načítá soubory do kontextu průběžně podle potřeby — ne všechno najednou. Vedou ho k tomu dva důvody:
- Snaha ušetřit rozsah zpracovávaných dat a tím i vaše tokeny a útratu
- Problém ztráty pozornosti LLM nad velkými prompty, kdy podobně jako lidé i LLM modely pustí některá data “z hlavy”, když jich je na ně prostě moc…
Z toho plyne klíčové pravidlo: do CLAUDE.md patří odkaz na dokumentaci, ne její obsah. Mimochodem, jak efektivní vlastně CLAUDE.md je, to je zajímavá otázka sama o sobě.
Místo kopírování celé API dokumentace do CLAUDE.md napíšeš:
## Dokumentace projektu
@docs/architecture.md
@docs/conventions.md
@docs/gotchas.md
## API dokumentace
Při práci s konkrétním API modulem přečti příslušný soubor z docs/api/
Soubory odkazované přes @ v CLAUDE.md jsou Claudovi k dispozici od začátku sezení. architecture.md a conventions.md patří do přímých odkazů v CLAUDE.md protože jsou relevantní pro téměř každý úkol — Claude s nimi bude pracovat pravidelně. Soubory v docs/api/ je lepší ponechat bez přímého odkazu a instruovat Claudea aby si přečetl příslušný soubor podle toho na čem pracuje. Výsledek: CLAUDE.md zůstane krátký, dokumentace zůstane v souborech kde ji lze verzovat a udržovat samostatně.
Upozornění k rozsáhlým souborům: pokud je dokumentace velmi dlouhá a Claude ji načte celou, může to kontext zatížit stejně jako přímé vložení. Pro rozsáhlé popisy rozhraní je lepší rozdělit je do menších tematických souborů — například popsat jednotlivé části API docs/api/auth.md místo jednoho popisu všech API docs/api.md o tisíci řádcích.
Doporučená struktura složky docs/
docs/
├── architecture.md # Jak je systém navržen a proč
├── conventions.md # Kódovací standardy a konvence
├── gotchas.md # Věci které nejsou zřejmé ze zdrojového kódu
├── api/
│ ├── auth.md # Autentizace a autorizace
│ ├── payments.md # Platební endpointy
│ └── users.md # Uživatelské endpointy
├── requirements/
│ ├── auth-redesign.md # PRD pro přepracování přihlašování
│ └── payment-flow-v2.md # PRD pro platební tok
└── decisions/
├── 001-db-choice.md # Proč PostgreSQL a ne MongoDB
└── 002-auth-flow.md # Proč JWT a ne sessions
Co patří do jednotlivých souborů
architecture.md popisuje celkový pohled na systém, hlavní moduly a jejich vztahy, technologický zásobník a důvody volby. Claude toto čte když dostane úkol který zasahuje do více částí systému.
api/*.md obsahuje podrobné popisy rozhraní, vstupní a výstupní tvary dat, chybové stavy a závislosti. Rozdělení do tematických souborů je klíčové — Claude načte jen api/auth.md když pracuje na přihlašování, ne celou API dokumentaci.
gotchas.md je nejcennější soubor v celé struktuře. Patří sem věci které nejsou zřejmé ze zdrojového kódu: “testy používají skutečnou databázi, ne atrapy”, “tento endpoint má vedlejší efekt který posílá e-mail”, “nikdy nevolej funkci X před inicializací Y”. Sem patří vše co jsi Claudovi musel vysvětlovat víckrát.
decisions/ obsahuje záznamy architektonických rozhodnutí. Claude pak nepřepisuje věci které byly záměrně rozhodnuty — ví proč jsou takto navrženy a respektuje to.
Automatická údržba přes CLAUDE.md
Klíčová změna přístupu: nech Claudea dokumentaci průběžně aktualizovat jako součást každého úkolu. Do CLAUDE.md přidej instrukci:
## Dokumentace
Po každém úkolu který mění chování systému aktualizuj příslušný soubor
v docs/. Zejména docs/gotchas.md pokud jsi narazil na něco
neočekávaného nebo jsi musel učinit předpoklad který není zřejmý
ze zdrojového kódu.
Výsledek: dokumentace roste organicky se samotným projektem, ne jako dodatečná práce navíc. A co je důležitější — Claude dokumentuje věci které sám objevil při práci na kódu. Příští sezení pak začíná se znalostí kterou předchozí sezení získalo.
Toto je přímá odpověď na jeden ze základních problémů Claude Code: každé sezení začíná bez paměti předchozích. Více praktických tipů, jak z Claude Code vytěžit maximum, najdete v přehledu insights. Dobře udržovaná docs/ složka tento problém z velké části řeší — ne přes paměť modelu, ale přes explicitní znalostní bázi v repozitáři.
Strategie pro PRD
PRD (specifikace produktových požadavků) má v kontextu Claude Code přirozené místo v docs/requirements/. Nedávej na něj odkaz přímo v CLAUDE.md — načítal by se vždy a zbytečně zatěžoval kontext. Místo toho přidej instrukci:
## Požadavky
Před implementací nové funkce přečti příslušný PRD z docs/requirements/.
Pokud PRD neexistuje, zeptej se na záměr před tím než začneš kódovat.
Jak spustit implementaci podle PRD
Základní prompt:
claude "přečti docs/requirements/payment-flow-v2.md a implementuj podle specifikace"
Funguje, ale má slabinu: Claude tiše doplní předpoklady tam kde zadání mlčí. PRD nikdy nepokryje vše — vždy jsou mezery, nejednoznačnosti, implicitní předpoklady. Tiché doplnění předpokladů je jeden z nejčastějších zdrojů toho, že výsledek “technicky odpovídá specifikaci” ale nedělá co jsi chtěl.
Lepší verze:
claude "přečti docs/requirements/payment-flow-v2.md. Před implementací
se mě zeptej sokratovskou metodou na všechna místa kde zadání nerozumíš,
je nejednoznačné nebo si interně protiřečí. Čekej na moje odpovědi
před tím než začneš kódovat."
Přidaná část “čekej na moje odpovědi před tím než začneš kódovat” je důležitá. Bez ní Claude někdy položí otázky a rovnou začne implementovat s vlastními předpoklady — splnil instrukci formálně, ale ne v duchu.
Sokratovské dotazování pokrývá tři různé situace které každá vyžadují jiný typ otázky: Claude neví jak něco implementovat, zadání připouští více výkladů, nebo zadání si interně protiřečí. Explicitní pojmenování všech tří v promptu výrazně zlepšuje kvalitu otázek které Claude položí.
Kdy sokratovský přístup použít a kdy ne
Tento přístup má smysl pro komplexní funkce kde PRD pokrývá záměr ale ne implementační detaily. Pro jednoduché dobře definované úkoly (“přidej validaci e-mailu do formuláře”) je zbytečná režie.
Praktické pravidlo: pokud úkol zasahuje do více než tří souborů nebo má netriviální obchodní logiku, sokratovský přístup před implementací se vyplatí. A pokud chcete Claude Code rozšířit o vlastní funkce, podívejte se na systém pluginů.
Co do docs/ nepatří
Obecná dokumentace pro uživatele produktu, návody, záznamy změn — to patří jinam. docs/ v kontextu Claude Code je interní znalostní báze agenta. Pokud projekt má obojí, doporučuji oddělit: docs/ pro Claudea, public-docs/ nebo wiki/ pro uživatele.
Shrnutí
Dobře navržená docs/ složka řeší jeden ze základních strukturálních problémů Claude Code: ztrátu kontextu mezi sezení. Ne přes paměť modelu, ale přes explicitní znalostní bázi která žije přímo v repozitáři, verzuje se spolu s kódem a aktualizuje se automaticky jako součást každého úkolu.
Výsledek po několika týdnech: Claude začíná každé sezení s hlubším porozuměním projektu než měl na konci sezení předchozího. A pokud s Claude Code teprve začínáte, projděte si praktický průvodce pro výuku.
Poznámka na závěr: tento článek má délku, která je zcela v intencích doporučené délky pro CLAUDE.md 😇