Immutable. This exact content is served forever at /api/v1/blob/f5cd6e78682f92c6.
--- name: specify description: Skill se použije, když uživatel zadá "/specify", nebo chce z nápadu udělat zadání – produktovou specifikaci a návrh řešení nového projektu, aplikace, webu nebo větší feature, ještě než se začne programovat. Vede debrief otázku po otázce, sepíše docs/requirements.md a docs/architecture.md a předá to do implementačního plánu. allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent, AskUserQuestion, Skill] --- # Specify ## Co skill dělá Uživatel má nápad a chce z něj zadání, podle kterého se dá stavět. Skill ho provede debriefem a sepíše **dva dokumenty**: | Dokument | Odpovídá na otázku | Pro koho | |---|---|---| | **`docs/requirements.md`** | Co stavíme a proč | Zadavatel, produkt, obchod – a ty za půl roku | | **`docs/architecture.md`** | Jak to postavíme | Ten, kdo to bude implementovat | Pak je předá do implementačního plánu. ## Proč dva dokumenty a ne jeden Mají **jinou životnost**. Produktový záměr se mění zřídka; technické řešení s každým rozhodnutím o technologii. V jednom souboru se při výměně databáze edituje tentýž dokument, ve kterém stojí popis cílové skupiny – a produktová část se tím postupně obrušuje. Platí tu *Cílová skupina určuje umístění* z `~/.claude/RULES.md`. **Nerozejdou se, protože se nepřekrývají.** Hranice je tvrdá: - **Do požadavků patří omezení**, do návrhu řešení **volba**. „Musí to běžet na běžném sdíleném hostingu bez placených závislostí“ je produktové omezení a patří do `requirements.md`. „Použijeme SQLite, protože…“ je volba a patří do `architecture.md`. - **`requirements.md` nesmí obsahovat architekturu.** Ani „nejspíš to bude na Vercelu“. Jakmile to tam napíšeš, začne se to rozcházet s `architecture.md`. - **`architecture.md` nesmí obsahovat zdůvodnění produktu.** Argumentuje z požadavků odkazem, neopisuje je. Když si nejsi jistý, kam věta patří, ptej se: *změní se, když se změní technologie?* Ano → `architecture.md`. Ne → `requirements.md`. ## Co skill nedělá - **Nic neprogramuje.** Ani scaffold, ani „jen rychle rozjedu projekt“. Tvrdá brána – viz *Zákaz implementace*. - **Nezakládá projekt.** Strukturu, git, autocommit a doménové importy dělá `/project`. Když chybí, skill na to upozorní a nabídne ho. - **Nepíše implementační plán.** Ten dělá `/breakdown`. Skill mu jen předá řízení, až je zadání schválené. - **Neduplikuje `superpowers:brainstorming`.** Dialog, klasifikaci rozsahu i návrh řešení řídí ten skill. ## Vztah k superpowers | Krok | Kdo ho dělá | |---|---| | Klasifikace rozsahu (spike / bounded / architectural) | `superpowers:brainstorming` | | Doptávání, varianty řešení, návrh, schvalovací brány | `superpowers:brainstorming` | | **Produktový rámec a sepsání požadavků** | **tenhle skill** | | Sepsání návrhu řešení | `brainstorming` ho vytvoří, tenhle skill mu určí cíl a tvar | | Implementační plán | `/breakdown` | | Realizace plánu | `/implement` | **Přepis výchozí cesty.** `brainstorming` ukládá design doc do `docs/superpowers/specs/YYYY-MM-DD-<téma>-design.md`. Explicitně přitom respektuje uživatelovu preferenci a ta zní jinak – podle `~/Dev/context/structure/structure.md` jsou v `docs/` jednoslovné anglické názvy bez datumových prefixů, takže cíl je **`docs/architecture.md`**. **Řekni mu to výslovně**, když ho vyvoláváš. Jinak si založí vlastní adresářový strom vedle toho tvého. Totéž platí pro plán, ale ten už si hlídá `/breakdown`. **Zadání pro plán je `docs/architecture.md`**, ne `requirements.md`. Plán argumentuje z návrhu řešení; požadavky jdou jako doplňkový kontext, aby bylo vidět, proč se to staví. O předání se stará `/breakdown`. ## Zásady pro celý průběh - **Ptej se postupně a přes tool `AskUserQuestion`** – postup, tvar otázky i mechanika toolu viz `~/.claude/RULES.md`, *Ptej se postupně, ne všechno najednou*. - **Nic si nevymýšlej** – technický název, ID, parametr, cizí API, cena. Viz `~/.claude/RULES.md`, *Při nejistotě se zeptej*. - **Zapisuj průběžně** – ve chvíli, kdy rozhodnutí padne, ne až na konci. Viz `~/.claude/RULES.md`, *Pravda v souborech, ne v konverzaci*; kam co patří, definuje `structure.md`. - **Navrhuj kompletně, realizuj postupně** – viz `~/.claude/RULES.md`. Tady to znamená: požadavky i návrh řešení popisují celou věc včetně toho, co bude až později; řeže se až plán, a ten se dělá jen na MVP. - **YAGNI.** Z každého návrhu vyhoď, co není potřeba – ale zapiš to do *Mimo rozsah*, ať je vidět, že to bylo zvážené a zamítnuté, ne opomenuté. ------ ## Zákaz implementace **Dokud není návrh hotový a schválený, nesmí vzniknout ani řádek produkčního kódu.** Žádný scaffold, žádné `npm create`, žádná databáze, žádné „jen si ověřím, že to jde“. Výjimka je jediná: **ověřovací sonda**, když na odpovědi stojí rozhodnutí v návrhu („zvládne to hosting?“, „má to API tenhle endpoint?“). Pak řekni dopředu, co zkoušíš a proč, výsledek použij jako podklad a **kód zahoď** – označ ho jako jednorázový a nenechávej ho v projektu. | Myšlenka | Realita | |---|---| | „Zadání je jasné, začnu rovnou“ | Když je jasné, sepsání trvá deset minut. Když ne, právě proto se píše. | | „Udělám scaffold, ať máme na čem stavět“ | Scaffold zamkne tech stack dřív, než se rozhodl. | | „Uživatel mi řekl ‚udělej to'“ | Řekl `/specify`. Kdyby chtěl kód, řekl by to. | ------ ## Fáze 0 – Pre-flight 1. **Kořen projektu.** Pracovní adresář, případně kořen repozitáře. Ve worktree layoutu (`~/Dev/context/worktree/worktree.md`) je projektem pracovní adresář větve – dokumenty patří do `main/docs/`, ne do kořene kontejneru. 2. **Přečti projektový `CLAUDE.md`** – metadata projektu, typ projektu, paměťová politika, `### Autocommit`, `## Výjimky z obecných pravidel`. 3. **Zkontroluj strukturu.** Existují standardní soubory `todo.md`, `done.md`, `decisions.md`, `rules.md` (v `docs/`, nebo v kořeni podle režimu)? Chybí-li, **nezakládej je potichu** – vypiš, co chybí, a nabídni `/project`. Pokračuj až pak; specifikace bez místa, kam zapisovat rozhodnutí, je poloviční práce. 4. **Existující podklady.** Projdi, co v projektu už je – zadání, brief, zápis ze schůzky, starý systém, exporty, `docs/research/`. **Cizí podklady jsou read-only** – kopírovat si z nich do projektu smíš a máš, zapisovat do nich nikdy. 5. **Urči vstupní bod.** Skill se dá spustit i uprostřed – neběží vždycky celý: | Stav | Kde začít | |---|---| | `requirements.md` ani `architecture.md` neexistují | Fáze 1, celý běh | | `requirements.md` existuje, `architecture.md` ne | Zeptej se: **navázat návrhem řešení**, nebo revidovat požadavky? Tohle je běžný případ – produkt se schválí dnes, návrh se dělá jindy. Při navázání **projdi Fázi 2 i tak** – `brainstorming` musíš vyvolat, jinak nemá kdo návrh vytvořit; jen mu místo produktových otázek předej hotové `docs/requirements.md` jako zadání a rovnou jdi na varianty řešení. | | Existují oba | Jde o revizi, nebo o novou část projektu? Při revizi **nepřepisuj** – rozšiř a přeformuluj stávající. | | `architecture.md` existuje a přidává se feature | Rozšiř ho. **Nezakládej druhý návrhový dokument** – jeden systém, jeden návrh. | Zjištěné shrň do tří až pěti řádků a pokračuj. ------ ## Fáze 1 – Nultý krok: vytěž, co už uživatel má **Než se na cokoliv zeptáš**, vyzvi ho, ať přiloží nebo nakopíruje všechno, co k tomu má – i nestrukturovaně. Zápis ze schůzky, poznámky, starý dokument, screenshoty, konkurenční web, mail od klienta. 1. **Originály ulož** do projektu (`docs/research/`), ať se dají dohledat. 2. **Sám si z nich zodpověz co nejvíc.** Cokoliv, co z podkladů plyne, se už neptej. 3. **Vypiš souhrn, co sis z toho odvodil**, ať to uživatel jedním pohledem potvrdí nebo opraví. 4. **Doptávej se jen na zbytek** – a na věci, kde si nejsi jistý. Nemá-li nic, přeskoč. Ale zeptej se – v praxi něco má skoro vždycky a nenapadne ho to poslat. ------ ## Fáze 2 – Klasifikace a dialog **Vyvolej `superpowers:brainstorming`.** Předej mu: - co ses dozvěděl z podkladů ve Fázi 1, - že se má ptát přes `AskUserQuestion`, jednu otázku na volání, - že **návrhovou část zapíše do `docs/architecture.md`**, ne do `docs/superpowers/specs/`, a až ve Fázi 3b – tedy po schválení produktové části. **Co udělat s klasifikací:** | Cesta | Co dělat | |---|---| | **Architectural** | Normální běh skillu. Tohle je jeho případ. | | **Bounded** | Specifikace nedává smysl – je to změna v existujícím kódu. **Řekni to a zastav se.** Nabídni pokračovat rovnou přes `brainstorming` (krátký návrh v chatu → schválení → implementace). Nenech se zatlačit do psaní specifikace na jednosouborovou změnu. | | **Spike** | Totéž – výstupem je odpověď, ne dokument. Zastav se a nabídni sondu. | **Rozsah.** Popisuje-li zadání víc nezávislých podsystémů, řekni to hned a rozlož to na dílčí projekty dřív, než se začnou ladit detaily. Každý dílčí projekt pak dostane vlastní dokumenty i vlastní plán. **Projekt bez kódu.** Je-li to znalostní, obsahový nebo obchodní projekt (kurz, brand, pozicování, evidence), `requirements.md` dává smysl, ale **návrh řešení ani `writing-plans` ne** – ty předpokládají kód, testy a commity. Skonči po Fázi 3a a místo plánu nabídni postupný rozpis kroků do `docs/todo.md`. ------ ## Fáze 3a – Produktová specifikace Zapiš do **`docs/requirements.md`**. Sekci, která pro projekt nedává smysl, vynech, ale **řekni, že jsi ji vynechal a proč**: ```markdown # <Lidský název> – produktová specifikace <Jedna věta, co to je. Shodná s popiskem v CLAUDE.md.> ## Proč to děláme Jaký problém to řeší, čí, a co se stane, když to neuděláme. ## Pro koho to je Persony. U každé: kdo to je, co od toho čeká, čeho se bojí, co ji odradí. Sekundární persony odděl a řekni, čím jsou omezené. ## Co to je Popis produktu ze strany uživatele. ## Hlavní scénáře Co člověk s produktem reálně dělá, od začátku do konce. Čitelně, jako příběh. Hlavní scénáře nahoře, okrajové pod čarou – ale popsané. ## User stories Jako <persona> chci <co>, abych <proč>. Seskupené podle oblastí. ## Varianty a rozhodovací větve Kde má scénář víc podob, vypiš je taxativně a řekni, čím se mezi nimi volí. Tohle je nejčastější místo, kde se zadání později rozpadne. ## Omezení Co návrh nesmí porušit: rozpočet, provozní prostředí, závislosti, které nejsou přípustné, jazyky, legislativa, termín. Omezení, ne volby řešení. ## Nefunkční požadavky Výkon, dostupnost, bezpečnost, osobní údaje a GDPR, přístupnost, lokalizace, provoz a zálohy. Jen to, co má reálné důsledky. ## MVP Zaškrtávací seznam toho, co musí být v první verzi. Řež agresivně. Každá položka je ověřitelná – ne „hotová registrace“, ale co konkrétně umí. ## Mimo rozsah Co vědomě neděláme a proč. Musí být neprázdné. Sem patří i to, co bylo v návrhu a vyhodilo se – ať to nikdo nevymyslí znovu. ## Jak poznáme, že to funguje Success metrics. Konkrétní, měřitelné, s cílovou hodnotou a termínem. ## Otevřené otázky Co ještě není rozhodnuté a co to blokuje. ``` **Jak psát:** česky, věcně, bez omáčky, typografie podle `~/Dev/context/text/text.md`. Konkrétně – „rychlé načítání“ je nic, „LCP pod 2,5 s na 4G“ je požadavek. Bez placeholderů; co nevíš, patří do *Otevřených otázek* s tím, kdo to má rozhodnout. **Brána uživatele.** Po sebe-revizi (Fáze 4) napiš: > Požadavky jsou sepsané a commitnuté v `docs/requirements.md`. Přečti si ho prosím a řekni, jestli chceš něco změnit, než se pustíme do návrhu řešení. **Počkej na odpověď.** Bez výslovného souhlasu nepokračuj na 3b – návrh postavený na neschváleném zadání se zahazuje celý. ------ ## Fáze 3b – Návrh řešení **Na návrhu se nešetří: nejsilnější model, `xhigh`.** Volba modelu a effortu podle `~/.claude/RULES.md`, *Model a effort podle úkolu*. Tohle není výroba dokumentu – dokument je jen zápis. Je to rozhodnutí, které se propíše do každého úkolu plánu a do každého řádku kódu pod ním, a **špatný návrh se dobrou implementací nezachrání**: špatná věc se jen udělá pořádně. Zápis hotového rozhodnutí do šablony už chytrý být nemusí. **Píše se, když platí aspoň jedno:** - je to nový projekt nebo nový podsystém, - zavádí nebo mění datový model či perzistentní stav, - zavádí rozhraní, na kterém stojí něco dalšího (API, formát, kontrakt), - napojuje se na cizí systém (platební brána, fakturace, externí API), - má stavový prostor s přechody, - existuje víc než jedna rozumná cesta, jak to postavit. **Nepíše se, když** je to přírůstek uvnitř už navrženého systému – pak rozšiř stávající `architecture.md`. A **nikdy** u projektu bez kódu. Přeskočíš-li ho, **řekni to i s důvodem** a jako zadání pro plán použij `requirements.md`. Návrh vytvoří `brainstorming` v dialogu s uživatelem – po sekcích, se schválením po každé. Zapiš do **`docs/architecture.md`**: ```markdown # <Lidský název> – návrh řešení Vychází z [produktové specifikace](requirements.md). Co a proč se staví, je tam; tady je, jak. ## Zvolený přístup Jaké varianty byly ve hře, která vyhrála a proč. Zamítnuté i s důvodem. ## Architektura Komponenty, jejich odpovědnosti a hranice. U každé: co dělá, jak se používá, na čem závisí. ## Datový model Entity, vztahy, klíčová pole. U netriviálních i důvod, proč zrovna takhle. ## Stavy a přechody Je-li tam stavový prostor: taxativně stavy, přechody mezi nimi, podmínky a co se v každém přechodu děje. Vše o jednom přechodu pohromadě u něj. ## Datové toky Co odkud kam teče, kdo to iniciuje a co se stane, když to selže. ## Rozhraní Veřejné API, formáty, kontrakty vůči okolí. Přesné názvy a typy. ## Cizí systémy Na co se to napojuje, co od toho očekáváme a co dělat, když to nefunguje. ## Chybové stavy Co může selhat, jak se to pozná a co se stane pak. ## Bezpečnostní model Kde se autorizuje a proč to nejde obejít. Jak se validuje vstup a na které hranici. Kde žijí tajemství. Co se loguje a co se logovat nesmí. Na konci **jmenný seznam citlivých oblastí** – přihlášení, oprávnění, platby, nahrávání souborů, osobní údaje, mazání dat, odesílání pošty ven. Změna v nich se nemerguje bez lidského pohledu na diff; `/review` na ně sahá přísněji. ## Technologie Konkrétní volba a proč – proti omezením z requirements.md. ## Testovací strategie Co se testuje a na jaké úrovni. U každého *Hlavního scénáře* a *Varianty* z requirements.md řekni, čím bude pokrytý – akceptačním testem, jednotkovým, nebo vědomě ničím a proč. Dál prahy, které bude projekt držet (pokrytí, mutation score) a čím se měří. Výchozí hodnoty a nástroje viz `~/Dev/context/coding/coding.md`, *Ověřování a brány kvality*. Zvlášť rozhodni o **generativních testech** – fuzzingu a property-based testech. Vyplatí se u parserů, validace vstupu, převodů formátů, výpočtů nad rozsahy a stavových automatů: najdou vstup, na který nikdo nepomyslel, a stojí tokeny jen jednou. Napiš, kde je projekt bude mít, nebo že je mít nebude a proč – prázdné místo tady znamená, že se nenapíšou nikdy. ## Ověřování a brány Konkrétní příkazy, které projekt bude mít – `test`, `typecheck`, `lint`, `build`, `audit`, případně `e2e` a `mutation`. Je to **záměr, ne kontrakt**: *Kontrakt příkazů* v `CLAUDE.md` musí odpovídat tomu, co projekt opravdu umí spustit, takže ho zapisuje až ten, kdo to vidí – první úkol plánu, který příkazy zavede, případně opakovaný běh `/project`. Řekni i, co se **nebude** kontrolovat automaticky a proč. ## Rizika Co je na tom nejistého a co by to znamenalo, kdyby se ukázalo jinak. ``` **Kontrola proti požadavkům:** projdi *Hlavní scénáře*, *Varianty* a *Nefunkční požadavky* v `requirements.md` a u každého ukaž, co v návrhu ho pokrývá. Nepokryté je nález, ne detail. **Bezpečnost se navrhuje, neaudituje.** Zhruba polovina kódu psaného modely obsahuje bezpečnostní chybu a je to předvídatelná množina. Nejúčinnější obrana není kontrola na konci, ale struktura, ve které díra nejde udělat – jedna vrstva autorizace, kterou nelze obejít, výhradně parametrizované dotazy, validace na hranici, tajemství jen z prostředí. Proto má návrh sekci *Bezpečnostní model*, a proto v ní nesmí stát „ošetříme to při implementaci“. **Doménové standardy.** Návrh se řídí tím, co si projekt importuje v `CLAUDE.md` – `~/Dev/context/coding/coding.md` vždy, dál podle povahy `web/web.md`, `web/admin.md`, `analytics/analytics.md`. Načti je, než začneš navrhovat, ne až při kontrole. ------ ## Fáze 4 – Sebe-revize a oponentura Běží **po každém z obou dokumentů zvlášť**, ne až na konci. **Sebe-revize** (rozšíření *Spec Self-Review* z brainstormingu): 1. **Placeholdery** – „TBD“, „TODO“, nedokončené sekce, vágní požadavky. Oprav. 2. **Vnitřní rozpory** – neodporují si sekce? Sedí počty a výčty s obsahem? 3. **Vymyšlené věci** – je tam technický název, ID, parametr nebo číslo, které jsi neměl od uživatele ani z podkladů? To je nález. Dohledej, nebo přesuň do *Otevřených otázek*. 4. **Prosakování hranice** – je v `requirements.md` architektura nebo volba technologie? Je v `architecture.md` zdůvodnění produktu? Přesuň. 5. **Pokrytí** – u návrhu proti požadavkům (viz 3b), u požadavků proti tomu, co padlo v dialogu. 6. **Dvojznačnost** – dá se něco přečíst dvěma způsoby? Vyber jeden a napiš ho jednoznačně. 7. **Rozsah** – vejde se to do jednoho implementačního plánu? Pokud ne, dekomponuj. 8. **Mimo rozsah není prázdné** (jen `requirements.md`) – prázdná sekce znamená, že se neřezalo. **Oponentura.** Dokument jsi psal ty a jsi na něj zaujatý. Nabídni `/oponent` – u většího projektu doporuč, u malého jen nabídni. Úhly se pro každý dokument liší: Povinné úhly *Vnitřní rozpor* a *Co chybí* platí vždy; k nim se podle dokumentu přidávají: - **`/oponent docs/requirements.md`** – cílová skupina, ekonomika, konkurence - **`/oponent docs/architecture.md`** – technická proveditelnost, hraniční případy, provoz **Brána uživatele** – po požadavcích (viz 3a) i po návrhu řešení: > Návrh řešení je sepsaný a commitnutý v `docs/architecture.md`. Přečti si ho prosím a řekni, jestli chceš něco změnit, než z něj uděláme implementační plán. Počkej na odpověď. Chce-li změny, proveď je a projdi sebe-revizi znovu. ------ ## Fáze 5 – Předání do plánu Po schválení návrhu předej řízení na **`/breakdown`**, který ze zadání udělá `docs/plan.md`. Ten si sám najde zadání i kontext a ohlídá rozsah – nemusíš mu nic předávat ručně, jen ho vyvolej. **Sám plán nepiš.** Ani „ať se to nemusí volat zvlášť“. Rozpad na úkoly má vlastní pravidla, vlastní kontrolu pokrytí MVP a vlastní schvalovací bránu. **U projektu bez kódu** `/breakdown` nevyvolávej – rozepiš kroky do `docs/todo.md`. Celý řetěz i s tím, co následuje po realizaci, je v `~/.claude/RULES.md`, *Životní cyklus práce*. ------ ## Když se zadání změní později Platí *Doc-first vývoj* z `~/.claude/RULES.md`; posloupnost souborů definuje `structure.md`: 1. Změní se požadavek → uprav **`requirements.md`**. 2. Zkontroluj, jestli to mění návrh → uprav **`architecture.md`**. 3. Zkontroluj, jestli to mění nehotové úkoly → uprav **`plan.md`**. 4. Rozhodnutí a důvod změny zapiš do `docs/decisions.md`. Původní záznam nepřepisuj – přibude revize. Přijde-li změna zdola (při implementaci se ukáže, že návrh nejde), **neopravuj to potichu v kódu**. Vrať se do návrhu řešení, uprav ho, a je-li dotčený i produktový záměr, řekni to a nech rozhodnout uživatele. ------ ## Závěr ``` ## Zadání hotové **Dokumenty** - docs/requirements.md – <počet> sekcí - docs/architecture.md – <počet> sekcí (nebo „přeskočeno: <důvod>“) **Zapsáno mimo ně** - docs/decisions.md: N rozhodnutí - docs/todo.md: N odložených položek - docs/rules.md: N principů **Otevřené otázky** - [seznam, nebo „žádné“] **Další krok** - [/breakdown / u projektu bez kódu rozpis kroků do docs/todo.md] ``` Zakonči jednou z těchto vět, nikdy ničím vágním mezi tím: - `Zadání je hotové a schválené, můžeme na implementační plán.` - `Zadání hotové není – brání tomu: <konkrétní seznam>.`