Lekce 06.3: Psaní skvělých specifikací pomocí dovednosti (Write Great Specs With This Skill)

⏱️ 2 min čtení • Lekce 06.3

🧠 Mentální model & teoretický rozbor

Proč je technická specifikace nejdůležitějším artefaktem v celém vývoji? Protože kód je pouze syntaktickým vyjádřením myšlenky. Pokud je myšlenka mlhavá, kód bude plný chyb. Kvalitní specifikace slouží jako kontrakt mezi vámi a agentem:

ANATOMIE DOKONALÉ SPECIFIKACE:
1. Uživatelský kontext (Co uživatel vidí a proč to děláme)
2. Změny v datovém modelu (SQL / Prisma schémata)
3. API kontrakty (Request, Response, Error Codes)
4. Bezpečnostní a autorizační pravidla
5. Akceptační kritéria a testovací scénáře

K vytvoření specifikace využíváme dedikovanou dovednost write-spec.

🏢 Realistický scénář z praxe

Před stavbou platební brány nechá inženýr agenta vygenerovat soubor specs/billing-integration.md. Specifikace přesně definuje, že při selhání platby musí systém poslat notifikaci přes webhook a uzamknout účet po 3 dnech grace periody. Když následně vývojář předává práci dalším sezením, všechna sezení se odkazují na tuto jednu specifikaci jako na jediný zdroj pravdy.

💻 Konkrétní ukázky kódu & promptů

Implementace dovednosti `write-spec` (`.agents/skills/write-spec/SKILL.md` nebo `.claude/skills/write-spec/SKILL.md`):

---
name: write-spec
description: Tvorba neprůstřelné technické specifikace před samotnou implementací
---

# Tvorba specifikace

Kdykoliv uživatel požádá o specifikaci nové funkce:
1. Nejprve polož 3 doplňující otázky na hraniční případy.
2. Vytvoř markdown dokument v `docs/specs/[nazev].md` s těmito sekcemi:
   - **Cíl funkce**: Jednověté shrnutí byznys hodnoty.
   - **Datové modely**: Přesné definice typů v TypeScriptu.
   - **API rozhraní**: HTTP metoda, URL, vstupy a výstupy.
   - **Chybové stavy**: Seznam HTTP statusů a error zpráv.
   - **Akceptační testy**: Seznam minimálně 3 unit/integračních testů.
3. Počkej na schválení specifikace uživatelem před psaním samotného kódu!

⚠️ Analýza selhání & Anti-patterns

Chyba: Psaní kódu před schválením specifikace

Agent začne psát soubory ještě během fáze specifikace.

Okamžitě ho zastavte (Ctrl + C)!
Dokud není specifikace odsouhlasena, do kódu se nesmí sáhnout.

🛠️ Inženýrský postup krok za krokem (Playbook)

Vyvolejte dovednost: /write-spec [nazev_funkce].
Prodiskutujte hraniční případy.
Schvalte finální dokument v docs/specs/.
Rozdělte specifikaci na tickety.

🧪 Praktické cvičení (Hands-on Lab)

Úkol:

Napište specifikaci pro novou funkci pomocí dovednosti write-spec.