Lekce 04.6: Stavba nové funkce (Build a Feature)

⏱️ 3 min čtení • Lekce 04.6

🧠 Mentální model & teoretický rozbor

Kompletní inženýrský cyklus pro stavbu nové produkční funkce propojuje všechny dosud probrané principy do uceleného řetězce:

INŽENÝRSKÝ CYKLUS TVORBY FUNKCE:
┌─────────────────────────────────────────────────────────────┐
│ 1. KONTRAKT & TYPY (Definice rozhraní a Zod schémat)        │
├─────────────────────────────────────────────────────────────┤
│ 2. SELHÁVAJÍCÍ TEST (TDD Red: ověření požadavků)            │
├─────────────────────────────────────────────────────────────┤
│ 3. MINIMÁLNÍ IMPLEMENTACE (TDD Green: čistý funkční kód)    │
├─────────────────────────────────────────────────────────────┤
│ 4. DETERMINISTICKÁ VALIDACE (Linter, Kompilátor, Test)      │
├─────────────────────────────────────────────────────────────┤
│ 5. CLEAN COMMIT & FLUSH (Git commit + /clear pro další úkol)│
└─────────────────────────────────────────────────────────────┘

Pokud přeskočíte krok 1 nebo 2, vracíte se zpět k náhodnému vibe codingu.

---

🏢 Realistický scénář z praxe

Úkol: Přidat do SaaS aplikace možnost vygenerovat jednorázový přihlašovací odkaz (Magic Link):

1. Typy: Definujeme rozhraní CreateMagicLinkInput a výstup MagicLinkResult.
2. Test: Napíšeme test ověřující generování kryptograficky bezpečného náhodného tokenu s expirací 15 minut a uložením hashe do DB.
3. Implementace: Agent napíše funkci s využitím nativního modulu crypto.
4. Validace: Spustíme vitest a tsc --noEmit.
5. Commit: Změna je uložena s konvenční zprávou feat(auth): add magic link generation.

---

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

Ukázka definice typu a Zod schématu (src/schemas/magic-link.ts):

import { z } from 'zod';

export const MagicLinkInputSchema = z.object({
  email: z.string().email('Neplatný formát e-mailu'),
  redirectUrl: z.string().url().optional()
});

export type MagicLinkInput = z.infer<typeof MagicLinkInputSchema>;

export interface MagicLinkResult {
  token: string;
  expiresAt: Date;
}

Inženýrský prompt pro agenta:

Kontext: Stavíme funkci pro generování Magic Linku podle schématu src/schemas/magic-link.ts.

Kroky:
1. Prohlédni si test src/services/__tests__/magic-link.test.ts (je ve stavu Red).
2. Implementuj funkci generateMagicLink v src/services/magic-link.ts.
3. Token generuj přes `crypto.randomBytes(32).toString('hex')`.
4. Expiraci nastav na aktuální čas + 15 minut.
5. Spusť test: `npx vitest run src/services/__tests__/magic-link.test.ts`.

---

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

Chyba: Snaha postavit frontend i backend v jednom jediném promptu

Vývojář zadá: „Vytvoř mi Magic Link přihlašování – UI komponentu, API endpoint, databázovou tabulku a posílání e-mailů přes Resend.“

• Agent se zahltí, vygeneruje poloviční řešení na 8 souborech a nic z toho nebude otestované.
• Pravidlo: Každá vrstva (DB ➔ Service ➔ API ➔ UI) je samostatný inženýrský krok s vlastním commitem!

---

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

1. Vytvořte Git branch: git checkout -b feat/magic-link.
2. Definujte typy a rozhraní.
3. Napište selhávající test.
4. Nechte agenta test zprovoznit.
5. Zkontrolujte kód v IDE a commitněte.

---

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

Úkol:

Postavte jednoduchou novou funkci podle tohoto 5krokového protokolu ve svém projektu.

Kroky:

1. Zvolte malou utilitu (např. formátovač telefonních čísel).
2. Vytvořte test phone.test.ts.
3. Nechte agenta kód implementovat.
4. Ověřte zelený test a proveďte commit.

---