Blog Maguyva

Kontekst, który podróżuje z tobą

Mon, 07 Sep 2026 00:00:00 GMT

Indekser Cursor jest doskonały wewnątrz Cursor. Autouzupełnianie, edycja w linii, czat i agent w tym oknie już opierają się na indeksie projektu, który Cursor utrzymuje dla otwartej przestrzeni roboczej. Jeśli Cursor jest jedynym miejscem, w którym piszesz kod, a ten indeks już znajduje właściwe pliki, zostań tam. To uczciwy przypadek „zostań tam, gdzie jesteś” i słusznie otwiera ten tekst.

Ten artykuł dotyczy drugiej połowy zwykłego tygodnia. To samo repozytorium jest też otwierane w Claude Code, odpytywane z Codex CLI, przeglądane na drugiej maszynie albo odpytywane przez agenta działającego w CI. Pytanie nie brzmi „który indekser jest lepszy”. Pytanie brzmi, czy mapa, której agent ufa w jednym oknie, jest tą samą mapą, której ufa w kolejnym.

Maguyva jest tą mapą, która podróżuje z tobą. To zdalna warstwa kontekstu bazy kodu oparta na MCP. Agent odpytuje ją tak samo, jak każde inne narzędzie MCP. Wyniki wracają jako uszeregowane ścieżki z numerami linii. Cursor pozostaje edytorem. To kontekst się przemieszcza.

Do czego służy indekser Cursor

Wbudowane indeksowanie Cursor istnieje po to, by czat, agent i wyszukiwanie w edytorze mogły pobierać istotny kod, zamiast polegać wyłącznie na tym, co mieści się w surowym oknie kontekstu modelu. To właściwy projekt dla IDE. Ten indeks jest natywny dla Cursor. Nie jest serwerem MCP i nie jest dostępny z żadnego innego klienta.

Oto jak to działa, zgodnie z publiczną dokumentacją Cursor i własnym opisem Cursor w chwili pisania tego tekstu: główna ścieżka wyszukiwania nie jest już chmurowym indeksem embeddingów. Zespół Cursor oświadczył na swoim forum społeczności, że dedykowane wyszukiwanie semantyczne oparte na embeddingach jest wygaszane na rzecz wyszukiwania opartego na grep, ponieważ obecne modele wystarczająco dobrze przeszukują żywe drzewo samodzielnie. W jego miejsce wchodzi Instant Grep, lokalny indeks wyszukiwania zbudowany z n-gramów, list odwróconych i filtrów Blooma, przechowywany w tabeli wyszukiwania zmapowanej w pamięci, dzięki czemu zapytania są rozwiązywane na własnej maszynie dewelopera, a nie na serwerze.

Sam indeks żyje w katalogu .git/cursor/ należącym do samego repozytorium, zakotwiczonym w konkretnym commicie git; zmiany od tego commitu nakładają się na niego zamiast wywoływać ponowne skanowanie, a indeks przebudowuje się dopiero, gdy stan lokalny znacznie odbiegł od tego, na czym został zbudowany. Ponieważ znajduje się wewnątrz .git, nigdy nie jest śledzony ani wypychany — usuń folder, a indeks zniknie. .gitignore jest respektowany z założenia, ponieważ tylko treść śledzona przez git kwalifikuje się do indeksowania, a .cursorignore jest egzekwowany na ścieżce odczytu. Na tej ścieżce nie ma już ani kroku embeddingu po stronie serwera, ani zdalnej bazy wektorowej. Wcześniejsza dokumentacja opisywała projekt wspomagany przez chmurę — szyfrowanie fragmentów, synchronizację przez drzewo Merkle’a, ponowne wykorzystanie indeksu między członkami zespołu — a sam zespół Cursor oświadczył od tego czasu, że ten projekt jest wygaszany, więc ten tekst nie opisuje go już jako aktualnego.

Wyróżniającą się cechą w edytorze jest subagent Explore Cursor. Może uruchamiać wiele równoległych wyszukiwań we własnym oknie kontekstu na szybszym modelu i zwracać tylko istotne wyniki, dzięki czemu główna rozmowa nie puchnie od wyników wyszukiwania. To prawdziwa siła wewnątrz edytora. Zachowaj ją.

Przestrzenie robocze z wieloma katalogami głównymi są obsługiwane: kontekst każdego otwartego folderu jest dostępny dla Agenta. Niektóre funkcje zależne od git, jak worktree, są wyłączone w konfiguracjach z wieloma katalogami głównymi, a Cloud Agents w ogóle nie obsługują przestrzeni roboczych z wieloma katalogami głównymi.

Nic z tego nie jest powodem, by opuszczać Cursor. To precyzyjny opis mapy, która jest doskonała tam, gdzie żyje.

Co naprawdę oznacza „podróżować z tobą”

Mapa podróżuje z tobą, gdy te same pytania zwracają ten sam rodzaj odpowiedzi, z cytatami, które możesz otworzyć, z więcej niż jednego klienta.

W Cursor: „Gdzie zdefiniowano parseConfig i kto go wywołuje?”
W Claude Code, na tym samym repozytorium: to samo pytanie.
W Codex CLI, na maszynie do przeglądu, która nigdy nie otworzyła okna Cursor: to samo pytanie.
W agencie CI mówiącym w MCP: to samo pytanie, wobec tego samego hostowanego zrzutu.

Jeśli każda powierzchnia buduje swój własny prywatny indeks, nie masz jednej mapy. Masz kilka pamięci podręcznych, które się rozjeżdżają. Indeks edytora może być aktualny dla drzewa na dysku. Sesja CLI może być o dzień w tyle. Zadanie CI może patrzeć na inny checkout. A agent i tak nadal będzie brzmiał pewnie.

Indekser Cursor nie ma tego rozwiązywać. Ponieważ żyje wewnątrz edytora, kontekst, który buduje, jest dla tego edytora. Czytelnik, który potrzebuje też CLI, pipeline’u CI albo innego edytora, potrzebuje osobnego narzędzia dla tych powierzchni. To fakt dotyczący zakresu, nie wada. Maguyva jest tym osobnym narzędziem.

Opublikowana liczba języków dla indeksera Cursor nie jest podana w materiałach, z których może korzystać ten tekst. Maguyva publikuje wsparcie dla ponad 279 języków i technologii tekstowych. Cennik Cursor również nie jest tu przepisywany; zobacz ich stronę z cenami. Maguyva pobiera opłaty za workspace, a nie za miejsce, z opublikowanymi planami $0, $19, $49 i $149, zależnie od indeksowanej objętości i rozmiaru workspace.

Jedna hostowana mapa, każdy klient MCP

Maguyva to zdalny serwer MCP. Łączysz GitHub, wybierasz repozytoria, a chmurowy pipeline buduje symbole, krawędzie grafu i uszeregowaną mapę. Dodajesz klucz API do konfiguracji MCP klienta, którego już używasz. Maguyva ma przewodniki konfiguracji dla 24 udokumentowanych klientów MCP — w tym Cursor — i może łączyć się z innymi klientami zgodnymi z MCP, które obsługują standardową konfigurację.

Strona konfiguracji Cursor to ścieżka specyficzna dla tego edytora, jeśli tam pracujesz. Ten sam serwer odpowiada Claude Code, VS Code, Windsurf, Codex CLI i innym. Nie zmieniasz edytora. Dajesz każdemu agentowi tę samą powierzchnię narzędzi: 11 skierowanych do klienta narzędzi MCP w zakresie wyszukiwania, symboli, analizy zależności, pobierania plików, kontekstu repozytorium i deterministycznych przepływów narzędziowych. Wyszukiwanie semantyczne, strukturalne, grafowe i tekstowe są łączone w uszeregowane wyniki.

Na tym polega korzyść z przenośności. Cytaty, które sprawdziłeś rano w Cursor, mają tę samą formę co cytaty, które Codex CLI zwróci dziś wieczorem. Ścieżka pliku i numer linii. Otwórz je. Jeśli są błędne, zobaczysz to. Jeśli są poprawne, kolejna edycja ma gdzie wylądować. Zatwierdzone twierdzenie to mniej zhalucynowanych edycji, nie obietnica, że każda edycja jest poprawna.

Aktualność jest publikowana. Migawki są opatrzone znacznikiem czasu, więc agent wie, którą wersję drzewa czyta. Częstotliwość przebudowy to codziennie w planie darmowym i co godzinę w planach płatnych. Uczciwym ograniczeniem jest niezsynchronizowana praca lokalna: edycja istniejąca tylko w drzewie roboczym jeszcze nie trafiła do hostowanej mapy. To ograniczenie jest takie samo niezależnie od tego, z którego klienta odpytujesz, i o to właśnie chodzi. Rozjazd między klientami przestaje być drugim, ukrytym ograniczeniem.

Dokumentacja podaje pętlę aktywacji, która dotyczy każdego klienta: zindeksuj repozytorium, które już znasz, połącz klienta, zadaj jedno pytanie, które możesz sprawdzić. Zrób to raz w Cursor. Zrób to jeszcze raz z CLI, którego naprawdę używasz w dni przeglądu. Jeśli obie odpowiedzi cytują ten sam handler, mapa naprawdę podróżowała z tobą.

Jak dwie mapy współistnieją obok siebie

Używaj obu. To nie są alternatywy w sensie strony porównawczej.

Zostaw indekser Cursor włączony dla projektu na dysku. Niech Explore, Instant Grep i agent wewnątrz edytora go używają. Ta pętla jest natywna i szybka.
Dodaj Maguyva jako serwer MCP w Cursor, żeby ta sama sesja mogła też odpytywać hostowaną mapę workspace. Cursor jest udokumentowanym klientem Maguyva. Nie wybierasz jednego indeksu, kasując drugi.
Dodaj ten sam serwer Maguyva do Claude Code, Codex CLI, lub dowolnego innego klienta MCP, który dotyka repozytorium. Jedna forma klucza API. Jeden workspace.
Jeśli agent CI jest zgodny z MCP, skieruj go na ten sam serwer. Przeczyta tę samą, opatrzoną znacznikiem czasu migawkę, co laptop.

Indeks edytora pozostaje najlepszym narzędziem do pytania „co jest na dysku w tym oknie, właśnie teraz”. Hostowana mapa jest najlepszym narzędziem do pytania „jak ten workspace wygląda dla każdego agenta, który dotknie go dzisiaj”. Te zdania nie konkurują ze sobą.

Limity workspace są publikowane na stronie cen: repozytoria, zindeksowane linie i użytkownicy, rozliczani za workspace. Agenci i ludzie dzielą tę samą liczbę użytkowników. Zacznij za darmo od repozytorium, które już potrafisz ocenić. Zwiększaj workspace dopiero po tym, jak cytaty przetrwają kontakt z drzewem.

Czego ta strona nie twierdzi

Nie twierdzi, że indekser Cursor jest słaby, niekompletny albo powodem, by zmienić edytor. Pierwsze zdanie tego tekstu mówi coś przeciwnego.

Nie twierdzi, że Maguyva zastępuje Instant Grep albo subagenta Explore. To funkcje Cursor. Zostają w Cursor.

Nie wymyśla liczby języków, wartości opóźnienia ani oszczędności tokenów dla żadnego z produktów. Nieznane liczby pozostają niepublikowane.

Nie udaje, że niewypchnięta praca lokalna jest w hostowanej mapie. Migawki ze znacznikiem czasu czynią to ograniczenie widocznym. Nie usuwają go.

Test jest zwyczajny. Zindeksuj repozytorium, które już znasz. Zadaj jedno pytanie, które możesz sprawdzić, najpierw w Cursor, potem w drugim kliencie MCP. Kontekst, który podróżuje z tobą, to ten sam cytat w obu miejscach.

// same map, wherever you opened it.

Najpierw mapa, potem przegląd

Mon, 07 Sep 2026 00:00:00 GMT

Po obu stronach pull requesta znajdują się dwa różne zadania. Zanim agent napisze, potrzebuje mapy drzewa, które zamierza zmienić. Gdy agent otworzy PR, coś powinno odczytać tę zmianę na tle reszty systemu i zostawić komentarze, na podstawie których człowiek może działać.

Te zadania z daleka wyglądają podobnie, bo oba dotyczą „rozumienia bazy kodu”. To nie ten sam produkt. Jedno odpowiada na pytanie „gdzie ta zmiana powinna wylądować?”. Drugie odpowiada na pytanie „co ten diff zepsuł, czego linter przeglądający linia po linii nie zauważy?”. Pomieszanie ich daje gorszy pierwszy szkic i głośniejszy przegląd.

Ten tekst jest przewodnikiem po wspólnym przepływie pracy. Maguyva to mapa, którą agent odpytuje najpierw. Greptile to agent przeglądający, który komentuje PR potem. Ta para jest uzupełniająca się z założenia: Maguyva nie przegląda pull requestów, a Greptile nie zastępuje warstwy kontekstu, której agent użył, żeby je napisać.

Dlaczego ten podział jest przydatny

Agent kodujący, który wychodzi od wiedzy wyniesionej z treningu plus kilku wklejonych plików, wymyśli wiarygodną ścieżkę i ją edytuje. To jest porażka „złego pliku” i jest to problem wyszukiwania. Maguyva to zdalna warstwa kontekstu bazy kodu oparta na MCP: wyszukiwanie semantyczne, strukturalne (AST), grafowe/zależnościowe i tekstowe łączą się w uszeregowane wyniki, plus wyszukiwanie symboli i pobieranie plików. Ugruntowane odpowiedzi wracają jako path/file.ext:line, więc możesz odrzucić chybienie, zanim powstanie łatka. Twierdzenie pozostaje skromne: mniej zhalucynowanych edycji. Model wciąż może zgadywać. Po prostu pierwszy krok przestaje być zgadywaniem.

Greptile to agent przeglądający kod oparty na AI. Ich własnymi słowami, automatycznie przegląda każdy pull request z pełnym zrozumieniem bazy kodu, przeciwstawiając to tradycyjnym linterom, które sprawdzają pliki w izolacji, a nie cały system. Konfiguracja polega na zainstalowaniu aplikacji GitHub lub GitLab i wybraniu repozytoriów. Nie ma lokalnego indeksu, którym musiałbyś zarządzać. Hostingiem jest Greptile Cloud (deklarują zgodność z SOC 2 Type II, z raportem dostępnym na żądanie), z opcją samodzielnego hostowania oferowaną firmom.

Ich własny ponumerowany przepływ wygląda tak: połączyć się i zbudować graf zależności każdej funkcji, klasy i zależności; przy każdym pull requeście analizować zmianę, używając tego pełnego grafu repozytorium, i publikować wyniki jako komentarze PR z sugerowanymi poprawkami w około trzy minuty; każdy komentarz może przekazać problem agentowi kodującemu, którego zespół już używa. Deklarują też, że czytają wcześniejsze komentarze ludzi do PR w czasie, aby nauczyć się standardów kodowania zespołu i zmniejszyć liczbę hałaśliwych sugestii. Ich system uczący się, jak deklarują, potrzebuje 2–3 tygodni na adaptację.

To przegląd, nie tworzenie szkicu. Mocną stroną Greptile jest kontekst pełnego grafu repozytorium dotyczący zmiany, która już wylądowała w PR, a potem zamknięta pętla wysyłająca wynik do Claude Code, Codex, Conductor, Cursor lub Devin. Mocną stroną Maguyva jest uszeregowana mapa, którą agent odpytał, zanim ta zmiana została napisana. Używaj obu. Nie proś żadnego z nich o wykonanie pracy drugiego.

Integracja produktowa pierwszej strony Maguyva–Greptile nie jest zadeklarowana. Nie potrzebujesz jej też. Maguyva rozmawia z agentem przez MCP. Greptile rozmawia z GitHub lub GitLab przez swoją aplikację. Spotykają się przy pull requeście. Bez skryptu łączącego, bez crona łączącego jedno narzędzie z drugim. Ta para obywa się bez bash, bo każdy produkt już zajmuje powierzchnię, która do niego należy.

Czym to nie jest

To nie jest demolka Greptile. To nie jest strona „zmień recenzenta”. Greptile wystartował na Hacker News 5 marca 2024 roku jako firma Y Combinator W24, i ten wątek jest tym, jak wiele osób po raz pierwszy poznało ten produkt. Jeśli tak właśnie ich znalazłeś, zostań przy nich. Ta strona jest brakującą przednią połową tej pętli: ugruntowanie agenta z wyprzedzeniem, żeby PR, który widzi Greptile, już celował we właściwe pliki.

Materiały marketingowe Greptile prowadzą z twierdzeniami o szybkości przeglądu i wykrywaniu błędów. Traktuj je jako własne twierdzenia Greptile, nie jako niezależnie zweryfikowane liczby. Ten tekst nie powtarza ich jako faktów.

Pokrycie językowe to ta sama uczciwość. Greptile przedstawia wsparcie jako obejmujące wszystkie języki programowania, a nie wymienioną listę; dokładna liczba nie jest podana. Maguyva publikuje wsparcie dla ponad 279 języków i technologii tekstowych, z technicznym podziałem (AST wsparte parserem kontra tylko tekst) na stronie, gdy pytanie jest techniczne. To różne produkty, składające różne twierdzenia. Nie mieszaj ich.

Ceny Greptile nie są podane w materiałach, z których może korzystać ten tekst. Płatne plany istnieją; zobacz ich stronę cen. Maguyva pobiera opłaty za workspace, nie za miejsce. Plany zaczynają się za darmo. Strona cen wymienia opublikowane poziomy, jeśli potrzebujesz liczb dotyczących workspace.

Przepływ pracy

Trzy nazwane etapy. Wykonuj je w tej kolejności. Nie pomijaj żadnego z nich za pierwszym razem, gdy próbujesz tej pary.

1. Kontekst Maguyva

Zindeksuj jedno repozytorium, które już znasz. Połącz klienta MCP, w którym już piszesz kod — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, albo innego klienta zgodnego z MCP. Maguyva ma przewodniki konfiguracji dla 24 udokumentowanych klientów MCP i może łączyć się z innymi klientami obsługującymi standardową konfigurację MCP.

Zadaj pytanie, które możesz ocenić, zanim ktokolwiek napisze linijkę. „Gdzie obsługiwane jest wygaśnięcie sesji i co to wywołuje?” to lepsze pierwsze posunięcie niż „napraw uwierzytelnianie”. Wymagaj cytatów. Otwórz wyniki file.ext:line. Podążaj za symbolem. Potwierdź zależność, której zamierzasz dotknąć.

Maguyva udostępnia 11 skierowanych do klienta narzędzi MCP w zakresie wyszukiwania, symboli, analizy zależności, pobierania plików, kontekstu repozytorium i deterministycznych przepływów narzędziowych. Cztery tryby wyszukiwania łączą się w uszeregowane wyniki; find_symbol to osobne narzędzie, gdy już znasz nazwę. Dokumentacja opisuje najkrótszą ścieżkę: zacznij za darmo, zindeksuj repozytorium, które już znasz, połącz klienta, potem zadaj jedno pytanie, które możesz sprawdzić.

Migawki są opatrzone znacznikiem czasu, więc agent może stwierdzić, którą wersję drzewa czyta. Uczciwym ograniczeniem jest niezsynchronizowana praca lokalna. Jeśli edycja istnieje tylko w drzewie roboczym i nie została wypchnięta, hostowana mapa jeszcze jej nie zawiera. Pliki instrukcji (CLAUDE.md, AGENTS.md) nadal mają tu swoje miejsce, dla konwencji i tego, czego nie dotykać. Nie są żywą mapą. Używaj ich do zachowania. Używaj Maguyva do faktów.

Nie pozwól agentowi otworzyć PR, zanim cytaty przetrwają kontakt z repozytorium. Ta bramka to cały sens tego etapu.

2. PR agenta

Ten sam agent teraz pisze zmianę w kliencie, za który już płacisz. Maguyva nie jest edytorem ani recenzentem. Agent nadal produkuje diff. Ty nadal otwierasz pull request na GitHub lub GitLabie, tak jak już to robisz.

To, co powinno być inne, to pierwszy plik. PR powinien wskazać handler, który rzeczywiście implementuje zachowanie, wywołującego, który się zepsuje, oraz test, który zawiedzie, jeśli zmiana jest błędna. Jeśli etap 1 został pominięty, etap 3 wyda swoje komentarze na zmianę, która wylądowała w złym pakiecie. Greptile wciąż może znaleźć problemy systemowe. Nie powinien musieć dodatkowo dochodzić do siebie po zhalucynowanej ścieżce.

Trzymaj PR w ryzach. Ugruntowany pierwszy plik to nie licencja na przepisanie modułu. Ta uzupełniająca się para działa, gdy agent wykonał jedną pracę z mapą, a potem poprosił recenzenta o wykonanie innej pracy na ograniczonym diffie.

3. Przegląd Greptile

Greptile jest już połączony z repozytorium przez aplikację GitHub lub GitLab. Na nowym pull requeście analizuje zmianę, używając zbudowanego przez siebie pełnego grafu repozytorium, i publikuje wyniki jako komentarze z sugerowanymi poprawkami. Ich własne materiały określają ten przebieg na około trzy minuty.

Czytaj komentarze tak, jak czytałbyś uważnego kolegę z zespołu: otwórz zacytowane miejsce, zdecyduj, czy wynik jest prawdziwy, potem działaj. Tam, gdzie Greptile oferuje „Fix with your Agent”, wysyła problem — ścieżki plików, numery linii, sugerowany kod — do Claude Code, Codex, Conductor, Cursor lub Devin. „Fix All” wysyła wszystkie problemy z przeglądu naraz. Dostarczają też Greptile MCP i wtyczkę Claude Code do tego przekazania. Maguyva nie ma na tej wymienionej liście celów; ten brak nie jest problemem. Maguyva wykonała już swoją pracę na etapie 1. Agent kodujący, który napisał PR, jest tym, który powinien otrzymać ładunek naprawczy.

Spodziewaj się szumu przez pierwsze 2–3 tygodnie, gdy system uczący się Greptile adaptuje się do komentarzy, które twój zespół rzeczywiście zostawia. To ich zadeklarowany harmonogram, nie wada tej pary. Przegląd przez człowieka pozostaje w pętli. Greptile to zautomatyzowany pierwszy przebieg, nie przycisk scalania.

Jeśli komentarz Greptile wskazuje na plik, którego agent nigdy nie odpytał na etapie 1, to przydatny sygnał. Albo mapa przeoczyła wywołującego, albo agent pominął cytat. Popraw szkic zgodnie z komentarzem. Nie wyłączaj recenzenta.

Jak zachować uczciwość tego uzupełniania się

Maguyva zawsze pierwsza. Przegląd PR ze złym plikiem nadal jest przeglądem złego pliku.
Greptile zawsze potem. Dobrze zacytowany szkic i tak potrzebuje odczytu diffa na poziomie całego systemu.
Nie proś Maguyva o publikowanie komentarzy do PR. Ona tego nie robi.
Nie proś Greptile o bycie pierwszą warstwą wyszukiwania agenta, gdy ten wciąż wybiera ścieżkę. To nie jest praca, do której zbudowana jest ich aplikacja GitHub lub GitLab.
Nie wymyślaj pipeline’u bash, który je „synchronizuje”. PR jest interfejsem.
Weryfikuj obie strony niezależnie. Zindeksuj repozytorium, które już znasz. Zadaj jedno pytanie, które możesz sprawdzić. Potem otwórz mały PR i przeczytaj, co Greptile faktycznie komentuje.

Gdy nadać temu nazwę, pętla staje się zwyczajna. Najpierw mapa. Potem PR agenta. Potem przegląd. Każdy produkt zostaje po tej stronie pull requesta, w której jest dobry.

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

Dać agentowi AI kontekst dużego repozytorium bez lokalnego indeksera

Fri, 14 Aug 2026 00:00:00 GMT

Duże repozytorium nie mieści się w oknie kontekstu, a jeśli kiedykolwiek skierowałeś indekser laptopa na prawdziwe monorepo, wiesz, że tam też nie mieści się wygodnie — RAM skacze, pierwsze indeksowanie trwa godzinę, a twój agent i tak zaczyna kolejną sesję od zgadywania, które pliki mają znaczenie.

Zwykłą odpowiedzią jest uruchomienie indeksera obok edytora i dla repozytorium, które wygodnie mieści się na jednej maszynie, to dobra odpowiedź. Jeśli twoje monorepo już szybko indeksuje się w Cursor, a to jedyne miejsce, w którym potrzebujesz mapy, ten tekst nie ma nic do dodania — pomiń go.

Ten tekst dotyczy innego przypadku — kiedy agent potrzebuje przeszukiwalnej mapy dużego repozytorium, a ty nie chcesz uruchamiać do tego lokalnego indeksera.

Kiedy lokalny indekser jest złym narzędziem

Lokalny indeks zakłada, że kod żyje na maszynie, która go odpytuje, a przy prawdziwej skali monorepo to założenie napina się nawet wewnątrz jednego edytora. Repozytorium jest po prostu większe, niż chcesz trzymać „rozgrzane” na laptopie: pracujesz w jednym pakiecie, podczas gdy zasięg wpływu leży trzy katalogi dalej, a pierwsze, zimne indeksowanie drzewa liczącego dwa miliony linii to nie jest coś, co chcesz przeżyć dwukrotnie — ani na własnej maszynie, ani na runnerze CI, który nigdy wcześniej nie sklonował tego drzewa. Albo współpracownik powinien móc odpytywać tę samą mapę co ty, nie czekając, aż jego własna maszyna przebrnie przez ten sam indeks.

Nic z tego nie jest powodem, by wyrzucać dobry indekser edytora. To powód, by mieć dodatkowo hostowaną mapę, którą każdy z twoich agentów może odpytać przez MCP.

A problem skali sięga głębiej niż „za dużo plików, żeby je wkleić”. Na dużym drzewie interesujące pytanie prawie nigdy nie brzmi „pokaż mi ten plik” — brzmi który plik, który symbol, którzy wywołujący, które testy. Agent, który zaczyna od wylistowania src/ i przeczytania pierwszych trzech wyników, beztrosko przeoczy handler w apps/api i wygenerowany klient w packages/sdk. Potrzebujesz wyszukiwania zbudowanego z całego drzewa, potem uszeregowanego, potem zacytowanego.

Co naprawdę oznacza „kontekst dużego repozytorium”

Wrzucanie plików do promptu to nie kontekst — to mniejsza, gorsza kopia drzewa. To, czego naprawdę potrzebuje twój agent, to zadawanie pytań i otrzymywanie w odpowiedzi zacytowanych odpowiedzi: gdzie zdefiniowano ten symbol i kto go wywołuje, co zależy od modułu, który zamierzam zmienić, który plik testu obejmuje to zachowanie, i jak drzewo wygląda teraz, a nie w zeszłym kwartale.

Te odpowiedzi muszą pochodzić z indeksu zbudowanego z twojego repozytorium, a nie z pamięci modelu o cudzych repozytoriach, a ten indeks musi żyć gdzieś poza oknem kontekstu agenta. W tym problemie powinien też żyć gdzieś poza twoim laptopem.

Jeszcze jedna rzecz, której pliki instrukcji nie mogą za ciebie zrobić: CLAUDE.md i AGENTS.md to właściwe miejsce na konwencje i zachowanie, ale nie są żywą, uszeregowaną, przeszukiwalną mapą drzewa liczącego dwa miliony linii. Używaj reguł do zachowania; używaj inteligencji repozytorium do faktów.

Budujemy mapę w chmurze, odpytujemy ją z dowolnego klienta

Maguyva to zdalna warstwa kontekstu bazy kodu oparta na MCP. Łączysz GitHub, wybierasz swoje repozytoria i możesz odejść, podczas gdy chmurowe pipeline’y parsują drzewo, budują symbole i krawędzie grafu oraz utrzymują uszeregowaną mapę — nigdy bez lokalnego indeksera.

Gdy wypychasz kod, zmienione pliki są parsowane przyrostowo, a warstwy grafu i rankingu przebudowują się według harmonogramu: codziennie w planie darmowym, co godzinę w płatnych. Każda migawka jest opatrzona znacznikiem czasu, więc twój agent może stwierdzić, którą wersję drzewa czyta. Uczciwym ograniczeniem jest tu niezsynchronizowana praca lokalna — edycja istniejąca tylko w twoim drzewie roboczym, nigdy niewypchnięta, jeszcze nie jest w hostowanej mapie.

Potem podłączasz dowolnego klienta, którego już używasz, dodając klucz API do jego konfiguracji MCP. Istnieją przewodniki konfiguracji dla 24 udokumentowanych klientów MCP, a każdy inny klient zgodny z MCP, który obsługuje standardową konfigurację, też może się połączyć. Jeśli Cursor jest twoim domem, strona Cursor przeprowadzi przez tę ścieżkę; ten sam serwer odpowiada Claude Code, VS Code, Windsurf, Codex CLI i innym.

Nie zmieniasz edytora. Dajesz swojemu agentowi powierzchnię narzędzi — 11 narzędzi MCP w zakresie wyszukiwania, symboli, analizy zależności, pobierania plików i kontekstu repozytorium — z pokryciem ponad 279 języków i technologii tekstowych, co znaczy więcej, niż myślisz, na monorepo, które przestało być jednojęzyczne wiele lat temu.

Odpowiedzi wracają ugruntowane, jako ścieżki plików z numerami linii. Wyszukiwanie semantyczne, strukturalne, grafowe i tekstowe są łączone w uszeregowane wyniki, więc pytanie w rodzaju „co zależy od parseConfig” daje nie zrzut grep ani pojedynczy fragment semantyczny, tylko garść miejsc, które naprawdę mają znaczenie.

Konkretna instrukcja

Nie zaczynaj od zindeksowania całej firmy. Oto ścieżka, która działa:

Wybierz jedno repozytorium, które już dobrze znasz — pakiet, który potrafisz ocenić ręcznie, jest wart więcej niż największe drzewo, jakie masz.
Zacznij za darmo: 3 repozytoria, 50 tys. zindeksowanych linii, wszystkie 11 narzędzi, bez miesięcznego limitu zapytań. Jeśli twoje reprezentatywne repozytorium jest większe, strona cen wymienia poziomy workspace ($0, $19, $49, $149) według zindeksowanej objętości — nie liczby miejsc.
Połącz GitHub i poczekaj na zakończenie pierwszego indeksowania. Nie kompilujesz niczego lokalnie.
Podłącz klienta MCP — kilka linii konfiguracji. Maguyva to zdalny serwer MCP, więc nie ma wtyczek, rozszerzeń ani drugiego edytora do przyswojenia.
Zadaj jedno pytanie, które możesz sprawdzić. „Co zależy od parseConfig?” albo „Gdzie obsługiwane jest wygaśnięcie sesji logowania?” Potem otwórz zacytowane wyniki file.ext:line i sprawdź je względem drzewa przed tobą.
Dopiero gdy cytaty przetrwają ten kontakt, pozwól agentowi edytować.

Jeśli pierwsze repozytorium dobrze pasuje, a twoje drzewo jest duże, podnieś workspace, dopasowując go do zindeksowanych linii i częstotliwości przebudowy. Ludzie i agenci dzielą tę samą liczbę użytkowników — Maguyva pobiera opłaty za workspace, nie za miejsce — więc dodanie trzeciego agenta do pętli nic cię nie kosztuje.

Test aktywacji jest taki sam, jak dokumentacja zaleca przy każdym pierwszym uruchomieniu: zindeksuj repozytorium, które już znasz, zadaj jedno pytanie, które możesz sprawdzić. Duże repozytorium nie zmienia testu; sprawia tylko, że błędny pierwszy plik jest droższy.

Na co zwracać uwagę po podłączeniu

Miej oko na trzy rzeczy. Aktualność: plany płatne przebudowują się co godzinę, darmowe codziennie, a niewypchnięta praca lokalna nie znajdzie się w mapie — to kompromis, na który się godzisz. Zakres: indeksuj reprezentatywny zbiór repozytoriów, nie każdy zarchiwizowany fork; darmowy poziom jest celowo tak dobrany, by dowiedzieć się, czy odpowiedzi warte są zachowania. I weryfikacja: mapa dużego repozytorium, która nie potrafi zacytować ścieżek i numerów linii, jest po prostu wolniejszym silnikiem zgadywania, więc niech twój agent pokaże lokalizację, zanim dostarczy łatkę.

Potem uruchom ten sam test, który uruchomiłbyś na małym repozytorium. Zindeksuj repozytorium, które już znasz. Zadaj jedno pytanie, które możesz sprawdzić. Jeśli mapa jest prawdziwa, twój agent przestanie zaczynać od zimnego drzewa.

// no laptop got hot building this map.

Dlaczego twój agent AI do kodowania halucynuje ścieżki plików

Fri, 14 Aug 2026 00:00:00 GMT

Sygnałem nie jest błędne ciało funkcji. To pewna siebie edycja pliku, który nie istnieje, albo pliku, który istnieje, ale nie jest tym, który implementuje dane zachowanie.

Poprosiłeś o naprawę wygasania sesji. Agent otworzył src/auth/session.ts. Ta ścieżka jest wiarygodna. Jest też błędna. Prawdziwy handler żyje w apps/api/src/middleware/expiry.ts, przemianowanym dwa refaktoringi temu. Agent cię nie okłamał. Uzupełnił łańcuch w kształcie ścieżki na podstawie wiedzy wyniesionej z treningu plus tego, co już było w oknie kontekstu.

To powszechny wzorzec porażki na prawdziwym repozytorium. Model potrafi pisać kod. Błędem jest wybór złego miejsca, żeby go napisać.

Dlaczego agenci wymyślają ścieżki

Agent kodujący to model przewidywania następnego tokena wyposażony w narzędzia. Gdy mówisz „napraw wygasanie sesji”, musi wskazać plik, zanim będzie mógł cokolwiek przeczytać lub załatać. Jeśli nie ma jeszcze ugruntowanej mapy, konstruuje ścieżkę z:

Konwencji nazewnictwa, które widział w innych repozytoriach. src/auth/session.ts to częsty kształt.
Plików już obecnych w rozmowie, które mogą być tymi, które wkleiłeś w zeszłym tygodniu, a nie tymi, które liczą się teraz.
Listingów katalogów, które przypadkiem uruchomił, niekompletnych na dużym drzewie.
Plików instrukcji. CLAUDE.md i AGENTS.md mówią agentowi, jak się zachowywać. Nie są żywym indeksem symboli, wywołujących ani aktualnych ścieżek.

Żadne z tych źródeł nie jest mapą tego repozytorium, dzisiaj. Model wypełnia lukę tak samo, jak wypełnia każdą lukę: kontynuacją o wysokim prawdopodobieństwie. Ta kontynuacja często wygląda jak prawdziwa ścieżka. Czasem plik istnieje i leży obok właściwego. Czasem istniał na branchu scalonym w zeszłym miesiącu. Czasem nigdy nie istniał.

Grep cię tu nie uratuje, jeśli agent w ogóle nie szuka właściwego ciągu znaków. Agent zgadł ścieżkę, potem przeczytał, co ta ścieżka zwróciła, potem ją edytował. Pierwszym błędnym krokiem była ścieżka, nie łatka.

Czytanie plików to też nie to samo, co znajdowanie właściwych. Claude Code, Cursor, Codex i podobne narzędzia mogą otworzyć wszystko, na co je skierujesz. Pytanie brzmi, czy niezawodnie znajdują właściwe pliki, ważne symbole, zależności, testy i zasięg wpływu, zanim zaczną edytować. Dostęp do plików bez mapy nadal zaczyna się od zgadywania.

Edycja złego pliku to problem wyszukiwania

Traktuj wymyśloną ścieżkę jako chybienie wyszukiwania, nie jako wadę charakteru.

Gdyby agent musiał zwrócić path/file.ext:line, zanim pozwolono by mu edytować, wydarzyłyby się dwie rzeczy. Po pierwsze, mógłbyś otworzyć cytat i odrzucić pracę w dziesięć sekund. Po drugie, agent musiałby odpytać coś, co rzeczywiście zna to drzewo.

To jest praca warstwy kontekstu bazy kodu. Samo wyszukiwanie semantyczne to za mało. Fragment, który „brzmi jak wygasanie sesji”, i tak może wylądować w wycofanym pakiecie. Potrzebujesz też dokładnego tekstu, gdy znasz ciąg znaków, wyszukiwania symboli, gdy znasz nazwę, wyszukiwania strukturalnego, gdy znasz kształt, oraz grafu zależności, gdy potrzebujesz wywołujących i zasięgu wpływu.

Maguyva jest tą warstwą dla agentów kodujących zgodnych z MCP. To nie jest edytor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf i inni klienci MCP zostają tam, gdzie są. Agent odpytuje uszeregowaną mapę, zanim dotknie linijki.

Twierdzenie jest celowo skromne: mniej zhalucynowanych edycji. Maguyva nie odbiera modelowi zdolności do zgadywania. Zmienia domyślny pierwszy krok z „wymyśl wiarygodną ścieżkę” na „poproś o uszeregowane, zacytowane lokalizacje”.

Jak wygląda ugruntowana odpowiedź

Użyteczna odpowiedź na pytanie „gdzie obsługiwane jest wygasanie sesji” to nie akapit. To krótka lista lokalizacji:

apps/api/src/middleware/expiry.ts:48 - handler
apps/web/src/lib/auth-client.ts:112 - wywołujący
apps/api/tests/expiry.test.ts:20 - test, który zawiedzie, jeśli zmiana jest błędna

Możesz otworzyć te linie. Jeśli są błędne, zatrzymujesz się. Jeśli są poprawne, agent może edytować. Chodzi o weryfikację, nie o hasło.

Maguyva udostępnia 11 skierowanych do klienta narzędzi MCP w zakresie wyszukiwania, symboli, analizy zależności, pobierania plików, kontekstu repozytorium i deterministycznych przepływów narzędziowych. Cztery tryby wyszukiwania (semantyczny, strukturalny, grafowy/zależnościowy i tekstowy) łączą się w uszeregowane wyniki; wyszukiwanie symboli to osobne narzędzie MCP (find_symbol). Ugruntowane odpowiedzi wracają ze ścieżkami plików i numerami linii, więc możesz je oceniać na tle drzewa przed tobą.

Dokumentacja opisuje najkrótszą ścieżkę: zacznij za darmo, zindeksuj repozytorium, które już znasz, połącz klienta, potem zadaj jedno pytanie, które możesz sprawdzić.

Pętla, która zmienia pierwszą edycję

Nie potrzebujesz nowej religii przepływu pracy. Potrzebujesz jednego dodatkowego kroku przed pierwszym zapisem.

Zadaj pytanie, które już możesz ocenić. „Jaki kod obsługuje logowanie i wygasanie sesji?” jest lepsze niż „napraw uwierzytelnianie”.
Wymagaj cytatów. Ścieżki pliku i numeru linii, nie streszczenia „modułu uwierzytelniania”.
Otwórz zacytowane pliki. Podążaj za symbolem. Potwierdź zależność, której zamierzasz dotknąć.
Dopiero wtedy pozwól agentowi załatać.

Jeśli krok 2 nie zwraca niczego użytecznego, agent nie ma prawa improwizować ścieżki. Szuka ponownie albo ty mu wskazujesz. Właśnie ta jedna bramka wytwarza mniej zhalucynowanych edycji. Model jest tym samym modelem. To, co się zmieniło, to mapa.

Pliki instrukcji nadal mają znaczenie. Zachowaj je. Używaj ich do konwencji, reguł przeglądu i tego, czego nie dotykać. Nie proś ich, żeby były indeksem. CLAUDE.md wymieniający trzy ważne katalogi zdezaktualizuje się tydzień po podziale pakietu. Przeszukiwalna mapa aktualizuje się, gdy aktualizuje się repozytorium.

Pokrewną porażką jest plik prawie trafiony: agent otwiera auth.ts, gdy zachowanie żyje w auth-client.ts, albo łata wygenerowany plik zamiast źródła, albo edytuje kopię w packages/legacy, bo nazwa pasowała. Cytaty nie sprawiają, że te pomyłki stają się niemożliwe. Sprawiają, że stają się widoczne, zanim diff wyląduje.

Czego mapa za ciebie nie naprawi

Bądź trzeźwy co do tego, co dostajesz. Ugruntowana mapa nie sprawi, że każda edycja będzie poprawna — twój agent nadal może napisać złą łatkę dokładnie we właściwym pliku. Jeśli twoja baza kodu opiera się na dynamicznym dispatchu, refleksji albo monkey-patchingu, niektóre wyszukiwania symboli będą wracać skromniejsze, niż byś chciał, bo to właśnie robi z każdym statycznym indeksem pośredniość w czasie działania. A jeśli liczysz na procent — „ścieżki halucynowane zredukowane o X%” — nie znajdziesz go tutaj, bo nikt poza tobą nie może uczciwie zmierzyć tej liczby dla twojego repozytorium.

To, czego możesz oczekiwać, jest węższe i bardziej użyteczne: agent przestaje zaczynać edycje od zgadniętej ścieżki. Ten pierwszy krok staje się ugruntowany w prawdziwej mapie, i stąd bierze się mniej zhalucynowanych edycji. Wszystko po cytacie — czytanie diffa, ocena łatki — nadal jest twoją pracą, tak jak zawsze było.

Ten test kosztuje cię niemal nic: zindeksuj repozytorium, które już znasz, i zadaj jedno pytanie, które możesz sprawdzić. Zacznij od ścieżki, na której już się kiedyś sparzyłeś. Jeśli cytaty są błędne, zobaczysz to od razu. Jeśli są poprawne, kolejna edycja twojego agenta będzie miała lepsze miejsce, żeby wylądować.

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

Dlaczego zaktualizowaliśmy wyszukiwanie kodu do voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Liczby benchmarków w tym wpisie odzwierciedlają rankingi RTEB w momencie publikacji (czerwiec 2026). Rankingi się zmieniają; traktuj je jako zrzut z danego momentu, nie trwały fakt.

Wyszukiwanie semantyczne jest tak dobre, jak leżące u jego podstaw embeddingi.

Gdy agent pyta Maguyva „gdzie obsługujemy ponowienia”, nie grepuje słowa „retry”. Pyta o znaczenie — pętlę backoff, mechanizm circuit breaker, coś, co opakowuje niestabilne wywołanie. Na to pytanie odpowiada model wektorowy, który zamienia kod w punkt w przestrzeni i znajduje sąsiadów. Wybierz lepszy model, a wyniki każdego zapytania semantycznego w produkcie po cichu stają się trafniejsze.

Więc zmieniliśmy nasz. Od czerwca 2026 embeddingi kodu Maguyva działają na voyage-4-large, zastępując voyage-code-3.

Benchmark

Nie podjęliśmy tej decyzji na wyczucie. Publiczny Retrieval Embedding Benchmark (RTEB) rankinguje modele embeddingów na prawdziwych zadaniach wyszukiwania, a na jego rankingu Code voyage-4-large zajmuje #1 ogółem (90,86) — przed gemini-embedding-2-preview (90,26) i, co istotne, przed modelem, którego już używaliśmy, voyage-code-3 (89,73, #3).

To niewielka różnica bezwzględna. Ale to różnica we właściwym kierunku, na publicznym benchmarku, w dokładnie tym zadaniu, na którym nam zależy: wydobywaniu kodu według znaczenia.

Kompromis, który akceptujemy: kwantyzacja binarna

Oto część, którą pomija większość wpisów typu „zaktualizowaliśmy nasz model”.

Maguyva nie przechowuje wektorów pełnej precyzji. Przechowujemy embeddingi skwantyzowane binarnie: każdy 2048-wymiarowy wektor zwija się do 2048-bitowej sygnatury — 256 bajtów na wektor. Te sygnatury są przeszukiwane przy użyciu odległości Hamminga, zaindeksowane i podzielone na partycje per tenant.

To celowy kompromis. Kwantyzacja binarna rezygnuje z części precyzji wyszukiwania w zamian za znacznie mniejsze zużycie miejsca oraz szybkie, tanie obliczanie odległości bez osobnej bazy wektorowej do utrzymywania. Dla produktu, który indeksuje całe repozytoria per workspace, ta ekonomia ma większe znaczenie niż wyciśnięcie ostatniego ułamka punktu benchmarku.

voyage-4-large pasuje do tego projektu bez wymuszania migracji warstwy przechowywania: produkuje wyjście 2048-wymiarowe, tak jak voyage-code-3, więc nasze kolumny bit(2048) i ścieżka wyszukiwania Hamminga się nie zmieniły. Model się poprawił; schemat pozostał na miejscu.

Kod to był dopiero początek

Maguyva to narzędzie inteligencji kodu. Ale jesteśmy też klientem zero i kierujemy je na coś jeszcze: markdown, który żyje w naszych repozytoriach obok kodu. Rekordy decyzji architektonicznych, runbooki, kontrakty, dokumenty finansowe i wewnętrzne regulaminy — wszystko to wersjonowane w Git, wszystko za tym samym serwerem MCP, semantyczny indeks nad dokumentami, nie tylko nad źródłem.

Właśnie dlatego szerokość voyage-4-large ma znaczenie. Na tej samej rodzinie rankingów RTEB jest #1 w finansach, #1 w ochronie zdrowia i #1 w ogólnym wyszukiwaniu tekstowym — przed Gemini Embedding od Google, Embed v4 od Cohere i text-embedding-3-large od OpenAI. (Voyage jest współtwórcą RTEB, więc czytamy to jako silny sygnał publiczny, a nie idealnie neutralnego sędziego — ale jest benchmarkowany bezpośrednio z każdym większym modelem komercyjnym, na prywatnych zbiorach hold-out). Ten sam indeks, który znajduje właściwą funkcję dla agenta, znajduje właściwą klauzulę w kontrakcie lub właściwy zapis w wewnętrznym regulaminie — a w tych domenach voyage-4-large to nie kompromis, to lider.

Dlaczego płacimy za embeddingi premium

Istnieje tańszy sposób na wyszukiwanie, a znaczna jego część jest darmowa. Wyszukiwanie leksykalne — BM25 i jego krewni — dopasowuje słowa kluczowe, działa lokalnie i nic nie kosztuje. Modele embeddingów open source, takie jak BGE, Nomic i embeddinggemma, dają naprawdę przyzwoite wyszukiwanie semantyczne, i możesz je hostować samodzielnie za cenę GPU. Maguyva korzysta też ze strony darmowej: każde zapytanie łączy wyszukiwanie tekstowe, AST, grafowe i semantyczne. Nie oszczędzamy na warstwie semantycznej.

Płacimy za token za embeddingi premium — voyage-4-large — zamiast hostować darmowy model samodzielnie, z dwóch powodów. Po pierwsze, samo wyszukiwanie słów kluczowych nie potrafi odpowiedzieć na „gdzie obsługujemy ponowienia”, gdy kod mówi backoff i circuit breaker, a nigdy nie mówi słowa „retry” — znaczenie to cały sens embeddingu, a w domenach, które obsługujemy, modele open source zostają w tyle za modelami premium: kilka punktów w tekście ogólnym, i jeszcze bardziej w niszach takich jak kod, kontrakty i finanse. Po drugie, z naszego doświadczenia jakość wyszukiwania kształtuje ostateczną odpowiedź bardziej niż model po drugiej stronie — silny agent otrzymujący niewłaściwy kontekst i tak odpowie źle, i nigdy nie zobaczy dokumentu, którego mu nigdy nie dano.

Więc embeddingi premium to rachunek za token, który skaluje się z każdym repozytorium i dokumentem, który indeksujemy — i płacimy go celowo. Dla wyniku, jaki dostają nasi użytkownicy, właściwej funkcji lub właściwej klauzuli, uważamy, że ten kompromis jest wart tego.

Uczciwa część

Własna dokumentacja Voyage wciąż oznacza voyage-code-3 jako model zoptymalizowany pod kod. Więc dlaczego zmiana?

Ponieważ czytamy publiczny benchmark, nie tylko tabelę modeli dostawcy, a benchmark postawił voyage-4-large na szczycie dla wyszukiwania kodu. To była decyzja patrząca w przyszłość: wziąć nowszy, ogólnie silniejszy model i zwalidować go względem publicznego rankingu na zadaniach, które mają znaczenie. Czujemy się komfortowo, podejmując ten zakład, ponieważ dowody są szerokie — voyage-4-large nie wygrywa tylko na kodzie, przoduje też w finansach, ochronie zdrowia i ogólnym wyszukiwaniu.

Niepozorny fundament

Każde narzędzie, które udostępniamy — wyszukiwanie semantyczne, gromadzenie kontekstu zadania, ugruntowane pytania i odpowiedzi — ostatecznie opiera się na wyszukiwaniu. Gdy retriever się poprawia, agent po drugiej stronie dostaje lepsze dowody, rzadziej podejmuje błędne decyzje i zakotwicza swoje odpowiedzi we właściwym kodzie — albo we właściwej klauzuli, albo we właściwym wewnętrznym regulaminie. Trafniejszy model embeddingów to nie efektowna funkcja. To fundament wszystkich pozostałych funkcji, który właśnie wzmocniliśmy. Nie zauważysz tego. O to właśnie chodzi.

Rekurencyjne samodoskonalenie językowe: szlifowanie inteligencji kodu w ~280 językach

Tue, 26 May 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (maj 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Maguyva ekstrahuje symbole, referencje i graf zależności z kodu źródłowego w około 280 językach. Każdy język to niestandardowy handler tree-sitter — zapytania, heurystyki, przypadki brzegowe — i każdy handler może być subtelnie błędny na swój własny sposób. Wywołanie metody wyemitowane jako odczyt. Funkcja przypisana do niewłaściwego zakresu otaczającego. Relacja, której po prostu nie ma.

Tego nie da się ręcznie zweryfikować. Żaden zespół nie przeczyta wyników ekstrakcji w 280 gramatykach i nie wyłapie złych krawędzi. Więc ciekawym pytaniem nie jest „czy nasza ekstrakcja jest poprawna” — tylko „jak odkryć, że jest błędna, przy tej skali, bez człowieka w każdej pętli”. Naszą odpowiedzią jest rekurencyjne samodoskonalenie językowe: pętla jakości napędzana przez agentów językowych, LLM działający jako sędzia i jedna zasada, której wciąż się na nowo uczymy: zielone nie znaczy poprawne.

Zielone nie znaczy poprawne

Każdy język ma zestaw fixture’ów, a kontrola przed wydaniem ocenia go w pięciu wymiarach — dokładność, integralność strukturalna, kompletność, jakość i wydajność. Język staje się ZIELONY tylko wtedy, gdy na swoich fixture’ach precyzja ≥ 0,95, recall ≥ 0,99, a F1 ≥ 0,97, przy co najmniej 20 oczekiwanych krawędziach dla wiarygodności statystycznej. Poniżej tego jest ŻÓŁTY lub CZERWONY i nie trafia do wydania.

Ta kontrola jest konieczna, ale niewystarczająca. Walidacja opiera się na fixture’ach, które sami napisaliśmy. Kodują przypadki, o których już pomyśleliśmy. Handler może być bezbłędny na swoich fixture’ach i wciąż zniekształcać wzorzec, który pojawia się tylko w prawdziwym kodzie — idiom makra, metodę z ograniczeniami parametrów typu generycznego, cechę języka, dla której nikt nie napisał fixture’a. ZIELONY oznacza, że fixture’y przechodzą. Nie oznacza, że prawdziwe repozytorium ekstrahuje się czysto. Więc pętla musi zostawić fixture’y za sobą i sprawdzić kod z rzeczywistych projektów.

Pętla wewnętrzna: wyrywkowa kontrola, sędzia, naprawa, dowód

Główna pętla działa po jednym języku naraz:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  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) ──┘

Kilka rzeczy sprawia, że to działa, a nie tylko się miota.

Sędzią jest agent, nie wywołanie API. Gdy mówimy „LLM jako sędzia”, mamy na myśli to, że sam agent językowy czyta każdą próbkowaną krawędź na tle prawdziwego źródła i klasyfikuje ją według stałego schematu pięciu kategorii: czy ta krawędź jest poprawna, jest fałszywie pozytywna, ma właściwą relację, ale zły typ, jest przypisana do niewłaściwego zakresu, czy niesie błędne metadane? Ten schemat ma kluczowe znaczenie — „23% wskaźnik błędów” nic nie znaczy, dopóki nie wiesz, czy to prawdziwe defekty, czy sędzia się myli w liczeniu.

Napraw jedną rzecz, a potem to udowodnij. Każda iteracja zmienia dokładnie jeden edytowalny zasób, a następnie ponownie uruchamia się względem stałego harnessu i zachowuje zmianę tylko wtedy, gdy F1 się poprawia, a ponowna klasyfikacja wygląda lepiej. Jeśli nie — wraca do poprzedniego stanu. Żadnych partii spekulatywnych edycji, żadnego „powinno być lepiej”. Zmiana zarabia na swoje miejsce albo znika. A gdy naprawa się utrzyma, jest promowana do zestawu fixture’ów — więc błąd, który naprawiła, nigdy po cichu nie wróci. Ten krok promocji jest tym, co czyni pętlę rekurencyjną, a nie tylko powtarzalną: każdy przebieg wzmacnia wzorzec odniesienia, względem którego walidowane są wyniki kolejnego przebiegu.

Lekcja, której wciąż się na nowo uczymy: metryki zawyżają

Oto pułapka, w którą wpadliśmy wprost. Drugorzędne metryki korpusu — jak często wyekstrahowanego celu nie da się powiązać z symbolem, ile symboli wygląda na „osierocone” i tak dalej — masowo zawyżają problemy. To w większości artefakty paradygmatu, nie błędy.

Najczystszy przykład: llvm pokazał kiedyś 73% wskaźnik „źródła bez symbolu” i został naznaczony jako katastrofalny. Wgłębiliśmy się. Prawdziwa dokładność wynosiła 98,5%. „Brakujące symbole” były niemal wszystkie poprawnymi referencjami zewnętrznymi — wywołaniami do biblioteki standardowej, do frameworków, do kodu żyjącego poza repozytorium. Metryka mierzyła właściwość języka, nie defekt handlera. Języki takie jak Zig, COBOL i Odin pokazują wskaźniki „osierocenia” na poziomie 65–70% i są całkowicie poprawne; COBOL nie miał ani jednego prawdziwego błędu.

Gdybyśmy pozwolili tym liczbom kierować pracą, spędzilibyśmy tygodnie na „naprawianiu” handlerów, które już były poprawne, ignorując języki z cichymi, prawdziwymi błędami. Wniosek jest brutalny: zagregowane metryki są w najlepszym razie zgrubnym sygnałem triażu. Prawdziwym sygnałem jakości jest wyrywkowa kontrola z klasyfikacją krawędzi — patrzenie na rzeczywiste krawędzie w rzeczywistych repozytoriach i osądzanie ich jedna po drugiej. Dane ponad intuicję, ale dopiero gdy wiesz, które dane mówią prawdę.

Pętla zewnętrzna: flota, nie maraton

Jeden język naraz zająłby wieczność przy 280 z nich, więc pętla wewnętrzna jest owinięta w zewnętrzną, która uruchamia wiele równolegle.

   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żdy agent pracuje w jednorazowym worktree, więc nie mogą sobie wchodzić w drogę. Orkiestrator integruje ich poprawki jedna po drugiej, każdą po pełnej kontroli regresji obejmującej cały manifest: zmiana, która pomaga własnemu językowi, ale po cichu psuje trzy inne, nie trafia do repozytorium. Integracja jest weryfikowana i zatwierdzana, zanim cokolwiek zostanie wypchnięte — kontrola regresji decyduje, co jest bezpieczne, człowiek wciąż decyduje, co trafia do wydania. Następnie pula rotuje do kolejnego zestawu języków i całość uruchamia się od nowa.

Co wciąż jest niedoskonałe

Sędzia może się mylić, a błąd ma kierunek: agent działający ze zbyt małym kontekstem zawyża zgłoszenia. W jednej partii osiem języków zostało oznaczonych jako mające 5–20% błędów; po inspekcji tylko w jednym z nich potwierdzono rzeczywisty błąd — reszta to pomyłki sędziego wynikające z pominięcia własnej semantyki danego języka (jedna linia źródła poprawnie emitująca kilka krawędzi, wiązania parametrów modelowane jako przypisania, języki z jedną referencją na identyfikator). Dlatego próbkujemy z dwoma ziarnami i krzyżowo weryfikujemy, i dlatego niezgodność między sędzią a fixture’ami jest traktowana jako najciekawszy sygnał, nie jako rozstrzygnięty werdykt — czasem to fixture jest tym, co jest błędne.

Jesteśmy też uczciwi co do celu. Celem jest zero prawdziwych błędów, kropka — ale „zero” to cel, do którego dążymy, doskonaląc obsługę kolejnych języków, nie pole do odhaczenia. Zawsze jest kolejne repozytorium z kolejnym idiomem.

Wypracowane, nie zadeklarowane

Wszystko, co Maguyva robi dla agenta — znalezienie symbolu, prześledzenie zależności, odpowiedź na pytanie z cytowanym kodem — opiera się na tym, że leżąca u podstaw ekstrakcja jest poprawna. W 280 językach „poprawność” nie może być jedynie deklarowana; trzeba na nią nieustannie pracować, weryfikując rzeczywisty kod. Pętla jest sposobem, w jaki na nią pracujemy: autonomiczny cykl wyrywkowej kontroli i naprawy, który podchodzi z podejrzliwością do własnych metryk, dowodzi każdej zmiany i zamienia każdą naprawę w strażnika przed kolejną regresją. To nie jest efektowne. To praca, która pozwala nam powiedzieć „obsługujemy Twój język” i mieć to na myśli. Zielone jest łatwe. Poprawność trzeba wypracować.

Wielomodalne wyszukiwanie z fuzją: dobór właściwego retrievera do każdego zapytania

Wed, 15 Apr 2026 00:00:00 GMT

Uwaga o historycznym projekcie: ten artykuł z kwietnia 2026 r. opisuje ówczesny projekt routingu, a nie obecne zachowanie domyślne. Poniższa korekta z września dotyczy wyłącznie twierdzenia pomiarowego. Aktualny routing, presety i jawne sterowanie modalnościami opisano na stronie Jak to działa.

Zapytanie wyszukiwania to nie jedna rzecz.

„gdzie zdefiniowano parseConfig” chce dokładnego symbolu — jednej precyzyjnej lokalizacji, szybko. „jak działa uwierzytelnianie” chce znaczenia — rozproszenia powiązanego kodu, które wyjaśnia koncept. „co się zepsuje, jeśli zmienię tę funkcję” chce grafu zależności. „znajdź ciąg ECONNREFUSED” chce dosłownego dopasowania, niczego sprytnego.

Grep jest świetny do dosłownych dopasowań i przydatny do części poszukiwań referencji, ale to nie graf zależności i nie rozumie znaczenia. Embeddingi pokrywają stronę semantyczną, ale są niewłaściwym narzędziem do dokładnych ciągów i analizy wpływu. Większość narzędzi do wyszukiwania kodu wybiera jeden silnik i zmusza każde zapytanie, by żyło z tym wyborem. Maguyva nie wybiera. Ustala, jakiego rodzaju pytanie zadałeś, a następnie miesza cztery retrievery w proporcji, na jaką to pytanie zasługuje.

Cztery tryby

Pod maską istnieją cztery niezależne sposoby na znalezienie kodu:

semantyczny — wyszukiwanie wektorowe na binarnych embeddingach Voyage; znajduje kod według znaczenia.
tekstowy — dopasowywanie trigramowe; znajduje literały, ciągi błędów, dokładne identyfikatory.
strukturalny — zapytania AST; znajduje definicje, sygnatury i konstrukty językowe.
grafowy — graf zależności; znajduje wywołujących, wywoływanych i zasięg wpływu.

Każdy jest silny w innej klasie pytań. Sztuka polega na tym, by zdecydować, jak bardzo ufać każdemu z nich dla zapytania, które masz przed sobą.

Klasyfikacja intencji

Zanim uruchomi się jakiekolwiek wyszukiwanie, lekki klasyfikator sortuje zapytanie do jednej z sześciu intencji, z wynikiem pewności. Jest celowo tani — uporządkowane heurystyki, pierwsze dopasowanie wygrywa — ponieważ działa na ścieżce krytycznej i dodaje tylko milisekundę lub dwie:

zaczyna się od def , class , func , import … → find_definition (pewność 0,95)
„who calls”, „usages of”, „references to” (pytania o wywołania, użycia i referencje) → find_references (0,90)
„impact”, „blast radius”, „what depends on” (wpływ, zasięg wpływu, co od tego zależy) → impact_analysis (0,90)
cytowany "string" lub token błędu jak traceback → exact_match (0,85–0,90)
identyfikator CamelCase lub snake_case → find_definition (0,60–0,80)
„how”, „why”, „explain”, „architecture” (pytania o sposób działania, przyczyny i architekturę) → understand_code (0,75)
nic nie pasuje → understand_code, niska pewność (0,40)

Każda intencja niesie profil wag rozłożony na cztery tryby. Oto prawdziwe liczby:

Intencja	semantyczny	tekstowy	strukturalny (AST)	grafowy
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

Więc „gdzie zdefiniowano parseConfig” mocno opiera się na AST (0,6). „jak działa uwierzytelnianie” opiera się na wektorach semantycznych (0,5). „co od tego zależy” to niemal wyłącznie graf (0,7). „znajdź ECONNREFUSED” to niemal wyłącznie trigram (0,9), z modelem embeddingów całkowicie wyłączonym — ponieważ podobieństwo semantyczne jest dokładnie niewłaściwym narzędziem dla dokładnego ciągu.

Szybka ścieżka i ścieżka fuzji

Gdy klasyfikator jest pewny — wynik ≥ 0,85 — a zapytanie jest zwyczajne, Maguyva całkowicie pomija fuzję i kieruje bezpośrednio do jednego dominującego trybu. „gdzie zdefiniowano X” nie potrzebuje czterech retrieverów; potrzebuje indeksu AST, natychmiast. Ta bezpośrednia ścieżka jest raportowana z powrotem jako fusion_strategy: "direct".

Wszystko niejednoznaczne przechodzi przez fuzję. Cztery (lub trzy, w domyślnym presecie) tryby uruchamiają się równolegle, każdy zwracając własną uszeregowaną listę, a my je łączymy.

Ważona Reciprocal Rank Fusion

Fuzja niejednorodnych retrieverów jest trudniejsza, niż się wydaje: podobieństwo kosinusowe 0,82, wynik trigramowy 137 i centralność grafu 0,004 nie są na tej samej skali, więc nie można ich po prostu dodać. Reciprocal Rank Fusion omija ten problem, odrzucając surowe wyniki i zachowując tylko rangę, jaką przypisał każdy silnik. Wkład wyniku z jednego trybu to:

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

gdzie rank to jego pozycja na liście danego trybu, a k to stała wygładzająca. Wkłady są sumowane po trybach dla każdego wyniku, który znalazł więcej niż jeden silnik — zgodność między retrieverami naturalnie unosi się na szczyt. Używamy k = 40 w domyślnym presecie i 60 w thorough (quick działa wyłącznie semantycznie, więc fuzja nigdy się tam nie włącza). Oryginalna praca o RRF wylądowała na k = 60 dla wyszukiwania ogólnego przeznaczenia; nasze ustawienie domyślne nadaje nieco większą wagę wynikom zajmującym wysokie pozycje w kilku trybach — i nie polecamy ręcznego dostrajania tego.

Ponadto wyniki niosą boost związany z ważnością w grafie. Hub — funkcja, na której opiera się cała baza kodu — powinien wyprzedzać mało znany węzeł liściowy nawet przy tej samej trafności tekstowej, więc mnożymy każdy wkład przez:

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

Centralność pochodzi z wstępnie obliczonych metryk PageRank/stopnia w pipeline, a boost jest ograniczony do 1,5×, żeby popularna funkcja nie mogła całkowicie zagłuszyć bardziej trafnej, mniej znanej funkcji. Na koniec degradujemy wyniki ze ścieżek vendor, build i archiwalnych oraz deduplikujemy do najlepszego fragmentu na plik.

Co wciąż jest niedoskonałe

Klasyfikator intencji to zbiór wyrażeń regularnych, nie wytrenowany model. Obsługuje typowe formy zapytań za pomocą heurystyk, a niejednoznaczne zapytanie wraca do understand_code i mieszanki z przewagą semantyki. Wcześniejsza wersja tego wpisu przedstawiała spadek odsetka wyszukiwań bez wyników z około 15% do poniżej 5% jako osiągnięty. Propozycja z grudnia 2025 r. zawierała w rzeczywistości szacunkowy punkt wyjścia i cel; nie dostarczono wspierającego zbioru zapytań ani raportu pomiarowego. Wycofujemy twierdzenie o osiągnięciu tej poprawy; zobacz dowody źródłowe i korektę. Nie zastąpiliśmy klasyfikatora wytrenowanym modelem, ponieważ tania wersja jest szybka i wystarczająco dobra do zamierzonej roli routingu, a klasyfikator, który myli się z pełnym przekonaniem, jest gorszy niż uczciwy fallback. Same wagi są ręcznie dobranymi wartościami a priori, a nie wynikiem uczenia na danych o kliknięciach, których nie zbieramy.

Zadawaj pytania zamiast wybierać narzędzia

Agent nie powinien musieć wiedzieć, czy sięgnąć po grep, embeddingi, czy graf wywołań — powinien zadać swoje pytanie prostymi słowami i uzyskać właściwą odpowiedź. Fuzja wielomodalna jest tym, co pozwala, by find_symbol, wyszukiwanie semantyczne i analiza zależności były dostępne przez jeden interfejs zapytań: system odczytuje kształt pytania i po cichu składa dla niego właściwy retriever. Model, który ocenia embeddingi, ma znaczenie, ale tak samo ważne jest, by wiedzieć, kiedy nie ich używać. Dobór właściwego narzędzia do każdego zapytania to odrębny wymiar jakości i wolelibyśmy być za niego odpowiedzialni, niż przerzucać go na wywołującego.

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

Obserwowalność agentów: hooki, Alloy i Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Systemy agentowe zawodzą na dziwne sposoby.

Czasem problemem jest model. Czasem narzędzie. Czasem Twój serwer MCP działa bez zarzutu, ale agent wybrał niewłaściwego specjalistę, albo spędził połowę sesji na pracy powłokowej, której się nie spodziewałeś, albo po cichu spalił budżet w pętli, która z zewnątrz wyglądała na produktywną.

Jeśli nie widzisz tej różnicy, tak naprawdę nie obsługujesz systemu agentowego. Zgadujesz.

Zbudowaliśmy więc stos obserwowalności dla naszego własnego przepływu pracy: Claude Code, Codex, zdarzenia hooków Claude, zdarzenia notify Codex, natywny OpenTelemetry, Grafana Alloy i Grafana Cloud po drugiej stronie.

Ciekawa część to nie „zrobiliśmy dashboard”. Ciekawa część polega na tym, że musieliśmy podzielić telemetrię na dwa różne strumienie, ponieważ żaden pojedynczy feed nie dawał nam pełnego obrazu.

Problem: telemetria agentów jest rozdrobniona

Nowoczesne agenty programistyczne już emitują część telemetrii. To pomaga, ale to nie wystarcza.

Natywny OTEL dobrze odpowiada na pytania w stylu:

Ile żądań wykonaliśmy?
Ile kosztowała dana sesja?
Gdzie są spany i ślady (traces)?
Czy nastąpił skok opóźnienia?

Znacznie gorzej radzi sobie z pytaniami takimi jak:

Na którym serwerze MCP agent się opierał?
Czy ta awaria dotyczyła Bash, wbudowanego narzędzia plikowego, czy wywołania MCP?
Który skill faktycznie się aktywował?
Jaki typ subagenta został wysłany do zadania?
Czy sesja wykonywała użyteczną pracę, czy tylko się miotała?

Ta druga klasa pytań leży bliżej hooków niż śladów.

Ale odwrotność też jest prawdą: część najważniejszych pytań o wydajność leży bliżej śladów niż hooków.

Jeśli chcesz wiedzieć, gdzie faktycznie kumulowało się opóźnienie, które spany były wolne, albo czy sesja spaliła czas na wywołaniach modelu czy na wykonywaniu narzędzi, potrzebujesz danych ze śladów tak samo jak zdarzeń semantycznych.

Architektura, na której skończyliśmy

Uruchamiamy dwie ścieżki telemetrii równolegle.

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

Ten podział jest celowy.

Jest też asymetryczny. Claude Code daje nam znacznie bogatszy interfejs hooków cyklu życia. Codex daje nam natywny OTEL plus interfejs notify, więc normalizujemy mniej szczegółowe zdarzenia zakończenia tury do tego samego schematu logów, zamiast udawać, że oba środowiska uruchomieniowe udostępniają te same mechanizmy sterowania.

Natywny OTEL daje nam bazowy strumień: logi i ślady z samego środowiska uruchomieniowego, plus metryki tam, gdzie środowisko faktycznie je emituje.

Zdarzenia hooków i notify dają nam warstwę semantyczną: rzeczy takie jak PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated oraz sklasyfikowane metadane, na których nam naprawdę zależy przy debugowaniu zachowania agenta. Claude Code dostarcza tu bogatszy strumień zdarzeń. Codex dostarcza mniej szczegółowy, ale wciąż użyteczny znormalizowany strumień.

Dlaczego hooki w ogóle istnieją

Nasz potok hooków wzbogaca zdarzenia, zanim trafią do Loki.

Zamiast po prostu powiedzieć „uruchomiło się narzędzie”, klasyfikujemy zdarzenie do pól takich jak:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: który backend MCP obsłużył wywołanie
bash_cli: rodzina poleceń powłoki
subagent_type: jaki rodzaj specjalisty został wysłany do zadania
agent_tool: czy źródłem był Claude Code, czy Codex

To oznacza, że możemy zadawać pytania, które mają znaczenie operacyjne:

{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 nie są pola dla ozdoby. To różnica między „agent wydawał się wolny” a „agent spędził ostatnie dziesięć minut na intensywnych operacjach git w powłoce z wysokim wskaźnikiem niepowodzeń narzędzi”.

Jeden szczegół implementacyjny, który wygląda dziwniej, niż jest: współdzielony strumień Loki wciąż używa service_name="claude-code-hooks" jako etykiety, nawet gdy zdarzenie pochodzi z Codex. Prawdziwy podział między środowiskami uruchomieniowymi następuje na agent_tool.

Dlaczego Alloy siedzi pośrodku

Grafana Alloy w tym układzie to nie tylko przekaźnik. To punkt egzekwowania reguł przetwarzania telemetrii.

Kierujemy natywny strumień OTEL z Claude Code i Codex do lokalnego proxy Alloy na localhost:4318, a następnie pozwalamy Alloy oczyścić ładunek, zanim przekaże go dalej do Grafana Cloud.

To ma znaczenie, ponieważ surowa telemetria agentów jest pełna pól o wysokiej kardynalności, które są przydatne do analizy, ale fatalne jako indeksowane etykiety:

session_id
prompt_id
liczba tokenów
czasy trwania
bloby parametrów narzędzi

Jeśli zaindeksujesz wszystko, dostajesz eksplozję etykiet i zepsuty dzień.

Więc Alloy robi dla nas trzy rzeczy:

Utrzymuje bardzo mały zestaw zaindeksowanych etykiet o niskiej kardynalności.
Przenosi zaszumione, ale użyteczne pola do ustrukturyzowanych metadanych.
Całkowicie odrzuca czysty szum.

Ważna idea jest prosta: obserwuj więcej, indeksuj mniej.

Dlaczego strumień hooków omija Alloy

Strumień hooków jest już ukształtowany pod Loki.

Zanim send_event.py wypchnie zdarzenie, już zdecydowaliśmy, które pola zasługują na traktowanie jako etykiety, a które należą do ustrukturyzowanego ciała JSON. Ten strumień trafia prosto do bramki OTLP Grafana Cloud, zamiast przechodzić kolejny raz przez Alloy.

System ma więc jasny podział pracy:

Alloy okiełznuje surowy natywny strumień OTEL.
Wzbogacanie hooków czyni zdarzenia semantyczne przeszukiwalnymi.

Dzięki temu architektura pozostaje prostsza niż próba przepchnięcia wszystkiego jedną ścieżką.

Co faktycznie pokazuje dashboard

Poniższy zrzut ekranu pochodzi z jednego z dashboardów obserwowalności stojących za naszym przepływem pracy agentów. To nie benchmark, a liczby to tylko wycinek z danego momentu. Chodzi o kształt danych: kanał aktywności, wywołania narzędzi, awarie, prompty oraz podziały według agenta, narzędzi wbudowanych, użycia MCP, poleceń powłoki i skilli.

Przydatne jest to, że ten dashboard żyje na tym samym stosie Grafana co reszta telemetrii agentów. Możemy filtrować według agenta źródłowego i rodziny narzędzi oraz patrzeć na różne środowiska uruchomieniowe bez wymyślania osobnej historii obserwowalności dla każdego systemu.

Jeden z działających dashboardów stojących za naszym przepływem pracy agentów. Ten zrzut ekranu to tylko wycinek współdzielonego stosu Grafana, który odbiera też telemetrię z naszych innych środowisk uruchomieniowych i systemów agentów. Kliknij obraz, aby zobaczyć wersję w pełnej rozdzielczości.

Dlaczego ślady mają większe znaczenie, niż się wydaje na pierwszy rzut oka

Logi mówią nam, jaka kategoria pracy się wydarzyła. Ślady mówią nam, jak ta praca rozwijała się w czasie.

To rozróżnienie ma znaczenie w systemach agentowych, ponieważ „wolno” jest zbyt ogólnym określeniem, by było użyteczne.

Ślad może nam powiedzieć, czy ból pochodził z:

opóźnienia modelu
czasu wykonania narzędzia
powtarzanych ponowień
jednej szczególnie kosztownej interakcji MCP
długiego ogona drobnych operacji, które osobno wyglądały niegroźnie

W praktyce używamy razem strumienia hooków i śladów Tempo.

Logi hooków odpowiadają: co się wydarzyło?
Ślady odpowiadają: gdzie poszedł czas?

To połączenie zmienia obserwowalność z dashboardu w wyjaśnienie.

Gdzie pasuje Codex

Codex jest częścią tego samego stosu, ale nie jest identyczny z Claude Code.

Dla Codex podłączamy dwa elementy:

Natywny OTEL z Codex do Alloy
Webhook notify do codex_notify.py, który mapuje zakończenia tur na ten sam schemat Loki, którego używamy dla zdarzeń hooków

To daje nam ujednolicony filtr taki jak agent_tool="codex-cli" w tym samym strumieniu logów.

Uczciwe zastrzeżenie: ładunek notify Codex jest obecnie mniej szczegółowy niż ładunek hooków Claude Code, ponieważ nie jest to ten sam rodzaj interfejsu integracji. W naszej konfiguracji dziś zakończenia tur Codex można znormalizować do współdzielonego schematu, ale bogata ekstrakcja narzędzie-po-narzędziu wciąż lepiej działa w natywnym strumieniu OTEL niż w moście notify.

To nie jest powód, by unikać tego wpisu. To właśnie jego sens. Prawdziwe systemy obserwowalności buduje się z niedoskonałych sygnałów.

Grafana przez MCP zmienia grę

Większa zmiana polega na tym, że Grafana to nie tylko miejsce, które ludzie odwiedzają w przeglądarce.

W tym repozytorium udostępniamy też Grafana przez MCP. To oznacza, że agent może odpytywać Loki, Prometheus i Tempo bezpośrednio, zamiast czekać, aż człowiek najpierw ręcznie sprawdzi dashboardy.

To zamienia obserwowalność w aktywny wkład w przepływ pracy.

Agent może zapytać:

Które rodziny narzędzi zawodziły najczęściej w ostatniej godzinie?
Który serwer MCP zdominował sesję?
Czy niedawne zmiany zmniejszyły liczbę niepowodzeń narzędzi, czy tylko przeniosły pracę na ścieżki bardziej powłokowe z tymi samymi błędami?
Które ślady pokazują najwyższe opóźnienie lub powtarzane ponowienia?

Gdy to masz, jesteś bardzo blisko pętli samodoskonalenia.

Od dashboardu do pętli sprzężenia zwrotnego

To jest część, którą uważamy za najciekawszą.

Gdy stos obserwowalności staje się przeszukiwalny z poziomu warstwy agenta, telemetria przestaje być biernym narzędziem raportowania i staje się sygnałem sterującym.

Pętla wygląda tak:

Aktywność agenta emituje ślady, metryki i wzbogacone logi hooków.
Grafana przechowuje dowody w Loki, Tempo i Prometheus, tam gdzie istnieją metryki.
Agenci odpytują te dowody przez Grafana MCP.
System identyfikuje zły dobór narzędzi, kruche skille, słabe trasowanie lub przepływy pracy zbyt zależne od powłoki, które wciąż generują błędy, których można było uniknąć.
Agenci lub operatorzy dostosowują prompty, konfiguracje agentów, opisy skilli, reguły trasowania lub dostęp do narzędzi.
Kolejna sesja generuje nowy kształt telemetrii, a cykl się powtarza.

Tak przechodzi się od „ciekawego dashboardu” do „mierzalnego systemu poprawy”.

Celem nie jest maksymalizacja jednej kategorii narzędzi. Celem jest znalezienie właściwej mieszanki CLI, narzędzi wbudowanych, wywołań MCP i skilli dla pracy, która faktycznie jest wykonywana.

Na co to pozwala nam odpowiedzieć

Gdy oba środowiska uruchomieniowe trafiają do tego samego stosu Grafana, możemy znacznie szybciej odpowiadać na pytania operacyjne:

Czy awarie skupiają się w jednej rodzinie narzędzi?
Czy przepływy pracy zbyt zależne od powłoki tworzą błędy, których można uniknąć tam, gdzie powinno istnieć narzędzie wyższego poziomu?
Które serwery MCP dźwigają większość obciążenia?
Czy płacimy za aktywność agenta, która nie generuje znaczącego postępu?
Czy sesja działa nieprawidłowo z powodu modelu, narzędzi, czy warstwy orkiestracji?

Jest to szczególnie przydatne w przepływach pracy z wieloma agentami, gdzie „agent był zajęty” nie mówi prawie nic.

Jeśli jeden specjalista jest wciąż wysyłany do zadań i generuje wysoki wskaźnik niepowodzeń, to problem trasowania lub kształtowania promptu.

Jeśli jeden serwer MCP dominuje wśród wszystkich wywołań, może to być dobra architektura albo sygnał, że reszta jest zbędnym balastem.

Jeśli niepowodzenia narzędzi rosną, a koszt pozostaje wysoki, masz problem operacyjny, nie jakościowy.

Jeśli praca powłokowa wciąż zawodzi w przewidywalny, możliwy do uniknięcia sposób tam, gdzie powinno istnieć narzędzie wyższego poziomu, to sygnał produktowy.

Jeśli jeden skill aktywuje się bez przerwy, ale nie poprawia wyników, to sygnał promptu lub trasowania.

Prawdziwa lekcja

Głębsza lekcja jest taka, że obserwowalność agentów potrzebuje zarówno telemetrii środowiska uruchomieniowego, jak i telemetrii przepływu pracy.

Telemetria środowiska uruchomieniowego mówi Ci, co system zrobił.

Telemetria przepływu pracy mówi Ci, co agent myślał, że robi.

Potrzebujemy obu.

Jeśli zachowujesz tylko ślady i liczniki, tracisz warstwę semantyczną. Jeśli zachowujesz tylko zdarzenia hooków, tracisz opóźnienia, spany i szerszy obraz środowiska uruchomieniowego.

A jeśli zachowujesz oba, ale nigdy nie sprzęgasz ich zwrotnie z warstwą agenta, masz monitoring, nie adaptację.

To połączenie sprawia, że system jest na tyle wytłumaczalny, by go obsługiwać, i na tyle strojalny, by go ulepszać.

Co wciąż jest niedoskonałe

Wciąż są szorstkie krawędzie.

Nie każde zdarzenie hooka zawiera dane o czasie trwania i tokenach, jakich byśmy chcieli.
Część najlepszych widoków czasowych wciąż pochodzi ze śladów Tempo, a nie z logów hooków.
Codex jest dziś mniej semantycznie bogaty niż Claude Code we wzbogaconym strumieniu zdarzeń.
Zrzut ekranu dashboardu to działający panel operacyjny, nie dopieszczony artefakt marketingowy.

Ten ostatni punkt jest zamierzony. Wolimy pokazać prawdziwy panel przyrządów niż udawać, że systemy agentowe magicznie same się tłumaczą.

Dlaczego to ma znaczenie dla Maguyva

Maguyva polega na dawaniu agentom lepszej inteligencji kodu. Ale gdy agenty faktycznie wykonują użyteczną pracę, natychmiast pojawia się nowy wymóg: musisz widzieć, jak się zachowują.

Jakość wyszukiwania, jakość trasowania, dobór narzędzi i efektywność kontekstu — wszystko to staje się problemami do zaobserwowania.

Dlatego uważamy, że warto o tym pisać. Przyszły stos agentowy to nie tylko prompty i narzędzia. To prompty, narzędzia i warstwa instrumentacji, która mówi Ci, czy całość działa.

Jeśli budujesz poważne przepływy pracy agentowej, obserwowalność nie jest opcjonalną infrastrukturą. Jest częścią produktu.

Wiedza z historii zmian zamyka pętlę: jak zmiany stają się pamięcią instytucjonalną

Tue, 03 Feb 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (luty 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Każdy zespół inżynieryjny mierzy się z tym samym wyzwaniem: zmiany zachodzą nieustannie, ale powód tych zmian znika. Sześć miesięcy później ktoś pyta „dlaczego przyjęliśmy DuckDB dla etapów pipeline’u?”, a odpowiedź żyje tylko w głowie osoby, która podjęła tę decyzję — jeśli w ogóle jeszcze tu jest.

Zbudowaliśmy przepływ pracy wydobywczy (mining), który zamyka tę pętlę. Zmiany przepływają przez commity git, są przetwarzane przez nasz pipeline wydobywczy, stają się ustrukturyzowanymi wpisami changeloga i rekordami decyzji architektonicznych, a następnie wracają do naszych agentów AI przez zapytania CLI. Wynik: pamięć instytucjonalna, do której mają dostęp zarówno ludzie, jak i AI.

Problem: decyzje wyparowują

Rozważ typowy scenariusz. Deweloper commituje:

feat(canonical): add DuckDB runtime for pipeline stages

Ten commit reprezentuje istotny wybór architektoniczny. Zespół ocenił opcje, rozważył kompromisy i wybrał DuckDB z konkretnych powodów. Ale cały ten kontekst żyje w:

Wątku na Slacku (prawdopodobnie usuniętym)
Pamięci kogoś (zdecydowanie blaknącej)
Komentarzu w kodzie (może, jeśli masz szczęście)

Trzy miesiące później nowy członek zespołu pyta: „Powinienem użyć DuckDB czy SQLite dla tego nowego etapu?”. Bez pamięci instytucjonalnej albo wymyśla koło na nowo, albo dokonuje niespójnych wyborów.

Pętla: od commitów do kontekstu

Nasz przepływ pracy wydobywczy zamienia historię git w przeszukiwalną wiedzę:

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)     │
      └───────────────┘

Kluczowa obserwacja: zarówno changelogi, jak i decyzje architektoniczne wypływają z tej samej historii git, przetwarzanej przez ujednolicony pipeline. To zapewnia, że nic nie umknie.

Jak działa wydobywanie

Krok 1: Synchronizacja indeksu

uv run orkestra mine sync

To polecenie skanuje historię git i buduje indeks wszystkich commitów. Wyodrębnia ustrukturyzowane sygnały z każdego commita:

Typ zgodny ze standardem Conventional Commits (feat, fix, chore, docs)
Zakres (który pakiet lub obszar)
Znaczniki zmian łamiących kompatybilność
Dotknięte pliki i metryki złożoności

Krok 2: Sprawdzenie statusu pokrycia

uv run orkestra mine status

Oto jak wygląda nasz obecny status:

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 przetworzonych commitów. 476 stało się decyzjami architektonicznymi. 6799 stało się wpisami changeloga. Każdy commit sklasyfikowany.

Krok 3: Uzyskanie kandydatów do przeglądu

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

To wydobywa commity, które nie zostały jeszcze przetworzone, wraz z pełnym kontekstem do klasyfikacji:

{
  "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}
}

Sygnały pomagają w klasyfikacji: is_releasable_type: true sugeruje, że powinno się to znaleźć w changelogu. Duża liczba wstawień i pliki infrastrukturalne sugerują, że może to być też decyzja architektoniczna.

Krok 4: Klasyfikacja commitów

W tym miejscu rozchodzą się dwie ścieżki: wpisy changeloga i decyzje architektoniczne.

Dla wpisów changeloga:

uv run orkestra mine classify abc123 --changelog added

To zapisuje, że commit abc123 powinien pojawić się w changelogu w kategorii „Dodano”.

Dla decyzji architektonicznych:

Najpierw uzyskaj prawdziwy identyfikator decyzji:

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

Następnie klasyfikuj z identyfikatorem decyzji:

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

To łączy commit z rekordem decyzji, który zostanie utworzony lub zaktualizowany.

Do przetwarzania wsadowego (co faktycznie robimy):

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

Format JSONL obsługuje obie domeny w jednym przebiegu:

{"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: Renderowanie wyników

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

To generuje pliki CHANGELOG.md dla poszczególnych pakietów na podstawie ledgera. Changelogi są artefaktami pochodnymi — usuń je, a wygenerują się na nowo idealnie z ledgera źródłowego.

Struktura rekordu decyzji

Wyodrębnione decyzje stają się plikami YAML z bogatymi metadanymi:

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żda decyzja odsyła z powrotem do swoich commitów źródłowych. Każda decyzja określa, których plików dotyczy. Relacje między decyzjami są jednoznaczne.

Integracja CLI: odpytywanie pamięci instytucjonalnej

Tu właśnie zamyka się pętla. Agenci mogą odpytywać decyzje przez CLI:

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

Zwraca decyzje dotyczące logiki ponawiania, obsługi błędów, wzorców odzyskiwania.

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

Zwraca kompletny rekord decyzji z kontekstem, uzasadnieniem i wpływem.

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

Pokazuje, jakie wybory architektoniczne zostały podjęte ostatnio.

Jak agenci tego używają

Bazowe instrukcje naszego orkiestratora zawierają:

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

Gdy agent zostaje poproszony o zaimplementowanie czegoś związanego z DuckDB, może najpierw sprawdzić:

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

I odkryć DEC-PL-142, dowiadując się:

Dlaczego wybraliśmy DuckDB (kontekst)
Jak używać go poprawnie (agent_guidance)
Na które pliki spojrzeć (files)
Jakie powiązane decyzje istnieją (related)

Agent nie wymyśla koła na nowo. Opiera się na ustalonych wzorcach.

Test trzech pytań

Nie każdy commit zasługuje na rekord decyzji. Używamy testu trzech pytań, aby filtrować:

Czy to było trudne do podjęcia? Czy wymagało znaczącej analizy, oceny kompromisów lub debaty?
Czy kosztowna jest zmiana tego? Czy cofnięcie tej decyzji wymagałoby znacznego nakładu pracy?
Czy ma wpływ na cały system? Czy wpływa na wiele pakietów lub ustanawia wzorce, które inni będą naśladować?

Jeśli commit odpowiada „tak” na przynajmniej jedno z tych pytań, jest kandydatem do ekstrakcji decyzji. Nasz typowy wskaźnik: 1-4 decyzje na 100 commitów (około 1-4%).

Dla wpisów changeloga próg jest niższy: każda zmiana widoczna dla użytkownika (funkcje, poprawki, usprawnienia) zostaje zapisana. Wewnętrzne porządki, aktualizacje dokumentacji i refaktoryzacje zazwyczaj są pomijane. Nasz typowy wskaźnik: 30-50 wpisów changeloga na 100 commitów.

Przechowywanie danych: ledgery tylko do dopisywania

System wydobywczy używa ledgerów JSONL tylko do dopisywania (append-only) dla bezkonfliktowej pracy wieloagentowej:

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
    └── ...

Format JSONL z merge=union w .gitattributes oznacza, że wielu agentów może klasyfikować commity jednocześnie bez konfliktów scalania. Każda linia jest niezależna.

Kontrole walidacyjne

Przed każdą sesją wydobywczą uruchamiamy walidację:

uv run orkestra mine validate --quick

Sprawdza to:

Poprawność formatu SHA
Zgodność formatu identyfikatora decyzji
Brak zduplikowanych wpisów dla tego samego SHA
Czy przywoływane decyzje faktycznie istnieją

Po klasyfikacji walidujemy ponownie przed zatwierdzeniem zmian.

Dlaczego to ma znaczenie

Pętla sprzężenia zwrotnego, którą zbudowaliśmy, rozwiązuje kilka problemów:

Dla nowych członków zespołu: Zamiast pytać „dlaczego zrobiliśmy X?”, mogą przeszukać rejestr decyzji. Kontekst jest zachowany.

Dla agentów AI: Nie działają w próżni. Mogą odpytywać wiedzę instytucjonalną, zanim wydadzą rekomendację. Poproszeni o dodanie nowego etapu pipeline’u, mogą odkryć wzorzec DuckDB i się go trzymać.

Dla spójności architektonicznej: Decyzje są jednoznaczne i przeszukiwalne. Gdy ktoś proponuje podejście sprzeczne z istniejącą decyzją, system może uwidocznić ten konflikt.

Dla generowania changeloga: Notatki wydania nie są gorączkowym pośpiechem w ostatniej chwili. Są produktem ubocznym ciągłej klasyfikacji podczas rozwoju.

Dla onboardingu: Nowi agenci dziedziczą pełny kontekst bazy kodu. Widzą nie tylko kod — widzą decyzje, które go ukształtowały.

Stan obecny

Na dziś:

15 637 commitów przetworzonych przez pipeline
476 decyzji architektonicznych wyodrębnionych i udokumentowanych
6799 wpisów changeloga zapisanych
100% pokrycia w obu domenach

Każdy commit od momentu, gdy zaczęliśmy, został sklasyfikowany. Pamięć instytucjonalna jest kompletna i przeszukiwalna.

Jak zacząć

Jeśli chcesz wdrożyć coś podobnego:

Zacznij od standardu Conventional Commits. Pipeline wydobywczy działa najlepiej, gdy commity mają ustrukturyzowane prefiksy (feat:, fix:, chore:).
Zdefiniuj swoje domeny. Używamy domen takich jak pipeline, agent-design, observability, data-modeling. Organizują one decyzje według obszaru.
Zbuduj nawyk klasyfikacji. Wydobywanie działa, gdy zespoły regularnie klasyfikują commity. Przetwarzanie wsadowe ze wsparciem LLM pomaga skalować.
Uczyń decyzje przeszukiwalnymi. Wartość kumuluje się, gdy agenci mogą przeszukiwać decyzje przez CLI. Nadaj wynikom strukturę odpowiednią do przetwarzania maszynowego.
Zamknij pętlę. Decyzje powinny wpływać na przyszłą pracę. Uwzględnij odniesienia do decyzji w instrukcjach agentów i listach kontrolnych przeglądu kodu.

Celem nie jest idealna dokumentacja. Chodzi o to, by powód stojący za zmianami był dostępny zarówno dla ludzi, jak i AI, dziś i za sześć miesięcy. Gdy zmiany stają się pamięcią instytucjonalną, zespoły opierają się na ustalonych wzorcach zamiast wymyślać je na nowo.

Przepływ pracy wydobywczy jest częścią naszego silnika orkiestracji, konkretnie modułu silnika kontekstu w naszym pakiecie orkiestracji.

Wydobywanie skilli: od 3500 kandydatów do 466 zdolności

Tue, 27 Jan 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Problem 3500 skilli

Gdy zaczęliśmy budować system orkiestracji agentów, natrafiliśmy na ciekawe wyzwanie: istnieją tysiące potencjalnych skilli rozproszonych po ekosystemie AI. Repozytoria GitHub, dokumentacja dostawców, projekty społecznościowe, wewnętrzne wzorce — skille istnieją wszędzie. Ale które mają znaczenie? Które działają? I jak utrzymać spójną bibliotekę skilli, z której agenci faktycznie mogą korzystać?

Nasza odpowiedź: systematyczna pętla wyszukiwania i włączania skilli do rejestru.

Liczby dziś

Zaledwie nieco ponad trzy miesiące po tym, jak Anthropic uruchomił Agent Skills 16 października 2025, oto gdzie byliśmy w momencie publikacji tego wpisu, 27 stycznia 2026:

Metryka	Liczba
Zidentyfikowani kandydaci	3500+
Przyjęte skille	466
Skille dostawców	373
Skille wewnętrzne	93
Aktywni dostawcy	25+
Średnia liczba tokenów na skill	2834
Przywoływane narzędzia	89
Unikalne tagi	635

Przejrzeliśmy ponad 3500 kandydatów na skille. Przyjęliśmy 466. To wskaźnik adopcji na poziomie 13% — i ta selektywność jest zamierzona.

System poziomów wiedzy

Nie wszystkie skille są sobie równe. Organizujemy je w pięć warstw wiedzy (K0-K4), z których każda reprezentuje inny zakres zastosowania:

K0: Fundamenty (uniwersalne)

Skille, które powinien mieć każdy agent. Reprezentują zdolności „dobrego myśliciela”, które działają wszędzie.

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

Skille K0 są przenośne do dowolnego projektu, dowolnej domeny, dowolnego stosu. Kodują uniwersalne wzorce poznawcze.

K1: Tożsamości (dziedzina zawodowa)

Skille „dobrego inżyniera” lub „dobrego badacza”, mające zastosowanie w wielu projektach w ramach danej dziedziny zawodowej.

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

K2: Domeny (wiedza specjalistyczna)

Skille „dobrego eksperta baz danych” lub „dobrego inżyniera bezpieczeństwa”, przenośne w ramach danej dziedziny.

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: Stosy (technologia)

Skille „dobrego użytkownika Supabase” lub „dobrego dewelopera Cloudflare” dla konkretnych stosów technologicznych.

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

K4: Projekt (organizacja)

Skille specyficzne dla naszej organizacji i przepływów pracy.

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

Pętla wydobywcza

Faza 1: odkrywanie

Skille pochodzą zewsząd:

Repozytoria dostawców: AWS, Anthropic, Cloudflare, Supabase i współtwórcy społecznościowi publikują kolekcje skilli. Śledzimy ponad 25 korzeni dostawców.

Projekty społecznościowe: GitHub jest pełen szablonów Claude Code, wzorców agentów i definicji przepływów pracy.

Wzorce wewnętrzne: gdy nasz zespół rozwiązuje problemy, powstają wzorce. Zostają one sformalizowane w skille.

Wydobywanie z dokumentacji: dokumentacja techniczna często zawiera niejawne skille — procedury, listy kontrolne, drzewa decyzyjne.

Odkrywanie jest ciągłe. Używamy backlogu skilli, żeby śledzić kandydatów przed formalną oceną.

Faza 2: ocena

Każdy kandydat jest oceniany według tych samych kryteriów:

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

Wszystkie pięć kryteriów produktowych musi być spełnionych. Dlatego 87% kandydatów zostaje odrzuconych.

Następnie każdy kandydat przechodzi przez osobny przegląd zaufania. Nie traktujemy oficjalnego repozytorium dostawcy, znanego opiekuna społecznościowego i przypadkowego repozytorium GitHub jako równoważnych źródeł prawdy.

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

Zaufani dostawcy otrzymują lżejszy przegląd pochodzenia, ale nie wolną przepustkę. Niezaufane lub nieznane źródła otrzymują głębszy ręczny audyt, a dołączonych skryptów nie uruchamiamy, dopóki nie zostaną przeczytane, sprawdzone pod kątem zakresu działania i uznane za bezpieczne.

Analiza luk: przed przyjęciem przeszukujemy nasz rejestr:

uv run orkestra skills search "<capability>"

Jeśli już to mamy, nie potrzebujemy tego. Jeśli mamy coś zbliżonego, możemy scalić zamiast przyjmować.

Ocena głębi i standardów: oceniamy też, jak w pełni kandydat wykorzystuje model agent-skill. Samotny SKILL.md wciąż może być użyteczny, ale głębsze skille są cenniejsze, gdy oddzielają instrukcje od referencji, skryptów i zasobów w sposób, do którego zachęca 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

Gwiazdki na GitHubie mogą nieco podnieść wynik wiarygodności, ale nigdy nie ratują płytkiego lub niebezpiecznego skilla. Repozytorium z dużą liczbą gwiazdek z jednym niejasnym SKILL.md i nieprzejrzystymi skryptami otrzymuje niższą ocenę niż mniejsze repozytorium z precyzyjnym opisem, starannie dobranymi materiałami w references/ i atomowymi pomocnikami, które faktycznie wykorzystują pełną zdolność skilla.

Analiza strukturalna: sprawdzamy jakość skilla:

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

Jeśli kandydat zawiera skrypty, ten przegląd staje się bardziej rygorystyczny. Dobry skill nie jest tylko użyteczny; musi być czytelny, ograniczony i bezpieczny do przekazania agentowi. Sam ten filtr bezpieczeństwa dyskwalifikuje znaczącą część skądinąd interesujących kandydatów.

Faza 3: włączanie do rejestru

Gdy skill przechodzi ocenę, wchodzi do rejestru. Ale skille nigdy nie są przyjmowane bez zmian. Są modyfikowane, żeby pasować do naszego systemu.

Modyfikacje przy adopcji:

Normalizacja metadanych: każdy skill otrzymuje nasz schemat frontmatter
Przypisanie poziomu K: skille są umieszczane we właściwej warstwie wiedzy
Wzbogacenie tagów: dodawane są tagi na potrzeby odkrywalności
Deklaracja narzędzi: dozwolone narzędzia są jednoznacznie deklarowane
Wyrównanie sekcji: treść jest restrukturyzowana, żeby pasować do naszego szablonu

Typowy YAML skilla po włączeniu do rejestru:

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

Faza 4: przypisanie zakresu

Skille są przypisywane do zakresów — kategorii, które determinują, którzy agenci wczytują które skille:

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

Agenci deklarują swoje zakresy, a skille są przypisywane automatycznie:

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

Faza 5: materializacja

Skille nie żyją jako YAML na produkcji. Są renderowane do plików SKILL.md, które Claude Code może wczytać:

uv run orkestra sync

To polecenie:

Czyta wszystkie definicje YAML skilli
Renderuje je przez szablony Jinja
Zapisuje pliki SKILL.md do .claude/skills/
Organizuje według poziomu K (foundations/, identities/, domains/, stacks/, project/)

Ostateczna struktura wyjściowa:

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

Wzorzec uśpionego zakresu

Jednym z naszych najpotężniejszych wzorców są skille „przyjęte, ale niewczytane”. Nazywamy je uśpionymi zakresami.

Rozważ skille obliczeń naukowych z repozytorium k-dense-scientific. Przyjęliśmy ponad 120 skilli obejmujących bioinformatykę, chemię, obliczenia kwantowe i informatykę kliniczną. Ale większość naszych agentów nie potrzebuje dokowania molekularnego ani analizy ekspresji genów.

Zamiast wczytywać wszystkie 120 skilli do każdego agenta (rozdymając okna kontekstu), robimy tak:

Przyjmujemy skille z konkretnym zakresem (np. bioinformatics)
Trzymamy je uśpione — zarejestrowane, ale niewczytane
Włączamy je tylko wtedy, gdy agent deklaruje ten zakres

# 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

Ten wzorzec pozwala nam mieć 466 skilli w rejestrze, podczas gdy typowi agenci wczytują tylko 40-60 istotnych.

Typy skilli

Skille występują w trzech wzorcach poznawczych:

Przepływ pracy (Workflow)

Uporządkowane kroki proceduralne: „1. Zrób X, 2. Potem Y, 3. Na koniec Z”

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

Dyscyplina (Discipline)

Behawioralne bariery ochronne: „Zawsze X”, „Nigdy Y”, „Preferuj Z”

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

Lista kontrolna (Checklist)

Kryteria weryfikacji: „Potwierdź X”, „Zweryfikuj Y”, „Sprawdź Z”

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

Kontrole jakości

Każdy skill musi przejść walidację, zanim trafi do wydania:

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

Opisy muszą mieć 50-400 znaków z frazami wyzwalającymi („Użyj, gdy…”, „Gdy potrzebujesz…”), żeby Claude Code wiedział, kiedy je zasugerować.

Walidujemy w sposób ciągły:

uv run orkestra validate --show-warnings

Ekosystem dostawców

Nasze 373 skille dostawców pochodzą z:

Dostawca	Skille	Domena
AWS Agent	19	Usługi chmurowe
Anthropic	12	Generowanie dokumentów
Cloudflare	8	Edge computing
Supabase	5	Baza danych
k-dense	100+	Obliczenia naukowe
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Automatyzacja przeglądarki

Każdy korzeń dostawcy jest zadeklarowany w 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

Gdy uruchamia się orkestra sync, skille dostawców są linkowane symbolicznie do .claude/skills/vendor/ z przestrzenią nazw ich dostawcy.

Czego się nauczyliśmy

Selektywność się opłaca. Kusi, żeby przyjmować wszystko, co wygląda na użyteczne. Ale każdy skill kosztuje tokeny. Przy średnio 2834 tokenach na skill, rozdęcie boli szybko. Nasz 13% wskaźnik adopcji utrzymuje agentów szczupłymi.

Struktura umożliwia odkrywalność. System poziomów K to nie tylko organizacja — chodzi o przenośność. Skille K0 można wykorzystać wszędzie. Skille K4 są celowo specyficzne dla projektu. Ta jasność pomaga zarówno ludziom, jak i agentom znaleźć to, czego potrzebują.

Uśpione zakresy skalują. Możesz przyjąć setki skilli bez wczytywania ich wszystkich. Zakresy pozwalają zbudować wyczerpujący rejestr, jednocześnie utrzymując okna kontekstu poszczególnych agentów w ryzach.

Modyfikacja przy adopcji jest niezbędna. Surowe skille dostawców rzadko pasują do Twojego systemu. Proces włączania do rejestru — dodawanie metadanych, przypisywanie poziomów, wzbogacanie tagów — sprawia, że zewnętrzne skille działają wewnętrznie.

Wydobywanie jest ciągłe. Liczba 3500 wciąż rośnie. Pojawiają się nowe repozytoria dostawców. Powstają wzorce społecznościowe. Utrwalają się wewnętrzne przepływy pracy. Pętla nigdy się nie zatrzymuje.

Co dalej

Pracujemy nad kilkoma usprawnieniami:

Automatyczne wykrywanie luk: alarm, gdy częste niepowodzenia agentów mogłyby zostać rozwiązane przez nieprzyjęty skill
Przepływy wycofywania skilli: formalny proces wycofywania skilli, które zostały zastąpione lub są nieużywane
Zależności między skillami: jednoznaczna deklaracja wymagań wstępnych skilla
Analityka użycia: śledzenie, które skille agenci faktycznie wywołują, a nie tylko wczytują

Pętla wydobywania skilli to infrastruktura. Nie jest efektowna. Ale to właśnie ona sprawia, że 41 agentów działa spójnie z 466 zdolnościami, pozostając w granicach kontekstu.

Taka jest historia tego, jak 3500 zamienia się w 466. Nie przez ignorowanie 3000 — przez systematyczną ocenę i przyjęcie tylko tego, co działa.

Chcesz zobaczyć system skilli w akcji? Sprawdź uv run orkestra skills list, żeby przejrzeć nasz obecny rejestr.

Stopniowe ujawnianie: okna CLI do systemów agentowych

Tue, 20 Jan 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Systemy agentowe są nieprzejrzyste z założenia. Podejmują decyzje, wywołują narzędzia i koordynują pracę wśród dziesiątek specjalistów. Ale gdy coś idzie nie tak — albo gdy po prostu chcesz zrozumieć, co się dzieje — gdzie szukasz?

Odpowiedzią jest stopniowe ujawnianie: warstwowy interfejs, który odsłania dokładnie tyle złożoności, ile potrzebujesz, dokładnie wtedy, gdy tego potrzebujesz.

Problem nieprzejrzystości

Nowoczesny system orkiestracji agentów może mieć:

40+ agentów specjalistycznych, każdy z odrębnymi zdolnościami
700+ skilli obejmujących wewnętrzną automatyzację i integracje z dostawcami
470+ decyzji architektonicznych kształtujących zachowanie
Dziesiątki serwerów narzędzi MCP dostarczających zdolności zewnętrzne

Ta złożoność jest zamierzona. Agenci potrzebują dostępu do bogatego kontekstu — wiedzy domenowej, inteligencji kodu, schematów baz danych — żeby podejmować dobre decyzje. Ale to samo bogactwo tworzy problem widoczności.

Skąd wiesz, który agent obsługuje migracje baz danych? Jakie decyzje ukształtowały zachowanie rankingowe systemu wyszukiwania? Do jakich narzędzi ma dostęp doradca architektury?

Bez ustrukturyzowanego dostępu zostajesz z czytaniem kodu źródłowego albo z nadzieją, że dokumentacja jest aktualna.

Stopniowe ujawnianie jako architektura

Stopniowe ujawnianie to nie tylko wzorzec UI. To zasada architektoniczna: organizuj informacje w warstwach, każdą głębszą od poprzedniej, tak by użytkownicy mogli zatrzymać się na poziomie, który odpowiada na ich pytanie.

Dla systemów agentowych przekłada się to na polecenia CLI o rosnącej głębokości:

Poziom	Polecenie	Pytanie, na które odpowiada
1	`orkestra system status`	Czy wszystko działa prawidłowo?
2	`orkestra agents list`	Jakie agenty istnieją?
3	`orkestra agents info <name>`	Co robi ten agent?
4	`orkestra decisions search`	Dlaczego działa w ten sposób?
5	Narzędzia MCP Maguyva	Pokaż mi kod.

Każdy poziom odpowiada na naturalne pytanie uzupełniające. Rzadko musisz skakać od razu do poziomu 5.

Poziom 1: stan systemu

Pierwsze pytanie jest zawsze takie: czy wszystko działa?

$ orkestra system status

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

Jedno polecenie. Cztery liczby. Wystarczająco, żeby wiedzieć, że system jest skonfigurowany, a rejestry wypełnione.

Jeśli liczba agentów nieoczekiwanie spada albo skille nie wczytują się, widzisz to tutaj najpierw. Bez konieczności przekopywania się przez logi.

Poziom 2: inwentarz agentów

Gdy już wiesz, że system działa prawidłowo, kolejne pytanie brzmi: co jest dostępne?

$ orkestra agents list

To zwraca ustrukturyzowane dane — nazwy agentów, opisy, preferowane modele, pokrycie domenowe. Wyjście jest domyślnie w JSON, co ułatwia przepuszczenie go przez jq do filtrowania:

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

Chcesz agentów, którzy obsługują pracę z bazami danych? Polecenie wyszukiwania zawęża to:

$ orkestra agents search "database"

To skanuje nazwy, opisy i zdolności. Znajdujesz właściwego specjalistę bez czytania 40 definicji agentów.

Poziom 3: szczegółowy wgląd w agenta

Znalazłeś agenta, który wygląda na odpowiedni? Polecenie info odsłania wszystko:

$ orkestra agents info architecture-advisor

Wyjście zawiera:

Metadane: nazwa, kategoria, preferowany model, opis
Domeny: które obszary wiedzy obejmuje ten agent
Tożsamość: cechy charakteru (architekt, strateg, knowledge-architect)
Przewodniki narzędzi: która dokumentacja narzędzi jest wstrzykiwana do kontekstu
Narzędzia: pełna lista narzędzi MCP dostępnych dla tego agenta

Oto próbka tego, co widzisz:

{
  "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 mówi Ci dokładnie, co agent potrafi zrobić. Bez potrzeby sięgania po kod źródłowy.

Poziom 4: archeologia decyzji

Agenci zachowują się zgodnie z udokumentowanymi decyzjami. Gdy musisz zrozumieć dlaczego coś działa w konkretny sposób, rejestr decyzji jest źródłem prawdy.

$ orkestra decisions search "agent"

To zwraca pasujące decyzje architektoniczne:

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

Każda decyzja ma pełną historię pochodzenia — kiedy została podjęta, dlaczego, jakie kompromisy rozważano, które commity ją zaimplementowały:

$ 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..."
    }
  ]
}

To dokumentacja architektoniczna, która pozostaje aktualna, ponieważ jest wydobywana z commitów, nie utrzymywana ręcznie.

Poziom 5: bezpośrednia inteligencja kodu

Gdy musisz zobaczyć rzeczywistą implementację — nie metadane o niej — narzędzia MCP Maguyva dostarczają bezpośredniego dostępu.

Z poziomu sesji agenta:

mcp__maguyva__intelligent_search
  query: "agent context loading"

To automatycznie trasuje przez wyszukiwanie semantyczne, tekstowe i AST, żeby znaleźć odpowiedni kod. Dla konkretnych symboli:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Dla analizy zależności:

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

To nie są tylko zamienniki grep. Uwzględniają graf, są semantycznie zaindeksowane i zintegrowane z tą samą inteligencją kodu, która napędza samych agentów.

Ujednolicone wyszukiwanie w rejestrach

Czasem nie wiesz, który rejestr zawiera odpowiedź. Ujednolicone wyszukiwanie obejmuje wszystko:

$ orkestra search "database" --summary

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

254 dopasowania w pięciu rejestrach. Podsumowanie mówi Ci, gdzie wejść głębiej. Usuń --summary, żeby uzyskać szczegółowe wyniki, albo dodaj --limit 5, żeby utrzymać wyjście w ryzach.

Dlaczego to ma znaczenie

Stopniowe ujawnianie to nie tylko wygoda. Zmienia sposób, w jaki wchodzisz w interakcję ze złożonymi systemami.

Debugowanie staje się wykonalne. Gdy agent podejmuje nieoczekiwaną decyzję, nie przeszukujesz logów za pomocą grep. Sprawdzasz, do jakich narzędzi ma dostęp (agents info), jakie decyzje kształtują jego zachowanie (decisions search), i śledzisz implementację, jeśli to konieczne (intelligent_search).

Onboarding przyspiesza. Nowi członkowie zespołu nie muszą czytać całej bazy kodu. Zaczynają od system status, eksplorują za pomocą agents list i idą głębiej dopiero, gdy trafią na coś, czego nie rozumieją.

Dokumentacja pozostaje aktualna. Ponieważ CLI czyta z tych samych rejestrów, które konfigurują agentów, wyjście jest zawsze dokładne. Nie ma rozjazdu między tym, co mówi dokumentacja, a tym, co robi system.

CLI jako interfejs

Mogliśmy zbudować dashboard webowy. Mogliśmy napisać obszerną dokumentację. Zamiast tego zbudowaliśmy CLI, które czyta ze źródła prawdy.

CLI ma przewagi:

Komponowalne: przepuszczaj wyjście przez jq, integruj ze skryptami
Skryptowalne: automatyzuj sprawdzenia, generuj raporty
Szybkie: bez ładowania stron, bez przepływów uwierzytelniania
Dokładne: czyta faktyczną konfigurację, nie zbuforowaną reprezentację

Dla systemów, w których poprawność liczy się bardziej niż estetyka, CLI wygrywa.

Budowanie własnego stopniowego ujawniania

Jeśli budujesz systemy agentowe, rozważ, jak użytkownicy będą je sprawdzać:

Zacznij od kontroli stanu systemu. Jedno polecenie, które mówi Ci, czy rzeczy działają.
Dostarcz widoki inwentarza. Wypisz, co istnieje, zanim wyjaśnisz, co to robi.
Umożliw celowane zapytania. Wyszukiwanie bije przeglądanie na dużą skalę.
Odsłoń pochodzenie. Pozwól użytkownikom śledzić decyzje do ich źródeł.
Połącz z inteligencją kodu. Ostatecznie użytkownicy muszą zobaczyć implementację.

Każda warstwa odpowiada na pytanie uzupełniające. Buduj je w kolejności częstotliwości — większość użytkowników zatrzymuje się na warstwie 2 lub 3. Tylko zaawansowani użytkownicy sięgają warstwy 5.

Celem nie jest odsłonięcie wszystkiego. Celem jest odsłonięcie dokładnie tego, co potrzebne, dokładnie wtedy, gdy jest potrzebne. To właśnie jest stopniowe ujawnianie zastosowane do architektury agentowej.

Ground Truths: zakotwiczanie agentów AI w rzeczywistości

Tue, 13 Jan 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Agenci AI są niezwykle zdolni. Potrafią rozumować, syntetyzować i generować. Ale mają fundamentalną słabość: zmyślają. Nie złośliwie, ale z pełnym przekonaniem. Agent może wymyślić parametry API, które nie istnieją, odwołać się do konfiguracji, które nigdy nie zostały zdefiniowane, albo zastosować wzorce ze swoich danych treningowych, które są sprzeczne z Twoją rzeczywistą architekturą.

Standardowym środkiem zaradczym jest „daj agentowi więcej kontekstu”. Ale kontekst może być sprzeczny. Dokumentacja odbiega od implementacji. Komentarze kłamią. Nawet kod może wprowadzać w błąd, gdy czyta się go bez zrozumienia intencji.

Potrzebowaliśmy czegoś bardziej jednoznacznego. Czegoś, czego nie da się zignorować ani błędnie zinterpretować. Czegoś, co zakotwiczy agentów w weryfikowalnej rzeczywistości.

Nazywamy je Ground Truths — faktami odniesienia.

Czym jest Ground Truth?

Ground truth to jednoznaczne, wersjonowane stwierdzenie faktu, którego agenci muszą przestrzegać. To nie dokumentacja. To nie komentarz. To pełnoprawna jednostka w systemie z:

Unikalnym identyfikatorem (takim jak GT-MAG-015 czy GT-MAG-036)
Statusem cyklu życia (aktualny, tymczasowy lub przestarzały)
Zakresem (obejmujący całą platformę, specyficzny dla pakietu lub związany z domeną)
Dowodem (ścieżki plików, adresy URL lub referencje, które potwierdzają stwierdzenie)
Wskazówkami dla agenta (jednoznaczne instrukcje rób/unikaj)

Oto przykład z naszej platformy inteligencji kodu 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

To nie jest proza. To kontrakt. Gdy agent natrafia na ten ground truth, wie, że:

Domyślne zachowanie jest deterministyczne (puste wyniki, nie rozmyte zgadywanie)
Istnieją konkretne parametry (find_similar, exact_match) o zdefiniowanym zachowaniu
Dowody istnieją w konkretnych plikach, które można zweryfikować
Stwierdzenie zostało zweryfikowane w konkretnej dacie

Anatomia rejestru Ground Truths

Ground truths żyją w rejestrach YAML pod ai_assets/reference/ground_truths.yaml. Każdy pakiet lub domena może mieć swój własny rejestr. Struktura wygląda tak:

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..."
    ...

Rejestr zawiera metadane o samej kolekcji, konfigurację renderowania na potrzeby generowania dokumentacji oraz same stwierdzenia. Każde stwierdzenie podlega ścisłemu schematowi walidowanemu przez modele Pydantic:

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 agenci uzyskują dostęp do Ground Truths

Ground truths są udostępniane przez wiele kanałów:

1. Wyrenderowana dokumentacja

Polecenie orkestra sync przekształca rejestry YAML w czytelny markdown:

uv run orkestra sync

Generuje to pliki GROUND_TRUTHS.md, które są włączane do kontekstu agenta. Wyrenderowany wynik grupuje stwierdzenia według statusu i kategorii:

## 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. Wyszukiwanie CLI

Agenci z dostępem do powłoki mogą przeszukiwać ground truths programowo:

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

Funkcja wyszukiwania ocenia dopasowania w wielu polach z ważoną trafnością:

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. Kompozycja kontekstu

Gdy agenci są renderowani z definicji YAML, ich kontekst może odwoływać się do rejestrów ground truths:

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

To zapewnia, że odpowiednie ground truths są wczytane, zanim agent zacznie pracę.

Kategorie Ground Truths

Patrząc na nasze rejestry, ground truths skupiają się w kilku wzorcach:

Zasady produktowe

Ograniczenia dotyczące tego, czym produkt jest, a czym nie jest:

„Maguyva korzysta z repozytoriów użytkowników wyłącznie w trybie odczytu; jedynym zasobem, którego nie da się odbudować, jest płatny cache embeddingów.” (GT-MAG-001)

Granice architektury

Gdzie leżą odpowiedzialności i dlaczego:

„Granice pipeline’u i Maguyva są celowe: pipeline jest wielokrotnego użytku, Maguyva przechowuje logikę specyficzną dla kodu, a CQRS oddziela operacje zapisu etapów potoku od operacji odczytu serwera.” (GT-MAG-006)

Zasady antyhalucynacyjne

Jednoznaczne reguły zapewniające deterministyczne kontrakty narzędzi zamiast opierania ich na domysłach:

„Rozmyte dopasowywanie symboli jest opcjonalne (opt-in) przez find_similar=true. Domyślne zachowanie zwraca puste wyniki dla nieistniejących symboli; exact_match=true wymusza ścisłe dopasowywanie i wyłącza wszystkie rozmyte fallbacki.” (GT-MAG-015)

Kontrole jakości

Standardy, które muszą być utrzymywane:

„Zmiany we współdzielonej infrastrukturze (post_filters.py, ekstraktory relacji, współdzielone handlery) MUSZĄ być zwalidowane względem WSZYSTKICH obsługiwanych języków przez generowanie pełnego manifestu przed commitem. Walidacja jednego języka jest niewystarczająca dla kodu współdzielonego.” (GT-MAG-036)

Wzorce kodu

Wymagania implementacyjne:

„Używaj asyncio.to_thread() do pracy obciążającej CPU w kontekstach asynchronicznych; przestarzały wzorzec loop.run_in_executor() nie powinien być używany w nowym kodzie.” (GT-MAG-018)

Cykl życia Ground Truth

Ground truths nie są statyczne. Ewoluują przez zdefiniowany cykl życia:

Tymczasowy

Proponowana prawda w trakcie oceny. Stwierdzenie jest zapisane, ale może się zmienić:

- 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.

Aktualny

Zweryfikowana prawda, której agenci muszą przestrzegać. Dowody zostały zwalidowane:

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

Przestarzały

Prawda, która już nie ma zastosowania. Zachowana jako odniesienie historyczne ze wskazaniem tego, co ją zastąpiło:

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

Dlaczego nie zwykła dokumentacja?

Dokumentacja służy innemu celowi. Wyjaśnia. Uczy. Może być niejednoznaczna, może używać kwalifikatorów takich jak „ogólnie” czy „zazwyczaj”.

Ground truths nie mogą być niejednoznaczne. To są asercje. Albo mają zastosowanie, albo nie.

Rozważ tę różnicę:

Dokumentacja: „API zazwyczaj zwraca puste wyniki, gdy symbol nie zostanie znaleziony, choć w niektórych konfiguracjach może być włączone rozmyte dopasowywanie.”

Ground Truth: „Domyślne zachowanie zwraca puste wyniki dla nieistniejących symboli; exact_match=true wymusza ścisłe dopasowywanie i wyłącza wszystkie rozmyte fallbacki.”

Pierwsze jest pomocne dla ludzi uczących się systemu. Drugie jest gotowe do działania dla agentów podejmujących decyzje.

Wskazówki dla agenta: rób i unikaj

Niektóre ground truths zawierają jednoznaczne wskazówki dla 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"

To usuwa niejednoznaczność. Agent czytający to wie nie tylko, co jest prawdą, ale jakie działania ta prawda implikuje.

Weryfikacja i utrzymanie

Ground truths wymagają utrzymania. Śledzimy:

last_verified: kiedy ktoś potwierdził, że stwierdzenie nadal obowiązuje
evidence: pliki, które potwierdzają stwierdzenie (można sprawdzić ich istnienie)
source: skąd pochodzi prawda (inspekcja CLI, przegląd architektury, wnioski po incydencie)

Ground truth z nieaktualnymi datami weryfikacji lub zerwanymi linkami do dowodów jest sygnałem do zbadania. Albo prawda wciąż jest ważna i wymaga ponownej weryfikacji, albo rzeczywistość się zmieniła i prawda wymaga aktualizacji.

Prawdziwe przykłady z produkcji

Granica bezpieczeństwa

- 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.

Ten ground truth zapobiega klasie błędnie pojętych „usprawnień bezpieczeństwa”, które zepsułyby produkt.

Dokładność w czasie ekstrakcji

- 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.

To wynikło z bolesnego doświadczenia. Agenci łatali zawodzące pakiety językowe, dodając filtry działające tylko w walidatorze, które sprawiały, że harness testowy wyglądał na bardziej zielony, podczas gdy działający ekstraktor Maguyva wciąż emitował złe krawędzie. Ta zasada zmusza naprawy z powrotem na prawdziwą ścieżkę: konfigurację YAML, zapytania lub handlery.

Filtrowanie wielopoziomowe

- 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).

To zapobiega dodawaniu przez agentów filtrów w niewłaściwym miejscu — częstemu błędowi, który powodował regresje dokładności.

Integracja z systemem orkiestracji

Ground truths to jedna warstwa szerszego systemu kontekstu:

Decyzje architektoniczne (ADR) - Zapisują, dlaczego wybraliśmy podejście A zamiast B
Ground Truths - Stwierdzają, co jest jednoznacznie prawdziwe teraz
Wzorce domenowe - Opisują, jak robić rzeczy poprawnie
Antywzorce - Opisują, czego unikać i dlaczego

Agent pracujący w systemie ma dostęp do wszystkich czterech. Ground truths dostarczają faktycznej kotwicy, decyzje wyjaśniają historię, wzorce prowadzą implementację, a antywzorce ostrzegają przed pułapkami.

Mierzenie wpływu

Od czasu wprowadzenia ground truths zaobserwowaliśmy:

Mniej cykli „napraw halucynowaną naprawę”
Bardziej pewne decyzje agentów, gdy fakty są jasne
Lepsze przeglądy PR, ponieważ oczekiwania są jednoznaczne
Skrócony czas wdrażania nowych agentów (i ludzi)

Inwestycja w utrzymanie ground truths zwraca się w postaci mniejszej liczby debugowań i wyraźniejszych granic systemu.

Jak zacząć

Aby dodać ground truth do swojego systemu:

Utwórz ground_truths.yaml w katalogu ai_assets/reference/ swojego pakietu
Zdefiniuj metadane i konfigurację renderowania
Dodaj stwierdzenia zgodnie ze schematem
Uruchom uv run orkestra sync, aby wygenerować dokumentację
Uwzględnij rejestr w kompozycji kontekstu agenta

Zacznij od faktów, które powodują najwięcej zamieszania, lub ograniczeń, które są najczęściej łamane. To Twoje najbardziej wartościowe ground truths.

Podsumowanie

Agenci AI będą halucynować. To ich natura. Ale możemy tworzyć środowiska, w których halucynacja jest ograniczona, w których pewne fakty są nienegocjowalne, w których agenci mogą sprawdzić swoje założenia względem zweryfikowanej rzeczywistości.

Ground truths nie są kompletnym rozwiązaniem. Wymagają utrzymania. Mogą stać się nieaktualne. Dodają narzut do procesu rozwoju.

Ale dają coś wartościowego: wspólne słownictwo faktów, któremu ludzie i agenci mogą zaufać. W świecie, w którym agenci coraz częściej uczestniczą w tworzeniu oprogramowania, ten wspólny fundament staje się niezbędny.

Alternatywą są niekończące się cykle, w których agenci z pełnym przekonaniem popełniają błędy, a ludzie je korygują. Ground truths przerywają ten cykl, czyniąc korekty jednoznacznymi i trwałymi.

Twoi agenci zasługują na to, by wiedzieć, co jest prawdą. Powiedz im.

Orkestra: orkiestracja agentów AI na dużą skalę

Tue, 06 Jan 2026 00:00:00 GMT

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Gdy zaczęliśmy budować z Claude Code, natrafiliśmy na problem, z którym prędzej czy później mierzy się każdy zespół korzystający z asystentów kodujących AI: jeden agent nie potrafi robić wszystkiego dobrze.

Możesz podpowiedzieć agentowi, żeby był specjalistą od baz danych. Albo audytorem bezpieczeństwa. Albo inżynierem frontendu. Ale w chwili, gdy poprosisz go, żeby był tymi trzema naraz, jakość spada. Kontekst się rozmywa. Instrukcje wchodzą w konflikt. Agent staje się generalistą, który jest przeciętny we wszystkim.

Więc zbudowaliśmy Orkestrę.

Czym jest Orkestra?

Orkestra to system orkiestracji agentów dla Claude Code i podobnych narzędzi AI do kodowania. Koordynuje wielu wyspecjalizowanych agentów, każdego z odrębną ekspertyzą, pod jednym orkiestratorem, który kieruje pracę do właściwego specjalisty.

Pomyśl o tym jak o agencji zatrudnienia dla agentów AI. Orkiestrator otrzymuje zadanie, identyfikuje, który specjalista powinien się nim zająć, i deleguje z właściwym kontekstem. Gdy praca jest gotowa, wyniki wracają do orkiestratora do syntezy.

Liczby mówią same za siebie:

Komponent	Liczba
Agenci specjalistyczni	46
Skille wielokrotnego użytku	466
Archetypy tożsamości	27
Sposoby myślenia (mindsety)	11
Style komunikacji	10
Domeny wiedzy	21

System charakteru: D&D dla agentów

Kluczową obserwacją stojącą za Orkestrą jest to, że zachowanie agenta wyłania się z trzech komponowalnych prymitywów:

Tożsamość definiuje, czym jest agent. Architekt projektuje struktury systemowe. Debugger śledzi awarie do ich pierwotnych przyczyn. Strażnik pilnuje zgodności z zasadami i przestrzegania granic bezpieczeństwa. Mamy 27 archetypów tożsamości, które można mieszać.

Mindset definiuje, jak agent myśli. Analityczny mindset zakotwicza twierdzenia w dowodach i kwantyfikuje niepewność. Sceptyczny mindset kwestionuje założenia i szuka dowodów obalających. Eksploracyjny mindset akceptuje niejednoznaczność i próbuje wielu podejść.

Styl definiuje, jak agent się komunikuje. Techniczny styl zawiera dokładne wartości i odwołuje się do konkretnych plików. Zwięzły styl obcina ozdobniki i zaczyna od odpowiedzi. Dyplomatyczny styl równoważy szczerość z taktem.

Agent łączy te prymitywy:

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

Ta kompozycja tworzy agenta, który projektuje systemy (architekt), łączy wiedzę między domenami (knowledge-architect), wyznacza kierunek strategiczny (strategist), myśli w kategoriach dowodów i danych (analityczny) i komunikuje się bez ozdobników (zwięzły).

Moc tkwi w eksplozji kombinatorycznej. 27 tożsamości razy 11 mindsetów razy 10 stylów daje prawie 3000 możliwych osobowości agentów. Ale definiujesz tylko te kombinacje, które mają znaczenie dla Twojej pracy.

Skille: wielokrotnego użytku moduły zdolności

Skille to wiedza i przepływy pracy, które agenci mogą wywoływać. Podlegają wielopoziomowemu systemowi opartemu na zakresie:

Poziom	Nazwa	Zakres	Przykład
K0	Fundamenty	Uniwersalna metodologia	Dyscyplina test-first, ukończenie oparte na dowodach
K1	Tożsamości	Przepływy pracy oparte na roli	Standardy interfejsu CLI, playbook wydajności
K2	Domeny	Wiedza specyficzna dla domeny	Wzorce migracji baz danych, walidacja uwierzytelniania
K3	Stosy	Specyficzne dla technologii	Wdrożenie Cloudflare, operacje Supabase
K4	Projekt	Tylko ta baza kodu	Przepływy pracy i konwencje specyficzne dla projektu

Skille są ładowane leniwie (lazy-loaded). Agent widzi nazwy i opisy skilli przy starcie, ale pełna treść skilla wczytuje się dopiero po wywołaniu. To utrzymuje kontekst szczupły, jednocześnie czyniąc setki skilli odkrywalnymi.

Każdy skill zawiera:

Jasne warunki wyzwalające („Użyj podczas migracji schematów bazy danych”)
Wskazówki krok po kroku
Dozwolone narzędzia dla przepływu pracy
Kryteria sukcesu i ścieżki odzyskiwania po niepowodzeniu

466 skilli w naszym rejestrze obejmuje wszystko, od izolacji git worktree po przepływy pracy badań webowych po walidację kondycji wdrożenia.

Dlaczego orkiestracja ma znaczenie

Architektury jednoagentowe szybko trafiają na ściany:

Rozmycie kontekstu. Okno kontekstu 200 tys. tokenów brzmi ogromnie, dopóki nie wczytasz schematów baz danych, dokumentacji API, fixture’ów testowych i wiedzy domenowej. Specjaliści mogą pracować z celowanym kontekstem.

Konflikty instrukcji. Powiedzenie agentowi „bądź dokładny, ale szybki” i „zweryfikuj wszystko, ale nie przeinżynieruj” tworzy napięcie. Specjaliści rozwiązują to, mając jasny zakres.

Głębia ekspertyzy. Agent generalista wie trochę o wszystkim. Agent specjalista, złożony z właściwej tożsamości i skilli, zna swoją domenę głęboko.

Orkestra implementuje płaską orkiestrację: jeden orkiestrator koordynuje wielu specjalistów. Specjaliści nie mogą tworzyć sub-specjalistów. To zapobiega eksplozji złożoności, jednocześnie umożliwiając pracę równoległą.

Orkiestrator ma dostęp do 2,2 miliona tokenów efektywnej pojemności: własne okno 200 tys. plus 10 równoczesnych subagentów po 200 tys. każdy. Praca, która wyczerpałaby jednego agenta, przebiega swobodnie w całej flocie.

Pipeline renderowania

Definicje agentów żyją w YAML. Claude Code czyta Markdown. Orkestra niweluje tę różnicę deterministycznym pipeline’em renderowania:

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

Operatorzy edytują źródło YAML. Uruchamiają orkestra sync. Wyrenderowany Markdown pojawia się w .claude/agents/. Claude Code odbiera zmiany.

To rozdzielenie służy różnym odbiorcom:

Źródło YAML zawiera metadane cyklu życia, tagi, reguły walidacji i notatki o wycofaniu na potrzeby narzędzi
Wyrenderowany Markdown zawiera tylko to, czego potrzebuje model: opis, narzędzia, skille i wskazówki behawioralne

Pipeline składa tożsamości, mindsety, style i skille w jeden spójny prompt. Agent architekt-analityczny-zwięzły otrzymuje bardzo inny prompt systemowy niż agent debugger-sceptyczny-techniczny, nawet jeśli dzielą część leżących u podstaw skilli.

Wiedza domenowa: wzorzec czterech plików

Każda domena wiedzy podąża za spójną strukturą:

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

Ta struktura służy wczytywaniu kontekstu agenta. Agent pracujący nad uwierzytelnianiem wczytuje authentication/patterns.md dla wskazówek i authentication/anti-patterns.md, by unikać znanych pułapek. Objętość plików jest dobrana tak, aby efektywnie wczytywać kontekst: treść jest wystarczająco konkretna, by być użyteczna, i wystarczająco wyczerpująca, by być wiarygodna.

Utrzymujemy 21 domen najwyższego poziomu, w tym analitykę, uwierzytelnianie, data science, infrastrukturę, uczenie maszynowe, wydajność, bezpieczeństwo i inne. Każda domena może mieć poddomeny dla drobniejszej granularności.

Wartości: system operacyjny

Wszyscy agenci dzielą bazową warstwę wartości, która definiuje, jak działają:

Prostota przede wszystkim. Używaj najprostszego rozwiązania, które działa. Dodawaj złożoność tylko wtedy, gdy jest uzasadniona.

Napraw pierwotne przyczyny. Nigdy nie maskuj awarii obejściami. Jeśli pipeline zawodzi, debuguj pipeline. Jeśli test zawodzi, napraw kod albo test.

Oparte na dowodach. Oznaczaj twierdzenia jako „zweryfikowane” (z benchmarkami) lub „szacowane” (z założeniami). Wykryty wzorzec nie równa się potwierdzonemu problemowi.

Ekonomia kontekstu. Narzędzia MCP kosztują 0,1% kontekstu. Odczyty plików kosztują po 2% każdy. Zastosuj ekspertyzę domenową, zanim zaczniesz eksplorować kod.

Te wartości propagują się do każdego specjalisty przez pipeline renderowania. Agent nie może ich obejść przez kompozycję.

CLI: płaszczyzna kontroli

Orkestra dostarczana jest z CLI do zarządzania ekosystemem agentów:

# 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 jest źródłem prawdy o tym, jakie agenty istnieją, jakie mają skille i czy system jest zdrowy. Uruchamia walidację przed synchronizacją, żeby wcześnie wychwycić problemy.

Rozważania dotyczące open source

Zbudowaliśmy Orkestrę, żeby rozwiązać nasz własny problem: koordynację agentów AI na dużą skalę dla złożonej bazy kodu. Wzorce, które odkryliśmy, nie są specyficzne dla naszej domeny.

System kompozycji charakteru (tożsamość + mindset + styl) ma zastosowanie do każdego zespołu definiującego osobowości agentów.

System poziomów skilli (K0-K4) dostarcza modelu mentalnego do organizowania wielokrotnego użytku zdolności według zakresu.

Wzorzec pipeline’u renderowania (źródło YAML + szablony + wygenerowane artefakty) rozdziela odpowiedzialności między narzędzia a konsumpcję przez model.

Płaski model orkiestracji (jeden koordynator, wielu specjalistów) unika eksplozji złożoności, jednocześnie umożliwiając równoległość.

Czy Orkestra stanie się open source, zależy od tego, czy te wzorce mają wartość dla innych budujących z Claude Code. Jeśli trafiasz na te same ściany, które opisaliśmy, ta architektura może pomóc.

Czego się nauczyliśmy

Budowanie Orkestry nauczyło nas, że orkiestracja nie polega na czynieniu agentów mądrzejszymi. Polega na czynieniu ich bardziej skupionymi.

Pojedynczy agent z idealnymi instrukcjami wciąż wyczerpuje kontekst. Pojedynczy agent ze wszystkimi skillami wciąż gubi się w tym, który zastosować. Pojedynczy agent próbujący być wszystkim produkuje przeciętne wyniki wszędzie.

Czterdziestu specjalistów, z których każdy jest doskonały w swojej domenie, koordynowanych przez orkiestratora, który wie, kiedy delegować: tak dostarczamy oprogramowanie.

Liczby mają mniejsze znaczenie niż architektura. Możesz potrzebować pięciu agentów albo pięćdziesięciu. Zasada pozostaje: kompozycja ponad zdolność, specjalizacja ponad generalizację, koordynacja ponad indywidualne bohaterstwo.

Orkestra napędza ekosystem agentów stojący za Maguyva, naszą platformą inteligencji kodu. Chcesz dowiedzieć się więcej? Skontaktuj się z zespołem.