Strukturace dokumentace pro Claude Code

Toto je starší verze dokumentu!

Vytvořeno: 5.5.2026 | Aktualizováno: 05.05.2026 09:03

Prezentace Ondřeje Tučného z akce Vibeco Ding Talks (20. 4. 2026) popisuje systém strukturování dokumentace pro projekty s Claude Code, který škáluje od malých repozitářů až po miliony řádků kódu. Výchozím bodem je vibecoding.cz – konkrétně přístup Patricka Zandla, který funguje do určité velikosti projektu. Tato prezentace řeší, co dělat, když tento přístup přestane stačit.

Základní přístup (CLAUDE.md = odkazy, tematické soubory, gotchas.md, aktualizace po každém úkolu) funguje dobře u menších projektů. Problémy nastávají při růstu:

Plochá docs/ – stovky souborů na jedné úrovni, bez orientace
gotchas.md jako jeden soubor – entropická past, která roste bez struktury
Specifikace v docs/ – míchá pending změny (TO BE) s aktuálním stavem systému (AS IS)
„Aktualizuj po každém úkolu„ – naděje, ne proces; bez struktury se nedodržuje
Žádná historie rozhodování – kontext se ztrácí mezi sekcemi

Dokumentace má dva úplně jiné životní cykly a nepatří do jedné složky.

docs/	tasks/<EPIC>/spec/
Popisuje, co systém je dnes	Popisuje, co se má stát v konkrétním epiku
Aktualizuje se při mergi úkolu nebo epiky	Vzniká před implementací, migruje do AS IS po dokončení
Čte se jako „jak to funguje“	Čte se jako „co mám udělat„
Jeden strom pro celý systém	Jeden strom pro každý epik, paralelně

Praktický dopad: Agent čte TO BE jako zadání a AS IS jako kontext. Po mergi se TO BE promítne do AS IS.

Toto jediné oddělení řeší velkou část problémů se stálostí dokumentace.

Stejný vzor na všech úrovních: systém → modul → podmoduly.

docs/
├── architecture/           # Systémová architektura
├── reference/              # Funkční referenční popis
├── modules/
│   ├── billing/
│   │   ├── README.md       # Konceptuální přehled
│   │   ├── architecture/
│   │   └── modules/        # Rekurze
│   └── invoicing/
└── …

Princip partial population: Substrát je superset. Malý repozitář instancuje jen část vzoru, velký projekt přidává hloubku – ale každý modul má stejnou strukturu.

Proč to funguje pro agenta: Claude se nenaučí konkrétní cesty, ale jeden vzor. Aplikuje ho v jakékoliv hloubce bez přeškolování.

V každé složce se zdrojáky přibydou dva soubory:

DESCRIPTION.md – co tady žije, jaké API poskytujeme, jak se to používá. Popis namespace (C#), modulu (Python/Rust) nebo package (TypeScript/Node).

MODULES.md – auto-generovaný přehled: co je v tomhle modulu za namespaces. Pro agenta rychlý scan před zanořením do detailů.

Logika provázání: Claude edituje soubor → vyjde nahoru k dokumentaci. Dokumentace zmíní funkci → Claude najde zdroj.

Pro sledování aktuálnosti lze přidat do frontmatteru hash API: api_hash: a7f3c9…

Ve velkém repozitáři jsou @odkazy v CLAUDE.md nepoužitelné – desítky cest, které se mění. Řešení je vlastní MCP nástroj ReadTheDocs, který zná strukturu repozitáře a vrátí jen relevantní dokumentaci.

Příklady volání:

ReadTheDocs({ topic: "architecture", module: "billing" })
ReadTheDocs({ forCode: "src/Billing/Invoicing" })   // co dokumentuje tenhle kód
ReadTheDocs({ concept: "idempotence" })              // najdi napříč celým repem
ReadTheDocs({ adr: "list", topics: ["auth"] })       // ADR filtrované podle tématu

Výsledek: CLAUDE.md se scvrkne z dvaceti @odkazů na jedinou větu: „Pro dokumentaci použij ReadTheDocs.“

Vlastnosti nástroje:

Bez cest – Claude zná jen konvenci, ne konkrétní soubory
Bez kolizí – stejné jméno souboru může existovat v každém modulu
Šetří kontext – agent dostane jen podstatné, ne celý strom

Prototyp je napsaný v PowerShellu 7, přibližně 300 řádků.

Každý úkol dostane vlastní složku – tasks/<EPIC-KEY>/<TASK-KEY>/.

tasks/CF-100-EPIC/
├── README.md               # Scope epiku
├── spec/                   # TO BE specifikace
├── CF-142/
│   ├── assignment.md       # Zadání – co a proč
│   ├── plan.md             # Plán – jak
│   └── changelog.md        # Co se skutečně udělalo
└── CF-143/
    └── …

tasks/ je cold storage – Claude ji standardně nečte. Použije ji jen na vyžádání nebo pro vedení dokumentace aktuálního tasku.

Proč to dává smysl:

Multi-session vývoj – každá session začíná bez paměti. plan.md + changelog.md v repozitáři řeknou, kde předchozí session skončila.
Rozhodnutí se neztratí – nejsou v commit messages, nepřekáží v docs/
Více agentů nebo vývojářů – každý vidí historii a důvody rozhodnutí

Klíčový meta-princip: nejdřív obecná stabilní struktura (substrát), pak specializace nad ní (metodiky).

Substrát definuje:

kde co leží – docs/, tasks/, src/
kdy se co aktualizuje – cadence
jak se to prohledává – ReadTheDocs kontrakt
základní frontmatter – schéma

Metodiky (UX, DevOps, analýza, …) jsou specializace nad substrátem. Nepřepisují ho, jen rozšiřují. Dvě metodiky mohou běžet v jednom repozitáři bez konfliktu.

Výhody substrátu:

Přenositelný – Claude chápe každý repozitář se stejnou strukturou stejně
Nezávislý vývoj – metodiky se sdílí mezi týmy bez zásahu do základu
Rozšiřitelný – nová role = nová metodika, substrát se nemění

Oddělte AS IS a TO BE. Jedna změna struktury, která řeší půlku problémů se stálostí dokumentace.
Nedávejte Claudeovi cesty. Dejte mu konvenci a nástroj. ReadTheDocs nebo ekvivalent. CLAUDE.md se zkrátí o polovinu.
Substrát před metodikou. Začněte obecně – struktura, stavy, frontmatter. Metodika přijde na druhý krok.

Prezentace: Ondřej Tučný – Strukturace dokumentace pro efektivní použití s Claude Code, Vibeco Ding Talks, 20. 4. 2026
vibecoding.cz – výchozí referenční základ (článek Patricka Zandla)