Maguyva Blog

Kontext, který cestuje s vámi

Mon, 07 Sep 2026 00:00:00 GMT

Indexer Cursor je uvnitř Cursor vynikající. Automatické doplňování, editace v řádku, chat a agent v tom okně už stojí na indexu projektu, který Cursor udržuje pro otevřený pracovní prostor. Pokud je Cursor jediné prostředí, kde píšete kód, a tento index už nachází správné soubory, zůstaňte tam. To je poctivý případ „zůstaňte tam, kde jste“ a právem otevírá tento text.

Tento článek je o druhé polovině běžného týdne. Stejný repozitář se také otevírá v Claude Code, ptá se ho Codex CLI, kontroluje se na druhém stroji nebo se ho dotazuje agent běžící v CI. Otázka nezní „který indexer je lepší“. Otázka zní, zda je mapa, které agent důvěřuje v jednom okně, stejná jako ta, které důvěřuje v následujícím.

Maguyva je ta mapa, která cestuje s vámi. Je to vzdálená vrstva kontextu kódové báze přes MCP. Agent ji dotazuje stejným způsobem jako jakýkoli jiný nástroj MCP. Výsledky se vracejí jako seřazené cesty s čísly řádků. Cursor zůstává editorem. Pohybuje se kontext.

K čemu slouží indexer Cursor

Vestavěné indexování Cursor existuje proto, aby chat, agent a vyhledávání uvnitř editoru mohly načítat relevantní kód, místo aby se spoléhaly jen na to, co se vejde do syrového kontextového okna modelu. To je správný návrh pro IDE. Tento index je nativní součástí Cursor. Není to MCP server a není dostupný z žádného jiného klienta.

Takto to funguje, podle veřejné dokumentace Cursor a vlastního vyjádření Cursor v době psaní tohoto textu: hlavní cesta vyhledávání už není cloudový index embeddingů. Tým Cursor na svém komunitním fóru uvedl, že vyhrazené sémantické vyhledávání založené na embeddingech se postupně utlumuje ve prospěch vyhledávání založeného na grep, protože současné modely už samy dokážou dostatečně dobře prozkoumávat živý strom. Na jeho místo nastupuje Instant Grep, lokální vyhledávací index postavený na n-gramech, invertovaných seznamech a Bloomových filtrech, uchovávaný v paměťově mapované vyhledávací tabulce, takže dotazy se řeší přímo na stroji vývojáře, a ne na serveru.

Samotný index žije uvnitř vlastního adresáře repozitáře .git/cursor/, ukotveného ke konkrétnímu git commitu; změny od tohoto commitu se na něj vrství, místo aby spouštěly nové skenování, a index se přestavuje jen tehdy, když se lokální stav výrazně odchýlí od toho, na čem byl postaven. Protože leží uvnitř .git, nikdy se nesleduje verzovacím systémem a nikdy se nepushuje — smažete složku a index zmizí. .gitignore je dodržováno samotnou konstrukcí, protože do úvahy připadá jen obsah sledovaný gitem, a .cursorignore se vynucuje na cestě čtení. Na této cestě už není žádný krok embeddingu na straně serveru ani vzdálená vektorová databáze. Dřívější dokumentace popisovala návrh podporovaný cloudem — šifrování bloků, synchronizaci pomocí Merkle stromu, opětovné využití indexu mezi členy týmu — a tým Cursor od té doby uvedl, že tento návrh se utlumuje, takže tento text ho už nepopisuje jako aktuální.

Výraznou předností uvnitř editoru je subagent Explore od Cursor. Dokáže spustit několik paralelních vyhledávání ve vlastním kontextovém okně na rychlejším modelu a vrátit jen relevantní nálezy, takže se hlavní konverzace nenafukuje výsledky vyhledávání. To je skutečná síla uvnitř editoru. Zachovejte ji.

Multi-root pracovní prostory jsou podporovány: kontext každé otevřené složky je dostupný agentovi. Některé funkce závislé na gitu, jako worktree, jsou v multi-root konfiguracích vypnuté a Cloud Agents multi-root pracovní prostory vůbec nepodporují.

Nic z toho není důvod opustit Cursor. Je to přesný popis mapy, která je vynikající tam, kde žije.

Co skutečně znamená „cestovat s vámi“

Mapa cestuje s vámi, když stejné otázky vracejí stejný typ odpovědi, s citacemi, které můžete otevřít, z více než jednoho klienta.

V Cursor: „Kde je definováno parseConfig a kdo to volá?“
V Claude Code, na stejném repozitáři: stejná otázka.
V Codex CLI, na kontrolním stroji, který nikdy neotevřel okno Cursor: stejná otázka.
V CI agentovi, který mluví MCP: stejná otázka, vůči stejnému hostovanému snímku.

Pokud si každé prostředí buduje vlastní privátní index, nemáte jednu mapu. Máte několik keší, které se rozcházejí. Index editoru může být aktuální pro strom na disku. Relace CLI může zaostávat o den. Úloha CI se může dívat na jiný checkout. A agent bude přesto znít sebejistě.

Indexer Cursor to řešit nemá. Protože žije uvnitř editoru, kontext, který buduje, je pro ten editor. Čtenář, který potřebuje ještě CLI, pipeline CI nebo jiný editor, potřebuje samostatný nástroj pro tato prostředí. To je fakt rozsahu, ne vada. Maguyva je ten samostatný nástroj.

Zveřejněný počet jazyků pro indexer Cursor není uveden v podkladech, které tento text smí použít. Maguyva zveřejňuje podporu více než 279 jazyků a textových technologií. Ceny Cursor se tu také nepřebírají; viz jejich stránku s cenami. Maguyva účtuje za pracovní prostor, ne za místo, se zveřejněnými plány $0, $19, $49 a $149 podle rozsahu indexace a velikosti pracovního prostoru.

Jedna hostovaná mapa, každý MCP klient

Maguyva je vzdálený MCP server. Připojíte GitHub, vyberete repozitáře a cloudový pipeline vybuduje symboly, hrany grafu a seřazenou mapu. Přidáte API klíč do MCP konfigurace klienta, který už používáte. Maguyva má návody na nastavení pro 24 zdokumentovaných MCP klientů — včetně Cursor — a umí se připojit i k dalším MCP kompatibilním klientům, kteří podporují standardní konfiguraci.

Stránka nastavení Cursor je cesta specifická pro tento editor, pokud tam pracujete. Stejný server odpovídá Claude Code, VS Code, Windsurf, Codex CLI a dalším. Nemusíte měnit editor. Každému agentovi dáváte stejný povrch nástrojů: 11 zákaznických MCP nástrojů napříč vyhledáváním, symboly, analýzou závislostí, získáváním souborů, kontextem repozitáře a deterministickými servisními pracovními postupy. Sémantické, strukturální, grafové a textové vyhledávání se slévají do seřazených výsledků.

V tom spočívá výhoda přenositelnosti. Citace, které jste dnes ráno ověřili v Cursor, mají stejnou podobu jako citace, které dnes večer vrátí Codex CLI. Cesta k souboru a číslo řádku. Otevřete je. Pokud jsou špatné, uvidíte to. Pokud jsou správné, další úprava má kam přistát. Schválené tvrzení zní méně halucinovaných úprav, ne slib, že každá úprava je správná.

Aktuálnost je zveřejněná. Snímky mají časové razítko, takže agent ví, kterou verzi stromu čte. Frekvence přestavby je denně u bezplatného plánu a hodinově u placených. Poctivým omezením je nesynchronizovaná lokální práce: úprava existující jen v pracovním stromu ještě není v hostované mapě. Toto omezení je stejné bez ohledu na to, ze kterého klienta se dotazujete, a přesně o to jde. Rozdíl mezi klienty už není druhé, skryté omezení.

Dokumentace uvádí aktivační smyčku, která platí pro každého klienta: naindexujte repozitář, který už znáte, připojte klienta, položte jednu otázku, kterou umíte ověřit. Udělejte to jednou v Cursor. Udělejte to znovu z CLI, které skutečně používáte ve dnech kontroly. Pokud obě odpovědi citují stejný handler, mapa skutečně cestovala s vámi.

Jak vedle sebe existují dvě mapy

Používejte obě. Nejsou to alternativy ve smyslu srovnávací stránky.

Nechte indexer Cursor zapnutý pro projekt na disku. Ať ho používá Explore, Instant Grep a agent uvnitř editoru. Tato smyčka je nativní a rychlá.
Přidejte Maguyva jako MCP server do Cursor, aby stejná relace mohla dotazovat i hostovanou mapu pracovního prostoru. Cursor je zdokumentovaný klient Maguyva. Nevybíráte jeden index a nemažete druhý.
Přidejte stejný server Maguyva do Claude Code, Codex CLI nebo jakéhokoli jiného MCP klienta, který se dotýká repozitáře. Jedna podoba API klíče. Jeden pracovní prostor.
Pokud je CI agent kompatibilní s MCP, nasměrujte ho na stejný server. Přečte stejný časově orazítkovaný snímek, jaký četl notebook.

Index editoru zůstává nejlepším nástrojem pro otázku „co je právě teď na disku v tomto okně“. Hostovaná mapa je nejlepší nástroj pro otázku „jak tento pracovní prostor vypadá pro každého agenta, který se ho dnes dotkne“. Tyto věty si nekonkurují.

Kvóty pracovního prostoru jsou zveřejněny na stránce s cenami: repozitáře, naindexované řádky a uživatelé, účtované za pracovní prostor. Agenti a lidé sdílejí stejný počet uživatelů. Začněte zdarma s repozitářem, který už umíte posoudit. Pracovní prostor zvětšujte až poté, co citace přežijí kontakt se stromem.

Co tato stránka netvrdí

Netvrdí, že indexer Cursor je slabý, neúplný nebo důvod ke změně editoru. První věta tohoto textu tvrdí opak.

Netvrdí, že Maguyva nahrazuje Instant Grep nebo subagenta Explore. To jsou funkce Cursor. Zůstávají v Cursor.

Nevymýšlí si počet jazyků, číslo latence ani úsporu tokenů pro žádný z produktů. Neznámá čísla zůstávají nezveřejněná.

Nepředstírá, že nenapushovaná lokální práce je v hostované mapě. Časově orazítkované snímky toto omezení zviditelňují. Neodstraňují ho.

Test je obyčejný. Naindexujte repozitář, který už znáte. Položte jednu otázku, kterou umíte ověřit, nejprve v Cursor, pak ve druhém MCP klientovi. Kontext, který cestuje s vámi, je stejná citace na obou místech.

// same map, wherever you opened it.

Nejdřív mapa, pak revize

Mon, 07 Sep 2026 00:00:00 GMT

Na obou stranách pull requestu stojí dva odlišné úkoly. Než agent začne psát, potřebuje mapu stromu, který se chystá změnit. Poté, co agent otevře PR, by měl něco přečíst tuto změnu vůči zbytku systému a nechat komentáře, podle kterých může jednat člověk.

Tyto úkoly vypadají z dálky podobně, protože oba zahrnují „porozumění kódové bázi“. Nejsou to stejný produkt. Jeden odpovídá na otázku „kam by tato změna měla přistát?“. Druhý odpovídá na otázku „co tento diff porušil, co linter kontrolující řádek po řádku přehlédne?“. Jejich zaměnění dává horší první koncept a hlučnější revizi.

Tento text je průvodce společným pracovním postupem. Maguyva je mapa, kterou agent dotazuje jako první. Greptile je agent revize, který PR komentuje pak. Tato dvojice je konstrukčně doplňující: Maguyva nerevidiuje pull requesty a Greptile nenahrazuje vrstvu kontextu, kterou agent použil k jejich napsání.

Proč je toto rozdělení užitečné

Kódovací agent, který vychází z tréninkových priorů plus pár vložených souborů, si vymyslí věrohodnou cestu a upraví ji. To je selhání „špatného souboru“ a je to problém vyhledávání. Maguyva je vzdálená vrstva kontextu kódové báze přes MCP: sémantické, strukturální (AST), grafové/závislostní a textové vyhledávání se slévá do seřazených výsledků, plus vyhledávání symbolů a získávání souborů. Podložené odpovědi se vracejí jako path/file.ext:line, takže omyl můžete odmítnout dřív, než patch vůbec existuje. Tvrzení zůstává skromné: méně halucinovaných úprav. Model může i tak hádat. Prostě první krok už není hádání.

Greptile je agent revize kódu s umělou inteligencí. Vlastními slovy automaticky revidiuje každý pull request s úplným porozuměním kódové bázi a staví to proti tradičním linterům, které kontrolují soubory izolovaně, ne celý systém. Nastavení spočívá v instalaci aplikace GitHub nebo GitLab a výběru repozitářů. Není tu žádný lokální index, který byste museli provozovat. Hostováno je to na Greptile Cloud (uvádějí soulad se SOC 2 Type II, se zprávou dostupnou na vyžádání), s možností vlastního hostování nabízenou podnikům.

Jejich vlastní číslovaný proces je: připojit se a vybudovat graf závislostí každé funkce, třídy a závislosti; při každém pull requestu analyzovat změnu pomocí tohoto úplného grafu repozitáře a zveřejnit nálezy jako komentáře PR s navrženými opravami zhruba za tři minuty; každý komentář může předat problém kódovacímu agentovi, kterého tým už používá. Uvádějí také, že v čase čtou předchozí lidské komentáře k PR, aby se naučili standardy kódu týmu a omezili hlučné návrhy. Jejich učicí se systém podle jejich slov potřebuje 2–3 týdny na přizpůsobení.

Toto je revize, ne psaní. Silnou stránkou Greptile je kontext úplného grafu repozitáře na změnu, která už v PR přistála, a pak uzavřená smyčka, která nález pošle do Claude Code, Codex, Conductor, Cursor nebo Devin. Silnou stránkou Maguyva je seřazená mapa, kterou agent dotázal dřív, než byla tato změna napsána. Používejte oba. Nežádejte po žádném z nich, aby dělal práci toho druhého.

Oficiální integrace produktů Maguyva–Greptile od první strany není uvedena. Ani ji nepotřebujete. Maguyva mluví s agentem přes MCP. Greptile mluví s GitHub nebo GitLab přes svou aplikaci. Setkávají se u pull requestu. Žádný lepicí skript, žádný cron, který propojuje jeden nástroj s druhým. Tato dvojice se obejde bez bash, protože každý produkt už stojí na povrchu, který mu patří.

Co tohle není

Toto není demolice Greptile. Není to stránka „vyměňte si recenzenta“. Greptile odstartoval na Hacker News 5. března 2024 jako firma Y Combinator W24 a to vlákno je způsob, jakým se s produktem poprvé seznamovala spousta lidí. Pokud jste je takto našli i vy, zůstaňte u nich. Tato stránka je chybějící přední polovina té smyčky: zakotvit agenta předem, aby PR, který Greptile vidí, už mířil na správné soubory.

Marketingové materiály Greptile vedou tvrzeními o rychlosti revize a odhalování chyb. Berte je jako vlastní tvrzení Greptile, ne jako nezávisle ověřená čísla. Tento text je neopakuje jako fakta.

Pokrytí jazyků je stejný druh poctivosti. Greptile rámuje podporu jako pokrytí všech programovacích jazyků, ne jako vyjmenovaný seznam; přesné číslo není uvedeno. Maguyva zveřejňuje podporu více než 279 jazyků a textových technologií, s technickým rozdělením (AST podpořené parserem versus jen text) na webu, když je otázka technická. Jsou to různé produkty s různými tvrzeními. Nemíchejte je.

Ceny Greptile nejsou uvedeny v podkladech, které tento text smí použít. Placené plány existují; viz jejich stránku s cenami. Maguyva účtuje za pracovní prostor, ne za místo. Plány začínají zdarma. Stránka s cenami uvádí zveřejněné úrovně, pokud potřebujete čísla pracovního prostoru.

Pracovní postup

Tři pojmenované fáze. Provádějte je v tomto pořadí. Žádnou z nich při prvním vyzkoušení této dvojice nepřeskakujte.

1. Kontext Maguyva

Naindexujte jeden repozitář, který už znáte. Připojte MCP klienta, ve kterém už píšete kód — Claude Code, Cursor, Codex CLI, VS Code, Windsurf nebo jiného MCP kompatibilního klienta. Maguyva má návody na nastavení pro 24 zdokumentovaných MCP klientů a umí se připojit i k dalším klientům, kteří podporují standardní konfiguraci MCP.

Položte otázku, kterou dokážete posoudit, dřív, než kdokoli napíše řádek. „Kde se řeší vypršení relace a co to volá?“ je lepší první tah než „oprav autentizaci“. Vyžadujte citace. Otevřete výsledky file.ext:line. Sledujte symbol. Potvrďte závislost, které se chystáte dotknout.

Maguyva zpřístupňuje 11 zákaznických MCP nástrojů napříč vyhledáváním, symboly, analýzou závislostí, získáváním souborů, kontextem repozitáře a deterministickými servisními pracovními postupy. Čtyři režimy vyhledávání se slévají do seřazených výsledků; find_symbol je samostatný nástroj, když už jméno znáte. Dokumentace popisuje nejkratší cestu: začít zdarma, naindexovat repozitář, který už znáte, připojit klienta, pak položit jednu otázku, kterou umíte ověřit.

Snímky mají časové razítko, takže agent pozná, kterou verzi stromu čte. Poctivým omezením je nesynchronizovaná lokální práce. Pokud úprava existuje jen v pracovním stromu a nebyla napushovaná, hostovaná mapa ji ještě neobsahuje. Instrukční soubory (CLAUDE.md, AGENTS.md) tu mají i nadále své místo pro konvence a to, čeho se nedotýkat. Nejsou to živá mapa. Používejte je pro chování. Používejte Maguyva pro fakta.

Nenechte agenta otevřít PR dřív, než citace přežijí kontakt s repozitářem. Tato brána je celý smysl této fáze.

2. PR agenta

Stejný agent teď píše změnu v klientovi, za který už platíte. Maguyva není editor ani recenzent. Agent stále produkuje diff. Vy stále otevíráte pull request na GitHub nebo GitLab tak, jak to už děláte.

Co by mělo být jiné, je první soubor. PR by měl pojmenovat handler, který dané chování skutečně implementuje, volajícího, který se rozbije, a test, který selže, pokud je změna špatná. Pokud byla fáze 1 přeskočena, fáze 3 utratí své komentáře na změnu, která přistála ve špatném balíčku. Greptile pořád dokáže najít systémové problémy. Neměl by se navíc muset zotavovat z halucinované cesty.

Držte PR úzce zaměřený. Podložený první soubor není licence k přepsání modulu. Tato doplňující se dvojice funguje, když agent odvedl jednu práci s mapou a pak požádal recenzenta, aby udělal jinou práci na ohraničeném diffu.

3. Revize Greptile

Greptile je už připojený k repozitáři přes aplikaci GitHub nebo GitLab. U nového pull requestu analyzuje změnu pomocí úplného grafu repozitáře, který vybudoval, a zveřejňuje nálezy jako komentáře s navrženými opravami. Jejich vlastní materiály udávají tento průchod na zhruba tři minuty.

Čtěte komentáře tak, jak byste četli pozorného kolegu z týmu: otevřete citované místo, rozhodněte, zda je nález reálný, pak jednejte. Tam, kde Greptile nabízí „Fix with your Agent“, pošle problém — cesty k souborům, čísla řádků, navržený kód — do Claude Code, Codex, Conductor, Cursor nebo Devin. „Fix All“ pošle všechny problémy z revize najednou. Dodávají také Greptile MCP a plugin pro Claude Code pro toto předání. Maguyva na tomto pojmenovaném seznamu cílů není; tato nepřítomnost není problém. Maguyva už svou práci odvedla ve fázi 1. Kódovací agent, který PR napsal, je ten, kdo by měl dostat opravný náklad.

V prvních 2–3 týdnech čekejte šum, zatímco se učicí se systém Greptile přizpůsobuje komentářům, které váš tým skutečně nechává. To je jejich uvedený harmonogram, ne vada dvojice. Lidská revize zůstává ve smyčce. Greptile je automatizovaný první průchod, ne tlačítko sloučení.

Pokud komentář Greptile ukazuje na soubor, který agent ve fázi 1 nikdy nedotázal, je to užitečný signál. Buď mapa přehlédla volajícího, nebo agent vynechal citaci. Opravte koncept podle komentáře. Nevypínejte recenzenta.

Jak udržet toto doplňování se poctivé

Maguyva vždy první. Revize PR se špatným souborem je pořád revize špatného souboru.
Greptile vždy pak. Dobře citovaný koncept přesto potřebuje přečtení diffu na úrovni celého systému.
Nežádejte Maguyva, aby zveřejňovala komentáře k PR. Nedělá to.
Nežádejte Greptile, aby byl první vyhledávací vrstvou agenta, zatímco ještě vybírá cestu. To není práce, na kterou je postavená jejich aplikace GitHub nebo GitLab.
Nevymýšlejte bash pipeline, který je „synchronizuje“. Rozhraním je PR.
Ověřujte obě strany nezávisle. Naindexujte repozitář, který už znáte. Položte jednu otázku, kterou umíte ověřit. Pak otevřete malý PR a přečtěte si, co Greptile skutečně komentuje.

Když tomu dáte jméno, smyčka je obyčejná. Nejdřív mapa. Pak PR agenta. Pak revize. Každý produkt zůstává na té straně pull requestu, ve které je dobrý.

// map first. review second. in that order.

Jak dát AI agentovi kontext velkého repozitáře bez lokálního indexeru

Fri, 14 Aug 2026 00:00:00 GMT

Velký repozitář se nevejde do kontextového okna, a pokud jste někdy namířili indexer z notebooku na skutečný monorepo, víte, že se pohodlně nevejde ani tam — RAM vyletí nahoru, první indexace trvá hodinu a váš agent i tak začíná další relaci hádáním, které soubory jsou důležité.

Běžnou odpovědí je spustit indexer vedle editoru, a pro repozitář, který se pohodlně vejde na jeden stroj, je to dobrá odpověď. Pokud se váš monorepo už rychle indexuje v Cursor a to je jediné místo, kde mapu potřebujete, tento text nemá co dodat — přeskočte ho.

Tento text je o jiném případu — kdy agent potřebuje dotazovatelnou mapu velkého repozitáře a vy k tomu nechcete spouštět lokální indexer.

Kdy je lokální indexer špatný nástroj

Lokální index předpokládá, že kód žije na stroji, který se ho dotazuje, a v měřítku skutečného monorepo se tento předpoklad napíná i uvnitř jednoho editoru. Repozitář je prostě větší, než chcete udržovat „zahřátý“ na notebooku: pracujete v jednom balíčku, zatímco rozsah dopadu leží o tři adresáře dál, a první studená indexace stromu o dvou milionech řádků není něco, co chcete zažít dvakrát — ani na svém stroji, ani na CI runneru, který tento strom nikdy dřív neklonoval. Nebo by měl kolega z týmu umět dotazovat stejnou mapu jako vy, aniž by čekal, až se jeho vlastní stroj prokouše stejným indexem.

Nic z toho není důvod zahodit dobrý indexer editoru. Je to důvod mít navíc hostovanou mapu, kterou kterýkoli z vašich agentů může dotazovat přes MCP.

A problém rozsahu jde hlouběji než „příliš mnoho souborů na vložení“. Na velkém stromu zajímavá otázka téměř nikdy nezní „ukaž mi tenhle soubor“ — zní který soubor, který symbol, kteří volající, které testy. Agent, který začíná výpisem src/ a čtením prvních tří výsledků, s klidem přehlédne handler v apps/api a vygenerovaného klienta v packages/sdk. Potřebujete vyhledávání postavené na celém stromu, pak seřazené, pak citované.

Co skutečně znamená „kontext velkého repozitáře“

Vysypat soubory do promptu není kontext — je to menší, horší kopie stromu. Co váš agent skutečně potřebuje, je klást otázky a dostávat v odpovědi citace: kde je definován tento symbol a kdo ho volá, co závisí na modulu, který se chystám změnit, který testovací soubor pokrývá toto chování a jak strom vypadá teď, ne minulé čtvrtletí.

Tyto odpovědi musí pocházet z indexu postaveného na vašem repozitáři, ne z paměti modelu o cizích repozitářích, a tento index musí žít někde mimo kontextové okno agenta. Pro tento problém by měl žít i někde mimo váš notebook.

Jedna další věc, kterou za vás instrukční soubory nezvládnou: CLAUDE.md a AGENTS.md jsou správné místo pro konvence a chování, ale nejsou to živá, seřazená, dotazovatelná mapa stromu o dvou milionech řádků. Pro chování používejte pravidla; pro fakta používejte inteligenci repozitáře.

Stavíme mapu v cloudu, dotazujeme se z libovolného klienta

Maguyva je vzdálená vrstva kontextu kódové báze přes MCP. Připojíte GitHub, vyberete své repozitáře a můžete odejít, zatímco cloudové pipeline parsují strom, budují symboly a hrany grafu a udržují seřazenou mapu — nikdy bez lokálního indexeru.

Když pushnete kód, změněné soubory se parsují postupně a vrstvy grafu a řazení se přestavují podle harmonogramu: denně u bezplatného plánu, hodinově u placených. Každý snímek má časové razítko, takže váš agent pozná, kterou verzi stromu čte. Poctivým omezením zde je nesynchronizovaná lokální práce — úprava existující jen ve vašem pracovním stromu, nikdy nenapushovaná, ještě není v hostované mapě.

Pak připojíte klienta, kterého už používáte, přidáním API klíče do jeho MCP konfigurace. Existují návody na nastavení pro 24 zdokumentovaných MCP klientů a připojit se může i jakýkoli jiný MCP kompatibilní klient, který podporuje standardní konfiguraci. Pokud je Cursor váš domov, stránka Cursor tou cestou provede; stejný server odpovídá Claude Code, VS Code, Windsurf, Codex CLI a dalším.

Nemusíte měnit editor. Svému agentovi dáváte povrch nástrojů — 11 MCP nástrojů napříč vyhledáváním, symboly, analýzou závislostí, získáváním souborů a kontextem repozitáře — s pokrytím více než 279 jazyků a textových technologií, což na monorepo, který přestal být jednojazyčný před lety, znamená víc, než byste čekali.

Odpovědi se vracejí podložené, jako cesty k souborům s čísly řádků. Sémantické, strukturální, grafové a textové vyhledávání se slévají do seřazených výsledků, takže otázka jako „co závisí na parseConfig“ nedá ani výpis grep, ani jediný sémantický útržek, ale hrst míst, na kterých skutečně záleží.

Konkrétní návod

Nezačínejte indexací celé firmy. Tady je cesta, která funguje:

Vyberte jeden repozitář, který už dobře znáte — balíček, který dokážete posoudit ručně, má větší cenu než největší strom, který máte.
Začněte zdarma: 3 repozitáře, 50 tisíc naindexovaných řádků, všech 11 nástrojů, žádná měsíční kvóta dotazů. Pokud je váš reprezentativní repozitář větší, stránka s cenami uvádí úrovně pracovního prostoru ($0, $19, $49, $149) podle rozsahu indexace — ne podle počtu míst.
Připojte GitHub a počkejte na dokončení první indexace. Nic přitom lokálně nekompilujete.
Připojte MCP klienta — pár řádků konfigurace. Maguyva je vzdálený MCP server, takže žádné pluginy, žádná rozšíření, žádný druhý editor k osvojení.
Položte jednu otázku, kterou umíte ověřit. „Co závisí na parseConfig?“ nebo „Kde se řeší vypršení přihlašovací relace?“ Pak otevřete citované výsledky file.ext:line a porovnejte je se stromem před sebou.
Až poté, co citace tuto konfrontaci přežijí, nechte agenta editovat.

Pokud první repozitář dobře sedí a váš strom je velký, zvětšete pracovní prostor podle svých naindexovaných řádků a frekvence přestavby. Lidé a agenti sdílejí stejný počet uživatelů — Maguyva účtuje za pracovní prostor, ne za místo —, takže přidání třetího agenta do smyčky vás nic nestojí.

Aktivační test je stejný, jaký dokumentace doporučuje pro jakékoli první spuštění: naindexujte repozitář, který už znáte, položte jednu otázku, kterou umíte ověřit. Velký repozitář test nemění; jen dělá špatný první soubor dražším.

Na co dávat pozor po připojení

Sledujte tři věci. Aktuálnost: placené plány se přestavují hodinově, bezplatné denně, a nenapushovaná lokální práce se v mapě neobjeví — to je kompromis, na který přistupujete. Rozsah: indexujte reprezentativní sadu repozitářů, ne každou archivovanou vidličku; bezplatná úroveň je záměrně dimenzovaná tak, abyste zjistili, jestli se odpovědi vyplatí udržovat. A ověřování: mapa velkého repozitáře, která neumí citovat cesty a čísla řádků, je jen pomalejší hádací stroj, takže ať vám agent ukáže místo dřív, než dodá patch.

Pak spusťte stejný test, jaký byste spustili na malém repozitáři. Naindexujte repozitář, který už znáte. Položte jednu otázku, kterou umíte ověřit. Pokud je mapa opravdová, váš agent přestane začínat od studeného stromu.

// no laptop got hot building this map.

Proč váš AI kódovací agent halucinuje cesty k souborům

Fri, 14 Aug 2026 00:00:00 GMT

Poznávacím znamením není špatné tělo funkce. Je to sebejistá úprava souboru, který neexistuje, nebo souboru, který existuje, ale neimplementuje dané chování.

Požádali jste o opravu vypršení relace. Agent otevřel src/auth/session.ts. Ta cesta je věrohodná. Je taky špatná. Skutečný handler žije v apps/api/src/middleware/expiry.ts, přejmenovaném před dvěma refaktoringy. Agent vám nelhal. Doplnil řetězec ve tvaru cesty na základě tréninkových priorů plus toho, co už bylo v kontextovém okně.

Toto je běžný vzorec selhání na skutečném repozitáři. Model umí psát kód. Chyba spočívá ve výběru špatného místa, kam ho napsat.

Proč si agenti vymýšlejí cesty

Kódovací agent je model predikce dalšího tokenu vybavený nástroji. Když řeknete „oprav vypršení relace“, musí nejdřív pojmenovat soubor, než bude moct cokoli číst nebo patchovat. Pokud ještě nemá podloženou mapu, sestaví cestu z:

Konvencí pojmenování, které viděl v jiných repozitářích. src/auth/session.ts je častý tvar.
Souborů už přítomných v konverzaci, které možná jsou ty, co jste vložili minulý týden, ne ty, na kterých teď záleží.
Výpisů adresářů, které náhodou spustil, neúplných na velkém stromu.
Instrukčních souborů. CLAUDE.md a AGENTS.md říkají agentovi, jak se chovat. Nejsou to živý index symbolů, volajících ani aktuálních cest.

Žádný z těchto zdrojů není mapou tohoto repozitáře, dnes. Model vyplňuje mezeru stejným způsobem, jakým vyplňuje jakoukoli mezeru: pokračováním s vysokou pravděpodobností. Toto pokračování často vypadá jako skutečná cesta. Někdy soubor existuje a leží vedle toho správného. Někdy existoval na větvi sloučené minulý měsíc. Někdy nikdy neexistoval.

Grep vás tu nezachrání, pokud agent vůbec nehledá správný řetězec. Agent uhodl cestu, pak přečetl, co ta cesta vrátila, pak ji upravil. Prvním chybným krokem byla cesta, ne patch.

Čtení souborů také není totéž co nalezení těch správných. Claude Code, Cursor, Codex a podobné nástroje dokážou otevřít cokoli, na co je namíříte. Otázka zní, jestli spolehlivě najdou správné soubory, důležité symboly, závislosti, testy a rozsah dopadu dřív, než upravují. Přístup k souborům bez mapy stále začíná hádáním.

Úprava špatného souboru je problém vyhledávání

Berte vymyšlenou cestu jako omyl vyhledávání, ne jako povahovou vadu.

Kdyby agent musel vrátit path/file.ext:line dřív, než by mu bylo dovoleno editovat, staly by se dvě věci. Za prvé byste mohli otevřít citaci a odmítnout práci za deset sekund. Za druhé by se agent musel dotázat něčeho, co strom skutečně zná.

Toto je práce vrstvy kontextu kódové báze. Samotné sémantické vyhledávání nestačí. Útržek, který „zní jako vypršení relace“, může pořád přistát v zastaralém balíčku. Potřebujete taky přesný text, když znáte řetězec, vyhledávání symbolů, když znáte jméno, strukturální vyhledávání, když znáte tvar, a graf závislostí, když potřebujete volající a rozsah dopadu.

Maguyva je tato vrstva pro kódovací agenty kompatibilní s MCP. Není to editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf a další MCP klienti zůstávají tam, kde jsou. Agent se dotazuje seřazené mapy dřív, než se dotkne řádku.

Tvrzení je záměrně skromné: méně halucinovaných úprav. Maguyva modelu neubírá schopnost hádat. Mění výchozí první krok z „vymyslet věrohodnou cestu“ na „vyžádat si seřazená, citovaná místa“.

Jak vypadá podložená odpověď

Užitečná odpověď na otázku „kde se řeší vypršení relace“ není odstavec. Je to krátký seznam míst:

apps/api/src/middleware/expiry.ts:48 - handler
apps/web/src/lib/auth-client.ts:112 - volající
apps/api/tests/expiry.test.ts:20 - test, který selže, pokud je změna špatná

Tyto řádky můžete otevřít. Pokud jsou špatné, zastavíte se. Pokud jsou správné, agent může editovat. Smysl je v ověření, ne v hesle.

Maguyva zpřístupňuje 11 zákaznických MCP nástrojů napříč vyhledáváním, symboly, analýzou závislostí, získáváním souborů, kontextem repozitáře a deterministickými servisními pracovními postupy. Čtyři režimy vyhledávání (sémantický, strukturální, grafový/závislostní a textový) se slévají do seřazených výsledků; vyhledávání symbolů je samostatný MCP nástroj (find_symbol). Podložené odpovědi se vracejí s cestami k souborům a čísly řádků, takže je můžete posuzovat vůči stromu před sebou.

Dokumentace popisuje nejkratší cestu: začít zdarma, naindexovat repozitář, který už znáte, připojit klienta, pak položit jednu otázku, kterou umíte ověřit.

Smyčka, která mění první úpravu

Nepotřebujete novou víru v pracovní postup. Potřebujete jeden krok navíc před prvním zápisem.

Položte otázku, kterou už dokážete posoudit. „Jaký kód řeší přihlášení a vypršení relace“ je lepší než „oprav autentizaci“.
Vyžadujte citace. Cestu k souboru a číslo řádku, ne shrnutí „modulu autentizace“.
Otevřete citované soubory. Sledujte symbol. Potvrďte závislost, které se chystáte dotknout.
Teprve pak nechte agenta patchovat.

Pokud krok 2 nevrátí nic užitečného, agent nemá právo cestu improvizovat. Buď hledá znovu, nebo mu ukážete cestu vy. Přesně tato jediná brána vytváří méně halucinovaných úprav. Model je stejný model. Změnila se mapa.

Instrukční soubory jsou pořád důležité. Zachovejte je. Používejte je pro konvence, revizní pravidla a to, čeho se nedotýkat. Nežádejte je, aby byly indexem. CLAUDE.md, který vyjmenovává tři důležité adresáře, zastará týden po rozdělení balíčku. Dotazovatelná mapa se aktualizuje, když se aktualizuje repozitář.

Příbuzné selhání je téměř správný soubor: agent otevře auth.ts, když chování žije v auth-client.ts, nebo patchuje vygenerovaný soubor místo zdroje, nebo edituje kopii v packages/legacy, protože se shodovalo jméno. Citace tyto chyby nedělají nemožnými. Dělají je viditelnými dřív, než diff přistane.

Co za vás mapa nevyřeší

Buďte střízliví ohledně toho, co dostáváte. Podložená mapa neudělá každou úpravu správnou — váš agent i tak může napsat špatný patch přesně do správného souboru. Pokud se vaše kódová báze opírá o dynamický dispatch, reflexi nebo monkey-patching, některá vyhledávání symbolů se vrátí chudší, než byste chtěli, protože přesně to dělá běhová nepřímost s jakýmkoli statickým indexem. A pokud doufáte v procento — „halucinované cesty snížené o X %“ — tady ho nenajdete, protože nikdo kromě vás nedokáže poctivě naměřit toto číslo pro váš repozitář.

Co můžete čekat, je užší a užitečnější: agent přestane začínat úpravy uhodnutou cestou. Tento první krok se podloží skutečnou mapou a odtud pochází méně halucinovaných úprav. Všechno po citaci — čtení diffu, posouzení patche — je pořád vaše práce, stejně jako vždycky byla.

Tento test vás nestojí skoro nic: naindexujte repozitář, který už znáte, a položte jednu otázku, kterou umíte ověřit. Začněte cestou, na které jste se už spálili. Pokud jsou citace špatné, uvidíte to hned. Pokud jsou správné, další úprava vašeho agenta dostane lepší místo k přistání.

// it doesn't know the file. it knows how to find it.

Proč jsme upgradovali vyhledávání v kódu na voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Čísla benchmarků v tomto příspěvku odrážejí žebříčky RTEB v době zveřejnění (červen 2026). Žebříčky se hýbou; berte pořadí jako momentku, ne trvalý fakt.

Sémantické vyhledávání je jen tak dobré jako embeddingy pod ním.

Když se agent zeptá Maguyvy „kde řešíme retry“, negrepuje slovo „retry“. Ptá se na význam — smyčku s backoffem, vzor circuit breaker, tu věc, která obaluje nespolehlivé volání. Na tuhle otázku odpovídá vektorový model, který promění kód na bod v prostoru a najde sousedy. Vyberte lepší model a každý sémantický dotaz v produktu se tiše zostří.

Tak jsme svůj změnili. Od června 2026 běží embeddingy kódu v Maguyvě na voyage-4-large, který nahrazuje voyage-code-3.

Benchmark

Tohle rozhodnutí jsme neudělali na základě pocitu. Veřejný Retrieval Embedding Benchmark (RTEB) řadí embedding modely podle skutečných retrieval úloh a na svém žebříčku Code sedí voyage-4-large na 1. místě celkově (90,86) — před gemini-embedding-2-preview (90,26) a, což je pozoruhodné, před modelem, který jsme už používali, voyage-code-3 (89,73, 3. místo).

To je malý absolutní rozdíl. Ale je to rozdíl ve správném směru, na veřejném benchmarku, přesně na úloze, na které nám záleží: dohledávat kód podle významu.

Kompromis, který přijímáme: binární kvantizace

Tady je část, kterou většina příspěvků typu „upgradovali jsme náš model“ vynechává.

Maguyva neukládá vektory v plné přesnosti. Ukládáme binárně kvantizované embeddingy: každý 2048-dimenzionální vektor se zkomprimuje na 2048bitovou signaturu — 256 bajtů na vektor. Tyto signatury se prohledávají Hammingovou vzdáleností, indexované a rozdělené na partition podle tenanta.

To je záměrný kompromis. Binární kvantizace obětuje trochu přesnosti retrievalu výměnou za dramaticky menší úložiště a rychlou, levnou matematiku vzdálenosti bez nutnosti provozovat samostatnou vektorovou databázi. Pro produkt, který indexuje celé repozitáře na jeden pracovní prostor, na téhle ekonomice záleží víc než na vymáčknutí posledního zlomku bodu z benchmarku.

voyage-4-large do tohoto designu zapadá, aniž by si vynutil migraci vrstvy úložiště: produkuje 2048-dimenzionální výstup, stejně jako voyage-code-3, takže se naše sloupce bit(2048) a cesta Hammingova vyhledávání nezměnily. Model se zlepšil; schéma zůstalo na místě.

Kód byl jen začátek

Maguyva je nástroj pro inteligenci nad kódem. Ale jsme také svým vlastním prvním zákazníkem a míříme s ní i na něco jiného: na markdown, který v našich repozitářích žije vedle kódu. Záznamy architektonických rozhodnutí, runbooky, smlouvy, finanční a policy dokumenty — všechno verzované v Gitu, všechno za stejným MCP serverem, sémantický index nad dokumenty, ne jen nad zdrojovým kódem.

Přesně proto na šíři voyage-4-large záleží. Na stejné rodině žebříčků RTEB je 1. na financích, 1. ve zdravotnictví a 1. na celkovém textovém retrievalu — před Gemini Embedding od Googlu, Embed v4 od Cohere a text-embedding-3-large od OpenAI. (Voyage je spoluautorem RTEB, takže to čteme jako silný veřejný signál, ne jako dokonale neutrálního rozhodčího — ale je přímo srovnávaný v benchmarku proti každému velkému komerčnímu modelu na privátních hold-out sadách.) Stejný index, který agentovi najde správnou funkci, najde i správnou klauzuli ve smlouvě nebo správný řádek v policy dokumentu — a v těchto doménách voyage-4-large není kompromis, je to lídr.

Proč platíme za prémiové embeddingy

Existuje levnější způsob, jak dělat vyhledávání, a velká část je zdarma. Lexikální vyhledávání — BM25 a jeho příbuzní — porovnává klíčová slova, běží lokálně a nic nestojí. Open-source embedding modely jako BGE, Nomic a embeddinggemma dávají opravdu slušný sémantický retrieval a můžete si je hostovat sami za cenu GPU. Maguyva používá i tu bezplatnou stranu: každý dotaz fúzuje textové, AST, grafové a sémantické vyhledávání. Na čem nešetříme, je sémantická vrstva.

Za prémiové embeddingy — voyage-4-large — platíme za token místo toho, abychom si sami hostovali bezplatný model, ze dvou důvodů. Za prvé, samotné vyhledávání podle klíčových slov nedokáže odpovědět na „kde řešíme retry“, když kód říká backoff a circuit breaker a nikdy neřekne slovo „retry“ — význam je celý smysl embeddingu a v doménách, které obsluhujeme, otevřené modely za prémiovými zaostávají: pár bodů pozadu na obecném textu a ještě víc pozadu v nikách jako kód, smlouvy a finance. Za druhé, podle naší zkušenosti kvalita retrievalu tvaruje finální odpověď víc než model na druhém konci — silný agent, kterému dáte špatný kontext, pořád odpoví špatně, a nikdy neuvidí dokument, který nikdy nedostal.

Prémiové embeddingy jsou tedy účet za token, který roste s každým repozitářem a dokumentem, který indexujeme — a platíme ho záměrně. Pro výsledek, který naši uživatelé dostanou, správnou funkci nebo správnou klauzuli, si myslíme, že ten kompromis stojí za to.

Upřímná část

Vlastní dokumentace Voyage pořád označuje voyage-code-3 jako model optimalizovaný pro kód. Tak proč přejít?

Protože jsme si přečetli veřejný benchmark, ne jen tabulku modelů dodavatele, a benchmark postavil na první místo pro retrieval kódu voyage-4-large. Bylo to rozhodnutí s výhledem dopředu: vzít novější, obecně silnější model a ověřit ho proti veřejnému žebříčku na úlohách, na kterých záleží. Cítíme se s touhle sázkou dobře, protože důkazy jsou široké — voyage-4-large nevyhrává jen na kódu, vede i na financích, zdravotnictví a celkovém retrievalu.

Nenápadný základ

Každý nástroj, který vystavujeme — sémantické vyhledávání, sběr task-context, ukotvené odpovídání na otázky — v základu stojí na kvalitě vyhledávání. Když se retriever zlepší, agent na druhém konci dostane lepší důkazy, udělá méně špatných odboček a ukotví své odpovědi ve správném kódu — nebo ve správné klauzuli, nebo ve správném policy dokumentu. Ostřejší embedding model není okázalá funkce. Je to základ všeho ostatního a ten jsme právě zlepšili. Nevšimnete si toho. To je ten záměr.

Jazykové rekurzivní sebezlepšování: brousíme code intelligence napříč ~280 jazyky

Tue, 26 May 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (květen 2026). Aktuální čísla najdete na naší stránce týmu.

Maguyva extrahuje symboly, reference a graf závislostí ze zdrojového kódu zhruba v 280 jazycích. Každý jazyk má vlastní tree-sitter handler — dotazy, heuristiky, hraniční případy — a každý handler může být po svém jemně špatně. Volání metody vyexportované jako čtení. Funkce přiřazená ke špatnému obklopujícímu scope. Vztah, který tam prostě není.

To se nedá ručně zaauditovat. Žádný tým nepřečte výstup extrakce napříč 280 gramatikami a nenajde ty špatné hrany. Zajímavá otázka tedy není „je naše extrakce správná“, ale „jak zjistíte, že je špatná, v této šíři, bez člověka v každé smyčce“. Naše odpověď je jazykové rekurzivní sebezlepšování: kvalitativní smyčka poháněná jazykovými agenty, LLM v roli rozhodčího a jedno pravidlo, které se pořád znovu učíme: zelená není totéž co správná.

Zelená není správná

Každý jazyk má sadu fixtures a release gate ho boduje napříč pěti dimenzemi — přesnost, strukturální integrita, úplnost, kvalita a výkon. Jazyk dostane ZELENOU jen tehdy, když na svých fixtures dosáhne precision ≥ 0,95, recall ≥ 0,99 a F1 ≥ 0,97, s alespoň 20 očekávanými hranami pro statistickou důvěru. Pod tím je ŽLUTÁ nebo ČERVENÁ, a nejde do provozu.

Tahle brána je nutná, ale ne dostatečná. Fixtures validují proti fixtures, které jsme sami napsali. Zakódovali jsme do nich případy, na které jsme už mysleli. Handler může být na svých fixtures bezchybný a přesto zpackat vzorec, který se objeví jen ve skutečném kódu — makro idiom, generická metoda, jazyková vlastnost, pro kterou nikdo fixture nenapsal. ZELENÁ znamená, že fixtures projdou. Neznamená to, že se skutečný repozitář extrahuje čistě. Smyčka proto musí opustit fixtures a podívat se do divočiny.

Vnitřní smyčka: namátková kontrola, rozhodčí, oprava, důkaz

Jádro smyčky běží vždy pro jeden jazyk:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Několik věcí zajišťuje, že tohle funguje, a ne jen mele naprázdno.

Rozhodčí je agent, ne API volání. Když říkáme „LLM jako rozhodčí“, myslíme tím, že samotný jazykový agent čte každou vzorkovanou hranu proti skutečnému zdroji a klasifikuje ji podle pevné hodnoticí metodiky s pěti kategoriemi: je tahle hrana správná, false positive, správný vztah se špatným typem, připojená ke špatnému scope, nebo nese špatná metadata? Tato metodika je klíčová — „23% chybovost“ nic neznamená, dokud nevíte, jestli jde o skutečné defekty, nebo o rozhodčího, který se spletl v počítání.

Oprav jednu věc, pak to dokaž. Každá iterace mění přesně jeden editovatelný asset, pak se znovu spustí proti pevnému harnessu a změnu si ponechá jen tehdy, pokud se zlepší F1 a překlasifikace vypadá lépe. Pokud ne, vrátí se zpět. Žádná dávka spekulativních úprav, žádné „mělo by být lepší“. Změna si své místo buď vydělá, nebo zmizí. A když se oprava chytí, povýší se do sady fixtures — takže chyba, kterou opravila, se už tiše nemůže vrátit. Tenhle krok povýšení je to, co dělá smyčku rekurzivní, a ne jen opakovanou: každý průchod zpevňuje orákulum, proti kterému validuje ten další.

Ponaučení, které se pořád znovu učíme: metriky nadhodnocují

Tady je past, do které jsme spadli po hlavě. Sekundární metriky korpusu — jak často má extrahovaný cíl nedořešitelný symbol, kolik symbolů vypadá „osiřele“ a tak dále — masivně nadhodnocují problémy. Jsou to většinou artefakty paradigmatu, ne bugy.

Nejčistší příklad: llvm jednou ukázal 73% míru „zdroj-bez-symbolu“ a byl označen za katastrofální. Ponořili jsme se do toho. Skutečná přesnost byla 98,5 %. „Chybějící symboly“ byly téměř všechny legitimní externí reference — volání do standardní knihovny, do frameworků, do kódu, který žije mimo repozitář. Metrika měřila vlastnost jazyka, ne defekt handleru. Jazyky jako Zig, COBOL a Odin ukazují 65–70% míru „osiřelosti“ a jsou přitom úplně v pořádku; COBOL neměl žádné skutečné chyby.

Kdybychom nechali tahle čísla řídit práci, strávili bychom týdny „opravováním“ handlerů, které už byly správné, a ignorovali bychom jazyky s tichými, skutečnými chybami. Závěr je nekompromisní: agregátní metriky jsou v nejlepším případě hrubý třídicí signál. Skutečný signál kvality je namátková kontrola s klasifikací hran — dívat se na skutečné hrany ve skutečných repozitářích a posuzovat je jednu po druhé. Data před intuicí, ale jen ve chvíli, kdy víte, která data mluví pravdu.

Vnější smyčka: flotila, ne maraton

Zpracovávat všech 280 jazyků jeden po druhém by trvalo věčnost, takže je vnitřní smyčka zabalená do vnější, která zpracovává mnoho jazyků paralelně.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Každý agent pracuje v jednorázovém pracovním stromě, takže si nemůžou šlapat na paty. Orchestrátor integruje jejich opravy jednu po druhé, každou za kontrolou regrese na celém manifestu: změna, která pomůže svému vlastnímu jazyku, ale tiše rozbije tři další, neprojde. Integrace je hlídaná bránou a potvrzená ještě předtím, než se cokoli pushne — regresní brána rozhoduje, co je bezpečné; o tom, co se odešle, pořád rozhoduje člověk. Pak se fronta protočí na další sadu jazyků a celé se to opakuje.

Co je pořád nedokonalé

Rozhodčí se může mýlit a ta mýlka má směr: agent běžící s příliš malým kontextem nadhodnocuje. V jedné dávce bylo osm jazyků označeno chybovostí 5–20 %; po prozkoumání byla skutečná chyba specifická pro jazyk jen jedna — zbytek byly chyby rozhodčího z toho, že mu unikla vlastní sémantika daného jazyka (jeden zdrojový řádek legitimně produkuje několik hran, vazby parametrů modelované jako přiřazení, jazyky typu reference-per-identifier). Proto vzorkujeme se dvěma seedy a křížově kontrolujeme, a proto se neshoda mezi rozhodčím a fixtures bere jako nejzajímavější signál, ne jako uzavřený verdikt — někdy je to fixture, co je špatně.

Jsme také upřímní ohledně cíle. Cílem je nula skutečných chyb, tečka — ale „nula“ je směr, ke kterému se brousíme jazyk po jazyku, ne políčko, které jednou zaškrtnete. Vždycky existuje další repozitář s dalším idiomem.

Vydobyté, ne tvrzené

Všechno, co Maguyva pro agenta dělá — najít symbol, sledovat závislost, odpovědět na otázku s citovaným kódem — stojí na tom, že podkladová extrakce je správná. Napříč 280 jazyky se „správnost“ nedá jen tvrdit; musí se soustavně vydobýt proti skutečnému kódu. Smyčka je způsob, jak si ji vydobýváme: autonomní cyklus namátkové kontroly a opravy, který ke svým vlastním metrikám přistupuje s podezřením, každou změnu dokazuje a každou opravu mění na strážce proti příští regresi. Není to okázalé. Je to práce, díky které můžeme říct „podporujeme váš jazyk“ a myslet to vážně. Zelená je snadná. Správná se vydobývá.

Multi-modální fúzní vyhledávání: pro každý dotaz ten správný retriever

Wed, 15 Apr 2026 00:00:00 GMT

Poznámka k historickému návrhu: tento článek z dubna 2026 popisuje tehdejší návrh směrování, nikoli současné výchozí chování. Níže uvedená zářijová oprava se týká pouze tvrzení o měření. Aktuální směrování, předvolby a explicitní nastavení modalit najdete na stránce Jak to funguje.

Vyhledávací dotazy mají různé potřeby.

„kde je definovaný parseConfig“ chce přesný symbol — jedno přesné místo, rychle. „jak funguje autentizace“ chce význam — rozptýlený související kód, který vysvětluje koncept. „co se rozbije, když změním tuhle funkci“ chce graf závislostí. „najdi řetězec ECONNREFUSED“ chce doslovnou shodu, nic chytrého.

Grep je výborný na doslovné shody a užitečný při některých pátráních po referencích, ale není to graf závislostí a nerozumí významu. Embeddingy pokrývají sémantickou stránku, ale jsou špatný nástroj na přesné řetězce a analýzu dopadu. Většina nástrojů pro vyhledávání v kódu si vybere jeden engine a nechá s tou volbou žít každý dotaz. Maguyva se neomezuje na jeden engine. Zjistí, jaký typ otázky jste položili, a pak smísí čtyři retrievery v poměru, jaký si daná otázka zaslouží.

Čtyři modality

Pod kapotou existují čtyři nezávislé způsoby, jak najít kód:

sémantický — vektorové vyhledávání nad binárními Voyage embeddingy; hledá kód podle významu.
textový — trigramová shoda; hledá literály, chybové řetězce, přesné identifikátory.
strukturální — dotazy AST; hledá definice, signatury a jazykové konstrukce.
grafový — graf závislostí; hledá volající, volané a rozsah dopadu.

Každý je silný na jiné třídě otázek. Trik je rozhodnout, nakolik každému z nich věřit pro dotaz, který máte před sebou.

Klasifikace záměru

Než proběhne jakékoliv vyhledávání, odlehčený klasifikátor zařadí dotaz do jednoho ze šesti záměrů, s mírou jistoty. Je záměrně levný — seřazené heuristiky, vyhrává první shoda — protože běží na hot path a přidává jen milisekundu nebo dvě:

začíná na def , class , func , import … → find_definition (jistota 0,95)
„who calls“, „usages of“, „references to“ (kdo volá, použití, odkazy na) → find_references (0,90)
„impact“, „blast radius“, „what depends on“ (dopad, rozsah dopadu, co na tom závisí) → impact_analysis (0,90)
"string" v uvozovkách nebo chybový token jako traceback → exact_match (0,85–0,90)
identifikátor ve tvaru CamelCase nebo snake_case → find_definition (0,60–0,80)
„how“, „why“, „explain“, „architecture“ (jak, proč, vysvětli, architektura) → understand_code (0,75)
nic nesedí → understand_code, nízká jistota (0,40)

Každý záměr nese profil vah napříč čtyřmi modalitami. Toto jsou skutečná čísla:

Záměr	sémantický	textový	strukturální (AST)	grafový
find_definition	0,2	0,1	0,6	0,1
find_references	0,1	0,2	0,2	0,5
understand_code	0,5	0,2	0,2	0,1
find_similar	0,4	0,3	0,2	0,1
impact_analysis	0,1	0,1	0,1	0,7
exact_match	0,0	0,9	0,1	0,0

Takže „kde je definovaný parseConfig“ se výrazně opírá o AST (0,6). „jak funguje autentizace“ se opírá o sémantické vektory (0,5). „co na tomhle závisí“ je skoro celé grafové (0,7). „najdi ECONNREFUSED“ je skoro celé trigramové (0,9), embedding model je úplně vypnutý — protože sémantická podobnost je přesně ten špatný nástroj na přesný řetězec.

Rychlá cesta a fúzovaná cesta

Když si je klasifikátor jistý — skóre ≥ 0,85 — a dotaz je běžný, Maguyva fúzi úplně přeskočí a routuje přímo na jednu dominantní modalitu. „kde je definované X“ nepotřebuje čtyři retrievery; potřebuje AST index, hned. Tahle přímá cesta se hlásí zpátky jako fusion_strategy: "direct".

Všechno nejednoznačné prochází fúzí. Čtyři (nebo tři, na výchozím presetu) modality běží paralelně, každá vrací svůj vlastní seřazený seznam, a my je kombinujeme.

Vážená Reciprocal Rank Fusion

Fúzovat heterogenní retrievery je těžší, než to zní: kosinová podobnost 0,82, trigramové skóre 137 a grafová centralita 0,004 nejsou na stejné škále, takže je nemůžete jen sečíst. Reciprocal Rank Fusion tenhle problém obchází tím, že zahodí syrová skóre a ponechá si jen pořadí, které danému výsledku přidělil každý engine. Příspěvek výsledku z jedné modality je:

contribution = weight × 1 / (k + rank + 1)

kde rank je jeho pozice v seznamu dané modality a k je vyhlazovací konstanta. Příspěvky se sčítají napříč modalitami pro každý výsledek, který našel víc než jeden engine — výsledky, na kterých se retrievery shodnou, přirozeně postoupí výš. Používáme k = 40 na výchozím presetu a 60 na thorough (quick běží čistě sémanticky, takže se tam fúze nikdy nezapojí). Původní práce o RRF přistála na k = 60 pro obecné vyhledávání; naše výchozí nastavení o něco více zvýhodňuje přední pozice, což dává shodě mezi modalitami na nejvyšších pozicích trochu větší váhu — a nedoporučujeme to ručně dolaďovat.

Nad tím vším výsledky nesou ještě boost za grafovou důležitost. Hub — funkce, o kterou se opírá celá kódová základna — by měla předstihnout málo známý listový uzel i při stejné textové relevanci, takže každý příspěvek násobíme:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Centralita pochází z předpočítaných metrik PageRank/stupně z pipeline a boost je oříznutý na 1,5×, aby populární funkce úplně nepohřbila relevantnější, ale obskurnější výsledek. Nakonec degradujeme výsledky z cest vendor, build a archive a deduplikujeme na nejlepší chunk na soubor.

Co je pořád nedokonalé

Klasifikátor záměru je sada regulárních výrazů, nikoli naučený model. Běžné podoby dotazů zpracovává pomocí heuristik a nejednoznačný dotaz přechází na understand_code a směs upřednostňující sémantiku. Starší verze tohoto článku popisovala pokles podílu dotazů bez výsledků z přibližně 15 % pod 5 % jako dosažený. Návrh z prosince 2025 však ve skutečnosti uváděl odhad výchozí hodnoty a cíl; podpůrná sada dotazů ani záznam měření nejsou k dispozici. Tvrzení o dosaženém zlepšení stahujeme; viz zdrojové důkazy a oprava. Klasifikátor jsme nenahradili trénovaným modelem, protože levná verze je rychlá a pro zamýšlené směrování dostatečná, a protože chybný, ale sebejistý klasifikátor je horší než otevřený návrat k výchozí variantě. Samotné váhy jsou ručně zvolené předpoklady, nikoli hodnoty naučené z údajů o kliknutí, které nesbíráme.

Položte otázku, výběr nástroje nechte systému

Agent by neměl muset vědět, jestli sáhnout po grepu, embeddingech, nebo grafu volání — měl by položit svou otázku prostými slovy a dostat správnou odpověď. Multi-modální fúze je to, co umožňuje find_symbol, sémantickému vyhledávání a analýze závislostí sedět za jedním dotazovacím rozhraním: systém přečte tvar otázky a tiše sestaví ten správný retriever. Na modelu, který embeddingy skóruje, záleží, ale záleží i na tom, kdy je nepoužít. Vybrat pro každý dotaz správný nástroj je svůj vlastní druh kvality, a raději ho vlastníme sami, než abychom ho přehazovali na volajícího.

// you bring the question. it brings the tools.

Observabilita agentů: hooks, Alloy a Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agentní systémy selhávají podivnými způsoby.

Někdy je problém v modelu. Někdy v nástroji. Někdy je váš MCP server v pořádku, ale agent si zvolil špatného specialistu, nebo strávil polovinu session prací v shellu, kterou jste nečekali, nebo potichu zvyšoval náklady ve smyčce, která zvenčí vypadala produktivně.

Pokud ten rozdíl nevidíte, agentní systém ve skutečnosti neprovozujete. Jen hádáte.

Postavili jsme si tedy observabilitu pro náš vlastní workflow: Claude Code, Codex, hook eventy Claude, notify eventy Codexu, nativní OpenTelemetry, Grafana Alloy a na druhé straně Grafana Cloud.

Zajímavá část není „udělali jsme dashboard“. Zajímavá je skutečnost, že jsme museli telemetrii rozdělit do dvou různých proudů, protože žádný jednotlivý feed nám nedal celý obrázek.

Problém: telemetrie agentů je roztříštěná

Moderní kódovací agenti už nějakou telemetrii vysílají. To pomáhá, ale nestačí to.

Nativní OTEL umí dobře odpovídat na otázky typu:

Kolik požadavků jsme provedli?
Kolik stála daná session?
Kde jsou spany a trace?
Vyskočila latence?

Mnohem hůř odpovídá na otázky jako:

Na který MCP server se agent spoléhal nejvíc?
Selhalo to v Bash, ve vestavěném nástroji pro práci se soubory, nebo ve volání MCP?
Který skill se skutečně aktivoval?
Jaký typ subagenta byl vyslán?
Dělala session užitečnou práci, nebo se jen bezcílně motala?

Ta druhá skupina otázek stojí blíž hookům než trace.

Platí ale i opak: některé z nejdůležitějších výkonnostních otázek stojí blíž trace než hookům.

Pokud chcete vědět, kde se latence skutečně nakumulovala, které spany byly pomalé, nebo jestli session propálila čas ve voláních modelu, nebo v provádění nástrojů, potřebujete kromě sémantických eventů i data z trace.

Architektura, u které jsme skončili

Provozujeme dvě telemetrické cesty vedle sebe.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Toto rozdělení je záměrné.

Je také asymetrické. Claude Code nám dává mnohem bohatší rozhraní hooků životního cyklu. Codex nám dává nativní OTEL plus notify rozhraní, takže méně podrobné události dokončení tahu normalizujeme do stejného schématu logů, místo abychom předstírali, že oba runtime nabízejí stejné kontrolní prvky.

Nativní OTEL nám dává základní proud: logy a trace ze samotného runtime, plus metriky tam, kde je runtime skutečně vysílá.

Hook a notify eventy nám dávají sémantickou vrstvu: věci jako PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated a klasifikovaná metadata, na kterých nám při ladění chování agentů skutečně záleží. Claude Code sem přispívá bohatším proudem eventů. Codex přispívá tenčím, ale pořád užitečným normalizovaným proudem.

Proč hooky vůbec existují

Naše hook pipeline eventy obohacuje ještě předtím, než dorazí do Loki.

Místo pouhého „nástroj proběhl“ klasifikujeme event do polí jako:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: který MCP backend volání zpracoval
bash_cli: rodina shellového příkazu
subagent_type: jaký typ specialisty byl vyslán
agent_tool: jestli zdroj byl Claude Code, nebo Codex

To znamená, že si můžeme klást otázky, na kterých provozně záleží:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

To nejsou okrasná pole. Právě v nich spočívá rozdíl mezi „agent připadal pomalý“ a „agent strávil posledních deset minut intenzivní prací s operacemi gitu v shellu s vysokou mírou selhání nástrojů“.

Jeden implementační detail, který vypadá podivněji, než ve skutečnosti je: sdílený proud Loki pořád používá service_name="claude-code-hooks" jako label, i když event pochází z Codexu. Skutečné rozdělení mezi runtimy probíhá na agent_tool.

Proč je Alloy uprostřed

Grafana Alloy v tomto nastavení není jen forwarder. Je to místo, kde se uplatňují pravidla pro telemetrii.

Nativní OTEL proud z Claude Code a Codexu míříme na lokální Alloy proxy na localhost:4318 a necháme Alloy payload vyčistit, než ho přepošle do Grafana Cloud.

Na tom záleží proto, že syrová telemetrie agentů je plná polí s vysokou kardinalitou, která jsou užitečná pro analýzu, ale hrozná jako indexované labely:

session_id
prompt_id
počty tokenů
doby trvání
blob s parametry nástrojů

Pokud indexujete všechno, dostanete explozi labelů a špatný den.

Alloy pro nás tedy dělá tři věci:

Udržuje indexovanou jen velmi malou sadu labelů s nízkou kardinalitou.
Přesouvá hlučná, ale užitečná pole do strukturovaných metadat.
Úplně zahazuje čistý šum.

Ta důležitá myšlenka je jednoduchá: pozoruj víc, indexuj méně.

Proč hookový proud obchází Alloy

Hookový proud je už tvarovaný pro Loki.

V okamžiku, kdy send_event.py odešle event, jsme už rozhodli, která pole si zaslouží zacházení jako label a která patří do strukturovaného JSON těla. Tento proud jde přímo do OTLP brány Grafana Cloud, místo aby procházel ještě jednou přes Alloy.

Systém tak má jasné rozdělení práce:

Alloy krotí syrový nativní OTEL proud.
Obohacení hooky dělá sémantické eventy dotazovatelnými.

Díky tomu je architektura jednodušší, než kdybychom se snažili prohnat všechno jednou cestou.

Co dashboard skutečně ukazuje

Snímek obrazovky níže pochází z jednoho z observability dashboardů za naším agentním workflow. Není to benchmark a čísla jsou jen výřez v jednom okamžiku. Jde o tvar dat: activity feed, volání nástrojů, selhání, prompty a členění podle agenta, vestavěných nástrojů, použití MCP, shellových příkazů a skillů.

Užitečné je, že tento dashboard žije na stejném Grafana stacku jako zbytek agentní telemetrie. Můžeme filtrovat podle zdrojového agenta a rodiny nástrojů a dívat se napříč runtimy, aniž bychom si pro každý systém vymýšleli jiný příběh observability.

Jeden z živých dashboardů za naším agentním workflow. Tento snímek je jen jeden výřez ze sdíleného Grafana stacku, který přijímá telemetrii i z našich dalších agentních runtimů a systémů. Klikněte na obrázek pro verzi v plném rozlišení.

Proč na trace záleží víc, než se na první pohled zdá

Logy nám říkají, jaká kategorie práce proběhla. Trace nám říkají, jak se práce v čase odvíjela.

Na tomto rozdílu v agentních systémech záleží, protože „pomalé“ je příliš tupý pojem na to, aby byl užitečný.

Trace nám dokáže říct, jestli bolest pramenila z:

latence modelu
doby provádění nástrojů
opakovaných pokusů
jedné obzvlášť nákladné interakce s MCP
dlouhého ocasu drobných operací, které samostatně vypadaly neškodně

V praxi používáme hookový proud a trace v Tempo společně.

Hook logy odpovídají na: jaký typ události nastal?
Trace odpovídají na: kam šel čas?

Ta kombinace je to, co promění observabilitu z dashboardu ve vysvětlení.

Kam zapadá Codex

Codex je součástí stejného stacku, ale není totožný s Claude Code.

Pro Codex zapojujeme dvě části:

Nativní OTEL z Codexu do Alloy
Notify webhook do codex_notify.py, který mapuje dokončení tahů do stejného schématu Loki, jaké používáme pro hook eventy

To nám dává jednotný filtr jako agent_tool="codex-cli" v rámci stejného proudu logů.

Poctivá výhrada: notify payload Codexu je v současnosti tenčí než hookový payload Claude Code, protože nejde o stejný typ integračního rozhraní. V našem dnešním nastavení se dokončení tahů Codexu dají normalizovat do sdíleného schématu, ale bohatá extrakce nástroj po nástroji je pořád lepší v nativním OTEL proudu než v notify mostu.

To není důvod se tomuto příspěvku vyhýbat. Je to jeho smysl. Skutečné observability systémy se sestavují z nedokonalých signálů.

Grafana přes MCP mění hru

Větší posun je v tom, že Grafana není jen místo, kam lidé chodí přes prohlížeč.

V tomto repozitáři vystavujeme Grafanu i přes MCP. To znamená, že agent umí dotazovat Loki, Prometheus a Tempo přímo, místo aby čekal, až člověk nejdřív ručně prohlédne dashboardy.

To mění observabilitu v aktivní vstup do workflow.

Agent se může zeptat:

Které rodiny nástrojů selhávaly nejvíc za poslední hodinu?
Který MCP server v session dominoval?
Snížily nedávné změny počet selhání nástrojů, nebo jen přesunuly práci do cest náročnějších na shell se stejnými chybami?
Které trace ukazují nejvyšší latenci nebo opakované pokusy?

Jakmile tohle máte, jste velmi blízko smyčce sebezlepšování.

Od dashboardu ke zpětnovazební smyčce

Toto je část, kterou považujeme za nejzajímavější.

Jakmile je observability stack dotazovatelný z vrstvy agenta, telemetrie přestává být pasivní reportovací plochou a stává se řídicím signálem.

Smyčka vypadá takto:

Aktivita agenta vysílá trace, metriky a obohacené hook logy.
Grafana ukládá důkazy do Loki, Tempo a Prometheus tam, kde metriky existují.
Agenti se na tyto důkazy dotazují přes Grafana MCP.
Systém identifikuje špatný mix nástrojů, křehké skilly, slabé směrování nebo workflow náročné na shell, které pořád produkují chyby, jimž se dalo vyhnout.
Agenti nebo operátoři upravují prompty, konfigurace agentů, popisy skillů, pravidla směrování nebo přístup k nástrojům.
Další session vyprodukuje nový tvar telemetrie a cyklus se opakuje.

Takhle se posunete od „zajímavého dashboardu“ k „měřitelnému systému zlepšování“.

Cílem není maximalizovat jednu kategorii nástrojů. Cílem je najít správný mix CLI, vestavěných nástrojů, volání MCP a skillů pro práci, která se skutečně dělá.

Co nám to umožňuje zodpovědět

Jakmile oba runtime přistanou ve stejném Grafana stacku, umíme mnohem rychleji odpovídat na provozní otázky:

Jsou selhání koncentrovaná v jedné rodině nástrojů?
Vytvářejí workflow náročné na shell chyby, kterým by se šlo vyhnout tam, kde by měl existovat nástroj vyšší úrovně?
Které MCP servery nesou většinu zátěže?
Platíme za aktivitu agenta, která neprodukuje smysluplný pokrok?
Je session nezdravá kvůli modelu, nástrojům, nebo orchestrační vrstvě?

To je obzvlášť užitečné ve víceagentních workflow, kde vám „agent byl zaneprázdněný“ neřekne skoro nic.

Pokud je jeden specialista pořád vysílán a produkuje vysokou míru selhání, jde o problém směrování nebo formulace promptu.

Pokud jeden MCP server dominuje všem voláním, může to být dobrá architektura, nebo signál, že všechno ostatní je mrtvá váha.

Pokud selhání nástrojů rostou, zatímco náklady zůstávají vysoké, máte provozní problém, ne problém kvality.

Pokud práce v shellu pořád selhává předvídatelně a vyhnutelně tam, kde by měl existovat nástroj vyšší úrovně, jde o produktový signál.

Pokud se jeden skill neustále aktivuje, ale výsledky nezlepšuje, jde o signál k promptu nebo směrování.

Skutečné ponaučení

Hlubší ponaučení je, že observabilita agentů potřebuje jak telemetrii runtime, tak telemetrii workflow.

Telemetrie runtime vám řekne, co systém udělal.

Telemetrie workflow vám řekne, co si agent myslel, že dělá.

Potřebujeme obojí.

Pokud si necháváte jen trace a čítače, přijdete o sémantickou vrstvu. Pokud si necháváte jen hook eventy, přijdete o latenci, spany a širší obrázek runtime.

A pokud si necháváte obojí, ale nikdy je nezapojíte zpět do vrstvy agenta, máte monitoring, ne adaptaci.

Kombinace je to, co dělá systém dostatečně vysvětlitelným na provoz a dostatečně laditelným na zlepšování.

Co je pořád nedokonalé

Pořád tu jsou hrubé hrany.

Ne každý hook event obsahuje data o délce trvání a tokenech, jaká bychom chtěli.
Některé z nejlepších pohledů na časování pořád pocházejí z Tempo trace, ne z hook logů.
Codex je dnes v obohaceném proudu eventů sémanticky chudší než Claude Code.
Snímek dashboardu je živý provozní povrch, ne vypulírovaný marketingový artefakt.

Tenhle poslední bod je záměrný. Radši ukážeme skutečný přístrojový panel, než abychom předstírali, že agentní systémy se magicky vysvětlují samy.

Proč na tom u Maguyva záleží

Maguyva má agentům dávat lepší inteligenci nad kódem. Ale jakmile agenti skutečně dělají užitečnou práci, okamžitě se objeví nový požadavek: potřebujete vidět, jak se chovají.

Kvalita vyhledávání, kvalita směrování, výběr nástrojů a efektivita kontextu se všechny stávají oblastmi, které lze sledovat.

Proto si myslíme, že o tom stojí za to psát. Budoucí agentní stack nejsou jen prompty a nástroje. Jsou to prompty, nástroje a instrumentační vrstva, která vám řekne, jestli to celé funguje.

Pokud stavíte seriózní agentní workflow, observabilita není volitelná infrastruktura. Je součástí produktu.

Mining smyčky: jak se ze změn stává institucionální paměť

Tue, 03 Feb 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (únor 2026). Aktuální čísla najdete na naší stránce týmu.

Každý inženýrský tým čelí stejné výzvě: změny se dějí neustále, ale důvody těchto změn se ztrácejí. O půl roku později se někdo zeptá „proč jsme pro pipeline stages přešli na DuckDB?“ a odpověď žije jen v hlavě toho, kdo to rozhodnutí udělal — pokud je ještě poblíž.

Postavili jsme mining workflow, který tuhle smyčku uzavírá. Změny proudí přes git commity, zpracuje je naše mining pipeline, promění se na strukturované záznamy changelogu a architektonická rozhodnutí a pak se vrátí zpátky do našich AI agentů přes CLI dotazy. Výsledek: institucionální paměť, ke které mají přístup lidé i AI.

Problém: rozhodnutí se vypařují

Zvažte typický scénář. Vývojář commitne:

feat(canonical): add DuckDB runtime for pipeline stages

Tenhle commit představuje významnou architektonickou volbu. Tým vyhodnotil možnosti, zvážil kompromisy a rozhodl se pro DuckDB z konkrétních důvodů. Ale celý ten kontext žije v:

Vlákně na Slacku (pravděpodobně smazaném)
Něčí paměti (rozhodně blednoucí)
Komentáři v kódu (možná, pokud máte štěstí)

O tři měsíce později se nový člen týmu zeptá: „Mám pro tenhle nový stage použít DuckDB, nebo SQLite?“ Bez institucionální paměti buď znovu vynalézají kolo, nebo dělají nekonzistentní rozhodnutí.

Smyčka: od commitů ke kontextu

Náš mining workflow proměňuje historii gitu na dotazovatelné znalosti:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Klíčový postřeh: changelogy i architektonická rozhodnutí plynou ze stejné historie gitu, zpracované jednotnou pipeline. Díky tomu nic nezapadne.

Jak mining funguje

Krok 1: Synchronizace indexu

uv run orkestra mine sync

Tenhle příkaz proskenuje historii gitu a postaví index všech commitů. Z každého commitu extrahuje strukturované signály:

Typ konvenčního commitu (feat, fix, chore, docs)
Scope (který balíček nebo oblast)
Značky breaking change
Dotčené soubory a metriky složitosti

Krok 2: Kontrola stavu pokrytí

uv run orkestra mine status

Takhle vypadá náš aktuální stav:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15 637 zpracovaných commitů. 476 se stalo architektonickými rozhodnutími. 6 799 se stalo záznamy changelogu. Každý commit je klasifikovaný.

Krok 3: Získání kandidátů k review

uv run orkestra mine candidates --limit 50 --full

Tím se zobrazí commity, které ještě nebyly zpracované, s plným kontextem pro klasifikaci:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Signály pomáhají vést klasifikaci: is_releasable_type: true naznačuje, že by se to mělo objevit v changelogu. Velké množství přidaných řádků a soubory infrastruktury naznačují, že by to mohlo být i architektonické rozhodnutí.

Krok 4: Klasifikace commitů

Tady se cesty rozdvojují: záznamy changelogu a architektonická rozhodnutí.

Pro záznamy changelogu:

uv run orkestra mine classify abc123 --changelog added

Tím se zaznamená, že by se commit abc123 měl objevit v changelogu pod kategorií „Added“.

Pro architektonická rozhodnutí:

Nejdřív získejte skutečné ID rozhodnutí:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Pak klasifikujte s tímto ID rozhodnutí:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Tím se commit propojí se záznamem rozhodnutí, který se vytvoří nebo aktualizuje.

Pro dávkové zpracování (co ve skutečnosti děláme):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Formát JSONL podporuje obě domény v jednom průchodu:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Krok 5: Vykreslení výstupů

uv run orkestra registry changelog render --package <pkg>

Tím se z ledgeru vygenerují soubory CHANGELOG.md pro jednotlivé balíčky. Changelogy jsou odvozené artefakty — smažte je a dokonale se znovu vygenerují ze zdrojového ledgeru.

Struktura záznamu rozhodnutí

Extrahovaná rozhodnutí se stávají YAML soubory s bohatými metadaty:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Každé rozhodnutí odkazuje zpátky na své zdrojové commity. Každé rozhodnutí specifikuje, které soubory ovlivňuje. Vztahy mezi rozhodnutími jsou explicitní.

Integrace s CLI: dotazování institucionální paměti

Tady se smyčka uzavírá. Agenti mohou rozhodnutí dotazovat přes CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Vrátí rozhodnutí o retry logice, zpracování chyb a vzorcích zotavení.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Vrátí kompletní záznam rozhodnutí s kontextem, zdůvodněním a dopadem.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Ukáže, jaká architektonická rozhodnutí byla nedávno učiněna.

Jak to agenti používají

Základní instrukce našeho orchestrátoru zahrnují:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Když je agent požádán, aby implementoval něco souvisejícího s DuckDB, může nejdřív zkontrolovat:

uv run orkestra registry decisions search --query "DuckDB"

A objevit DEC-PL-142, kde se dozví:

Proč jsme zvolili DuckDB (kontext)
Jak ho správně používat (agent_guidance)
Do kterých souborů se podívat (files)
Jaká související rozhodnutí existují (related)

Agent nevynalézá znovu kolo. Staví na zavedených vzorcích.

Test tří otázek

Ne každý commit si zaslouží záznam rozhodnutí. K filtrování používáme test tří otázek:

Bylo těžké toto rozhodnutí přijmout? Vyžadovalo to významnou analýzu, vyhodnocení kompromisů nebo debatu?
Je nákladné to změnit? Vyžadovalo by zvrácení tohoto rozhodnutí významnou práci navíc?
Má to celosystémový dopad? Ovlivňuje to více balíčků, nebo zakládá vzorce, kterými se budou řídit další?

Pokud commit na aspoň jednu z těchto otázek odpoví „ano“, je kandidátem na extrakci rozhodnutí. Náš typický poměr: 1–4 rozhodnutí na 100 commitů (zhruba 1–4 %).

U záznamů changelogu je laťka nižší: zaznamená se každá změna viditelná pro uživatele (funkce, opravy, vylepšení). Interní úklid, aktualizace dokumentace a refaktoring se obvykle přeskočí. Náš typický poměr: 30–50 záznamů changelogu na 100 commitů.

Ukládání dat: append-only ledgery

Mining systém používá append-only JSONL ledgery pro bezkonfliktní operace více agentů najednou:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Formát JSONL s merge=union v .gitattributes znamená, že více agentů může klasifikovat commity současně bez merge konfliktů. Každý řádek je nezávislý.

Validační brány

Před každou mining session spouštíme validaci:

uv run orkestra mine validate --quick

Ta kontroluje:

Platnost formátu SHA
Shodu s formátem ID rozhodnutí
Žádné duplicitní záznamy pro stejné SHA
Že odkazovaná rozhodnutí skutečně existují

Po klasifikaci validujeme znovu, ještě než změny commitneme.

Proč na tom záleží

Zpětnovazební smyčka, kterou jsme postavili, řeší několik problémů:

Pro nové členy týmu: Místo aby se ptali „proč jsme udělali X?“, mohou prohledat registr rozhodnutí. Kontext je zachovaný.

Pro AI agenty: Neoperují ve vakuu. Mohou se dotázat na institucionální znalosti dřív, než dají doporučení. Když jsou požádáni o přidání nového stage do pipeline, mohou objevit vzorec DuckDB a řídit se jím.

Pro architektonickou konzistenci: Rozhodnutí jsou explicitní a prohledatelná. Když někdo navrhne přístup, který odporuje existujícímu rozhodnutí, systém dokáže konflikt vynést na povrch.

Pro generování changelogu: Poznámky k vydání nejsou honička na poslední chvíli. Jsou vedlejším produktem průběžné klasifikace během vývoje.

Pro onboarding: Noví agenti dědí plný kontext kódové základny. Nevidí jen kód — vidí i rozhodnutí, která ho utvářela.

Aktuální stav

K dnešnímu dni:

15 637 commitů zpracováno přes pipeline
476 architektonických rozhodnutí extrahováno a zdokumentováno
6 799 záznamů changelogu zaznamenáno
100% pokrytí napříč oběma doménami

Každý commit od chvíle, kdy jsme začali, je klasifikovaný. Institucionální paměť je kompletní a dotazovatelná.

Jak začít

Pokud chcete implementovat něco podobného:

Začněte s konvenčními commity. Mining pipeline funguje nejlépe, když mají commity strukturované prefixy (feat:, fix:, chore:).
Definujte své domény. My používáme domény jako pipeline, agent-design, observability, data-modeling. Ty organizují rozhodnutí podle oblasti.
Vybudujte si návyk klasifikace. Mining funguje, když týmy pravidelně commity klasifikují. Dávkové zpracování s asistencí LLM pomáhá škálovat.
Udělejte rozhodnutí dotazovatelná. Hodnota roste s tím, jak agenti mohou rozhodnutí prohledávat přes CLI. Strukturujte svůj výstup pro strojové zpracování.
Uzavřete smyčku. Rozhodnutí by měla ovlivňovat budoucí práci. Zahrňte odkazy na rozhodnutí do instrukcí pro agenty a checklistů pro code review.

Cílem není dokonalá dokumentace. Je to zpřístupnění důvodů těchto změn lidem i AI, dnes i za šest měsíců. Když se změny stanou institucionální pamětí, týmy stavějí na zavedených vzorcích místo toho, aby je znovu vynalézaly.

Mining workflow je součástí našeho orchestračního enginu, konkrétně modulu kontextového enginu v našem orchestračním balíčku.

Mining skillů: od 3 500 kandidátů k 466 schopnostem

Tue, 27 Jan 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

Problém 3 500 skillů

Když jsme začali stavět systém orchestrace agentů, narazili jsme na zajímavou výzvu: v AI ekosystému jsou rozprostřeny tisíce potenciálních skillů. Repozitáře na GitHubu, dokumentace dodavatelů, komunitní projekty, interní vzorce — skilly existují všude. Ale na kterých záleží? Které fungují? A jak si udržíte koherentní knihovnu skillů, kterou agenti skutečně dokážou používat?

Naše odpověď: systematická smyčka těžby a příjmu.

Čísla dnes

Něco přes tři měsíce po tom, co Anthropic 16. října 2025 spustil Agent Skills, takhle jsme na tom byli ve chvíli, kdy byl tento příspěvek publikován 27. ledna 2026:

Metrika	Počet
Identifikovaní kandidáti	3 500+
Přijaté skilly	466
Skilly od dodavatelů	373
Interní skilly	93
Aktivní dodavatelé	25+
Průměrný počet tokenů na skill	2 834
Referencované nástroje	89
Unikátní tagy	635

Prošli jsme přes 3 500 kandidátů na skilly. Přijali jsme 466. To je 13% míra přijetí — a ta selektivita je záměrná.

Systém znalostních vrstev

Ne všechny skilly jsou si rovny. Organizujeme je do pěti znalostních vrstev (K0–K4), z nichž každá představuje jiný rozsah použitelnosti.

K0: Foundations (univerzální)

Skilly, které by měl mít každý agent. Představují schopnosti „dobrého myslitele“, které fungují kdekoliv.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Skilly K0 jsou přenositelné do jakéhokoliv projektu, jakékoliv domény, jakéhokoliv stacku. Kódují univerzální kognitivní vzorce.

K1: Identities (disciplína)

Skilly „dobrého inženýra“ nebo „dobrého výzkumníka“, které platí napříč projekty v rámci disciplíny.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (oborová expertíza)

Skilly „dobrého databázového experta“ nebo „dobrého bezpečnostního inženýra“ přenositelné v rámci oboru.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (technologie)

Skilly „dobrého uživatele Supabase“ nebo „dobrého vývojáře pro Cloudflare“ pro konkrétní technologické stacky.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (organizace)

Skilly specifické pro naši organizaci a naše workflow.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Smyčka těžby

Fáze 1: Objevování

Skilly přicházejí odevšad:

Repozitáře dodavatelů: AWS, Anthropic, Cloudflare, Supabase a přispěvatelé z komunity publikují kolekce skillů. Sledujeme 25+ kořenů dodavatelů.

Komunitní projekty: GitHub je plný šablon pro Claude Code, vzorců agentů a definic workflow.

Interní vzorce: Jak náš tým řeší problémy, vynořují se vzorce. Ty se formalizují do skillů.

Těžba dokumentace: Technická dokumentace často obsahuje implicitní skilly — postupy, checklisty, rozhodovací stromy.

Objevování je nepřetržité. K sledování kandidátů před formálním vyhodnocením používáme backlog skillů.

Fáze 2: Vyhodnocení

Každý kandidát se hodnotí podle stejných kritérií:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Všech pět produktových kritérií musí projít. Proto je 87 % kandidátů odmítnuto.

Pak každý kandidát prochází samostatným review důvěryhodnosti. Oficiální repozitář dodavatele, známého komunitního maintainera a náhodný repozitář na GitHubu nepovažujeme za rovnocenné zdroje pravdy.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Důvěryhodní dodavatelé dostanou lehčí review provenience, ale ne výjimku z kontroly. Nedůvěryhodné nebo neznámé zdroje dostanou hlubší ruční audit a přiložené skripty nespouštíme, dokud nejsou přečtené, ohraničené rozsahem a klasifikované jako bezpečné.

Analýza mezer: Před přijetím prohledáme náš registr:

uv run orkestra skills search "<capability>"

Pokud to už máme, nepotřebujeme to. Pokud máme něco blízkého, možná to spíš sloučíme, než abychom to přijímali.

Skórování hloubky a standardů: Skórujeme také, jak plně kandidát využívá model agent-skill. Osamocený SKILL.md může být pořád užitečný, ale hlubší skilly jsou cennější, když oddělují instrukce od referencí, skriptů a assetů tak, jak to podporuje agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Hvězdičky na GitHubu dokážou skóre důvěryhodnosti trochu zvednout, ale nikdy nezachrání mělký nebo nebezpečný skill. Repozitář s mnoha hvězdami a jedním vágním SKILL.md a neprůhlednými skripty skóruje níž než menší repozitář s přesným popisem, kurátorovanými references/ a malými, jasně vymezenými pomocnými skripty, které skutečně využívají plnou schopnost skillu.

Strukturální analýza: Kontrolujeme kvalitu skillu:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Pokud kandidát obsahuje skripty, ten review je přísnější. Dobrý skill není jen užitečný; musí být čitelný, ohraničený a bezpečný na to, aby se předal agentovi. Sám tenhle bezpečnostní filtr diskvalifikuje významný podíl jinak zajímavých kandidátů.

Fáze 3: Příjem

Když skill projde vyhodnocením, vstoupí do registru. Skilly ale nikdy nepřijímáme nezměněné. Upravují se, aby seděly do našeho systému.

Úpravy při přijetí:

Normalizace metadat: každý skill dostane naše frontmatter schéma
Přiřazení K-vrstvy: skilly se zařadí do odpovídající znalostní vrstvy
Obohacení tagy: tagy se přidávají pro objevitelnost
Deklarace nástrojů: povolené nástroje jsou explicitně deklarované
Zarovnání sekcí: obsah se restrukturuje podle naší šablony

Typický YAML skillu po příjmu:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fáze 4: Přiřazení scope

Skilly se přiřazují ke scope — kategoriím, které určují, kteří agenti které skilly načtou:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Agenti deklarují své scope a skilly se přiřazují automaticky:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fáze 5: Materializace

Skilly nežijí v produkci jako YAML. Vykreslují se do souborů SKILL.md, které Claude Code umí načíst:

uv run orkestra sync

Tento příkaz:

Přečte všechny YAML definice skillů
Vykreslí je přes šablony Jinja
Zapíše soubory SKILL.md do .claude/skills/
Organizuje je podle K-vrstvy (foundations/, identities/, domains/, stacks/, project/)

Finální struktura výstupu:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Vzorec spícího scope

Jeden z našich nejsilnějších vzorců jsou skilly „přijaté, ale nenačtené“. Říkáme jim spící scope.

Vezměte si skilly pro vědecké výpočty z repozitáře k-dense-scientific. Přijali jsme 120+ skillů pokrývajících bioinformatiku, chemii, kvantové počítání a klinickou informatiku. Většina našich agentů ale nepotřebuje molekulární docking ani analýzu genové exprese.

Místo abychom všech 120 skillů naložili do každého agenta (a nafoukli kontextová okna), postupujeme takto:

Přijmeme skilly s konkrétním scope (např. bioinformatics)
Necháme je spící – registrované, ale nenačtené
Zapneme je jen tehdy, když agent tento scope deklaruje

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Díky tomuto vzorci můžeme mít v registru 466 skillů, zatímco typický agent jich načte jen 40–60 relevantních.

Typy skillů

Skilly přicházejí ve třech kognitivních vzorcích:

Workflow

Seřazené procedurální kroky: „1. Udělej X, 2. Pak Y, 3. Nakonec Z“

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Disciplína

Mantinely chování: „Vždy X“, „Nikdy Y“, „Upřednostni Z“

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Ověřovací kritéria: „Potvrď X“, „Ověř Y“, „Zkontroluj Z“

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Brány kvality

Než skill vyjde do provozu, musí projít validací:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Popisy musí mít 50–400 znaků se spouštěcími frázemi („Použij, když…“, „Když potřebuješ…“), aby Claude Code věděl, kdy je navrhnout.

Validujeme průběžně:

uv run orkestra validate --show-warnings

Ekosystém dodavatelů

Našich 373 skillů od dodavatelů pochází z:

Poskytovatel	Skilly	Doména
AWS Agent	19	Cloudové služby
Anthropic	12	Generování dokumentů
Cloudflare	8	Edge computing
Supabase	5	Databáze
k-dense	100+	Vědecké výpočty
silvainfm	4	Datová věda
Java Developer Kit	45+	Spring/Java
Vercel	1	Automatizace prohlížeče

Každý kořen dodavatele je deklarovaný v metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Když proběhne orkestra sync, skilly dodavatelů se symlinknou do .claude/skills/vendor/ pod jejich namespace poskytovatele.

Co jsme se naučili

Selektivita se vyplácí. Je lákavé přijmout všechno, co vypadá užitečně. Ale každý skill stojí tokeny. S průměrem 2 834 tokenů na skill bobtnání rychle bolí. Naše 13% míra přijetí drží agenty útlé.

Struktura umožňuje objevitelnost. Systém K-vrstev není jen organizace — jde o přenositelnost. Skilly K0 lze znovu použít kdekoliv. Skilly K4 jsou záměrně specifické pro projekt. Tahle jasnost pomáhá lidem i agentům najít, co potřebují.

Spící scope škálují. Můžete přijmout stovky skillů, aniž byste je všechny museli načíst. Scope vám umožní vybudovat rozsáhlý registr a přitom udržet kontextová okna jednotlivých agentů zvladatelná.

Úprava při přijetí je zásadní. Syrové skilly dodavatelů se do vašeho systému málokdy hodí beze změny. Proces příjmu — přidání metadat, přiřazení vrstev, obohacení tagů — dělá z externích skillů funkční interní součást.

Těžba je nepřetržitá. Číslo 3 500 pořád roste. Objevují se nové repozitáře dodavatelů. Vynořují se komunitní vzorce. Interní workflow se ustalují. Smyčka se nikdy nezastaví.

Co je dál

Pracujeme na několika vylepšeních:

Automatizovaná detekce mezer: upozornění, když by dosud nepřijatý skill mohl vyřešit běžná selhání agenta
Workflow pro deprecaci skillů: formální proces pro vyřazování skillů, které jsou nahrazené nebo nepoužívané
Cross-skill závislosti: explicitní deklarace předpokladů mezi skilly
Analytika používání: sledování, které skilly agenti skutečně vyvolávají, a ne jen načítají

Smyčka mining skillů je infrastruktura. Není okázalá. Ale je to to, díky čemu 41 agentů koherentně funguje se 466 schopnostmi a přitom zůstává v kontextových limitech.

To je příběh, jak se z 3 500 stává 466. Ne tak, že bychom 3 000 ignorovali — tím, že jsme je systematicky vyhodnotili a přijali jen to, co funguje.

Chcete vidět systém skillů v akci? Podívejte se na uv run orkestra skills list a prozkoumejte náš aktuální registr.

Progresivní odkrývání: okna CLI do agentních systémů

Tue, 20 Jan 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

Agentní systémy jsou neprůhledné záměrně. Dělají rozhodnutí, volají nástroje a koordinují práci napříč desítkami specialistů. Ale když se něco pokazí — nebo když si prostě chcete ujasnit, co se děje — kam se podíváte?

Odpověď je progresivní odkrývání: vrstvené rozhraní, které odkryje přesně tolik složitosti, kolik potřebujete, přesně ve chvíli, kdy to potřebujete.

Problém neprůhlednosti

Moderní systém orchestrace agentů může mít:

40+ specializovaných agentů, každý s odlišnými schopnostmi
700+ skillů rozprostřených napříč interní automatizací a integracemi dodavatelů
470+ architektonických rozhodnutí, která formují chování
desítky serverů nástrojů MCP poskytujících externí schopnosti

Tahle složitost je záměrná. Agenti potřebují přístup k bohatému kontextu — doménovým znalostem, inteligenci nad kódem, databázovým schématům —, aby se dobře rozhodovali. Ale právě tahle bohatost vytváří problém s viditelností.

Jak poznáte, který agent má na starosti databázové migrace? Jaká rozhodnutí utvářela chování řazení výsledků ve vyhledávacím systému? Ke kterým nástrojům má přístup poradce pro architekturu?

Bez strukturovaného přístupu vám zbývá číst zdrojový kód nebo doufat, že dokumentace je aktuální.

Progresivní odkrývání jako architektura

Progresivní odkrývání není jen vzorec UI. Je to architektonický princip: organizujte informace do vrstev, každou hlubší než tu předchozí, aby uživatelé mohli zastavit na úrovni, která zodpoví jejich otázku.

Pro agentní systémy se to překládá do CLI příkazů rostoucí hloubky:

Úroveň	Příkaz	Zodpovězená otázka
1	`orkestra system status`	Je všechno zdravé?
2	`orkestra agents list`	Jací agenti existují?
3	`orkestra agents info <name>`	Co tenhle agent dělá?
4	`orkestra decisions search`	Proč to funguje takhle?
5	Nástroje Maguyva MCP	Ukaž mi kód.

Každá úroveň zodpoví přirozenou navazující otázku. Zřídkakdy potřebujete skočit rovnou na úroveň 5.

Úroveň 1: Zdraví systému

První otázka je vždy: funguje všechno?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Jeden příkaz. Čtyři čísla. Dost na to, abyste věděli, že systém je nakonfigurovaný a registry jsou naplněné.

Pokud počet agentů neočekávaně klesne, nebo se skilly nenačtou, uvidíte to tady jako první. Žádné hrabání se v lozích.

Úroveň 2: Inventář agentů

Jakmile víte, že je systém zdravý, další otázka zní: co je k dispozici?

$ orkestra agents list

Vrátí strukturovaná data — jména agentů, popisy, preference modelu, pokrytí domén. Výstup je ve výchozím stavu JSON, takže se snadno pipe-uje do jq pro filtrování:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Chcete agenty, kteří zvládají databázovou práci? Příkaz pro vyhledávání to zúží:

$ orkestra agents search "database"

Prochází jména, popisy a schopnosti. Najdete správného specialistu, aniž byste museli číst 40 definic agentů.

Úroveň 3: Hluboký ponor do agenta

Našli jste agenta, který vypadá relevantně? Příkaz info odhalí všechno:

$ orkestra agents info architecture-advisor

Výstup obsahuje:

Metadata: jméno, kategorii, preferenci modelu, popis
Domény: které znalostní oblasti tento agent pokrývá
Identitu: charakterové rysy (architect, strategist, knowledge-architect)
Průvodce nástroji: která dokumentace nástrojů se vkládá do kontextu
Nástroje: úplný seznam MCP nástrojů dostupných tomuto agentovi

Tady je ukázka toho, co uvidíte:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

To vám přesně řekne, co agent umí. Nemusíte číst zdrojový kód.

Úroveň 4: Archeologie rozhodnutí

Agenti se chovají podle zdokumentovaných rozhodnutí. Když potřebujete pochopit proč něco funguje určitým způsobem, registr rozhodnutí je zdroj pravdy.

$ orkestra decisions search "agent"

Vrátí odpovídající architektonická rozhodnutí:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Každé rozhodnutí má plnou provenienci — kdy bylo učiněno, proč, jaké kompromisy byly zvažovány, které commity ho implementovaly:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Tohle je architektonická dokumentace, která zůstává aktuální, protože se těží z commitů, ne udržuje ručně.

Úroveň 5: Přímá inteligence nad kódem

Když potřebujete vidět skutečnou implementaci — ne metadata o ní —, nástroje MCP od Maguyvy poskytují přímý přístup.

Zevnitř session agenta:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Tohle automaticky routuje napříč sémantickým, textovým a AST vyhledáváním, aby našlo relevantní kód. Pro konkrétní symboly:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Pro analýzu závislostí:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Tohle nejsou jen náhrady za grep. Pracují s grafem, jsou sémanticky indexované a integrované se stejnou inteligencí nad kódem, která pohání samotné agenty.

Sjednocené vyhledávání napříč registry

Někdy nevíte, který registr obsahuje odpověď. Sjednocené vyhledávání pokrývá všechno:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 shod napříč pěti registry. Souhrn vám řekne, kam se ponořit hlouběji. Odeberte --summary pro podrobné výsledky, nebo přidejte --limit 5, aby výstup zůstal přehledný.

Proč na tom záleží

Progresivní odkrývání není jen o pohodlí. Mění to, jak interagujete se složitými systémy.

Debugování se stává zvladatelným. Když agent udělá neočekávané rozhodnutí, nehrabete se v lozích. Zkontrolujete, ke kterým nástrojům má přístup (agents info), jaká rozhodnutí formují jeho chování (decisions search), a v případě potřeby vysledujete implementaci (intelligent_search).

Onboarding se zrychluje. Noví členové týmu nemusí číst celou kódovou základnu. Začnou s system status, prozkoumají s agents list a ponoří se hlouběji, jen když narazí na něco, čemu nerozumí.

Dokumentace zůstává aktuální. Protože CLI čte ze stejných registrů, které konfigurují agenty, výstup je vždy přesný. Nevzniká nesoulad mezi tím, co říká dokumentace, a tím, co systém skutečně dělá.

CLI jako rozhraní

Mohli jsme postavit webový dashboard. Mohli jsme napsat rozsáhlou dokumentaci. Místo toho jsme postavili CLI, které čte ze zdroje pravdy.

CLI má výhody:

Kompozovatelné: pipe-ujte výstup skrz jq, propojte je se skripty
Skriptovatelné: automatizujte kontroly, generujte reporty
Rychlé: žádné načítání stránek, žádné autentizační toky
Přesné: čte skutečnou konfiguraci, ne cachovanou reprezentaci

Pro systémy, kde na správnosti záleží víc než na estetice, vyhrává CLI.

Postavte si vlastní progresivní odkrývání

Pokud stavíte agentní systémy, zvažte, jak je budou uživatelé zkoumat:

Začněte kontrolami zdraví. Jeden příkaz, který vám řekne, jestli věci fungují.
Poskytněte pohledy na inventář. Vypište, co existuje, dřív než vysvětlíte, co to dělá.
Umožněte cílené dotazy. Při velkém objemu dat je vyhledávání účinnější než procházení.
Vystavte provenienci. Nechte uživatele vysledovat rozhodnutí k jejich původu.
Napojte se na inteligenci nad kódem. Nakonec uživatelé potřebují vidět implementaci.

Každá vrstva zodpoví navazující otázku. Stavte je v pořadí podle frekvence — většina uživatelů zastaví na vrstvě 2 nebo 3. Jen power useři dosáhnou vrstvy 5.

Cílem není vystavit všechno. Je to vystavit přesně to, co je potřeba, přesně ve chvíli, kdy je to potřeba. To je progresivní odkrývání aplikované na architekturu agentů.

Ground Truths: ukotvení AI agentů v realitě

Tue, 13 Jan 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

AI agenti jsou pozoruhodně schopní. Umí uvažovat, syntetizovat a generovat. Mají ale zásadní slabinu: vymýšlejí si věci. Ne zlomyslně, ale sebevědomě. Agent si může vymyslet parametry API, které neexistují, odkázat na konfigurace, které nikdy nebyly definované, nebo použít vzorce ze svých trénovacích dat, které odporují vaší skutečné architektuře.

Standardní protilék zní „dej agentovi víc kontextu“. Kontext ale může být protichůdný. Dokumentace se odchyluje od implementace. Komentáře lžou. Dokonce i kód dokáže zmást, když se čte bez pochopení záměru.

Potřebovali jsme něco explicitnějšího. Něco, co se nedá ignorovat ani špatně interpretovat. Něco, co by agenty ukotvilo v ověřitelné realitě.

Říkáme tomu Ground Truths.

Co je Ground Truth?

Ground truth je explicitní, verzované faktické tvrzení, které agenti musí respektovat. Není to dokumentace. Není to komentář. Je to plnohodnotná entita v systému s:

Unikátním identifikátorem (jako GT-MAG-015 nebo GT-MAG-036)
Stavem životního cyklu (aktuální, předběžný nebo zastaralý)
Rozsahem (celoplošný pro platformu, specifický pro balíček, nebo vázaný na doménu)
Důkazem (cesty k souborům, URL nebo reference, které tvrzení dokládají)
Pokyny pro agenta (explicitní instrukce co dělat a čemu se vyhnout)

Tady je příklad z naší platformy pro code intelligence Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Tohle není próza. Je to smlouva. Když agent na tuto ground truth narazí, ví:

Výchozí chování je deterministické (prázdné výsledky, ne mlhavé odhady)
Existují konkrétní parametry (find_similar, exact_match) s definovaným chováním
Existují důkazy v konkrétních souborech, které lze ověřit
Tvrzení bylo ověřeno k určitému datu

Anatomie registru Ground Truths

Ground truths žijí v YAML registrech pod ai_assets/reference/ground_truths.yaml. Každý balíček nebo doména může mít vlastní registr. Struktura je:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Registr obsahuje metadata o samotné kolekci, konfiguraci vykreslení pro generování dokumentace a samotná tvrzení. Každé tvrzení dodržuje přísné schéma validované Pydantic modely:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Jak agenti přistupují k Ground Truths

Ground truths jsou vystaveny přes několik kanálů:

1. Vykreslená dokumentace

Příkaz orkestra sync transformuje YAML registry na čitelný markdown:

uv run orkestra sync

Tím vzniknou soubory GROUND_TRUTHS.md, které se zahrnou do kontextu agenta. Vykreslený výstup seskupuje tvrzení podle stavu a kategorie:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI vyhledávání

Agenti s přístupem k shellu mohou ground truths vyhledávat programově:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Vyhledávací funkce boduje shody napříč více poli s váženou relevancí:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Skladba kontextu

Když jsou agenti vykreslováni z YAML definic, jejich kontext může odkazovat na registry ground truths:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Tím je zajištěno, že relevantní ground truths se načtou dřív, než agent začne pracovat.

Kategorie Ground Truths

Když se podíváme napříč našimi registry, ground truths se shlukují do několika vzorců:

Produktové principy

Omezení toho, čím produkt je a čím není:

„Maguyva je vůči repozitářům uživatelů pouze pro čtení; jediné neobnovitelné aktivum je placená cache embeddingů.“ (GT-MAG-001)

Architektonické hranice

Kdo za co odpovídá a proč:

„Hranice mezi pipeline a Maguyva jsou záměrné: pipeline je znovupoužitelná, Maguyva drží logiku specifickou pro kód a CQRS odděluje zápisy stage od čtení serveru.“ (GT-MAG-006)

Pravidla proti halucinacím

Explicitní mandáty, které udržují kontrakty nástrojů deterministickými, ne odvozenými:

„Fuzzy shoda symbolů je opt-in přes find_similar=true. Výchozí chování vrací prázdné výsledky pro neexistující symboly; exact_match=true vynucuje striktní shodu a vypíná všechny fuzzy fallbacky.“ (GT-MAG-015)

Brány kvality

Standardy, které se musí udržovat:

„Změny sdílené infrastruktury (post_filters.py, extraktory vztahů, sdílené handlery) MUSÍ být validovány proti VŠEM podporovaným jazykům přes generování celého manifestu ještě před commitem. Validace jednoho jazyka nestačí pro sdílený kód.“ (GT-MAG-036)

Vzorce kódu

Implementační požadavky:

„Pro CPU-náročnou práci v asynchronním kontextu používejte asyncio.to_thread(); zastaralý vzorec loop.run_in_executor() by se v novém kódu neměl používat.“ (GT-MAG-018)

Životní cyklus Ground Truth

Ground truths nejsou statické. Vyvíjejí se skrz definovaný životní cyklus:

Předběžná

Navržené tvrzení, které se zatím vyhodnocuje. Tvrzení je zaznamenané, ale může se změnit:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Aktuální

Ověřená pravda, kterou agenti musí respektovat. Důkaz byl validován:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Zastaralá

Pravda, která už neplatí. Zachovaná pro historickou referenci s odkazem na to, čím byla nahrazena:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Proč ne prostě dokumentace?

Dokumentace slouží jinému účelu. Vysvětluje. Učí. Může být vágní, může používat kvalifikátory jako „obecně“ nebo „obvykle“.

Ground truths nemohou být vágní. Jsou to tvrzení. Buď platí, nebo neplatí.

Zvažte ten rozdíl:

Dokumentace: „API obecně vrací prázdné výsledky, když symbol nenajde, i když fuzzy matching může být v některých konfiguracích zapnutý.“

Ground Truth: „Výchozí chování vrací prázdné výsledky pro neexistující symboly; exact_match=true vynucuje striktní shodu a vypíná všechny fuzzy fallbacky.“

První je užitečné pro lidi, kteří se systém učí. Druhé dává agentům konkrétní podklad pro rozhodování.

Pokyny pro agenta: dělej a vyhýbej se

Některé ground truths obsahují explicitní pokyny pro agenta:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Tím mizí nejednoznačnost. Agent, který tohle čte, ví nejen, co je pravda, ale i to, jaké kroky ta pravda implikuje.

Ověřování a údržba

Ground truths vyžadují údržbu. Sledujeme:

last_verified: kdy někdo potvrdil, že tvrzení pořád platí
evidence: soubory, které tvrzení dokládají (lze ověřit jejich existenci)
source: odkud pravda pochází (inspekce CLI, architektonický review, ponaučení po incidentu)

Ground truth se zastaralým datem ověření nebo rozbitými odkazy na důkazy je signál k prošetření. Buď je pravda pořád platná a potřebuje znovu ověřit, nebo se realita změnila a pravda potřebuje aktualizovat.

Skutečné příklady z provozu

Bezpečnostní hranice

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Tato ground truth brání třídě zavádějících „bezpečnostních vylepšení“, která by produkt rozbila.

Přesnost v čase extrakce

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Tohle vzniklo z bolestivé zkušenosti. Agenti opravovali selhávající jazykové balíčky přidáváním filtrů jen na straně validátoru, díky kterým test harness vypadal zeleněji, zatímco živý extraktor Maguyva pořád emitoval špatné hrany. Pravidlo vrací opravy zpátky do skutečné cesty: YAML konfigurace, dotazy nebo handlery.

Vícevrstvé filtrování

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Tohle brání agentům přidávat filtry na špatné místo, což je běžná chyba, která způsobovala regrese přesnosti.

Integrace s orchestračním systémem

Ground truths jsou jedna vrstva širšího kontextového systému:

Architektonická rozhodnutí (ADR) – zaznamenávají, proč jsme zvolili přístup A před B
Ground Truths – uvádějí, co je definitivně pravda právě teď
Doménové vzorce – popisují, jak věci dělat správně
Antivzorce – popisují, čemu se vyhnout a proč

Agent pracující v systému má přístup ke všem čtyřem. Ground truths poskytují faktické ukotvení, rozhodnutí vysvětlují historii, vzorce vedou implementaci a antivzorce varují před nástrahami.

Měření dopadu

Od zavedení ground truths jsme zaznamenali:

Méně cyklů „oprav tu vyhalucinovanou opravu“
Sebejistější rozhodování agentů, když jsou fakta jasná
Lepší review pull requestů, protože očekávání jsou explicitní
Zkrácenou dobu onboardingu nových agentů (i lidí)

Investice do udržování ground truths se vyplácí ve zmenšeném objemu debugování a jasnějších systémových hranicích.

Jak začít

Chcete-li do svého systému přidat ground truth:

Vytvořte ground_truths.yaml v adresáři ai_assets/reference/ svého balíčku
Definujte metadata a konfiguraci vykreslení
Přidejte tvrzení podle schématu
Spusťte uv run orkestra sync pro vygenerování dokumentace
Zahrňte registr do skladby kontextu agenta

Začněte s fakty, která způsobují nejvíc zmatku, nebo s omezeními, která se nejčastěji porušují. To jsou vaše nejcennější ground truths.

Závěr

AI agenti budou halucinovat. To je jejich přirozenost. Můžeme ale vytvořit prostředí, kde je halucinace omezená, kde jsou určitá fakta nezpochybnitelná, kde si agenti mohou ověřit své předpoklady proti ověřené realitě.

Ground truths nejsou kompletní řešení. Vyžadují údržbu. Mohou zastarat. Přidávají do vývojového procesu režii.

Poskytují ale něco cenného: sdílenou slovní zásobu faktů, které mohou důvěřovat lidé i agenti. Ve světě, kde se agenti čím dál víc podílejí na vývoji softwaru, se tenhle sdílený základ stává nezbytným.

Alternativou jsou nekonečné cykly agentů, kteří sebevědomě dělají chyby, a lidí, kteří je opravují. Ground truths tenhle cyklus přerušují tím, že opravy dělají explicitní a trvalé.

Vaši agenti si zaslouží vědět, co je pravda. Řekněte jim to.

Orkestra: orchestrace AI agentů ve velkém měřítku

Tue, 06 Jan 2026 00:00:00 GMT

Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (leden 2026). Aktuální čísla najdete na naší stránce týmu.

Když jsme začali stavět s Claude Code, narazili jsme na problém, na který dřív nebo později narazí každý tým používající AI kódovací asistenty: jeden agent nedokáže dělat všechno dobře.

Můžete agenta napromptovat, aby byl databázový specialista. Nebo bezpečnostní auditor. Nebo frontend inženýr. Ale v momentě, kdy ho požádáte, aby byl všechny tři najednou, kvalita utrpí. Kontext se rozřídí. Instrukce si odporují. Z agenta se stane generalista, který je ve všem průměrný.

Postavili jsme si tedy Orkestru.

Co je Orkestra?

Orkestra je systém pro orchestraci agentů pro Claude Code a podobné AI kódovací nástroje. Koordinuje více specializovaných agentů, každý s odlišnou expertízou, pod jedním orchestrátorem, který směruje práci na správného specialistu.

Představte si ji jako personální agenturu pro AI agenty. Orchestrátor přijme úkol, identifikuje, který specialista by ho měl řešit, a deleguje ho se správným kontextem. Když je práce hotová, výsledky tečou zpátky k orchestrátorovi na syntézu.

Čísla mluví sama za sebe:

Komponenta	Počet
Specializovaní agenti	46
Znovupoužitelné skilly	466
Archetypy identity	27
Mindsety	11
Komunikační styly	10
Znalostní domény	21

Systém charakterů: D&D pro agenty

Klíčový postřeh za Orkestrou je, že chování agenta vzniká ze tří skládatelných primitiv:

Identita definuje, čím agent je. Architekt navrhuje strukturu systémů. Debugger sleduje selhání k jejich kořenové příčině. Guardian vynucuje compliance a bezpečnostní hranice. Máme 27 archetypů identity, které lze míchat.

Mindset definuje, jak agent přemýšlí. Analytický mindset ukotvuje tvrzení v důkazech a kvantifikuje nejistotu. Skeptický mindset zpochybňuje předpoklady a hledá vyvracející důkazy. Explorativní mindset přijímá nejednoznačnost a zkouší více přístupů.

Styl definuje, jak agent komunikuje. Technický styl obsahuje přesné hodnoty a odkazuje na konkrétní soubory. Stručný styl seká balast a začíná odpovědí. Diplomatický styl vyvažuje upřímnost s taktem.

Agent tato primitiva kombinuje:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Tato kompozice vytváří agenta, který navrhuje systémy (architect), propojuje znalosti napříč doménami (knowledge-architect), stanovuje strategický směr (strategist), přemýšlí v důkazech a datech (analytical) a komunikuje bez balastu (concise).

Síla je v kombinatorické explozi. 27 identit krát 11 mindsetů krát 10 stylů dává skoro 3 000 možných osobností agenta. Definujete si ale jen ty kombinace, na kterých pro vaši práci záleží.

Skilly: znovupoužitelné moduly schopností

Skilly jsou znalosti a workflow, které agenti mohou vyvolat. Řídí se vrstveným systémem podle rozsahu:

Vrstva	Název	Rozsah	Příklad
K0	Foundations	Univerzální metodologie	Test-first disciplína, dokončování založené na důkazech
K1	Identities	Workflow podle role	Standardy CLI rozhraní, playbook výkonu
K2	Domains	Znalosti specifické pro doménu	Vzorce migrace databáze, validace autentizace
K3	Stacks	Specifické pro technologii	Nasazení na Cloudflare, operace v Supabase
K4	Project	Jen tato kódová základna	Workflow a konvence specifické pro projekt

Skilly se načítají líně. Agent při startu vidí názvy a popisy skillů, ale plný obsah skillu se načte, až je vyvolán. Díky tomu zůstává kontext útlý, zatímco stovky skillů zůstávají objevitelné.

Každý skill obsahuje:

Jasné spouštěcí podmínky („Použij při migraci databázových schémat“)
Pokyny krok za krokem
Povolené nástroje pro daný workflow
Kritéria úspěchu a cesty zotavení z chyby

Našich 466 skillů v registru pokrývá všechno od izolace v git worktree přes workflow webového výzkumu po kontrolu stavu nasazení.

Proč na orchestraci záleží

Architektury s jedním agentem rychle narazí na zeď:

Ředění kontextu. Kontextové okno o 200 tisících tokenech zní velkoryse, dokud do něj nenaložíte databázová schémata, dokumentaci API, testovací fixtures a doménové znalosti. Specialisté umí pracovat s cíleným kontextem.

Konflikty instrukcí. Říct agentovi, aby byl „důkladný, ale rychlý“ a „všechno ověřoval, ale neover-engineeroval“, vytváří napětí. Specialisté to řeší tím, že mají jasný rozsah.

Hloubka expertízy. Generalistický agent ví trochu o všem. Specializovaný agent, poskládaný ze správné identity a skillů, zná svou doménu do hloubky.

Orkestra implementuje plochou orchestraci: jeden orchestrátor koordinuje více specialistů. Specialisté nemohou spouštět dalšího sub-specialistu. Tím se předchází explozi složitosti a zároveň to umožňuje paralelní práci.

Orchestrátor má přístup k 2,2 milionům tokenů efektivní kapacity: svému vlastnímu 200k oknu plus 10 souběžným subagentům po 200k. Práce, která by vyčerpala jednoho agenta, běží pohodlně napříč celou flotilou.

Vykreslovací pipeline

Definice agentů žijí v YAML. Claude Code čte Markdown. Orkestra tuhle mezeru přemosťuje deterministickou vykreslovací pipeline:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operátoři editují YAML zdroj. Spustí orkestra sync. Vykreslený Markdown se objeví v .claude/agents/. Claude Code změny vyzvedne.

Tohle oddělení slouží různým publikům:

YAML zdroj obsahuje metadata životního cyklu, tagy, validační pravidla a poznámky o zastarávání pro tooling
Vykreslený Markdown obsahuje jen to, co model potřebuje: popis, nástroje, skilly a vodítko chování

Pipeline skládá identity, mindsety, styly a skilly do jednoho koherentního promptu. Agent architect-analytical-concise dostane úplně jiný systémový prompt než agent debugger-skeptical-technical, i když sdílejí některé podkladové skilly.

Doménové znalosti: vzorec čtyř souborů

Každá znalostní doména se drží konzistentní struktury:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Tahle struktura slouží k načítání kontextu agenta. Agent pracující na autentizaci si načte authentication/patterns.md pro vedení a authentication/anti-patterns.md, aby se vyhnul známým úskalím. Soubory jsou dimenzované pro efektivní načítání kontextu: dostatečně zaměřené na to, aby byly užitečné, dostatečně obsáhlé na to, aby byly autoritativní.

Udržujeme 21 doménových vrstev na nejvyšší úrovni včetně analytiky, autentizace, datové vědy, infrastruktury, strojového učení, výkonu, bezpečnosti a dalších. Každá doména může mít poddomény pro jemnější granularitu.

Hodnoty: operační systém

Všichni agenti sdílejí základní vrstvu hodnot, která definuje, jak fungují:

Jednoduchost na prvním místě. Používejte nejjednodušší řešení, které funguje. Složitost přidávejte jen tehdy, když je oprávněná.

Řešte kořenové příčiny. Nikdy nezalepujte selhání. Pokud selže pipeline, ladíte pipeline. Pokud selže test, opravíte kód nebo test.

Na základě důkazů. Tvrzení označujte jako „ověřené“ (s benchmarky) nebo „odhadované“ (s předpoklady). Detekovaný vzorec neznamená potvrzený problém.

Ekonomika kontextu. MCP nástroje stojí 0,1 % kontextu. Čtení souboru stojí 2 % za každé. Doménovou expertízu aplikujte dřív, než začnete kód prozkoumávat.

Tyto hodnoty se šíří ke každému specialistovi přes vykreslovací pipeline. Agent je nemůže kompozicí obejít.

CLI: řídicí rovina

Orkestra se dodává s CLI pro správu agentního ekosystému:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI je zdroj pravdy o tom, jací agenti existují, jaké skilly mají a jestli je systém zdravý. Před synchronizací spouští validaci, aby zachytilo problémy včas.

Úvahy o open source

Orkestru jsme postavili, abychom vyřešili náš vlastní problém: koordinaci AI agentů ve velkém měřítku pro komplexní kódovou základnu. Vzorce, které jsme objevili, nejsou specifické pro naši doménu.

Systém kompozice charakteru (identita + mindset + styl) se hodí pro jakýkoliv tým, který definuje osobnosti agentů.

Systém vrstev skillů (K0–K4) poskytuje mentální model pro organizaci znovupoužitelných schopností podle rozsahu.

Vzorec vykreslovací pipeline (YAML zdroj + šablony + generované artefakty) odděluje požadavky nástrojů od obsahu určeného modelu.

Model ploché orchestrace (jeden koordinátor, mnoho specialistů) se vyhýbá explozi složitosti a přitom umožňuje paralelismus.

Jestli se Orkestra stane open source, závisí na tom, zda tyto vzorce mají hodnotu pro ostatní, kdo staví s Claude Code. Pokud narážíte na zdi, které jsme popsali, tahle architektura by mohla pomoct.

Co jsme se naučili

Stavba Orkestry nás naučila, že orchestrace není o tom, dělat agenty chytřejšími. Je o tom, dělat je zaměřenějšími.

I agentovi s dokonalými instrukcemi nakonec dojde kontext. Jeden agent se všemi skilly se pořád může splést v tom, který z nich použít. Jeden agent, který se snaží být vším, produkuje průměrné výsledky ve všem.

Čtyřicet specialistů, každý excelentní ve své doméně, koordinovaných orchestrátorem, který ví, kdy delegovat: takhle dodáváme.

Na číslech záleží míň než na architektuře. Můžete potřebovat pět agentů, nebo padesát. Princip zůstává: kompozice před schopností, specializace před generalizací, koordinace před individuálním hrdinstvím.

Orkestra pohání agentní ekosystém za Maguyva, naší platformou pro code intelligence. Chcete se dozvědět víc? Ozvěte se týmu.