Lekce 04.4: Průzkum codebase (Codebase Exploration)

⏱️ 3 min čtení • Lekce 04.4

🧠 Mentální model & teoretický rozbor

Jak se má agent zorientovat v cizím repozitáři o 500 souborech, aniž by zahltil svůj kontext? Amatérský přístup spočívá v tom, že necháte agenta číst soubory naslepo. Inženýrský přístup využívá strukturovanou trychtýřovou metodu (Top-Down Funnel):

TOP-DOWN PRŮZKUM REPOZITÁŘE:
┌─────────────────────────────────────────────────────────────┐
│ 1. ÚROVEŇ: Manifest projektu (package.json / Cargo.toml)    │
│    Zjištění ekosystému, frameworku, ORM a skriptů (30s)     │
├─────────────────────────────────────────────────────────────┤
│ 2. ÚROVEŇ: Adresářový strom do hloubky 2 (tree -L 2)        │
│    Pochopení organizace složek (kde je frontend, backend)   │
├─────────────────────────────────────────────────────────────┤
│ 3. ÚROVEŇ: Cílené prohledání symbolů (ripgrep / grep)       │
│    Nalezení přesného výskytu konkrétního modelu či funkce   │
├─────────────────────────────────────────────────────────────┤
│ 4. ÚROVEŇ: Čtení typových definic (.d.ts / interfaces)      │
│    Pochopení rozhraní BEZ nutnosti číst 1 000 řádků kódu   │
└─────────────────────────────────────────────────────────────┘

---

🏢 Realistický scénář z praxe

Nový vývojář dostane za úkol přidat pole do uživatelského profilu v neznámém projektu:

• Špatný pokus: Nechá agenta hledat text “User” v celém repozitáři. Vyhledávač vrátí 800 řádků ze všech souborů. Kontext je zahlcen.
• Top-Down pokus:
  1. Agent otevře package.json ➔ vidí @prisma/client.
  2. Agent otevře přímo prisma/schema.prisma a vyhledá model User.
  3. Za 10 sekund přesně ví, jak schéma vypadá, s minimální spotřebou tokenů.

---

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

Šablona promptu pro úsporný průzkum neznámého kódu:

Úkol: Zorientuj se v autentizačním toku tohoto projektu.

Postupuj striktně top-down:
1. Přečti závislosti v package.json (sekce dependencies).
2. Spusť v bashi `tree src/lib/auth -L 2`, abys pochopil strukturu složky.
3. Přečti POUZE hlavičky a exportované typy v src/lib/auth/types.ts.
4. Napiš mi 3bodové shrnutí: jaký token systém se používá (JWT vs Session), kde se ověřuje a jaké role existují.
Nevykonávej žádné změny v souborech!

---

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

Chyba: Čtení implementačních detailů namísto rozhraní

Agent se snaží pochopit fungování platební brány tím, že přečte 1 500 řádků obslužného kódu se všemi matematickými operacemi.

• Pro návrh nové platby přitom nepotřebuje vidět algoritmus výpočtu kontrolního součtu – stačí mu vidět rozhraní metody createPayment(params: PaymentInput): Promise<PaymentResult>.

---

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

1. Začněte u manifestu závislostí (package.json).
2. Prozkoumejte adresářovou mapu (tree).
3. Použijte ripgrep pro nalezení definičního souboru.
4. Přečtěte pouze typové rozhraní.
5. Teprve po ujasnění souvislostí přejděte k samotné editaci.

---

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

Úkol:

Vyzkoušejte si top-down průzkum na svém vlastním projektu.

Kroky:

1. Spusťte claude a zadejte mu: „Prozkoumej tento repozitář pomocí stromu adresářů a manifestu a vysvětli mi jeho architekturu v 5 větách.“
2. Zkontrolujte přes /cost, kolik tokenů agent spotřeboval. (Při správném postupu by to mělo být pod 5 000 tokenů!).

---