Návrh systému agentů
Přejít na sekci
Separation of Concerns pro AI agenty
Největší chyba, kterou týmy s AI nástroji dělají, je zacházet s každým úkolem stejně: otevřít Claude Code, popsat co chcete a nechat to na AI. To funguje pro malé úkoly, ale u čehokoliv komplexního to selhává. AI se snaží plánovat, implementovat, testovat a reviewovat najednou — a kvalita každého kroku trpí.
Řešení je stejný princip, který aplikujete na lidské týmy: oddělení odpovědností. Různí agenti se specializují na různé úkoly. Architekt plánuje, ale nikdy nepíše kód. Vývojář implementuje, ale nikdy nediagnostikuje příčiny problémů. Runner spouští příkazy, ale nikdy nedělá rozhodnutí. Reviewer kontroluje kvalitu, ale nikdy přímo neopravuje.
Čtyři role agentů
1. Architekt
Architekt analyzuje požadavky, rozkládá tickety, rozhoduje které repos se budou měnit a vytváří implementační plány. Nikdy nepíše produkční kód — pouze plánuje. To je zásadní: když se AI pokouší plánovat a implementovat současně, plán je často neúplný, protože AI spěchá začít psát kód.
---
name: Backend Architect
description: |
Plánuje backend změny pro Django API. Analyzuje tickety,
rozkládá je na implementační kroky, identifikuje dotčené soubory
a píše detailní plány. NIKDY neimplementuje — pouze plánuje.
model: opus
---
# Backend Architect
Jsi backend architekt pro naše Django + Ninja API.
## Tvoje role
- Analyzuj feature requesty a bug reporty
- Rozlož tickety na konkrétní implementační kroky
- Identifikuj které soubory potřebují změny a jaké
- Piš implementační plány, které developer agent může následovat
- Upozorni na rizika, závislosti a edge cases
## Pravidla
- NIKDY nepiš produkční kód. Tvůj výstup jsou POUZE plány.
- NIKDY nedělej předpoklady o existujícím kódu — vždy nejprve čti soubory.
- Vždy zkontroluj existující patterny než navrhneš nové.
- Zahrň požadavky na testy do každého plánu.
## Formát výstupu
Pro každý implementační krok:
1. Soubor k úpravě (plná cesta)
2. Co změnit (konkrétně, ne vágně)
3. Proč (zdůvodnění)
4. Potřebné pokrytí testy2. Vývojář
Vývojář dostane plán a implementuje ho. Píše kód, vytváří soubory, modifikuje existující kód. Striktně následuje plán — pokud něco nedává smysl, zastaví se a zeptá místo toho, aby improvizoval. Vývojář nikdy nediagnostikuje problémy ani nemění plán.
---
name: Backend Developer
description: |
Implementuje backend změny podle plánů architekta.
Píše Django kód, vytváří endpointy, modely, testy.
Striktně následuje plány — eskaluje, pokud je plán nejasný.
model: sonnet
---
# Backend Developer
Jsi backend vývojář. Implementuješ změny
podle plánů vytvořených architektem.
## Tvoje role
- Implementuj změny kódu podle plánu
- Piš čistý, otestovaný kód podle konvencí projektu
- Po implementaci spusť testy
- Nahlásit výsledky zpět
## Pravidla
- NÁSLEDUJ PLÁN. Neodchyluj se.
- Pokud je plán nejasný nebo se zdá špatný, ZASTAV SE a nahlaš.
Nehádej a neimprovizuj.
- NIKDY nediagnostikuj bugy. Pokud testy selžou, nahlaš selhání.
Architekt analyzuje a poskytne plán opravy.
- Vždy spusť test suite po změnách.
## Konvence (z AGENTS.md)
- Django apps pod apps/
- Jeden soubor na skupinu endpointů v api/
- Pydantic schémata v api/schemas.py
- Testy zrcadlí strukturu appek v tests/3. Runner
Runneři spouštějí konkrétní příkazy a reportují výstup. Jsou stateless — nepamatují si předchozí běhy, nedělají rozhodnutí a neinterpretují výsledky. Jsou to glorifikované shell skripty s AI, které čte výstup. Používejte je pro deploymenty, migrace, setup prostředí.
---
name: Test Runner
description: |
Spouští test suites a reportuje výsledky. Neopravuje selhání —
pouze je reportuje s plným výstupem.
model: sonnet
---
# Test Runner
Spouštíš testy a reportuješ výsledky. Nic víc.
## Příkazy
- Backend: cd repos/backend && uv run pytest -x -v
- Frontend: cd repos/frontend && npm test
- Infra: cd repos/infra && terraform validate
## Pravidla
- Spusť požadovaný test suite
- Nahlaš: PASS/FAIL, počet testů, detaily selhání
- NIKDY neopravuj kód. NIKDY nemodifikuj soubory.
- NIKDY neinterpretuj proč testy selhaly — jen nahlaš výstup.4. Reviewer
Reviewer zkoumá změny kódu a kontroluje kvalitu. Dívá se na diff, kontroluje běžné chyby, ověřuje pokrytí testy a poskytuje zpětnou vazbu. Nikdy neopravuje problémy — vytváří seznam nálezů, které jdou zpět architektovi k plánování.
---
name: Code Reviewer
description: |
Reviewuje změny kódu napříč repos. Kontroluje bugy,
bezpečnostní problémy, chybějící testy a porušení konvencí.
Reportuje nálezy — nikdy přímo neopravuje.
model: opus
---
# Code Reviewer
Reviewuješ změny kódu z hlediska kvality a správnosti.
## Checklist
- [ ] Žádné N+1 dotazy (zkontroluj select_related/prefetch_related)
- [ ] Všechny nové endpointy mají testy (success + error cases)
- [ ] Žádné hardcoded secrets nebo credentials
- [ ] Error handling odpovídá projektovým patternům
- [ ] API schémata sedí mezi backendem a frontendem
- [ ] Databázové migrace jsou reverzibilní
- [ ] Žádné nepoužité importy nebo mrtvý kód
## Pravidla
- NIKDY neopravuj kód. Vytvoř seznam nálezů.
- Ohodnoť každý nález: CRITICAL / WARNING / SUGGESTION
- Pro každý nález: soubor, řádek, problém, doporučení
- Pokud vše vypadá dobře, řekni to explicitně.Strategie výběru modelu
Ne každý agent potřebuje nejsilnější model. Použijte Opus (nebo nejsilnější dostupný model) pro úkoly vyžadující hluboké uvažování: architektura, review, analýza root cause. Použijte Sonnet (nebo mid-tier modely) pro implementační úkoly, kde je plán jasný.
- Opus: Architekti, Revieweři, Solution Architects — úkoly vyžadující analýzu a úsudek
- Sonnet: Vývojáři, Runneři, Test Writeři — úkoly následující jasné plány nebo spouštějící příkazy
- Haiku: Jednoduché runnery, formátování, extrakce dat — úkoly bez ambiguity
Nejde jen o úsporu nákladů (i když pomáhá). Sonnet modely jsou rychlejší než Opus. Pro implementační úkoly, kde je plán jasný, rychlejší exekuce znamená rychlejší feedback loop. Použijte správný nástroj pro správnou práci.
Klíčová disciplína: Žádné překračování rolí
Nejdůležitější pravidlo v systému agentů: agenti nesmí nikdy překračovat hranice rolí. Když vývojář narazí na selhávající test, instinkt je ho debugovat. Ale debugging vyžaduje diagnostiku — pochopení proč něco selhává — což je práce architekta. Pokud vývojář začne diagnostikovat, často aplikuje povrchový fix, který skryje skutečný problém.
Správný flow: vývojář nahlásí selhání, architekt analyzuje root cause, architekt napíše plán opravy, vývojář implementuje opravu. Vypadá to pomalejší, ale produkuje mnohem lepší výsledky, protože každý krok používá správný model a správnou specializaci.
# Flow pro řešení chyb
1. Vývojář implementuje feature podle plánu
2. Testy selžou
3. Vývojář nahlásí: "Testy X, Y, Z selhaly. Výstup: [plný výstup]"
4. Architekt analyzuje: čte výstup testů, čte kód, identifikuje root cause
5. Architekt napíše plán opravy: "Změň soubor A řádek 42, protože..."
6. Vývojář implementuje opravu
7. Testy projdou -> pokračujeme na review
# ŠPATNÝ flow (častá chyba):
1. Vývojář implementuje feature
2. Testy selžou
3. Vývojář se pokouší opravit testy
4. Vývojář zavede nový bug při opravě
5. Více testů selže
6. Vývojář je teď hluboko v debugging rabbit hole
7. Kontext je znečištěný, kvalita klesáRegistr agentů v AGENTS.md
Každý agent musí být registrován v AGENTS.md, aby workspace věděl, co je k dispozici. Registr zahrnuje jméno agenta, cestu k souboru, model a jednořádkový popis jeho role.
## Agenti
| Agent | Soubor | Model | Role |
|-------|--------|-------|------|
| Solution Architect | .claude/agents/solution-architect.md | opus | Cross-repo plánování features |
| Backend Architect | .claude/agents/backend-architect.md | opus | Plánování Django API |
| Backend Developer | .claude/agents/backend-dev.md | sonnet | Django implementace |
| Frontend Architect | .claude/agents/frontend-architect.md | opus | Plánování Next.js |
| Frontend Developer | .claude/agents/frontend-dev.md | sonnet | Next.js implementace |
| Infra Engineer | .claude/agents/infra-eng.md | sonnet | Terraform + k8s |
| Test Runner | .claude/agents/test-runner.md | sonnet | Spouštění test suites |
| Code Reviewer | .claude/agents/reviewer.md | opus | Kontrola kvality |
| Deploy Runner | .claude/agents/deploy-runner.md | sonnet | Spouštění deploymentů |Formát souboru agenta
Každý agent je Markdown soubor s YAML frontmatter. Frontmatter poskytuje metadata, která nástroje mohou parsovat programově. Tělo souboru poskytuje system prompt — instrukce, které AI následuje, když jedná jako daný agent.
---
name: Název agenta
description: Jeden odstavec popisující co agent dělá
model: opus | sonnet | haiku
---
# Název agenta
## Tvoje role
[Co děláš a co neděláš]
## Pravidla
[Tvrdá omezení — NIKDY/VŽDY]
## Konvence
[Projektově-specifické patterny]
## Formát výstupu
[Jak strukturovat odpovědi]Udržujte definice agentů zaměřené. Častá chyba je psát 500řádkovou definici, která se snaží pokrýt každý scénář. Začněte s 30-50 řádky, které definují klíčovou roli, pravidla a formát výstupu. Přidávejte specifika jen když narazíte na opakující se problémy.
Vytvořte 4 definice agentů pro primární repo vašeho týmu: 1. Architekt (model: opus) — plánuje změny, nikdy neimplementuje 2. Vývojář (model: sonnet) — implementuje plány, nikdy nediagnostikuje 3. Runner (model: sonnet) — spouští příkazy, nikdy nerozhoduje 4. Reviewer (model: opus) — kontroluje kvalitu, nikdy neopravuje Pro každého agenta napište YAML frontmatter a hlavní prompt (role, pravidla, konvence). Umístěte je do .claude/agents/ ve vašem workspace. Zaregistrujte všechny čtyři v AGENTS.md.
Nápověda
Začněte s konvencemi z vašeho reálného codebase: struktura souborů, pojmenovávací vzory, požadavky na testování. Čím specifičtější konvence, tím lépe agent funguje.
Otevřete Claude Code a zavolejte vašeho Developer agenta. Dejte mu úkol, kde plán záměrně obsahuje drobnou chybu. Například: 'Implementuj tento endpoint, ale použij nesprávný název modelu.' Sledujte, jestli vývojář zachytí problém a nahlásí ho, nebo tiše implementuje špatný kód. Iterujte definici agenta, dokud spolehlivě nezastaví a nenahlásí problémy v plánu místo slepé implementace.
Nápověda
Přidejte specifické pravidlo jako: 'Pokud jakýkoliv odkazovaný soubor, model nebo funkce neexistuje, ZASTAV SE a nahlaš nesoulad. Nevytvářej chybějící entity bez schválení architekta.'
- Čtyři role agentů: Architekt (plánuje), Vývojář (implementuje), Runner (spouští), Reviewer (kontroluje)
- Agenti nesmí nikdy překračovat hranice rolí — vývojáři nediagnostikují, architekti neimplementují
- Opus pro reasoning úkoly (architektura, review), Sonnet pro implementační úkoly
- Řešení chyb vždy prochází zpět přes architekta pro analýzu root cause
- Definice agentů jsou Markdown soubory s YAML frontmatter, registrované v AGENTS.md
V příští lekci se ponoříme do Skills a vývojové pipeline — technika, která vám dá jasnou převahu. Odemkněte celý kurz a pokračujte hned.
2/8 hotovo — pokračujte!