Rozdíly

Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.

--- ai:platformy:claude-code:strukturace-dokumentace [05.05.2026 09:03] – Nový článek: Strukturace dokumentace pro Claude Code (podle prezentace Ondřeje Tučného, Vibeco Ding Talks 2026) Petr Nosek
+++ ai:platformy:claude-code:strukturace-dokumentace [05.05.2026 09:38] (aktuální) – Doplnění dvou klíčových principů: PROČ místo CO/JAK, AS IS místo changelogu Petr Nosek
@@ Řádek 3: / Řádek 3: @@
 //Vytvořeno: **5.5.2026** | Aktualizováno: **~~LASTMOD~~**//
-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 [[https://vibecoding.cz|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.
+[[https://www.vibecoding.cz/download/strukturace-dokumentace-pro-claude-code-v2.pdf|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 [[https://vibecoding.cz|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.
+===== Co AI agent z dokumentace skutečně potřebuje =====
+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.
 ===== Kde plochá struktura přestává stačit =====
@@ Řádek 61: / Řádek 71: @@
 Pro sledování aktuálnosti lze přidat do frontmatteru hash API: ''api_hash: a7f3c9…''
+===== ADR – architektonická rozhodnutí =====
+[[https://adr.github.io|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'':
+<code markdown>
+# 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.
+</code>
+**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 [[https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions|Michael Nygard (2011)]]. Dnes existuje více variant; populární je [[https://adr.github.io/madr/|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/''.
 ===== ReadTheDocs – nástroj místo @odkazů =====
+> **Poznámka:** ''ReadTheDocs'' není 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 [[https://readthedocs.io|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.
@@ Řádek 82: / Řádek 123: @@
   * 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ů.
 ===== Úkolová historie v tasks/ =====
@@ Řádek 108: / Řádek 147: @@
   * **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í
+==== Spec Kit jako konkrétní implementace tasks/ ====
+[[ai:platformy:agenti-a-orchestrace:spec-kit|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í.
 ===== Substrát, ne metodika =====
@@ Řádek 136: / Řádek 181: @@
 ===== Zdroje =====
-  * Prezentace: Ondřej Tučný – Strukturace dokumentace pro efektivní použití s Claude Code, Vibeco Ding Talks, 20. 4. 2026
+  * [[https://www.vibecoding.cz/download/strukturace-dokumentace-pro-claude-code-v2.pdf|Ondřej Tučný – Strukturace dokumentace pro efektivní použití s Claude Code]] (PDF, Vibeco Ding Talks, 20. 4. 2026)
   * [[https://vibecoding.cz|vibecoding.cz]] – výchozí referenční základ (článek Patricka Zandla)
+  * [[ai:platformy:agenti-a-orchestrace:spec-kit|Spec Kit]] – nástroj pro TO BE část workflow
+  * [[https://adr.github.io|adr.github.io]] – nástroje a přehled ADR
+  * [[https://adr.github.io/madr/|MADR – Markdown Architectural Decision Records]]
+  * [[https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions|Michael Nygard – Documenting Architecture Decisions (2011)]]
+  * [[https://readthedocs.io|readthedocs.io]] – nesouvisející služba pro hosting dokumentace (stejný název, jiný účel)