Lekce 2 - Spec-driven development a Codex Nové

V minulé lekci, Vývoj s AI - Příprava VS Code a Codexu, jsme si představili vývoj s AI, připravili VS Code a Codex a založili projekt společnosti EnergoSun.

V tomto tutoriálu kurzu vývoje aplikací s AI připravíme zadání pro portál interních požadavků společnosti EnergoSun. Ve Visual Studio Code vytvoříme dokument SPEC.md ve formátu Markdown, popíšeme současný firemní proces a pomocí Codexu zkontrolujeme, co ve specifikaci chybí. Budeme postupovat podle principu spec-driven development, tedy vývoje řízeného zadáním. Programový kód zatím vytvářet nebudeme.

Vibe coding a spec-driven development

Představme si, že chceme postavit dům. Přijdeme za stavitelem a řekneme mu pouze: "Postav mi dům." Stavitel začne pracovat. Později mu řekneme, že chceme dvě patra, takže musí část práce předělat. Potom změníme rozmístění místností a následně přidáme další požadavky.

Vibe coding a jeho omezení

Podobně můžeme pracovat i s AI. Zadáme krátký pokyn, zkontrolujeme výsledek a postupně požadujeme další změny. Tento přístup se často označuje jako vibe coding.

Jeho výhodou je rychlý začátek bez podrobného zadání. U větších aplikací ale mohou opakované změny přinášet rozpory a chyby, zabírat čas a rychleji čerpat dostupné limity AI.

Pokud například zadáme pouze "Vytvoř aplikaci na zaměstnanecké požadavky", neříkáme, kdo ji bude používat, jak dnes požadavky fungují, co má aplikace umět ani podle čeho ověříme výsledek. AI si pak některá rozhodnutí musí domyslet, podobně jako kolega, kterému jsme nepředali úplné zadání.

Spec-driven development

Proto v tomto kurzu používáme spec-driven development (SDD), tedy vývoj podle specifikace. Nejdříve popíšeme problém a připravíme požadavky na aplikaci. Teprve podle nich budeme zadávat konkrétní vývojové úkoly.

AI nám může pomoci hledat ve specifikaci nejasnosti, rozpory nebo chybějící rozhodnutí, neměla by ale sama určovat, jak firma funguje. Chybějící pravidla proto musíme ověřit, nikoli je nechat AI domyslet.

Specifikace je zdrojem pravdy pro projekt, zatímco prompt je konkrétní pracovní pokyn pro právě řešený úkol.

Založení souboru SPEC.md

Otevřeme ve VS Code naši složku interni-pozadavky/. V Průzkumníku vytvoříme soubor SPEC.md:

Formát Markdown

Přípona .md označuje dokument ve formátu Markdown. Tento jednoduchý textový formát umožňuje zapisovat nadpisy, seznamy a další strukturu. Soubor bude sloužit jako zadání, kterému porozumí lidé i Codex.

V Markdownu vytváříme nadpis pomocí znaků #, přičemž # označuje hlavní nadpis a ## nadpis nižší úrovně. Text mezi ** zobrazíme tučně, mezi * kurzívou a položky seznamu zapisujeme například pomocí -. Odkaz zapisujeme ve tvaru [text odkazu](adresa) a obrázek podobně jako ![popis obrázku](adresa). Pro naši specifikaci nám budou stačit hlavně nadpisy, odstavce a seznamy.

Do souboru vložíme hlavní nadpis # Portál interních požadavků EnergoSun:

Soubor uložíme klávesami Ctrl + S, na macOS Cmd + S. Ukládání budeme opakovat při dalších úpravách.

Popis současného problému

Zaměstnanci řeší například nefunkční pracovní telefon, přístup do sdílené složky, potvrzení od HR nebo chybějící pracovní vybavení. Tyto požadavky nesouvisejí přímo se zákaznickými zakázkami, ale ovlivňují každodenní chod firmy.

Požadavky dnes přicházejí e-mailem, chatem, telefonicky nebo osobně. Informace si zaměstnanci opakovaně předávají a část komunikace zůstává pouze v soukromých zprávách. Chybí jednotné místo s požadavkem, řešitelem, stavem a výsledkem.

Pro řešení zvolíme webovou aplikaci, protože ji zaměstnanci mohou otevřít v prohlížeči na počítači i telefonu bez instalace samostatné aplikace. Pro jednu malou firmu tak můžeme vytvořit jedno rozhraní dostupné z více zařízení.

První zápis do specifikace

Do SPEC.md doplníme:

## Kontext společnosti

EnergoSun má 15 zaměstnanců v kancelářských a terénních rolích.
Interní provozní požadavky přicházejí e-mailem, chatem,
telefonicky nebo osobně.

## Současný problém

Požadavky nemají jednotnou evidenci, odpovědného řešitele
ani dohledatelný stav. Zaměstnanci nevědí, kdo se požadavku
věnuje, a vedení nemá přehled o neuzavřených případech.

## Cíl aplikace

Vytvořit jednoduchou webovou aplikaci pro evidenci a sledování
interních provozních požadavků zaměstnanců.

Tři zapsané části oddělují prostředí firmy, problém a zamýšlený výsledek. Díky nim bude pro nás i pro AI snazší najít potřebné informace.

Současný firemní proces

Než navrhneme aplikaci, popíšeme postup, který firma používá nyní. Proces si můžeme představit jako cestu zásilky. Pokud neznáme její začátek, jednotlivá předání ani místo, kde se může ztratit, nedokážeme navrhnout spolehlivější cestu.

Současný proces probíhá takto:

1. Zaměstnanec předá požadavek kolegovi, manažerovi nebo pracovníkovi, o kterém se domnívá, že jej řeší.
2. Pokud příjemce není správným řešitelem, zjistí, komu požadavek předat.
3. Požadavek se dostane k odpovědnému pracovníkovi.
4. Řešitel provede potřebnou činnost.
5. Výsledek oznámí zaměstnanci.

Hranice a slabá místa procesu

Proces začíná předáním interního požadavku a končí oznámením výsledku. Samotnou opravu telefonu, vystavení potvrzení nebo objednání vybavení automatizovat nebudeme. Aplikace bude evidovat požadavek a jeho průběh.

Z popisu vyplývají hlavní problémy:

• požadavek se může ztratit,
• není jasné, kdo jej řeší,
• zaměstnanec nevidí aktuální stav,
• chybí společná historie,
• vedení nemá přehled o neuzavřených případech.

Průběh i problematická místa ukazuje diagram současného stavu:

Doplnění procesu do SPEC.md

Do specifikace zapíšeme:

## Současný proces

1. Zaměstnanec předá požadavek kolegovi, manažerovi nebo pracovníkovi, o kterém se domnívá, že jej řeší.
2. Pokud příjemce není správným řešitelem, zjistí, komu požadavek předat.
3. Požadavek se dostane k odpovědnému pracovníkovi.
4. Řešitel provede potřebnou činnost.
5. Výsledek oznámí zaměstnanci.

### Slabá místa

- Požadavek se může ztratit.
- Není jasný jeho aktuální řešitel.
- Zaměstnanec nevidí stav řešení.
- Chybí společná historie.
- Vedení nemá přehled o neuzavřených případech.

Náš soubor SPEC.md nyní vypadá takto:

Kontrola procesu pomocí Codexu

Codex zatím nepožádáme o vytvoření aplikace. Necháme jej pouze hledat nejasnosti v popsaném procesu:

Přečti soubor SPEC.md.

Nevytvářej programový kód a neměň žádný soubor.
Zkontroluj pouze popis současného procesu. Upozorni:
1. na nejasné kroky,
2. na chybějící informace o předávání požadavku,
3. na místa, kde se může požadavek ztratit.

Chybějící informace nevymýšlej. Formuluj je jako otázky, které je potřeba ověřit s firmou.

Před odesláním promptu soubor uložíme pomocí Ctrl + S. Jinak může Codex pracovat se starší verzí souboru. Ve VS Code můžeme také zapnout Soubor -> Automatické ukládání.

Všimněme si, že prompt stanovuje zdroj informací, rozsah kontroly i omezení činnosti agenta. Codex má odpovědět pouze na zadaný analytický úkol. Kliknutím na odesílací šipku v panelu Codexu požadavek odešleme.

Vyhodnocení odpovědi

Codex upozorní na možná slabá místa zadání. Jeho výstup může vypadat takto:

V našem příkladu Codex upozornil, že v prvním kroku není určeno, podle čeho zaměstnanec vybírá příjemce požadavku. U předávání také chybí postup, jak příjemce zjistí správného řešitele. Není ani popsáno, jak se potvrzuje převzetí požadavku.

Codex za nás tato rozhodnutí nedělá. Pomohl nám najít konkrétní otázky, které musíme vyřešit sami nebo ověřit s lidmi, kteří daný proces ve firmě skutečně používají.

Vytvořili jsme dokument SPEC.md, popsali v něm firemní problém i současný proces a využili Codex k odhalení nejasností. Máme tak první podklad pro řízený vývoj aplikace. Než zadáme generování kódu, potřebujeme zpřesnit pravidla, která specifikace dosud neobsahuje.

V příští lekci, Specifikace MVP ve VS Code s Codexem, ve Visual Studio Code rozšíříme specifikaci portálu EnergoSun o cílový proces, uživatelské role, rozsah MVP a základní pravidla požadavku.

 

Měl jsi s čímkoli problém? Stáhni si vzorové řešení níže a porovnej ho se svým projektem, chybu tak snadno najdeš.