Lekce 05.1: Řídicí mapa (The Steering Map)

⏱️ 4 min čtení • Lekce 05.1

🧠 Mentální model & teoretický rozbor

Řízení chování agenta (Steering) není o tom, že budete do každého promptu znovu psát: „Piš hezký kód, používej TypeScript a dávej pozor na testy.“ Skuteční inženýři navrhují hierarchickou řídicí mapu (Steering Architecture), která definuje mantinely na různých úrovních abstrakce:

HIERARCHIE ŘÍZENÍ AGENTA:
┌─────────────────────────────────────────────────────────────────────────┐
│ ÚROVEŇ 1: UŽIVATELSKÝ GLOBÁL                                            │
│ • Antigravity: ~/.gemini/config/skills/, pravidla, MCP servery          │
│ • Claude Code: ~/.claude/skills/, ~/.claude/config                      │
│ Osobní preference stylu, editor, shell aliasy, globální skilly.        │
├─────────────────────────────────────────────────────────────────────────┤
│ ÚROVEŇ 2: PROJEKT V REPOZITÁŘI                                          │
│ • Antigravity: AGENTS.md, GEMINI.md (hierarchické hledání od cwd nahoru)│
│ • Claude Code: CLAUDE.md v kořenu projektu                              │
│ Architektura, build skripty, pravidla pro linter, týmové standardy.    │
├─────────────────────────────────────────────────────────────────────────┤
│ ÚROVEŇ 3: SPECIALIZOVANÉ DOVEDNOSTI                                     │
│ • Antigravity: .agents/skills/<nazev>/SKILL.md                          │
│ • Claude Code: .claude/skills/<nazev>/SKILL.md                          │
│ Procedury pro konkrétní domény (databázové migrace, tvorba endpointů). │
├─────────────────────────────────────────────────────────────────────────┤
│ ÚROVEŇ 4: PROMPT SEZENÍ & SLASH COMMANDS                                │
│ Konkrétní inženýrský úkol (/grill-me, /plan, /goal, exekutivní prompt). │
└─────────────────────────────────────────────────────────────────────────┘

[!IMPORTANT] Hierarchické prohledávání v Antigravity: Antigravity prohledává adresářovou strukturu od aktuálního pracovního adresáře (cwd) rekurzivně směrem nahoru ke kořenu Gitu. Hledá soubory AGENTS.md i GEMINI.md. To je obrovská výhoda pro monorepozitáře (např. Turborepo, Nx nebo pnpm workspaces): balíček apps/web může mít své specifické AGENTS.md s pravidly pro Next.js, zatímco packages/database má vlastní AGENTS.md s pravidly pro Prisma a PostgreSQL!

Pokud se pokusíte nacpat pravidla z úrovně 3 do úrovně 2, vytvoříte gigantický soubor, který zahltí kontext a zničí Smart Zone.

🏢 Realistický scénář z praxe

V týmu pracuje 8 vývojářů na Next.js monorepu:

Bez řídicí mapy: Každý vývojář zadává agentovi jiné instrukce. Jeden preferuje Jest, druhý Vitest; jeden píše arrow functions, druhý function declarations. Repozitář se stává chaotickým slepencem.
S řídicí mapou: V kořenu projektu leží verzovaný AGENTS.md (případně CLAUDE.md) a v .agents/skills/ (nebo .claude/skills/) jsou uloženy firemní dovednosti. Každý agent spuštěný libovolným vývojářem (agy i claude) okamžitě dodržuje identické standardy.

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

Ukázka hierarchického souboru `AGENTS.md` (nebo `CLAUDE.md`):

# Projekt: Fintech Core API (Next.js 15, TypeScript, Prisma)

## Řídicí mapa projektu
- Globální pravidla: Striktní TypeScript, zákaz `any`, linter `biome`.
- Databáze: Řiď se ukazatelem `docs/database-guidelines.md`.
- Autentizace: Při změnách v auth použij dovednost `.agents/skills/audit-auth` (nebo `.claude/skills/audit-auth`).
- Testy: `pnpm vitest run <cesta_k_testu>`
- Typová kontrola: `pnpm tsc --noEmit`

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

Anti-pattern: Kolize pravidel mezi úrovněmi

Pokud máte v globálním nastavení vývojáře „Vždy používej npm“, ale projektový AGENTS.md / CLAUDE.md říká „Vždy používej pnpm“:

Model dostane protichůdné instrukce a začne se chovat nedeterministicky (v jednom tahu spustí npm a v druhém pnpm).
Pravidlo: Projektová pravidla v repozitáři mají vždy přednost před globálními preferencemi jednotlivce.

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

Vytvořte v kořenu projektu soubor AGENTS.md (pro Antigravity) a případně symbolický link či kopii na CLAUDE.md (pro kompatibilitu s Claude Code).
Definujte buildovací a testovací příkazy a commitněte soubor do Gitu.
Specifické procedury vyčleňte do samostatných dovedností ve složce .agents/skills/ (nebo .claude/skills/).
V hlavním konfiguračním souboru na tyto dovednosti odkazujte pomocí lehkých ukazatelů (pointers).

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

Úkol:

Vytvořte si základní řídicí mapu pro svůj projekt a otestujte její načtení.

Kroky:

Vytvořte v kořenu projektu AGENTS.md.
Rozdělte ho do 3 jasných sekcí:
- Příkazy pro build/test/lint.
- Architektonické mantinely.
- Odkazy na podrobnou dokumentaci (docs/).
Spusťte agy (nebo claude) a zeptejte se: „Jaké jsou klíčové příkazy a architektonická pravidla tohoto projektu?“
Ověřte, že agent okamžitě cituje pravidla z vašeho souboru.