Lekce 06.2: Nastavení issue trackeru (Set Up Your Issue Tracker)

⏱️ 3 min čtení • Lekce 06.2

🧠 Mentální model & teoretický rozbor

Agent potřebuje externí paměť, která existuje nezávisle na jeho kontextovém okně. K tomu slouží Issue Tracker:

DVĚ MOŽNOSTI ISSUE TRACKERU PRO AGENTA:
┌─────────────────────────────────────────────────────────────┐
│ 1. LOKÁLNÍ TRACKER V REPOZITÁŘI (Složka .tickets/ nebo TODO) │
│    • Maximální rychlost: Agent soubory čte přímo přes disk.  │
│    • Verzováno v Gitu: Stav úkolů odpovídá přesné větvi.    │
│    • Ideální pro sólový vývoj a rychlé iterace.             │
├─────────────────────────────────────────────────────────────┤
│ 2. CLOUDOVÝ TRACKER (GitHub Issues, Linear, Jira)           │
│    • Týmová viditelnost a propojení s PR.                   │
│    • Vyžaduje CLI nástroje (např. `gh issue list`).         │
└─────────────────────────────────────────────────────────────┘

Lokální souborový issue tracker má obrovskou výhodu: agent si může soubor sám otevřít, přečíst akceptační kritéria a po dokončení odškrtnout checklist!

---

🏢 Realistický scénář z praxe

V repozitáři existuje složka .tickets/:

.tickets/
├── 01-schema-subscription.md (status: DONE)
├── 02-stripe-webhook.md      (status: IN_PROGRESS)
└── 03-checkout-button.md     (status: TODO)

Vývojář spustí čerstvé sezení a napíše pouze: „Pokračuj v práci na ticketu .tickets/02-stripe-webhook.md.“ Agent otevře soubor, přečte přesná kritéria, implementuje kód a přepíše status na DONE. Žádné dlouhé vysvětlování v promptu!

---

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

Šablona lokálního ticketu (.tickets/02-stripe-webhook.md):

# Ticket 02: Stripe Webhook Handler

## Stav: IN_PROGRESS
Předchozí závislost: Ticket 01 (hotovo)

## Popis úkolu
Implementuj API route handler pro příjem události `checkout.session.completed` ze Stripe.

## Akceptační kritéria (Checklist):
- [ ] Validace kryptografického podpisu přes `stripe.webhooks.constructEvent`.
- [ ] Zápis `stripeCustomerId` a `subscriptionStatus: 'ACTIVE'` do tabulky `User`.
- [ ] Vrácení HTTP 200 pro validní webhook.
- [ ] Vrácení HTTP 400 pro neplatný podpis.
- [ ] Integrační test v `src/app/api/webhooks/__tests__/stripe.test.ts` prochází.

---

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

Chyba: Úkoly bez ověřitelného checklistu

Zadat ticket s textem: „Zlepši výkon aplikace.“

• Agent neví, kdy je úkol hotov, a začne provádět náhodné změny.
• Pravidlo: Každý ticket musí mít konkrétní seznam zaškrtávacích políček (Checklist).

---

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

1. Vytvořte složku .tickets/ v kořenu projektu (přidejte ji do Gitu).
2. Založte první ticket podle šablony s akceptačními kritérii.
3. Spusťte agy (nebo claude) a odkažte agenta na tento soubor.
4. Po dokončení a ověření testů nechte agenta ticket označit jako splněný ([x]).

---

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

Úkol:

Založte v projektu složku .tickets/ a vytvořte svůj první ticket s akceptačními kritérii pro vybranou komponentu nebo utilitu.

Kroky:

1. Vytvořte soubor .tickets/01-init-auth.md.
2. Definujte konkrétní akceptační kritéria (např. export funkce, Zod validace, test ve Vitestu).
3. Spusťte agy (nebo claude) a zadejte: „Pracuj podle .tickets/01-init-auth.md. Splň checklist a spusť testy.“
4. Zkontrolujte výsledek a ověřte stav ticketu.

---