Lekce 06.6: Máte si specifikace ponechat? (Should You Keep Your Specs?)

⏱️ 2 min čtení • Lekce 06.6

🧠 Mentální model & teoretický rozbor

Když je funkce naimplementována a tickety jsou hotové, vyvstává otázka: Co udělat se soubory specifikací a tickety? Ponechat je v repozitáři, nebo smazat?

ROZCESTÍ ŽIVOTNÍHO CYKLU DOKUMENTACE:
┌─────────────────────────────────────────────────────────────┐
│ 1. DOČASNÝ LEŠENÁŘSKÝ BALAST (Smazat / Archivovat)          │
│    • Jednorázové tickety (.tickets/01-*.md).                │
│    • Po commitu a mergi ztrácejí hodnotu, zastarávají       │
│      a zbytečně matou budoucí vyhledávání agenta.          │
├─────────────────────────────────────────────────────────────┤
│ 2. TRVALÉ ARCHITEKTONICKÉ ZÁZNAMY (ADR - Ponechat v repu!)   │
│    • Zásadní architektonická rozhodnutí (docs/adr/*.md).    │
│    • Popisují PROČ bylo rozhodnutí učiněno a jaké byly      │
│      alternativy. Slouží jako ukazatele pro budoucí agenty.│
└─────────────────────────────────────────────────────────────┘

🏢 Realistický scénář z praxe

Tým před půl rokem přešel z REST na GraphQL a nechal v repozitáři ležet staré tickety z roku 2023. Nový agent při vyhledávání narazil na starý ticket s instrukcemi pro REST a začal navrhovat nové endpointy podle zastaralých konvencí. Jakmile tým staré tickety smazal a zavedl složku docs/adr/001-graphql-migration.md, agent okamžitě pochopil aktuální standard.

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

Šablona Architectural Decision Record (`docs/adr/002-jwt-vs-sessions.md`):

# ADR 002: Přechod na HTTP-only Session Cookies

## Kontext a problém
Mobilní i webová aplikace dosud používaly JWT tokeny ukládané v localStorage, což představovalo bezpečnostní riziko (XSS zranitelnost).

## Rozhodnutí
Rozhodli jsme se přejít na serverové sessions uložené v Redisu s předáváním session ID přes HTTP-only, Secure SameSite=Lax cookies.

## Důsledky
- **Pozitivní**: Vyšší bezpečnost, možnost okamžitého zneplatnění session administrátorem.
- **Negativní**: Nutnost provozovat Redis cluster pro sdílení stavu mezi instancemi API.

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

Chyba: Hromadění neudržované dokumentace

Dokumentace, která neodpovídá realitě kódu, je horší než žádná dokumentace. Model jí věří a generuje kód pro neexistující systémy.

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

Po mergi feature větve smažte složku .tickets/ nebo ji přesuňte do archivu.
Pokud funkce zavedla nový vzor, sepište stručný záznam do docs/adr/.
Na ADR odkažte v AGENTS.md (nebo CLAUDE.md).

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

Úkol:

Vytvořte svůj první ADR záznam pro klíčové rozhodnutí ve vašem projektu.