Lekce 05.6: Navigační ukazatele (Navigation Pointers)

⏱️ 2 min čtení • Lekce 05.6

🧠 Mentální model & teoretický rozbor

Ve velkém repozitáři o tisících souborů je orientace agenta energeticky nejnáročnější fází. Pokud agent neví, kde co leží, stráví 10 tahů vyhledáváním. Navigační ukazatel (Navigation Map) je lehký index architektury:

ARCHITEKTONICKÁ MAPA (ARCHITECTURE.md):
├── src/app/          <── Next.js App Router (stránky a routy)
├── src/server/db/    <── Drizzle schémata a migrace
├── src/services/     <── Byznys logika (platby, maily, exporty)
└── src/components/   <── UI komponenty (Tailwind, Radix)

Tento soubor zabere pouhých 200 tokenů, ale ušetří desítky tisíc tokenů při každém průzkumu!

🏢 Realistický scénář z praxe

Agent má za úkol upravit způsob odesílání uvítacího e-mailu:

Bez mapy: Agent prohledává src/components, src/utils, src/pages…
S mapou: Agent otevře ARCHITECTURE.md, okamžitě vidí řádek src/services/mail/ ➔ odesílání transakčních e-mailů a jde rovnou na cíl.

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

Šablona `docs/ARCHITECTURE.md`:

# Architektonická mapa repozitáře

## Klíčové adresáře a jejich účel
- `src/server/routers/`: Definice tRPC API endpointů.
- `src/server/services/`: Čistá doménová byznys logika bez závislosti na transportní vrstvě.
- `src/server/db/schema/`: Databázové tabulky (PostgreSQL / Drizzle).
- `src/components/ui/`: Znovupoužitelné atomické komponenty (Design System).
- `src/components/features/`: Složitější komponenty vázané na konkrétní doménu.

## Datový tok aplikace
Klient (React) ──> tRPC Router ──> Doménová služba (Service) ──> Databáze (Drizzle)

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

Chyba: Zastaralá mapa po velkém refaktoru

Pokud přejmenujete klíčové adresáře, ale neaktualizujete ARCHITECTURE.md:

Agent bude hledat soubory na neexistujících cestách.
Pravidlo: Aktualizace mapy je povinnou součástí každého velkého refaktoru.

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

Vytvořte soubor docs/ARCHITECTURE.md.
Zmapujte do něj hlavní složky vašeho projektu do hloubky 2 úrovní.
Přidejte odkaz do AGENTS.md (nebo CLAUDE.md): - Architektura: Viz docs/ARCHITECTURE.md.

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

Úkol:

Zmapujte architekturu svého projektu v jednom stručném markdown souboru a ověřte orientaci agenta.

Kroky:

Vytvořte docs/ARCHITECTURE.md s mapou klíčových adresářů.
Přidejte pointer do AGENTS.md / CLAUDE.md.
V novém sezení agy nebo claude zadejte: „Kde v našem projektu leží logika pro odesílání e-mailů a jak ji upravit?“
Sledujte, zda agent využije mapu a ušetří tokeny při průzkumu.