Vytvořeno: 5.5.2026 | Aktualizováno: 05.05.2026 09:38
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.
Dva principy, které stojí za celým přístupem:
Dokumentace pro AI odpovídá na PROČ, ne na CO nebo JAK. CO a JAK jde přečíst přímo z kódu — agent to zvládne sám. Jediné, co z kódu vyčíst nejde, je záměr: proč byl zvolen tento přístup, jaké alternativy byly zamítnuty, co se tímto rozhodnutím vědomě obětovalo. Bez tohoto kontextu agent při každé nové session navrhuje „lepší„ řešení, které ale ignoruje důvody, proč věci jsou tak, jak jsou.
AS IS místo changelogu. Changelog zaznamenává historii změn — co se dělalo před rokem, před půl rokem. Pro AI agenta je tato historie bezcenná a škodlivá: zbytečně plní kontext a mate model tím, co už dávno neplatí. Místo toho dokumentace popisuje aktuální stav systému — jak věci fungují teď. Historie patří do verzovacího systému (git), ne do dokumentace pro agenta.
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:
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…
ADR (Architecture Decision Records) je praxe dokumentování důležitých architektonických rozhodnutí. Každé rozhodnutí dostane vlastní soubor — typicky v docs/decisions/ — a zaznamenává tři věci: kontext (proč jsme to vůbec řešili), rozhodnutí (co jsme zvolili) a důsledky (co to přináší a co to stojí).
Příklad souboru docs/decisions/001-pouzivame-postgresql.md:
# ADR-001: Používáme PostgreSQL jako primární databázi ## Status Accepted ## Kontext Potřebujeme relační databázi s podporou JSONB a plnotextového vyhledávání. ## Rozhodnutí Zvolíme PostgreSQL. Tým ho zná, splňuje technické požadavky a je dostupný v managed variantě na všech cílových platformách. ## Důsledky + Nepotřebujeme samostatnou službu pro full-text search. - Musíme zajistit správnou migrační strategii při změnách schématu.
Proč to dává smysl pro práci s AI agenty: Bez ADR agent při každé nové session neví, proč byl zvolen konkrétní přístup — a může navrhnout „lepší„ řešení, které ale rozhodnutí z minulosti ignoruje. ADR mu dá kontext, který v kódu samotném není vidět.
Formát ADR původně popsal Michael Nygard (2011). Dnes existuje více variant; populární je MADR (Markdown Architectural Decision Records), který přidává strukturovanější šablonu a podporu pro alternativy a zdůvodnění zamítnutých možností.
ADR není součástí Spec Kitu ani žádného konkrétního frameworku — jde o konvenci, která funguje nezávisle a snadno se přidá do jakékoliv struktury docs/.
Poznámka:ReadTheDocsnení veřejně dostupný nástroj ani hotová knihovna. Jde o vlastní MCP server, který si Ondřej Tučný postavil na míru pro svůj repozitář — prototyp v PowerShellu 7, přibližně 300 řádků. Nesouvisí se službou readthedocs.io. Název je jeho vlastní volba pro interní nástroj.
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:
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:
plan.md + changelog.md v repozitáři řeknou, kde předchozí session skončila.
Spec Kit od GitHubu implementuje právě tuto TO BE stranu — generuje strukturu tasks/ přes sadu příkazů (constitution → specify → plan → tasks → implement). Tučného framework říká kde TO BE dokumentace patří a jaký má životní cyklus; Spec Kit říká jak ji konkrétně vytvářet a udržovat.
Jsou to tedy dvě doplňující se vrstvy, ne alternativy: Spec Kit pokrývá TO BE část, ale neřeší strukturu AS IS docs/, dokumentaci u kódu ani MCP nástroj pro vyhledávání.
Klíčový meta-princip: nejdřív obecná stabilní struktura (substrát), pak specializace nad ní (metodiky).
Substrát definuje:
docs/, tasks/, src/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: