Shrnutí
Spec dokumenty jsem nesnášel. Sednout, otevřít markdown, dvacet minut zírat na kurzor a pak napsat něco, co stejně neobsahuje polovinu kontextu, který mám v hlavě. Před měsícem jsem to vyměnil za workflow, kde Whisprflow diktuje brain dump do Claude Code, agent ho přeformuluje na strukturovaný spec a explicitně se zeptá, jestli to chápe správně. Deset minut místo hodiny — a spec, který má víc detailů, než kdybych ho psal ručně.
Proč o tom píšu
Tenhle workflow vznikl z frustrace. Chtěl jsem, aby agent dodal feature, kterou jsem měl jasně v hlavě, ale nějak se mi nedařilo ji dostat na papír. Napsal jsem stručně, agent vygeneroval polovičatý kód, já doplnil další požadavek, agent přepsal, znova zapomněl edge case. Po třetí iteraci mi došlo, že problém není agent — problém je můj vstup.
Pokud chceš z agenta dostat dobrý kód, musíš mu dát dobrý spec. A psát dobrý spec ručně je peklo, na které žádný senior nemá náladu.
Problém: psaný spec je past
Když začnu psát markdown, stane se několik věcí najednou, a všechny zhorší výstup:
- Psaní zpomalí myšlení. Kdykoli si vzpomenu na další kontext, musím počkat, až dopíšu větu. Za tu dobu se mi vypaří třetina věcí, na které jsem si vzpomněl.
- Editor svádí k editaci. Vidím, že věta nezní hezky, opravím slovosled, místo abych dumpoval další myšlenku. Forma vyhrává nad obsahem.
- Výsledek vypadá hezky, ale chybí 3 edge case. Při psaní jsem si na ně nevzpomněl, protože mi mozek visel nad formulací, ne nad problémem.
- Polovičatý spec → polovičatý kód. Agent z toho udělá implementaci, která dělá 70 % toho, co jsem chtěl, a já strávím další půlhodinu vysvětlováním zbylých 30 %.
Tohle je přesný okamžik, kdy se vibecoding stane vibedebuggingem.
Workflow: tři kroky, deset minut
Workflow má tři části. Žádná z nich není složitá, žádná z nich nepotřebuje speciální nástroj — Whisprflow se dá nahradit čímkoli, co umí dictation, Claude Code čímkoli, co umí konverzaci.
1. Připravený prompt v Claude Code
Mám prompt, kterým přepnu Claude Code do spec interview módu. V tomhle módu agent nepíše kód. Místo toho poslouchá, sumarizuje, doptává se a explicitně potvrzuje pochopení. Je to jako mít junior product manažera, který tě vede strukturou.
Prompt v článku doslova nepublikuju — pošlu ho komukoliv, kdo o něj požádá na info@kontradigital.com. Důvod: prompt jsem ladil několik týdnů, ale jeho přesné znění je míň důležité než pochopení principu, který za ním stojí.
2. Diktování přes Whisprflow
Otevřu Claude Code v terminálu, spustím prompt a zapnu Whisprflow. Pak prostě mluvím. Říkám rozházeně, opakuju se, vracím se k věcem, na které jsem si vzpomněl o dvě věty později. Kontext mi teče přímo z hlavy do textu, bez filtru editace.
Whisprflow používám, protože je rychlý, nepotřebuje překlik a běží v pozadí. Není to jediná volba — princip workflow je o mluveném brain dumpu, ne o konkrétním nástroji. Kdyby ses zeptal, doporučím Whisprflow, ale macOS dictation nebo SuperWhisper fungujou stejně.
3. Reflexivní smyčka
Tohle je část, kde se workflow liší od obyčejného diktování do markdownu. Po brain dumpu agent neudělá to, co bych čekal — neuloží mi text. Místo toho:
- Shrne problém vlastními slovy.
- Vypíše bullet pointy: "rozumím tomu jako…", "předpokládám, že…", "co jsem nezaslechl: …".
- Zeptá se: "Chápu to správně?"
- Čeká na ano / ne / "skoro, ještě X".
Pokud řeknu ne, doplním kontext mluvenou cestou, a smyčka se opakuje. Když agent řekne, co slyší, často odhalí mezery, na které bych při psaní nepřišel — protože ten model nemá dovysvětlovaný kontext, který mám já v hlavě, takže explicitně formuluje, co předpokládá.
Po dvou až třech kolech smyčky mám spec, na který jsem řekl ano. Ten spec je pak vstupem pro implementační fázi (může to být nový agent, nebo prostě další prompt do téhož sezení).
Jak to vypadá v praxi
Nedávno jsem takhle specifikoval feature do Skillsmith — placeholder proměnné v skill.md, které se při exportu přepíšou podle vendora (jiná syntax pro odkazy na soubory v Claude vs. Cursor).
Brain dump byl asi takový:
"Mám v skillu odkaz na soubor, ale Claude chce
@path/to/file.ts, Cursor chce[file](mdc:path/to/file.ts). Nechci to udržovat dvakrát, mám jeden zdroj. Asi placeholder, něco jako{{file path/to/file.ts}}, a adapter to přeloží. Ale taky mě napadá, jestli se to neřeší přes nějakou jinou syntax, třeba…"
Agent z toho po jednom kole "chápu to správně?" vytáhl:
- problém: vendor-specific syntax pro file references
- navrhované řešení: placeholder syntax
{{file …}} - otevřená otázka: má placeholder řešit i víc než jen soubory (URL, anchor v souboru)?
- co chybí: chování při neplatné cestě, escape pro literály se složenými závorkami
Tu poslední věc bych při psaní zapomněl. Agent si ji vyžádal, protože musel formulovat, co předpokládá. Po druhém kole měl spec strukturu pěti sekcí a mohl jít rovnou do implementace.
Proč to funguje líp než psaní
Mluvený jazyk má vyšší propustnost než psaný — řeknu za minutu třikrát víc kontextu, než napíšu. Agent jako rubber duck, který umí odpovídat vytahuje implicitní předpoklady ven, takže je vidím dřív, než se zhmotní v kódu. Validační smyčka mě nutí explicitně potvrdit pochopení, ne implicitně doufat. A výstup je rovnou použitelný jako vstup pro implementační fázi — žádné přepisování.
Co potřebuješ, abys to zkusil
- Claude Code (nebo Cursor, Codex, libovolný agent, který umí konverzaci, ne jen code completion).
- Whisprflow (nebo libovolný dictation tool — princip je o mluveném brain dumpu, ne o nástroji).
- Prompt, který agenta přepne do spec interview módu. Pošlu ti ten svůj na vyžádání: info@kontradigital.com.
Závěr
Spec dokumentace nemusí být utrpení. Mluvený brain dump + reflexivní agent dává lepší vstup pro AI implementaci než hodina ručního psaní markdownu — a navíc tě spec nestojí mentální energii, kterou potřebuješ na samotnou featuru. Zkus to jednou. Pokud ti workflow sedne, uvidíš, že psát specy ručně je stejně outdated jako psát code reviews v textovém editoru.
