Lekce 04.10: Předávání (Handoff) (Handing Off)

⏱️ 3 min čtení • Lekce 04.10

🧠 Mentální model & teoretický rozbor

Co uděláte, když máte před sebou masivní inženýrský úkol, který se nevejde do jednoho kontextového okna (např. trvá 3 dny a zasahuje 25 souborů)? Vibe coder nechá jedno sezení běžet do nekonečna, až model zhloupne a kód rozbije. Skutečný inženýr využívá Handoff Protocol (Protokol předávání štafety):

SEZENÍ 1 (Fáze A: Databáze a schémata)
  │ • Vyčerpáno 45 % kontextu
  │ • Zelený test, kód commitnut v Gitu
  │ • Vytvoření předávacího souboru HANDOFF.md na disku
  ▼
/clear (NEBO NOVÉ SEZENÍ)
  │
SEZENÍ 2 (Fáze B: API Endpointy)
  │ • Čistý kontext (100% Smart Zone, 0 tokenů historie)
  │ • Načtení HANDOFF.md -> Okamžitá kontinuita práce s plným IQ modelu!

Handoff odděluje trvalý stav projektu (kód a soubor na disku) od dočasného stavu sezení (kontext v paměti).

🏢 Realistický scénář z praxe

Vývojář migruje REST API na tRPC:

V sezení 1 vytvoří základní routery a procedury pro uživatele. Kontext dosáhne 40 %.
Místo pokračování v tomtéž sezení vyzve agenta: „Vytvoř HANDOFF.md se shrnutím: co je zmigrováno, které procedury zbývají a kde přesně máme zítra začít.“
Provede commit, vypne počítač.
Druhý den ráno otevře terminál, napíše agy (nebo claude) a zadá: „Pokračuj podle HANDOFF.md.“
Agent naváže přesně tam, kde včera skončil, ale s čerstvým, nezatíženým mozkem!

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

Šablona profesionálního souboru `HANDOFF.md`:

# Předávací protokol (Handoff) - Migrace platební brány

## Aktuální stav (Co je hotovo a otestováno)
- Vytvořena tabulka `Subscription` v `prisma/schema.prisma`.
- Migrace aplikována v lokální DB (`20250219_init_subs`).
- Integrační test `src/services/__tests__/stripe.test.ts` prochází.

## Kde práce skončila (Rozpracováno)
- Začali jsme psát webhook handler v `src/app/api/webhooks/stripe/route.ts`.
- Chybí validace podpisu webhooku (`stripe.webhooks.constructEvent`).

## Okamžité další 2 kroky pro nové sezení:
1. Otevři `src/app/api/webhooks/stripe/route.ts` a doplň ověření podpisu podle stripe dokumentace.
2. Napiš test pro neplatný podpis v `src/app/api/webhooks/stripe/__tests__/route.test.ts`.

## Identifikovaná úskalí a varování:
- Stripe raw body se v Next.js App Routeru musí číst přes `req.text()`, nikoliv `req.json()`!

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

Chyba: Příliš vágní Handoff

Pokud soubor HANDOFF.md obsahuje pouze: „Pracujeme na stripe, zbývá dodělat zbytek,“ nové sezení stráví 5 tahů zjišťováním, co je vlastně hotovo a co zbývá.

Pravidlo: Handoff musí obsahovat přesné cesty k souborům a konkrétní první krok.

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

Dosáhli jste 40 % kontextu nebo končíte pracovní blok.
Vyzvěte agenta k vygenerování HANDOFF.md podle šablony.
Zkontrolujte soubor v editoru (doplňte případné postřehy).
Commitněte kód i s HANDOFF.md.
Zadejte /clear.

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

Úkol:

Vyzkoušejte si kompletní Handoff cyklus.

Kroky:

V rozehraném sezení vyzvěte agenta: „Vytvoř strukturovaný HANDOFF.md pro náš aktuální stav repozitáře.“
Zkontrolujte vygenerovaný soubor.
Zadejte /clear.
Napište: „Přečti si HANDOFF.md a řekni mi, jaký je náš první úkol pro dnešek.“
Sledujte hladkost přechodu!