diff --git a/docs/USING_VIBE_AGENTS.md b/docs/USING_VIBE_AGENTS.md new file mode 100644 index 0000000..51026b1 --- /dev/null +++ b/docs/USING_VIBE_AGENTS.md @@ -0,0 +1,310 @@ +# 🤖 Využití Vibe agentů v tomto monorepu + +Tento návod vysvětluje, jak **používat Vibe agenty** pro efektivnější práci s tímto monorepo. Agenti jsou navrženi tak, aby vám pomohli s vývojem, testováním a výukou API. + +--- + +## 🎯 Dostupní agenti + +| Agent | Účel | Vyvolání | Kdy použít | +|-------|-------|----------|------------| +| **API Test Assistant** | Pomoc s vytvářením, úpravou a spouštěním API testů | `/api-tester` | Potřebuji vytvořit nové testy, opravit selhávající testy, spustit testy | +| **Bruno Expert** | Specialista na Bruno CLI a pokročilé funkce | `/bruno-expert` | Potřebuji pomoci s Bruno syntaxí, řetězením testů, sdílenými proměnnými | +| **Learning Guide** | Výuka API testování krok za krokem | `/learning-guide` | Jsem nováček, chci se naučit základy API testování | + +--- + +## 🚀 Jak agenty vyvolat + +### V rozhovoru s Vibe CLI +Jednoduše napište příslušný příkaz: + +``` +/api-tester +``` + +nebo + +``` +/bruno-expert +``` + +Vibe automaticky aktivuje příslušného agenta a poskytne mu kontext tohoto repozitáře. + +--- + +## 📝 Příklady použití + +### Příklad 1: Vytvoření nového testu +**Situace:** Chcete vytvořit test pro nový endpoint v JsonPlaceholder API. + +``` +/api-tester +Vytvoř nový test pro endpoint POST /posts v JsonPlaceholder kolekci +``` + +**Očekávaná odpověď:** +- Agent navrhne strukturu nového testu +- Ukáže, kam soubor uložit +- Poskytne ukázkový YAML kód + +--- + +### Příklad 2: Oprava selhávajícího testu +**Situace:** Test vrací chybu "You can run only at the root of a collection" + +``` +/api-tester +Můj test selhává s chybou "You can run only at the root of a collection" +``` + +**Očekávaná odpověď:** +- Agent vysvětlí příčinu chyby +- Ukáže, jak spustit test ze správného adresáře +- Poskytne příklad příkazu + +--- + +### Příklad 3: Pokročilé Bruno funkce +**Situace:** Potřebujete vytvořit řetězec testů (CREATE → READ → UPDATE → DELETE) + +``` +/bruno-expert +Jak vytvořím CRUD testovací řetězec v Bruno? +``` + +**Očekávaná odpověď:** +- Vysvětlení principu řetězení +- Ukázka použití `bru.setEnvVar()` +- Kompletní příklad YAML souborů + +--- + +### Příklad 4: Výuka základů +**Situace:** Jste nováček a chcete se naučit, co je to API + +``` +/learning-guide +Co je to REST API? +``` + +**Očekávaná odpověď:** +- Vysvětlení pojmu API +- Rozdíl mezi REST, SOAP, GraphQL +- Příklady použitelnosti + +--- + +## 🎓 Výukové cesty s Learning Guide + +### Úroveň 1: Základy (pro úplné začátečníky) +``` +/learning-guide +Chci se naučit základy API testování +``` + +**Obsah:** +- Co je API +- HTTP metody (GET, POST, PUT, DELETE) +- Stavové kódy (200, 201, 400, 404, 500) +- Instalace a nastavení Bruno + +--- + +### Úroveň 2: Práce s tímto monorepo +``` +/learning-guide +Jak přidám novou API službu do tohoto monorepa? +``` + +**Obsah:** +- Struktura repozitáře +- Vytváření nové kolekce +- Spouštění testů +- Úprava existujících testů + +--- + +### Úroveň 3: Pokročilé techniky +``` +/learning-guide +Jak používat sdílené proměnné a řetězení testů? +``` + +**Obsah:** +- Autentikace (Basic Auth, Bearer Token) +- Řetězení testů (Chaining) +- Sdílené proměnné prostředí +- Testování různých typů API + +--- + +### Úroveň 4: CI/CD a automatizace +``` +/learning-guide +Jak funguje CI/CD pipeline v tomto repozitáři? +``` + +**Obsah:** +- GitHub Actions workflow +- Spouštění testů v CI/CD +- Ladění selhávajících testů +- Integrace s dalšími nástroji + +--- + +## 💡 Tipy pro efektivní použití agentů + +### 1. **Buďte specifický** +❌ Špatně: "Pomoc s testy" +✅ Dobře: "Potřebuji vytvořit test pro GET /users endpoint v JsonPlaceholder" + +### 2. **Poskytujte kontext** +``` +/api-tester +Právě jsem vytvořil nový endpoint /api/v2/users a potřebuji pro něj vytvořit test. +Endpoint vrací array uživatelů s poli id, name, email. +``` + +### 3. **Kladte konkrétní otázky** +``` +/bruno-expert +Jak mohu v Bruno testu zkontrolovat, že pole 'id' je unikatní napříč všemi položkami? +``` + +### 4. **Žádejte příklady** +``` +/learning-guide +Můžeš mi ukázat příklad testu pro POST požadavek s JSON tělem? +``` + +--- + +## ⚙️ Technické detaily + +### Jak agenti vědí o tomto monorepu +Každý agent má přístup k: +- **Struktuře repozitáře** - Zná cesty k backendum a testům +- **Konfiguraci** - Ví, kde jsou jednotlivé soubory +- **Dokumentaci** - Odkazuje na existující návody + +### Co agenti umí automaticky +- **API Test Assistant:** + - Generovat YAML strukturu pro nové testy + - Analyzovat existující testy + - Navrhovat opravení chyb + +- **Bruno Expert:** + - Vysvětlovat pokročilé funkce Bruno + - Řešit specifické chyby + - Optimalizovat testovací scénáře + +- **Learning Guide:** + - Vysvětlovat koncepty krok za krokem + - Poskytovat příklady + - Navrhovat výukové cesty + +--- + +## 🔧 Řešení běžných problémů + +### Problém: Agent nerozumí mé otázce +**Řešení:** +- Zopakuji otázku s více detaily +- Specifikuj, kterou část repozitáře se týká +- Ukáž příklad toho, co chci dosáhnout + +### Problém: Agent poskytuje obecné odpovědi +**Řešení:** +- Žádej konkrétní příklady +- Specifikuj, že chceš odpověď pro tento repozitář +- Vyzvi agenta k použití konkrétních cest + +### Problém: Agent navrhuje něco, co již existuje +**Řešení:** +- Upozorněte agenta, že soubor již existuje +- Žádej úpravu existujícího souboru +- Požádej o verifikaci, zda soubor existuje + +--- + +## 📚 Příklady konverzací + +### Konverzace 1: Vytvoření nové kolekce +``` +Uživatel: /api-tester + Chci vytvořit novou kolekci pro testování OpenWeather API + +Agent: Dobře! Zde je návod: + 1. Vytvoř: mkdir -p apiTest/OpenWeather/Current + 2. Přidej opencollection.yml s obsahem: [ukázka YAML] + 3. Vytvoř folder.yml: [ukázka] + 4. Vytvoř test: [ukázka] + + Chceš, abych ti vygeneroval konkrétní soubory? +``` + +### Konverzace 2: Oprava chyby +``` +Uživatel: /api-tester + Můj test pro POST /spells selhává s kódem 400 + +Agent: Zkontroluj následující: + 1. Má test správný Content-Type header? + 2. Je tělo požadavku validní JSON? + 3. Neexistuje již kouzlo se stejným jménem? + + Ukáž mi svůj testovací soubor a pomohu ti ho opravit. +``` + +### Konverzace 3: Výuka +``` +Uživatel: /learning-guide + Jak funguje autentikace v API? + +Agent: Autentikace slouží k ověření identity klienta. Zde jsou hlavní typy: + + 1. Basic Auth: Uživatelské jméno + heslo + 2. Bearer Token: JWT token v Authorization header + 3. API Key: Klíč v hlavičce nebo query parametru + + V PotterAPI se používá Basic Auth pro /characters endpoint. + Chceš vidět příklad? +``` + +--- + +## 📊 Kdy použít který agenta + +| Situace | Doporučený agent | Důvod | +|---------|------------------|--------| +| Vytváření nových testů | API Test Assistant | Specializovaný na vytváření testů | +| Oprava selhávajících testů | API Test Assistant | Zná běžné chyby a jejich řešení | +| Pokročilé Bruno funkce | Bruno Expert | Hluboké znalosti Bruno CLI | +| Řetězení testů | Bruno Expert | Zkušenosti s komplexními scénáři | +| Základy API | Learning Guide | Vzdělávací přístup | +| Nováček v repozitáři | Learning Guide | Provází krok za krokem | +| Optimalizace testů | Bruno Expert | Zkušenosti s výkonem | + +--- + +## 🎯 Best Practices + +1. **Začněte s Learning Guide** - Pokud jste nováček +2. **Používejte API Test Assistant** - Pro každodenní práci s testy +3. **Konultujte Bruno Expert** - Pro složité problémy +4. **Kombinujte agenty** - Například: Learning Guide → API Test Assistant → Bruno Expert + +--- + +## 📞 Podpora + +Pokud agenti neposkytují očekávané odpovědi: +1. Zkontrolujte, zda je otázka jasná a specifická +2. Přidejte více kontextu +3. Ověřte, že používáte správného agenta +4. Podívejte se do dokumentace v `docs/` + +--- + +*Poslední aktualizace: 15. září 2026* \ No newline at end of file