Maguyva-blogi

Konteksti, joka kulkee mukanasi

Mon, 07 Sep 2026 00:00:00 GMT

Cursor indeksoija on erinomainen Cursor sisällä. Tab-täydennys, rivinsisäinen muokkaus, chat, ja agentti siinä ikkunassa nojaavat jo projektin indeksiin, jota Cursor ylläpitää avoinna olevalle työtilalle. Jos Cursor on ainoa pinta, jossa kirjoitat, ja indeksi löytää jo oikeat tiedostot, pysy siellä. Se on rehellinen ‘pysy siellä missä olet’ -tapaus, ja se ansaitsee olla tämän sivun ensimmäinen lause.

Tämä teksti kertoo tavallisen viikon toisesta puoliskosta. Sama repositorio avataan myös Claude Code, siltä kysytään Codex CLI:stä, se katselmoidaan toisella koneella, tai sitä kysyy CI:ssä ajettava agentti. Kysymys ei ole ‘kumpi indeksoija on parempi’. Kysymys on, onko kartta, johon agentti luottaa yhdessä ikkunassa, sama kartta, johon se luottaa seuraavassa.

Maguyva on se kartta, joka kulkee mukanasi. Se on etäinen MCP-koodikannan kontekstikerros. Agentti kysyy sitä samalla tavalla kuin mitä tahansa muuta MCP-työkalua. Tulokset palautuvat järjestettyinä polkuina rivinumeroineen. Cursor pysyy editorina. Konteksti on se, mikä liikkuu.

Mihin Cursor indeksoija on tarkoitettu

Cursor sisäänrakennettu indeksointi on olemassa, jotta chat, agentti ja haku editorin sisällä voivat hakea relevanttia koodia sen sijaan, että ne luottaisivat vain siihen, mikä mahtuu mallin raakaan kontekstiikkunaan. Se on oikea suunnittelu IDE:lle. Tämä indeksi on natiivi Cursor. Se ei ole MCP-palvelin eikä ole tavoitettavissa mistään muusta asiakasohjelmasta.

Näin se toimii, kuten kuvattu Cursor julkisessa dokumentaatiossa ja Cursor omassa kuvauksessa tämän kirjoitushetkellä: ensisijainen hakupolku ei ole enää pilvipohjainen embedding-indeksi. Cursor tiimi on ilmoittanut yhteisöfoorumillaan, että omistautunut semanttinen, embeddingeihin perustuva haku ajetaan alas grep-pohjaisen haun hyväksi, koska nykyiset mallit tutkivat jo elävää puuta itsekin riittävän hyvin. Sen tilalla on Instant Grep, paikallinen hakuindeksi rakennettu n-grammeista, käänteisistä listoista ja Bloom-suodattimista, säilytettynä muistiin kartoitetussa hakutaulussa, jotta kyselyt ratkaistaan kehittäjän omalla koneella palvelimen sijaan.

Itse indeksi elää repositorion omassa .git/cursor/-hakemistossa, ankkuroituna tiettyyn git-committiin; muutokset tuon committin jälkeen kerrostuvat sen päälle sen sijaan, että ne käynnistäisivät uuden skannauksen, ja indeksi rakennetaan uudelleen vain, kun paikallinen tila on ajautunut kauas siitä, mitä vasten se rakennettiin. Koska se sijaitsee .git:n sisällä, sitä ei koskaan seurata eikä koskaan pusheta — poista kansio, ja indeksi katoaa. .gitignore toteutuu rakenteen ansiosta, koska vain gitillä seurattu sisältö on kelvollista, ja .cursorignore pakotetaan lukupolulla. Sillä polulla ei ole enää palvelinpuolen embedding-vaihetta eikä etäistä vektoritietokantaa. Aiempi dokumentaatio kuvasi pilviavusteisen suunnittelun — lohkojen salauksen, synkronoinnin Merkle-puun kautta, indeksin uudelleenkäytön tiimin jäsenten välillä — ja Cursor oma tiimi on sittemmin sanonut, että tuo suunnittelu ajetaan alas, joten tämä teksti ei enää kuvaa sitä ajankohtaisena.

Editorin sisällä erottuva vahvuus on Cursor Explore-alaagentti. Se voi käynnistää useita rinnakkaisia hakuja omassa kontekstiikkunassaan nopeammalla mallilla ja palauttaa vain relevantit löydökset, jotta pääkeskustelu ei paisu hakutuloksista. Se on aito vahvuus editorin sisällä. Säilytä se.

Monijuuriset työtilat ovat tuettuja: jokaisen avatun kansion konteksti on Agentin käytettävissä. Jotkin gitistä riippuvat ominaisuudet, kuten worktreet, on poistettu käytöstä monijuurisissa asetuksissa, eivätkä Cloud Agents tue lainkaan monijuurisia työtiloja.

Mikään näistä ei ole syy jättää Cursor. Se on tarkka kuvaus kartasta, joka on erinomainen siellä, missä se elää.

Mitä ‘kulkea mukanasi’ oikeasti tarkoittaa

Kartta kulkee mukanasi, kun samat kysymykset palauttavat saman tyyppisen vastauksen, lainauksineen, jotka voit avata, useammasta kuin yhdestä asiakasohjelmasta.

Cursor: ‘Missä parseConfig on määritelty, ja kuka sitä kutsuu?’
Claude Code, samassa repossa: sama kysymys.
Codex CLI:ssä, katselmointikoneella, joka ei ole koskaan avannut Cursor-ikkunaa: sama kysymys.
CI-agentissa, joka puhuu MCP:tä: sama kysymys, samaa isännöityä tilannevedosta vasten.

Jos jokainen pinta rakentaa oman yksityisen indeksinsä, sinulla ei ole yhtä karttaa. Sinulla on useita välimuisteja, jotka ajautuvat erilleen. Editorin indeksi voi olla ajan tasalla levyllä olevalle puulle. CLI-istunto voi olla päivän jäljessä. CI-työ voi katsoa eri checkoutia. Ja agentti kuulostaa silti itsevarmalta.

Cursor indeksoijan ei ole tarkoitus ratkaista tätä. Koska se elää editorin sisällä, konteksti, jonka se rakentaa, on sitä editoria varten. Lukija, joka tarvitsee myös CLI:n, CI-putken, tai eri editorin, tarvitsee erillisen työkalun näille pinnoille. Se on laajuuden tosiasia, ei puute. Maguyva on se erillinen työkalu.

Julkaistua kielten määrää Cursor indeksoijalle ei ole ilmoitettu materiaaleissa, joita tämä teksti saa käyttää. Maguyva julkaisee tuen yli 279 kielelle ja tekstipohjaisille teknologioille. Cursor hintoja ei myöskään toisteta tässä; katso heidän hintasivunsa. Maguyva veloittaa työtilaa kohden, ei paikkaa kohden, julkaistuilla hinnoilla $0, $19, $49 ja $149 indeksoidun laajuuden ja työtilan koon mukaan.

Yksi isännöity kartta, jokainen MCP-asiakasohjelma

Maguyva on etäinen MCP-palvelin. Yhdistät GitHub, valitset repositoriot, ja pilviputki rakentaa symbolit, graafin reunat ja järjestetyn kartan. Lisäät API-avaimen jo käyttämäsi asiakasohjelman MCP-asetuksiin. Maguyva on asennusoppaat 24 dokumentoidulle MCP-asiakasohjelmalle — Cursor mukaan lukien — ja se voi yhdistää muihin MCP-yhteensopiviin asiakasohjelmiin, jotka tukevat vakioasetuksia.

Cursor asennussivu on editorikohtainen polku, jos siellä työskentelet. Sama palvelin vastaa Claude Code, VS Code, Windsurf, Codex CLI:lle ja muille. Et vaihda editoria. Annat jokaiselle agentille saman työkalupinnan: 11 asiakaskäyttöistä MCP-työkalua haulle, symboleille, riippuvuusanalyysille, tiedostojen haulle, repo-kontekstille ja deterministisille apuohjelmatyönkuluille. Semanttinen, rakenteellinen, graafi- ja tekstihaku sulautuvat järjestetyiksi tuloksiksi.

Siinä on siirrettävyyden hyöty. Lainaukset, jotka tarkistit Cursor tänä aamuna, ovat samanmuotoisia kuin lainaukset, jotka Codex CLI palauttaa tänä iltana. Tiedostopolku ja rivinumero. Avaa ne. Jos ne ovat väärin, näet sen. Jos ne ovat oikein, seuraavalla muutoksella on paikka laskeutua. Hyväksytty väite on vähemmän hallusinoituja muutoksia, ei lupaus siitä, että jokainen muutos on oikein.

Tuoreus on julkaistu. Tilannevedokset on aikaleimattu, joten agentti tietää, mitä versiota puusta se lukee. Uudelleenrakennustahti on päivittäinen ilmaisella suunnitelmalla ja tunneittainen maksullisilla suunnitelmilla. Rehellinen rajoitus on synkronoimaton paikallinen työ: muutos, joka on olemassa vain työpuussa, ei ole vielä isännöidyssä kartassa. Tämä rajoitus on sama riippumatta siitä, mistä asiakasohjelmasta kysyt, ja juuri se on pointti. Asiakasohjelmien välinen ajautuminen ei ole enää toinen, piilotettu rajoitus.

Dokumentaatio antaa aktivointisilmukan, joka pätee jokaiseen asiakasohjelmaan: indeksoi repo, jonka jo tunnet, yhdistä asiakasohjelma, esitä yksi kysymys, jonka voit varmistaa. Tee se kerran Cursor. Tee se uudelleen siitä CLI:stä, jota oikeasti käytät katselmointipäivinä. Jos molemmat vastaukset lainaavat samaa käsittelijää, kartta todella kulki mukanasi.

Kuinka kaksi karttaa elävät rinnakkain

Käytä molempia. Ne eivät ole vaihtoehtoja vertailusivun mielessä.

Pidä Cursor indeksoija päällä levyllä olevalle projektille. Anna Exploren, Instant Grepin ja editorin sisäisen agentin käyttää sitä. Tuo silmukka on natiivi ja nopea.
Lisää Maguyva MCP-palvelimeksi Cursor, jotta sama istunto voi myös kysyä isännöityä työtilan karttaa. Cursor on dokumentoitu Maguyva-asiakasohjelma. Et valitse yhtä indeksiä poistamalla toista.
Lisää sama Maguyva-palvelin Claude Code, Codex CLI:hin, tai mihin tahansa muuhun MCP-asiakasohjelmaan, joka koskettaa repoa. Yksi API-avaimen muoto. Yksi työtila.
Jos CI-agentti on MCP-yhteensopiva, osoita se samaan palvelimeen. Se lukee saman aikaleimatun tilannevedoksen, jonka kannettava luki.

Editorin indeksi pysyy parhaana työkaluna kysymykselle ‘mitä levyllä on tässä ikkunassa juuri nyt’. Isännöity kartta on paras työkalu kysymykselle ‘miltä tämä työtila näyttää jokaiselle agentille, joka koskettaa sitä tänään’. Nämä lauseet eivät kilpaile.

Työtilakiintiöt julkaistaan hintasivulla: repot, indeksoidut rivit ja käyttäjät, laskutettuna työtilaa kohden. Agentit ja ihmiset jakavat saman käyttäjämäärän. Aloita ilmaiseksi repolla, jonka jo osaat arvioida. Nosta työtilaa vasta sen jälkeen, kun lainaukset ovat selvinneet kosketuksesta puun kanssa.

Mitä tämä sivu ei väitä

Se ei väitä, että Cursor indeksoija on heikko, puutteellinen, tai syy vaihtaa editoria. Tämän tekstin ensimmäinen lause sanoo päinvastaista.

Se ei väitä, että Maguyva korvaa Instant Grepin tai Explore-alaagentin. Ne ovat Cursor ominaisuuksia. Ne pysyvät Cursor.

Se ei keksi kielten määrää, viivelukua, tai token-säästöä kummallekaan tuotteelle. Tuntemattomat luvut pysyvät julkaisemattomina.

Se ei teeskentele, että pushaamaton paikallinen työ on isännöidyssä kartassa. Aikaleimatut tilannevedokset tekevät tuon rajoituksen näkyväksi. Ne eivät poista sitä.

Testi on tavallinen. Indeksoi repo, jonka jo tunnet. Esitä yksi kysymys, jonka voit varmistaa, ensin Cursor, sitten toisessa MCP-asiakasohjelmassa. Konteksti, joka kulkee mukanasi, on sama lainaus molemmissa paikoissa.

// same map, wherever you opened it.

Kartta ensin, katselmointi sitten

Mon, 07 Sep 2026 00:00:00 GMT

Kaksi eri tehtävää istuu pull requestin molemmin puolin. Ennen kuin agentti kirjoittaa, se tarvitsee kartan puusta, jota se on muuttamassa. Sen jälkeen, kun agentti avaa PR:n, jonkin pitäisi lukea tuo muutos suhteessa muuhun järjestelmään ja jättää kommentteja, joiden perusteella ihminen voi toimia.

Nämä tehtävät näyttävät samankaltaisilta etäältä katsottuna, koska molemmat sisältävät ‘koodikannan ymmärtämisen’. Ne eivät ole sama tuote. Toinen vastaa kysymykseen ‘minne tämän muutoksen pitäisi laskeutua?’. Toinen vastaa kysymykseen ‘mitä tämä diffi rikkoi, minkä rivi riviltä tarkistava linter ohittaa?’. Niiden sekoittaminen tuottaa huonomman ensimmäisen luonnoksen ja meluisamman katselmoinnin.

Tämä teksti on opas yhteiselle työnkululle. Maguyva on kartta, jota agentti kysyy ensin. Greptile on katselmointiagentti, joka kommentoi PR:ää jälkeenpäin. Pari on rakenteeltaan toisiaan täydentävä: Maguyva ei katselmoi pull requesteja, eikä Greptile korvaa kontekstikerrosta, jota agentti käytti niiden kirjoittamiseen.

Miksi tämä jako on hyödyllinen

Koodausagentti, joka lähtee liikkeelle koulutuksen ennakko-oletuksista ja muutamasta liitetystä tiedostosta, keksii uskottavan polun ja muokkaa sitä. Se on ‘väärän tiedoston’ epäonnistuminen, ja se on hakuongelma. Maguyva on etäinen MCP-koodikannan kontekstikerros: semanttinen, rakenteellinen (AST), graafi-/riippuvuus- ja tekstihaku sulautuvat järjestetyiksi tuloksiksi, plus symbolihaku ja tiedostojen haku. Perustellut vastaukset palaavat muodossa path/file.ext:line, joten voit hylätä osuman ennen kuin korjaus on olemassa. Väite pysyy vaatimattomana: vähemmän hallusinoituja muutoksia. Malli voi silti arvata. Vain ensimmäinen askel lakkaa olemasta arvaus.

Greptile on tekoälypohjainen koodikatselmointiagentti. Omin sanoin se katselmoi automaattisesti jokaisen pull requestin täydellä koodikannan ymmärryksellä, ja asettaa sen vastakkain perinteisten linttereiden kanssa, jotka tarkistavat tiedostoja eristyksissä koko järjestelmän sijaan. Asetus koostuu GitHub- tai GitLab-sovelluksen asentamisesta ja repositorioiden valitsemisesta. Ei paikallista indeksiä, jota sinun pitäisi ylläpitää. Isännöinti on Greptile Cloud (he ilmoittavat SOC 2 Type II -vaatimustenmukaisuudesta, raportti saatavilla pyynnöstä), ja itse isännöity vaihtoehto tarjotaan yrityksille.

Heidän oma numeroitu kulkunsa on: yhdistä ja rakenna riippuvuusgraafi jokaisesta funktiosta, luokasta ja riippuvuudesta; jokaisella pull requestilla, analysoi muutos käyttäen tätä täyttä repo-graafia ja julkaise löydökset PR-kommentteina ehdotetuilla korjauksilla noin kolmessa minuutissa; jokainen kommentti voi luovuttaa ongelman koodausagentille, jota tiimi jo käyttää. He myös ilmoittavat lukevansa aiempia ihmisten PR-kommentteja ajan mittaan oppiakseen tiimin koodistandardit ja vähentääkseen meluisia ehdotuksia. Heidän oppimisjärjestelmänsä tarvitsee omien sanojensa mukaan 2–3 viikkoa sopeutuakseen.

Se on katselmointia, ei luonnostelua. Greptilen vahvuus on täyden repo-graafin konteksti muutokseen, joka on jo laskeutunut PR:ään, seurattuna suljetulla silmukalla, joka lähettää löydöksen Claude Code, Codexiin, Conductoriin, Cursor, tai Deviniin. Maguyva vahvuus on järjestetty kartta, jota agentti kysyi ennen kuin se muutos kirjoitettiin. Käytä molempia. Älä pyydä kumpaakaan tekemään toisen työtä.

Ensimmäisen osapuolen tuoteintegraatiota Maguyva ja Greptilen välillä ei ole ilmoitettu. Et myöskään tarvitse sitä. Maguyva puhuu agentille MCP:n kautta. Greptile puhuu GitHub tai GitLabille oman sovelluksensa kautta. Ne kohtaavat pull requestissa. Ei liimaskriptiä, ei cronia, joka yhdistäisi yhden työkalun toiseen. Pari pärjää ilman bashia, koska jokainen tuote istuu jo pinnalla, joka sille kuuluu.

Mitä tämä ei ole

Tämä ei ole Greptilen murskaus. Se ei ole ‘vaihda katselmoijaa’ -sivu. Greptile lanseerattiin Hacker Newsissa 5. maaliskuuta 2024 Y Combinator W24 -yrityksenä, ja se ketju on tapa, jolla moni ensin tutustui tuotteeseen. Jos näin löysit heidät, pysy heidän parissaan. Tämä sivu on sen silmukan puuttuva etupuolisko: ankkuroida agentti etukäteen, jotta Greptilen näkemä PR jo tähtää oikeisiin tiedostoihin.

Greptilen markkinointimateriaali johtaa väitteillä katselmointinopeudesta ja bugien kiinnisaannista. Kohtele niitä Greptilen omina väitteinä, ei riippumattomasti todennettuina lukuina. Tämä teksti ei toista niitä faktoina.

Kielikattavuus on samanlaista rehellisyyttä. Greptile kehystää tuen kaikkien ohjelmointikielten kattamisena luetellun listan sijaan; tarkkaa lukua ei ilmoiteta. Maguyva julkaisee tuen yli 279 kielelle ja tekstipohjaisille teknologioille, teknisellä jaottelulla (jäsentäjän tukema AST versus pelkkä teksti) sivustolla, kun kysymys on tekninen. Nämä ovat eri tuotteita, jotka tekevät erilaisia väitteitä. Älä sekoita niitä.

Greptilen hintoja ei ole ilmoitettu materiaaleissa, joita tämä teksti saa käyttää. Maksulliset suunnitelmat ovat olemassa; katso heidän hintasivunsa. Maguyva veloittaa työtilaa kohden, ei paikkaa kohden. Suunnitelmat alkavat ilmaiseksi. Hintasivu listaa julkaistut tasot, jos tarvitset työtilalukuja.

Työnkulku

Kolme nimettyä vaihetta. Suorita ne tässä järjestyksessä. Älä ohita yhtäkään niistä ensimmäisellä kerralla, kun kokeilet paria.

1. Maguyva-konteksti

Indeksoi yksi repositorio, jonka jo tunnet. Yhdistä MCP-asiakasohjelma, jossa jo kirjoitat — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, tai muu MCP-yhteensopiva asiakasohjelma. Maguyva on asennusoppaat 24 dokumentoidulle MCP-asiakasohjelmalle, ja se voi yhdistää muihin asiakasohjelmiin, jotka tukevat vakio-MCP-asetuksia.

Esitä kysymys, jonka voit arvioida ennen kuin kukaan kirjoittaa riviäkään. ‘Missä istunnon vanhentuminen käsitellään, ja mikä sitä kutsuu?’ on parempi ensimmäinen siirto kuin ‘korjaa autentikointi’. Vaadi lainauksia. Avaa file.ext:line-tulokset. Seuraa symbolia. Vahvista riippuvuus, jota olet koskettamassa.

Maguyva paljastaa 11 asiakaskäyttöistä MCP-työkalua haulle, symboleille, riippuvuusanalyysille, tiedostojen haulle, repo-kontekstille ja deterministisille apuohjelmatyönkuluille. Neljä hakutilaa sulautuvat järjestetyiksi tuloksiksi; find_symbol on erillinen työkalu, kun jo tiedät nimen. Dokumentaatio kuvaa lyhimmän polun: aloita ilmaiseksi, indeksoi repo, jonka jo tunnet, yhdistä asiakasohjelma, esitä sitten yksi kysymys, jonka voit varmistaa.

Tilannevedokset on aikaleimattu, joten agentti voi kertoa, mitä versiota puusta se lukee. Rehellinen rajoitus on synkronoimaton paikallinen työ. Jos muutos on olemassa vain työpuussa eikä sitä ole pushattu, isännöity kartta ei vielä sisällä sitä. Ohjetiedostot (CLAUDE.md, AGENTS.md) kuuluvat yhä tänne, käytännöille ja sille, mitä ei pidä koskea. Ne eivät ole elävä kartta. Käytä niitä käyttäytymiselle. Käytä Maguyva faktoille.

Älä anna agentin avata PR:ää ennen kuin lainaukset selviävät kosketuksesta repon kanssa. Tuo portti on tämän vaiheen koko pointti.

2. Agentin PR

Sama agentti kirjoittaa nyt muutoksen asiakasohjelmassa, josta jo maksat. Maguyva ei ole editori eikä katselmoija. Agentti tuottaa yhä diffin. Avaat yhä pull requestin GitHub tai GitLabissa niin kuin jo teet.

Mikä pitäisi olla erilaista, on ensimmäinen tiedosto. PR:n pitäisi nimetä käsittelijä, joka todella toteuttaa käyttäytymisen, kutsuja, joka rikkoutuu, ja testi, joka epäonnistuu, jos muutos on väärä. Jos vaihe 1 ohitettiin, vaihe 3 käyttää kommenttinsa muutokseen, joka laskeutui väärään pakettiin. Greptile voi silti löytää systeemisiä ongelmia. Sen ei pitäisi myös joutua toipumaan hallusinoidusta polusta.

Pidä PR rajattuna. Perusteltu ensimmäinen tiedosto ei ole lupa kirjoittaa moduuli uudelleen. Tämä toisiaan täydentävä pari toimii, kun agentti teki yhden työn kartan kanssa, ja pyysi sitten katselmoijaa tekemään toisen työn rajatulla diffillä.

3. Greptile-katselmointi

Greptile on jo yhdistetty repositorioon GitHub- tai GitLab-sovelluksen kautta. Uudella pull requestilla se analysoi muutoksen käyttäen rakentamaansa täyttä repo-graafia, ja julkaisee löydökset kommentteina ehdotetuilla korjauksilla. Heidän omat materiaalinsa asettavat tämän vaiheen noin kolmeen minuuttiin.

Lue kommentit niin kuin lukisit huolellista tiimikaveria: avaa lainattu sijainti, päätä onko löydös aito, sitten toimi. Missä Greptile tarjoaa ‘Fix with your Agent’, se lähettää ongelman — tiedostopolut, rivinumerot, ehdotetun koodin — Claude Code, Codexiin, Conductoriin, Cursor, tai Deviniin. ‘Fix All’ lähettää kaikki katselmoinnin ongelmat kerralla. He toimittavat myös Greptile MCP:n ja Claude Code -laajennuksen tälle luovutukselle. Maguyva ei ole tuolla nimetyllä kohdelistalla; se poissaolo ei ole ongelma. Maguyva on jo tehnyt työnsä vaiheessa 1. Koodausagentti, joka kirjoitti PR:n, on se, jonka pitäisi vastaanottaa korjauksen hyötykuorma.

Odota melua ensimmäiset 2–3 viikkoa, kun Greptilen oppimisjärjestelmä sopeutuu kommentteihin, joita tiimisi oikeasti jättää. Se on heidän ilmoittama aikataulunsa, ei parin puute. Ihmisen katselmointi pysyy silmukassa. Greptile on automatisoitu ensimmäinen kierros, ei yhdistämispainike.

Jos Greptile-kommentti osoittaa tiedostoon, jota agentti ei koskaan kysynyt vaiheessa 1, se on hyödyllinen signaali. Joko kartta jätti kutsujan väliin, tai agentti ohitti lainauksen. Korjaa luonnos kommentin mukaan. Älä poista katselmoijaa käytöstä.

Kuinka pitää tämä täydentävyys rehellisenä

Maguyva aina ensin. Väärän tiedoston PR:n katselmointi on silti väärän tiedoston katselmointia.
Greptile aina jälkeen. Hyvin lainatussa luonnoksessa on silti tarve koko järjestelmän tason diffin lukemiselle.
Älä pyydä Maguyva julkaisemaan PR-kommentteja. Se ei tee sitä.
Älä pyydä Greptileä olemaan agentin ensimmäinen hakukerros, kun se vielä valitsee polkua. Se ei ole työ, johon heidän GitHub- tai GitLab-sovelluksensa on kytketty.
Älä keksi bash-putkea, joka ‘synkronoi’ ne. PR on rajapinta.
Varmenna molemmat puolet itsenäisesti. Indeksoi repo, jonka jo tunnet. Esitä yksi kysymys, jonka voit varmistaa. Avaa sitten pieni PR ja lue, mitä Greptile todella kommentoi.

Silmukka on tavallinen heti kun sille annetaan nimi. Kartta ensin. Agentin PR. Katselmointi jälkeen. Jokainen tuote pysyy sillä pull requestin puolella, jossa se on hyvä.

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

Anna AI-agentille konteksti suuresta repositoriosta ilman paikallista indeksoijaa

Fri, 14 Aug 2026 00:00:00 GMT

Suuri repositorio ei mahdu kontekstiikkunaan, ja jos olet koskaan osoittanut kannettavan indeksoijan oikeaan monorepoon, tiedät, ettei se mahdu mukavasti sinnekään — RAM-muisti ampaisee ylös, ensimmäinen indeksointi kestää tunnin, ja agenttisi silti aloittaa seuraavan istunnon arvaamalla, mitkä tiedostot ovat tärkeitä.

Tavallinen vastaus on ajaa indeksoija editorin vierellä, ja repolle, joka mahtuu mukavasti yhdelle koneelle, se on hyvä vastaus. Jos monorepoosi indeksoituu jo nopeasti Cursor ja se on ainoa paikka, jossa tarvitset karttaa, tällä tekstillä ei ole mitään lisättävää — ohita se.

Tämä teksti käsittelee toista tapausta — kun agentti tarvitsee kyseltävän kartan suuresta repositoriosta, etkä halua ajaa paikallista indeksoijaa saadaksesi sen.

Milloin paikallinen indeksoija on väärä työkalu

Paikallinen indeksi olettaa, että koodi elää koneella, joka sitä kysyy, ja todellisessa monorepo-mittakaavassa tämä oletus kiristyy jo yhden editorin sisälläkin. Repo on yksinkertaisesti isompi kuin haluat pitää ‘lämpimänä’ kannettavalla: työskentelet yhdessä paketissa, kun vaikutusalue on kolme hakemistoa kauempana, ja kahden miljoonan rivin puun ensimmäinen kylmä indeksointi ei ole jotain, minkä haluat kokea kahdesti — ei omalla koneellasi eikä CI-suorittimella, joka ei ole koskaan aiemmin kloonannut sitä puuta. Tai tiimikaverin pitäisi pystyä kyselemään samaa karttaa kuin sinä, odottamatta oman koneensa raivaavan tiensä läpi saman indeksin.

Mikään näistä ei ole syy heittää hyvää editorin indeksoijaa pois. Se on syy myös omistaa isännöity kartta, jota kuka tahansa agenteistasi voi kysyä MCP:n kautta.

Ja mittakaavaongelma menee syvemmälle kuin ‘liikaa tiedostoja liitettäväksi’. Suurella puulla mielenkiintoinen kysymys on lähes koskaan ‘näytä minulle tämä tiedosto’ — se on mikä tiedosto, mikä symboli, ketkä kutsujat, mitkä testit. Agentti, joka aloittaa listaamalla src/ ja lukemalla kolme ensimmäistä tulosta, ohittaa iloisesti käsittelijän kohteessa apps/api ja generoidun asiakasohjelman kohteessa packages/sdk. Tarvitset haun, joka on rakennettu koko puusta, sitten järjestetty, sitten lainattu.

Mitä ‘suuren repon konteksti’ oikeasti tarkoittaa

Tiedostojen tyhjentäminen promptiin ei ole kontekstia — se on pienempi, huonompi kopio puusta. Mitä agenttisi oikeasti tarvitsee, on kysymysten esittäminen ja lainattujen vastausten saaminen takaisin: missä tämä symboli on määritelty ja kuka sitä kutsuu, mikä riippuu moduulista, jota olen muuttamassa, mikä testitiedosto kattaa tämän käyttäytymisen, ja miltä puu näyttää nyt, ei viime vuosineljänneksellä.

Näiden vastausten pitää tulla indeksistä, joka on rakennettu repostasi eikä mallin muistista muiden repoista, ja indeksin pitää elää jossain agentin kontekstiikkunan ulkopuolella. Tälle ongelmalle sen pitäisi elää myös jossain kannettavasi ulkopuolella.

Vielä yksi asia, jota ohjetiedostot eivät voi tehdä puolestasi: CLAUDE.md ja AGENTS.md ovat oikea paikka käytännöille ja käyttäytymiselle, mutta ne eivät ole elävä, järjestetty, kyseltävä kartta kahden miljoonan rivin puusta. Käytä sääntöjä käyttäytymiselle; käytä repo-älyä faktoille.

Rakennamme kartan pilvessä, kyselemme sitä miltä tahansa asiakasohjelmalta

Maguyva on etäinen MCP-koodikannan kontekstikerros. Yhdistät GitHub, valitset repositoriosi, ja voit lähteä, kun pilviputket jäsentävät puun, rakentavat symbolit ja graafin reunat, ja ylläpitävät järjestettyä karttaa — ei koskaan paikallista indeksoijaa.

Kun pushaat koodia, muuttuneet tiedostot jäsennetään inkrementaalisesti, ja graafi- ja rankingkerrokset rakennetaan uudelleen aikataulun mukaan: päivittäin ilmaisella suunnitelmalla, tunneittain maksullisilla. Jokainen tilannevedos on aikaleimattu, joten agenttisi voi kertoa, mitä versiota puusta se lukee. Rehellinen rajoitus tässä on synkronoimaton paikallinen työ — muutos, joka on olemassa vain työpuussasi, ei koskaan pushattu, ei ole vielä isännöidyssä kartassa.

Sitten yhdistät minkä tahansa asiakasohjelman, jota jo käytät, lisäämällä API-avaimen sen MCP-asetuksiin. Asennusoppaita on 24 dokumentoidulle MCP-asiakasohjelmalle, ja mikä tahansa muu MCP-yhteensopiva asiakasohjelma, joka tukee vakioasetuksia, voi myös yhdistää. Jos Cursor on kotisi, Cursor-sivu kulkee sen polun; sama palvelin vastaa Claude Code, VS Code, Windsurf, Codex CLI:lle ja muille.

Et vaihda editoria. Annat agentillesi työkalupinnan — 11 MCP-työkalua haulle, symboleille, riippuvuusanalyysille, tiedostojen haulle ja repo-kontekstille — kattaen yli 279 kieltä ja tekstipohjaisia teknologioita, mikä merkitsee enemmän kuin luulet monorepossa, joka lakkasi olemasta yksi kieli vuosia sitten.

Vastaukset palaavat perusteltuina, tiedostopolkuina rivinumeroineen. Semanttinen, rakenteellinen, graafi- ja tekstihaku sulautuvat järjestetyiksi tuloksiksi, joten kysymys kuten ‘mikä riippuu parseConfigista’ ei anna sinulle grep-tulostetta eikä yhtä semanttista katkelmaa, vaan sen kourallisen paikkoja, jotka todella merkitsevät.

Konkreettinen ohje

Älä aloita indeksoimalla koko yritystä. Tässä on polku, joka toimii:

Valitse yksi repositorio, jonka jo tunnet hyvin — paketti, jonka voit arvioida käsin, on arvokkaampi kuin suurin puu, joka sinulla on.
Aloita ilmaiseksi: 3 repoa, 50 000 indeksoitua riviä, kaikki 11 työkalua, ei kuukausittaista kyselykiintiötä. Jos edustava repository on tätä suurempi, hintasivu listaa työtilatasot ($0, $19, $49, $149) indeksoidun laajuuden mukaan — ei paikkojen määrän mukaan.
Yhdistä GitHub ja odota, että ensimmäinen indeksointi valmistuu. Et käännä mitään paikallisesti.
Yhdistä MCP-asiakasohjelma — muutama rivi asetuksia. Maguyva on etäinen MCP-palvelin, joten liitännäisiä, laajennuksia tai toista omaksuttavaa editoria ei ole.
Esitä yksi kysymys, jonka voit varmistaa. ‘Mikä riippuu parseConfigista?’ tai ‘Missä kirjautumisistunnon vanhentuminen käsitellään?’ Avaa sitten lainatut file.ext:line-tulokset ja tarkista ne edessäsi olevaa puuta vasten.
Vasta sen jälkeen, kun lainaukset selviävät tästä kosketuksesta, annat agentin muokata.

Jos ensimmäinen repo sopii hyvin ja puusi on suuri, nosta työtilaa vastaamaan indeksoituja rivejäsi ja uudelleenrakennustahtia. Ihmiset ja agentit jakavat saman käyttäjämäärän — Maguyva veloittaa työtilaa kohden, ei paikkaa kohden — joten kolmannen agentin lisääminen silmukkaan ei maksa sinulle mitään.

Aktivointitesti on sama, jota dokumentaatio suosittelee jokaiselle ensimmäiselle ajolle: indeksoi repo, jonka jo tunnet, esitä yksi kysymys, jonka voit varmistaa. Suuri repo ei muuta testiä; se vain tekee väärästä ensimmäisestä tiedostosta kalliimman.

Mitä seurata yhdistämisen jälkeen

Pidä silmällä kolmea asiaa. Tuoreus: maksulliset suunnitelmat rakentuvat uudelleen tunneittain, ilmaiset päivittäin, eikä pushaamaton paikallinen työ näy kartassa — se on kompromissi, jonka teet. Laajuus: indeksoi edustava joukko repoja, ei jokaista arkistoitua forkkia; ilmainen taso on tarkoituksella mitoitettu selvittämään, kannattaako vastauksia säilyttää. Ja varmennus: suuren repon kartta, joka ei voi lainata polkuja ja rivinumeroita, on vain hitaampi arvauskone, joten anna agenttisi näyttää paikka ennen kuin se toimittaa korjauksen.

Aja sitten sama testi, jonka ajaisit pienelle repolle. Indeksoi repo, jonka jo tunnet. Esitä yksi kysymys, jonka voit varmistaa. Jos kartta on aito, agenttisi lakkaa aloittamasta kylmästä puusta.

// no laptop got hot building this map.

Miksi AI-koodausagenttisi hallusinoi tiedostopolkuja

Fri, 14 Aug 2026 00:00:00 GMT

Merkki ei ole väärä funktion runko. Se on itsevarma muutos tiedostoon, jota ei ole olemassa, tai tiedostoon, joka on olemassa mutta ei ole se, joka toteuttaa käyttäytymisen.

Pyysit korjausta istunnon vanhentumiseen. Agentti avasi src/auth/session.ts. Se polku on uskottava. Se on myös väärä. Aito käsittelijä elää kohteessa apps/api/src/middleware/expiry.ts, uudelleennimetty kaksi refaktorointia sitten. Agentti ei valehdellut sinulle. Se täydensi polun muotoisen merkkijonon koulutuksen ennakko-oletusten ja kontekstiikkunassa jo olleen perusteella.

Tämä on tavallinen epäonnistumismalli oikealla repositoriolla. Malli osaa kirjoittaa koodia. Virhe on väärän paikan valitsemisessa sen kirjoittamiseen.

Miksi agentit keksivät polkuja

Koodausagentti on seuraavan tokenin ennustemalli työkaluineen. Kun sanot ‘korjaa istunnon vanhentuminen’, sen täytyy nimetä tiedosto ennen kuin se voi lukea tai korjata mitään. Jos sillä ei jo ole ankkuroitua karttaa, se rakentaa polun:

Nimeämiskäytännöistä, joita se on nähnyt muissa repositorioissa. src/auth/session.ts on yleinen muoto.
Tiedostoista, jotka ovat jo keskustelussa, jotka saattavat olla niitä, jotka liitit viime viikolla, eivät niitä, jotka ovat tärkeitä nyt.
Hakemistolistauksista, jotka se sattui ajamaan, epätäydellisiä suurella puulla.
Ohjetiedostoista. CLAUDE.md ja AGENTS.md kertovat agentille, miten käyttäytyä. Ne eivät ole elävä indeksi symboleista, kutsujista, tai nykyisistä poluista.

Mikään näistä lähteistä ei ole kartta tästä repositoriosta, tänään. Malli täyttää aukon samalla tavalla kuin se täyttää minkä tahansa aukon: korkean todennäköisyyden jatkumolla. Se jatkumo näyttää usein aidolta polulta. Joskus tiedosto on olemassa ja sijaitsee oikean vieressä. Joskus se oli olemassa haarassa, joka yhdistettiin viime kuussa. Joskus sitä ei ole koskaan ollut.

Grep ei pelasta sinua tässä, jos agentti ei koskaan etsi oikeaa merkkijonoa. Agentti arvasi polun, luki sitten mitä se polku palautti, muokkasi sitten sitä. Ensimmäinen väärä askel oli polku, ei korjaus.

Tiedostojen lukeminen ei myöskään ole sama asia kuin oikeiden löytäminen. Claude Code, Cursor, Codex, ja vastaavat työkalut voivat avata mitä tahansa, mihin osoitat ne. Kysymys on, löytävätkö ne luotettavasti oikeat tiedostot, tärkeät symbolit, riippuvuudet, testit, ja vaikutusalueen ennen muokkaamista. Tiedostoihin pääsy ilman karttaa alkaa silti arvauksella.

Väärän tiedoston muokkaaminen on hakuongelma

Kohtele keksittyä polkua hakuosumana, ei luonteen puutteena.

Jos agentin pitäisi palauttaa path/file.ext:line ennen kuin sen sallitaan muokata, kaksi asiaa tapahtuisi. Ensinnäkin voisit avata lainauksen ja hylätä työn kymmenessä sekunnissa. Toiseksi agentin pitäisi kysyä jotain, joka todella tuntee puun.

Se on koodikannan kontekstikerroksen työ. Pelkkä semanttinen haku ei riitä. Katkelma, joka ‘kuulostaa istunnon vanhentumiselta’, voi silti laskeutua vanhentuneeseen pakettiin. Tarvitset myös tarkan tekstin, kun tiedät merkkijonon, symbolihaun, kun tiedät nimen, rakenteellisen haun, kun tiedät muodon, ja riippuvuusgraafin, kun tarvitset kutsujia ja vaikutusalueen.

Maguyva on se kerros MCP-yhteensopiville koodausagenteille. Se ei ole editori. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, ja muut MCP-asiakasohjelmat pysyvät siellä, missä ne ovat. Agentti kysyy järjestettyä karttaa ennen kuin se koskee riviä.

Väite on tarkoituksella vaatimaton: vähemmän hallusinoituja muutoksia. Maguyva ei riistä mallilta kykyä arvata. Se muuttaa oletusarvoisen ensimmäisen askeleen ‘keksi uskottava polku’ -askeleesta ‘pyydä järjestettyjä, lainattuja sijainteja’ -askeleeksi.

Miltä perusteltu vastaus näyttää

Hyödyllinen vastaus kysymykseen ‘missä istunnon vanhentuminen käsitellään’ ei ole kappale. Se on lyhyt lista sijainneista:

apps/api/src/middleware/expiry.ts:48 - käsittelijä
apps/web/src/lib/auth-client.ts:112 - kutsuja
apps/api/tests/expiry.test.ts:20 - testi, joka epäonnistuu, jos muutos on väärä

Voit avata nämä rivit. Jos ne ovat väärin, pysähdyt. Jos ne ovat oikein, agentti voi muokata. Varmennus on pointti, ei iskulause.

Maguyva paljastaa 11 asiakaskäyttöistä MCP-työkalua haulle, symboleille, riippuvuusanalyysille, tiedostojen haulle, repo-kontekstille ja deterministisille apuohjelmatyönkuluille. Neljä hakutilaa (semanttinen, rakenteellinen, graafi/riippuvuus, ja teksti) sulautuvat järjestetyiksi tuloksiksi; symbolihaku on erillinen MCP-työkalu (find_symbol). Perustellut vastaukset palaavat tiedostopolkuineen ja rivinumeroineen, joten voit arvioida niitä edessäsi olevaa puuta vasten.

Dokumentaatio kuvaa lyhimmän polun: aloita ilmaiseksi, indeksoi repo, jonka jo tunnet, yhdistä asiakasohjelma, esitä sitten yksi kysymys, jonka voit varmistaa.

Silmukka, joka muuttaa ensimmäisen muutoksen

Et tarvitse uutta työnkulun uskontoa. Tarvitset yhden ylimääräisen askeleen ennen ensimmäistä kirjoitusta.

Esitä kysymys, jonka jo voit arvioida. ‘Mikä koodi käsittelee kirjautumisen ja istunnon vanhentumisen?’ on parempi kuin ‘korjaa autentikointi’.
Vaadi lainauksia. Tiedostopolku ja rivinumero, ei yhteenvetoa ‘autentikointimoduulista’.
Avaa lainatut tiedostot. Seuraa symbolia. Vahvista riippuvuus, jota olet koskettamassa.
Vasta silloin annat agentin korjata.

Jos vaihe 2 ei palauta mitään hyödyllistä, agentilla ei ole oikeutta improvisoida polkua. Se etsii uudelleen, tai sinä osoitat sen. Juuri tämä yksi portti on se, mikä tuottaa vähemmän hallusinoituja muutoksia. Malli on sama malli. Kartta on se, mikä on muuttunut.

Ohjetiedostot ovat yhä tärkeitä. Säilytä ne. Käytä niitä käytännöille, katselmointisäännöille, ja sille, mitä ei pidä koskea. Älä pyydä niitä olemaan indeksi. CLAUDE.md, joka listaa kolme tärkeää hakemistoa, vanhenee viikko paketin jakamisen jälkeen. Kyseltävä kartta päivittyy, kun repo päivittyy.

Sukua oleva epäonnistuminen on lähes oikea tiedosto: agentti avaa auth.ts, kun käyttäytyminen elää kohteessa auth-client.ts, tai korjaa generoidun tiedoston lähteen sijaan, tai muokkaa kopiota kohteessa packages/legacy, koska nimi täsmäsi. Lainaukset eivät tee näistä virheistä mahdottomia. Ne tekevät ne näkyviksi ennen kuin diffi laskeutuu.

Mitä kartta ei ratkaise puolestasi

Ole selväpäinen siitä, mitä saat. Perusteltu kartta ei tee jokaisesta muutoksesta oikeaa — agenttisi voi silti kirjoittaa huonon korjauksen täsmälleen oikeaan tiedostoon. Jos koodikantasi nojaa dynaamiseen lähetykseen, refleksioon, tai monkey-patchingiin, jotkin symbolihaut palaavat laihempina kuin toivoisit, koska sitä ajonaikainen epäsuoruus tekee mille tahansa staattiselle indeksille. Ja jos toivot prosenttilukua — ‘hallusinoidut polut vähentyneet X%’ — et löydä sitä täältä, koska kukaan ei voi rehellisesti mitata sitä lukua repollesi paitsi sinä itse.

Mitä voit odottaa, on kapeampaa ja hyödyllisempää: agentti lakkaa aloittamasta muutoksiaan arvatulla polulla. Tuo ensimmäinen askel ankkuroituu aitoon karttaan, ja siitä vähemmän hallusinoidut muutokset tulevat. Kaikki lainauksen jälkeen — diffin lukeminen, korjauksen arvioiminen — on yhä sinun työtäsi, niin kuin se aina on ollut.

Testi ei maksa sinulle juuri mitään: indeksoi repo, jonka jo tunnet, ja esitä yksi kysymys, jonka voit varmistaa. Aloita polulla, jonka takia sinua on jo poltettu. Jos lainaukset ovat väärin, näet sen heti. Jos ne ovat oikein, agenttisi seuraavalla muutoksella on parempi paikka laskeutua.

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

Miksi päivitimme koodihaun malliin voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Tämän postauksen vertailuarvoluvut heijastavat RTEB-ranking-listoja julkaisuhetkellä (kesäkuu 2026). Ranking-listat liikkuvat; kohtele sijoituksia hetkellisenä otoksena, ei pysyvänä tosiasiana.

Semanttinen haku on vain niin hyvä kuin sen alla olevat upotukset.

Kun agentti kysyy Maguyvalta “missä käsittelemme uudelleenyrityksiä”, se ei grep-hae sanaa “retry”. Se kysyy merkitystä — uudelleenyritysten odotussilmukkaa, katkaisijaa, epävakaata kutsua ympäröivää käsittelylogiikkaa. Tuohon kysymykseen vastaa vektorimalli, joka muuttaa koodin pisteeksi avaruudessa ja löytää naapurit. Valitse parempi malli, ja jokainen semanttinen kysely tuotteessa terävöityy hiljaa.

Joten muutimme omaamme. Kesäkuusta 2026 alkaen Maguyvan koodiupotukset ajetaan mallilla voyage-4-large, joka korvaa mallin voyage-code-3.

Vertailutesti

Emme tehneet tätä päätöstä fiiliksellä. Julkinen Retrieval Embedding Benchmark (RTEB) rankkaa upotusmalleja todellisilla noutotehtävillä, ja sen Code-ranking-listalla voyage-4-large istuu sijalla #1 kokonaisuudessaan (90,86) — edellä mallia gemini-embedding-2-preview (90,26) ja huomionarvoisesti edellä mallia, jota jo käytimme, voyage-code-3 (89,73, #3).

Se on pieni absoluuttinen ero. Mutta se on ero oikeaan suuntaan, julkisessa vertailutestissä, juuri sillä tehtävällä, josta välitämme: koodin noutaminen merkityksen perusteella.

Kompromissi, jonka hyväksymme: binäärikvantisointi

Tässä on osa, jonka useimmat “päivitimme mallimme” -postaukset jättävät pois.

Maguyva ei tallenna täystarkkoja vektoreita. Tallennamme binäärikvantisoituja upotuksia: jokainen 2048-ulotteinen vektori kutistuu 2048-bittiseksi allekirjoitukseksi — 256 tavua per vektori. Näitä allekirjoituksia haetaan Hamming-etäisyydellä, indeksoituna ja osioituna vuokralaisittain.

Se on tarkoituksellinen kompromissi. Binäärikvantisointi luopuu jonkin verran noutotarkkuudesta vastineeksi dramaattisesti pienemmästä tallennustilasta ja nopeasta, halvasta etäisyyslaskennasta ilman erillistä vektoritietokantaa operoitavaksi. Tuotteelle, joka indeksoi kokonaisia repositorioita per työtila, nämä kustannushyödyt merkitsevät enemmän kuin viimeisen vertailuarvopisteen murto-osan puristaminen.

voyage-4-large sopii tähän suunnitteluun pakottamatta tallennuskerroksen migraatiota: se tuottaa 2048-ulotteisen tulosteen, saman kuin voyage-code-3, joten bit(2048)-sarakkeemme ja Hamming-hakupolku eivät muuttuneet. Malli parani, skeema pysyi paikallaan.

Koodi oli vasta alku

Maguyva on koodiälytyökalu. Mutta olemme myös oma ensimmäinen asiakkaamme, ja osoitamme sen johonkin muuhun: markdowniin, joka elää repositorioissamme koodin vieressä. Arkkitehtoniset päätöstietueet, toimintaohjeet, sopimukset, talous- ja käytäntödokumentit — kaikki versionhallinnassa Gitissä, kaikki saman MCP-palvelimen takana, semanttinen indeksi dokumenttien, ei vain lähdekoodin, yli.

Juuri siksi voyage-4-largen laajuus merkitsee. Samalla RTEB-ranking-listaperheellä se on #1 taloudessa, #1 terveydenhuollossa ja #1 kokonaistekstinoudossa — edellä Googlen Gemini Embeddingiä, Coheren Embed v4:ää ja OpenAI:n text-embedding-3-largea. (Voyage on RTEB:n yhteisluoja, joten luemme sen vahvana julkisena signaalina emmekä täysin neutraalina tuomarina — mutta se on vertailtu suoraan jokaista suurta kaupallista mallia vastaan yksityisillä hold-out-aineistoilla.) Sama indeksi, joka löytää agentille oikean funktion, löytää oikean lausekkeen sopimuksesta tai oikean rivin käytännöstä — ja näillä toimialueilla voyage-4-large ei ole kompromissi, se on johtaja.

Miksi maksamme premium-upotuksista

On halvempi tapa tehdä hakua, ja suuri osa siitä on ilmaista. Leksikaalinen haku — BM25 ja sen sukulaiset — täsmää avainsanoja, toimii paikallisesti eikä maksa mitään. Avoimen lähdekoodin upotusmallit kuten BGE, Nomic ja embeddinggemma antavat aidosti kelvollisen semanttisen noudon, ja voit isännöidä niitä itse GPU:n hinnalla. Maguyva käyttää myös ilmaista puolta: jokainen kysely yhdistää teksti-, AST-, graafi- ja semanttisen haun. Se, mistä emme säästä, on semanttinen kerros.

Maksamme tokenia kohti premium-upotuksista — voyage-4-large — sen sijaan että isännöisimme itse ilmaista mallia, kahdesta syystä. Ensinnäkin pelkkä avainsanahaku ei osaa vastata kysymykseen “missä käsittelemme uudelleenyrityksiä”, kun koodi sanoo backoff ja circuit breaker eikä koskaan sanaa “retry” — merkitys on koko upotuksen pointti, ja toimialueilla, joita palvelemme, avoimet mallit jäävät jälkeen premium-malleista: pari pistettä jäljessä yleistekstissä ja vielä enemmän jäljessä kapeissa alueissa kuten koodi, sopimukset ja talous. Toiseksi kokemuksemme mukaan noudon laatu muovaa lopullista vastausta enemmän kuin toisessa päässä oleva malli — vahva agentti, jolle annetaan väärä konteksti, vastaa silti väärin, eikä se koskaan näe dokumenttia, jota sille ei koskaan annettu.

Joten premium-upotukset ovat tokenikohtainen lasku, joka skaalautuu jokaisen indeksoimamme repositorion ja dokumentin mukana — ja maksamme sen tarkoituksella. Tuloksesta, jonka käyttäjämme saavat, oikeasta funktiosta tai oikeasta lausekkeesta, ajattelemme tuon kompromissin olevan sen arvoinen.

Rehellinen osa

Voyagen oma dokumentaatio yhä merkitsee mallin voyage-code-3 koodioptimoiduksi malliksi. Miksi siis vaihtaa?

Koska luimme julkisen vertailutestin, emme vain vendorin mallitaulukkoa, ja vertailutesti asetti mallin voyage-4-large kärkeen koodin noudossa. Tämä oli eteenpäin katsova päätös: ottaa uudempi, yleisesti vahvempi malli ja validoida se julkista ranking-listaa vasten tehtävillä, jotka merkitsevät. Olemme tyytyväisiä tuon vedon tekemiseen, koska todistusaineisto on laaja — voyage-4-large ei voita vain koodissa, se johtaa myös taloudessa, terveydenhuollossa ja kokonaisnoudossa.

Huomaamaton perusta

Jokainen tarjoamamme työkalu — semanttinen haku, tehtäväkontekstin kerääminen, perusteltu (grounded) kysymys-vastaus — pohjautuu lopulta noutoon. Kun noutokone paranee, toisessa päässä oleva agentti saa parempaa todistusaineistoa, tekee vähemmän vääriä käänteitä ja ankkuroi vastauksensa oikeaan koodiin — tai oikeaan lausekkeeseen, tai oikeaan käytäntöön. Terävämpi upotusmalli ei ole hohdokas ominaisuus. Se on kaiken muun perusta, ja juuri vahvistimme sitä. Et huomaa sitä. Se on pointti.

Kielituen rekursiivinen parantaminen: koodiälyn hiominen noin 280 kielessä

Tue, 26 May 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (toukokuu 2026). Katso tiimisivumme ajantasaiset luvut.

Maguyva poimii symboleita, viittauksia ja riippuvuusgraafin lähdekoodista noin 280 kielessä. Jokainen kieli on räätälöity tree-sitter-käsittelijä — kyselyt, heuristiikat, reunatapaukset — ja jokainen käsittelijä voi olla hienovaraisesti väärässä omalla tavallaan. Metodikutsu, joka on merkitty lukuviittaukseksi. Funktio, joka on liitetty väärään ympäröivään näkyvyysalueeseen. Suhde, jota ei yksinkertaisesti ole olemassa.

Sitä ei voi auditoida käsin. Mikään tiimi ei pysty lukemaan poimintatulosteita 280 kieliopin yli ja havaitsemaan huonoja reunoja. Joten kiinnostava kysymys ei ole “onko poimintamme oikein” — se on “miten otat selvää, että se on väärin, tässä laajuudessa, ilman ihmistä jokaisessa silmukassa”. Vastauksemme on kielituen rekursiivinen parantaminen: laatusilmukka, jota ajavat kieliagentit, LLM tuomarina, ja yksi sääntö, jonka opimme yhä uudelleen: vihreä ei ole sama kuin oikein.

Vihreä ei ole oikein

Jokaisella kielellä on fixture-sarja, ja julkaisuportti pisteyttää sen viidellä ulottuvuudella — tarkkuus, rakenteellinen eheys, kattavuus, laatu ja suorituskyky. Kieli menee VIHREÄKSI vain, kun sen fixtureilla precision ≥ 0.95, recall ≥ 0.99 ja F1 ≥ 0.97, vähintään 20 odotetulla reunalla tilastollista luottamusta varten. Sen alapuolella se on KELTAINEN tai PUNAINEN, eikä sitä julkaista.

Tuo portti on välttämätön muttei riittävä. Fixturet validoivat vasten fixtureita, jotka me itse kirjoitimme. Ne koodaavat tapaukset, jotka jo keksimme. Käsittelijä voi olla virheetön fixtureillaan ja silti sotkea kuvion, joka näkyy vain oikeassa koodissa — makro-idiomi, geneerisesti rajoitettu metodi, kielipiirre, jolle kukaan ei kirjoittanut fixturea. VIHREÄ tarkoittaa, että fixturet menevät läpi. Se ei tarkoita, että oikea repositorio poimitaan siististi. Joten silmukan täytyy jättää fixturet taakseen ja tarkastella oikeiden projektien koodia.

Sisäsilmukka: pistokoe, tuomari, korjaa, todista

Ydinsilmukka ajaa yhtä kieltä kerrallaan:

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

Muutama asia saa tämän toimimaan sen sijaan että se rimpuilisi paikallaan.

Tuomari on agentti, ei API-kutsu. Kun sanomme “LLM tuomarina”, tarkoitamme, että kieliagentti itse lukee jokaisen otetun reunan todellista lähdekoodia vasten ja luokittelee sen kiinteällä viisikategorisella luokitusperusteella: onko tämä reuna oikea, väärä positiivinen, oikea suhde väärällä tyypillä, kiinnitetty väärään laajuuteen vai kantaako se väärää metadataa? Tuo luokitusperuste on ratkaiseva — “23 %:n virhesuhde” on merkityksetön, kunnes tiedät, ovatko ne todellisia vikoja vai tuomarin väärinlaskentaa.

Korjaa yksi asia, sitten todista se. Jokainen iteraatio muuttaa täsmälleen yhden muokattavan resurssin, ajaa sitten uudelleen kiinteää testikehystä vasten ja pitää muutoksen vain, jos F1 paranee ja uudelleenluokittelu näyttää paremmalta. Jos ei, se peruutetaan. Ei erää spekulatiivisia muokkauksia, ei “pitäisi olla parempi”. Muutos ansaitsee paikkansa tai se poistetaan. Ja kun korjaus jää pysyväksi, se ylennetään fixture-sarjaan — jotta korjattu bugi ei koskaan voi hiljaa palata. Tuo ylennysaskel on se, mikä tekee silmukasta rekursiivisen eikä vain toistuvan: jokainen kierros vahvistaa oraakkelia, jota vasten seuraava kierros validoi.

Opetus, jonka opimme yhä uudelleen: metriikat liioittelevat ongelmia

Tässä on ansa, johon kävelimme suoraan. Toissijaiset korpusmetriikat — kuinka usein poimitulla kohteella ei ole symbolia, johon viittaus voidaan yhdistää, kuinka moni symboli näyttää “orvolta” ja niin edelleen — liioittelevat ongelmien määrää valtavasti. Ne ovat enimmäkseen paradigma-artefakteja, eivät bugeja.

Selkein esimerkki: llvm näytti kerran 73 %:n “lähde-ilman-symbolia”-suhteen ja leimattiin katastrofaaliseksi. Kaivauduimme asiaan. Todellinen tarkkuus oli 98,5 %. “Puuttuvat symbolit” olivat lähes kaikki kelvollisia ulkoisia viittauksia — kutsuja standardikirjastoon, frameworkeihin, koodiin, joka elää repositorion ulkopuolella. Metriikka mittasi kielen ominaisuutta, ei käsittelijän vikaa. Kielet kuten Zig, COBOL ja Odin näyttävät 65–70 %:n “orpo”-suhteita ja ovat täysin oikein; COBOLissa ei ollut yhtäkään todellista virhettä.

Jos olisimme antaneet noiden lukujen ohjata työtä, olisimme käyttäneet viikkoja “korjaamassa” käsittelijöitä, jotka olivat jo oikein, ja jättäneet huomiotta kielet, joissa oli hiljaisia, todellisia bugeja. Johtopäätös on suora: aggregaattimetriikat ovat parhaimmillaankin karkea priorisointisignaali. Todellinen laatusignaali on pistokoe reunaluokituksella — todellisten reunojen tarkastelu todellisissa repositorioissa ja niiden arvioiminen yksitellen. Dataa intuition sijaan, mutta vasta kun tiedät, mikä data kertoo totuuden.

Ulkosilmukka: parvi, ei maraton

Yksi kieli kerrallaan veisi ikuisuuden 280 kielen yli, joten sisäsilmukka on kääritty ulkosilmukkaan, joka ajaa monia rinnakkain.

   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

Jokainen agentti työskentelee kertakäyttöisessä worktreessä, jotta ne eivät voi astua toistensa varpaille. Orkestraattori integroi niiden korjaukset yksi kerrallaan, jokainen täyden manifestin regressiotarkistuksen takana: muutos, joka auttaa omaa kieltään mutta hiljaa rikkoo kolme muuta, ei mene läpi. Integraatio on portitettu ja vahvistettu ennen kuin mitään työnnetään — regressioportti päättää, mikä on turvallista, ihminen päättää yhä, mikä julkaistaan. Sitten agenttijoukko siirtyy seuraaviin kieliin ja koko homma ajetaan uudelleen.

Mikä on yhä epätäydellistä

Tuomari voi olla väärässä, ja virheillä on tietty suunta: agentti, joka ajaa liian vähällä kontekstilla, liioittelee ongelmien määrää. Yhdessä erässä kahdeksan kieltä merkittiin 5–20 %:n virheelle; tarkastuksessa vain yhdessä oli todellinen kielikohtainen bugi — loput olivat tuomarin virheitä, jotka johtuivat kielen omien semantiikkojen huomiotta jättämisestä (yksi lähderivi, joka voi kelvollisesti tuottaa useita reunoja, parametrien sidonnat mallinnettuina sijoituksina, viittaus-per-tunniste-kielet). Siksi otamme näytteitä kahdella siemenellä ja ristiintarkistamme, ja siksi tuomarin ja fixturejen välinen erimielisyys käsitellään kiinnostavimpana signaalina, ei ratkaistuna tuomiona — joskus fixture on se, joka on väärässä.

Olemme myös rehellisiä tavoitteen suhteen. Tavoite on nolla todellista virhettä, piste — mutta “nolla” on suunta, jota kohti hiomme kieli kerrallaan, ei laatikko, joka rastitetaan. Aina on toinen repositorio toisella idiomilla.

Ansaittua, ei väitettyä

Kaikki, mitä Maguyva tekee agentin puolesta — symbolin löytäminen, riippuvuuden jäljittäminen, kysymykseen vastaaminen viitatulla koodilla — lepää sen varassa, että alla oleva poiminta on oikein. 280 kielen yli “oikein” ei voida väittää; se täytyy jatkuvasti ansaita oikeaa koodia vasten. Silmukka on se, miten ansaitsemme sen: autonominen pistokoe-ja-korjaa-sykli, joka suhtautuu omiin metriikoihinsa epäluuloisesti, todistaa jokaisen muutoksen ja muuttaa jokaisen korjauksen suojaksi seuraavaa regressiota vastaan. Se ei ole hohdokasta. Se on työtä, joka antaa meille mahdollisuuden sanoa “tuemme kieltäsi” ja tarkoittaa sitä. Vihreä on helppoa. Oikein on ansaittua.

Monimodaalinen fuusiohaku: oikean hakukoneen valinta jokaiselle kyselylle

Wed, 15 Apr 2026 00:00:00 GMT

Huomautus historiallisesta suunnittelusta: tämä huhtikuun 2026 artikkeli kuvaa silloista reitityssuunnitelmaa, ei nykyistä oletustoimintaa. Alla oleva syyskuun korjaus koskee vain mittausväitettä. Nykyinen reititys, esiasetukset ja hakutapojen suorat valinnat esitellään sivulla Näin se toimii.

Hakukysely ei ole yksi asia.

“missä parseConfig on määritelty” haluaa tarkan symbolin — yhden täsmällisen sijainnin, nopeasti. “miten todennus toimii” haluaa merkityksen — liittyvän koodin levittäytymän, joka selittää käsitteen. “mitä hajoaa, jos muutan tätä funktiota” haluaa riippuvuusgraafin. “etsi merkkijono ECONNREFUSED” haluaa kirjaimellisen osuman, ei mitään nokkelaa.

Grep on erinomainen kirjaimellisiin osumiin ja hyödyllinen joissakin viittausmetsästyksissä, mutta se ei ole riippuvuusgraafi eikä ymmärrä merkitystä. Upotukset kattavat semanttisen puolen, mutta ne ovat väärä työkalu tarkoille merkkijonoille ja vaikutusanalyysille. Useimmat koodihakutyökalut valitsevat yhden moottorin ja pakottavat jokaisen kyselyn elämään sen valinnan kanssa. Maguyva ei sitoudu yhteen moottoriin. Se selvittää, minkälainen kysymys esitit, ja sekoittaa sitten neljä hakukonetta suhteessa, jonka kysymys ansaitsee.

Neljä modaliteettia

Konepellin alla on neljä riippumatonta tapaa löytää koodia:

semanttinen — vektorihaku Voyage-binääriupotusten yli; löytää koodia merkityksen perusteella.
teksti — trigrammivastaavuus; löytää literaalit, virhemerkkijonot, tarkat tunnisteet.
rakenteellinen — AST-kyselyt; löytää määrittelyt, allekirjoitukset ja kielirakenteet.
graafi — riippuvuusgraafi; löytää kutsujat, kutsuttavat ja vaikutusalueen.

Jokainen on vahva erilaisessa kysymysluokassa. Temppu on päättää, kuinka paljon kuhunkin hakutapaan luotetaan käsiteltävän kyselyn kohdalla.

Tarkoituksen luokittelu

Ennen minkään haun ajamista kevyt luokitin lajittelee kyselyn yhteen kuudesta tarkoituksesta, luottamuspisteellä. Se on tarkoituksella halpa — järjestettyjä heuristiikkoja, ensimmäinen osuma voittaa — koska se ajetaan usein käytetyllä suorituspolulla ja lisää vain millisekunnin tai pari:

alkaa sanoilla def , class , func , import … → find_definition (luottamus 0.95)
“who calls”, “usages of”, “references to” → find_references (0.90)
“impact”, “blast radius”, “what depends on” → impact_analysis (0.90)
lainausmerkeissä oleva "string" tai virhetunniste kuten traceback → exact_match (0.85–0.90)
CamelCase- tai snake_case-tunniste → find_definition (0.60–0.80)
“how”, “why”, “explain”, “architecture” → understand_code (0.75)
mikään ei täsmää → understand_code, matala luottamus (0.40)

Jokaisella tarkoituksella on painoprofiili neljän modaliteetin yli. Nämä ovat todelliset luvut:

Tarkoitus	semanttinen	teksti	rakenteellinen (AST)	graafi
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

Joten “missä parseConfig on määritelty” nojaa vahvasti ASTiin (0.6). “miten todennus toimii” nojaa semanttisiin vektoreihin (0.5). “mikä on riippuvainen tästä” on lähes kokonaan graafia (0.7). “etsi ECONNREFUSED” on lähes kokonaan trigrammia (0.9), upotusmallin ollessa kokonaan pois päältä — koska semanttinen samankaltaisuus on juuri väärä työkalu tarkalle merkkijonolle.

Nopea polku ja yhdistetty polku

Kun luokitin on varma — pisteet ≥ 0.85 — ja kysely on tavallinen, Maguyva ohittaa fuusion kokonaan ja reitittää suoraan yhteen hallitsevaan modaliteettiin. “missä X on määritelty” ei tarvitse neljää hakukonetta; se tarvitsee AST-indeksin, heti. Tuo suora polku raportoidaan takaisin nimellä fusion_strategy: "direct".

Kaikki epäselvä kulkee fuusion läpi. Neljä (tai kolme, oletusesiasetuksella) modaliteettia ajetaan rinnakkain, kukin palauttaen oman järjestetyn listansa, ja yhdistämme ne.

Painotettu Reciprocal Rank Fusion

Heterogeenisten hakukoneiden yhdistäminen on vaikeampaa kuin miltä kuulostaa: kosinisamankaltaisuus 0.82 ja trigrammipisteet 137 ja graafin keskeisyys 0.004 eivät ole samalla asteikolla, joten niitä ei voi vain laskea yhteen. Reciprocal Rank Fusion kiertää ongelman heittämällä pois raakapisteet ja säilyttämällä vain kunkin moottorin antaman sijoituksen. Tuloksen panos yhdestä modaliteetista on:

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

jossa rank on sen sijainti kyseisen modaliteetin listalla ja k on tasoituskonstantti. Panokset summataan yli modaliteettien mille tahansa tulokselle, jonka useampi kuin yksi moottori löysi — hakukoneiden välinen yksimielisyys nousee luonnollisesti pintaan. Käytämme k = 40 oletusesiasetuksella ja 60 thorough:ssä (quick ajaa vain semanttisen haun, joten fuusio ei koskaan käynnisty siellä). Alkuperäinen RRF-työ päätyi arvoon k = 60 yleiskäyttöiselle haulle; oletusasetuksemme painottaa hieman enemmän tuloksia, jotka sijoittuvat korkealle useassa modaliteetissa — emmekä suosittele sen käsivaraista säätämistä.

Tämän lisäksi tulokset kantavat graafin tärkeyden korotusta. Solmupisteen — funktion, johon koko koodikanta nojaa — pitäisi sijoittua vähemmän tunnetun lehtisolmun edelle jopa samalla tekstuaalisella relevanssilla, joten kerromme jokaisen panoksen luvulla:

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

Keskeisyys tulee putken esilasketuista PageRank/aste-metriikoista, ja korotus rajataan 1.5×:ään, jotta suosittu funktio ei voi täysin peittää alleen relevantimpaa, vähemmän tunnettua funktiota. Lopuksi alennamme tuloksia vendor-, build- ja arkistopoluista ja poistamme duplikaatit siten, että kustakin tiedostosta jää paras katkelma.

Mikä on yhä epätäydellistä

Aikeen luokittelija on joukko säännöllisiä lausekkeita, ei koulutettu malli. Se käsittelee tavallisia kyselymuotoja heuristiikoilla, ja monitulkintainen kysely ohjautuu vaihtoehtoon understand_code sekä semantiikkaa painottavaan yhdistelmään. Tämän kirjoituksen aiempi versio kuvasi tuloksettomien hakujen osuuden laskun noin 15 prosentista alle 5 prosenttiin saavutetuksi. Joulukuun 2025 ehdotuksessa esitettiin todellisuudessa arvioitu lähtötaso ja tavoite; tueksi ei ole toimitettu kyselyjoukkoa tai mittausraporttia. Perumme väitteen saavutetusta parannuksesta; katso lähdeaineisto ja korjaus. Emme ole korvanneet luokittelijaa koulutetulla mallilla, koska edullinen versio on nopea ja riittävä sille tarkoitettuun reititystehtävään ja koska virheellinen mutta itsevarma luokittelija on huonompi kuin rehellinen oletusvaihtoehto. Painot ovat käsin valittuja ennakko-oletuksia, eivät opittuja klikkausdatasta, jota emme kerää.

Esitä kysymys ilman työkalun valintaa

Agentin ei pitäisi joutua tietämään, tarttuuko grepiin, upotuksiin vai kutsugraafiin — sen pitäisi esittää kysymyksensä yksinkertaisin sanoin ja saada oikea vastaus. Monimodaalinen fuusio on se, mikä antaa find_symbol:n, semanttisen haun ja riippuvuusanalyysin istua yhden kyselyrajapinnan takana: järjestelmä lukee kysymyksen muodon ja kokoaa hiljaa oikean hakukoneen sitä varten. Malli, joka pisteyttää upotukset, merkitsee, mutta niin merkitsee myös tietäminen, milloin ei käyttää niitä. Oikean työkalun valitseminen jokaiselle kyselylle on omanlaistaan laatua, ja se on sellaista, jonka mieluummin omistamme kuin työnnämme kutsujalle.

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

Agenttien havainnointi: Hookit, Alloy ja Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agenttijärjestelmät epäonnistuvat oudoilla tavoilla.

Joskus malli on ongelma. Joskus työkalu on ongelma. Joskus MCP-palvelimesi on kunnossa, mutta agentti valitsi väärän erikoisosaajan, tai käytti puolet istunnosta shell-työhön, jota et odottanut, tai kasvatti huomaamatta kustannuksia silmukassa, joka näytti ulospäin tuottavalta.

Jos et näe eroa, et oikeasti operoi agenttijärjestelmää. Arvailet.

Joten rakensimme havainnointipinon omalle työnkulullemme: Claude Code, Codex, Claude-hook-tapahtumat, Codex-notify-tapahtumat, natiivi OpenTelemetry, Grafana Alloy ja toisella puolella Grafana Cloud.

Mielenkiintoinen osa ei ole “teimme kojelaudan”. Mielenkiintoinen osa on se, että meidän piti jakaa telemetria kahteen eri virtaan, koska mikään yksittäinen syöte ei antanut meille koko kuvaa.

Ongelma: agenttien telemetria on pirstoutunutta

Modernit koodausagentit lähettävät jo jonkin verran telemetriaa. Se auttaa, mutta ei riitä.

Natiivi OTEL osaa vastata hyvin kysymyksiin kuten:

Kuinka monta pyyntöä teimme?
Kuinka paljon istunto maksoi?
Missä jäljitykset (spans ja traces) ovat?
Kasvoiko viive äkillisesti?

Se on paljon huonompi vastaamaan kysymyksiin kuten:

Mihin MCP-palvelimeen agentti nojasi?
Oliko epäonnistuminen Bash:ssa, sisäänrakennetussa tiedostotyökalussa vai MCP-kutsussa?
Mikä taito oikeasti aktivoitui?
Minkä tyyppinen alaagentti lähetettiin?
Tekikö istunto hyödyllistä työtä vai rimpuiliko se vain paikallaan?

Tuo toinen kysymysluokka elää lähempänä hookeja kuin jäljityksiä.

Mutta myös käänteinen pätee: jotkin tärkeimmistä suorituskykykysymyksistä elävät lähempänä jäljityksiä kuin hookeja.

Jos haluat tietää, mihin viive todella kertyi, mitkä spanit olivat hitaita tai poltettiinko istunnossa aikaa mallikutsuihin vai työkalujen suoritukseen, tarvitset jäljitysdataa semanttisten tapahtumien lisäksi.

Arkkitehtuuri, johon päädyimme

Ajamme kahta telemetriapolkua rinnakkain.

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

Tuo jako on tarkoituksellinen.

Se on myös epäsymmetrinen. Claude Code antaa meille paljon rikkaamman elinkaari-hookien rajapinnan. Codex antaa meille natiivin OTEL:in plus notify-rajapinnan, joten normalisoimme vähemmän yksityiskohtaiset keskusteluvuoron päättymistapahtumat samaan lokiskeemaan sen sijaan että teeskentelisimme molempien ajoympäristöjen paljastavan samat säätimet.

Natiivi OTEL antaa meille perusvirran: lokit ja jäljitykset itse ajoympäristöstä sekä metriikat siellä, missä ajoympäristö niitä todella lähettää.

Hook- ja notify-tapahtumat antavat meille semanttisen kerroksen: asioita kuten PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, ja luokitellun metadatan, josta oikeasti välitämme agenttien käyttäytymistä vianetsittäessä. Claude Code antaa tässä rikkaamman tapahtumavirran. Codex antaa vähemmän yksityiskohtaisen mutta silti hyödyllisen normalisoidun virran.

Miksi hookit ylipäätään ovat olemassa

Hook-putkemme rikastaa tapahtumat ennen kuin ne osuvat Lokiin.

Sen sijaan että vain sanoisimme “työkalu ajettiin”, luokittelemme tapahtuman kenttiin kuten:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: mikä MCP-taustajärjestelmä käsitteli kutsun
bash_cli: shell-komennon perhe
subagent_type: minkälainen erikoisosaaja lähetettiin
agent_tool: oliko lähde Claude Code vai Codex

Se tarkoittaa, että voimme kysyä operatiivisesti merkityksellisiä kysymyksiä:

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

Ne eivät ole turhia kenttiä. Ne ovat ero sen välillä, että “agentti tuntui hitaalta” ja sen välillä, että “agentti käytti viimeiset kymmenen minuuttia shell-painotteisiin git-operaatioihin, joissa työkalujen epäonnistumisaste oli korkea”.

Yksi toteutusyksityiskohta, joka näyttää oudommalta kuin onkaan: jaettu Loki-virta käyttää yhä service_name="claude-code-hooks":ta tunnisteena silloinkin, kun tapahtuma tuli Codexista. Todellinen jako ajoympäristöjen välillä tapahtuu kentässä agent_tool.

Miksi Alloy istuu keskellä

Grafana Alloy ei ole tässä asetelmassa vain edelleenlähettäjä. Se on kohta, jossa telemetrian käsittelysäännöt pannaan täytäntöön.

Ohjaamme Claude Coden ja Codexin natiivin OTEL-virran paikalliseen Alloy-proxyyn osoitteessa localhost:4318 ja annamme sitten Alloyn siivota hyötykuorman ennen sen edelleenlähetystä Grafana Cloudiin.

Se merkitsee, koska raaka agenttitelemetria on täynnä korkean kardinaliteetin kenttiä, jotka ovat hyödyllisiä analyysille mutta kauheita indeksoituina tunnisteina:

session_id
prompt_id
token-määrät
kestot
työkalun parametriblobit

Jos indeksoit kaiken, saat tunnisteräjähdyksen ja huonon päivän.

Joten Alloy tekee meille kolme asiaa:

Pitää hyvin pienen joukon matalan kardinaliteetin tunnisteita indeksoituna.
Siirtää meluisat mutta hyödylliset kentät rakenteelliseen metadataan.
Pudottaa puhtaan kohinan kokonaan.

Tärkeä idea on yksinkertainen: havainnoi enemmän, indeksoi vähemmän.

Miksi hook-virta ohittaa Alloyn

Hook-virta on jo muotoiltu Lokia varten.

Siihen mennessä, kun send_event.py työntää tapahtuman, olemme jo päättäneet, mitkä kentät ansaitsevat tunnistekohtelun ja mitkä kuuluvat rakenteelliseen JSON-runkoon. Tuo virta menee suoraan Grafana Cloudin OTLP-yhdyskäytävään ilman toista kierrosta Alloyn kautta.

Järjestelmässä on siis selkeä työnjako:

Alloy kesyttää raa’an natiivin OTEL-virran.
Hook-rikastus tekee semanttisista tapahtumista kyselykelpoisia.

Se pitää arkkitehtuurin yksinkertaisempana kuin yrittää pakottaa kaikki yhden polun läpi.

Mitä kojelauta oikeasti näyttää

Alla oleva kuvakaappaus on yksi agenttityönkulkumme takana olevista havainnointikojelaudoista. Se ei ole vertailuarvo, ja luvut ovat vain hetkellinen siivu. Pointti on datan muoto: aktiviteettivirta, työkalukutsut, epäonnistumiset, kehotteet ja jaottelut agentin, sisäänrakennettujen työkalujen, MCP-käytön, shell-komentojen ja taitojen mukaan.

Hyödyllinen osa on se, että tämä kojelauta elää samassa Grafana-pinossa kuin muu agenttitelemetria. Voimme suodattaa lähdeagentin ja työkaluperheen mukaan ja tarkastella eri ajoympäristöjä rakentamatta erillistä havainnointiratkaisua jokaiselle järjestelmälle.

Yksi agenttityönkulkumme takana olevista live-kojelaudoista. Tämä kuvakaappaus on vain yksi siivu jaetusta Grafana-pinosta, joka vastaanottaa telemetriaa myös muista agenttiajoympäristöistämme ja järjestelmistämme. Napsauta kuvaa nähdäksesi täyden resoluution version.

Miksi jäljitykset merkitsevät enemmän kuin ne aluksi näyttävät

Lokit kertovat, minkä kategorian työtä tapahtui. Jäljitykset kertovat, miten työ eteni ajan myötä.

Tuo ero merkitsee agenttijärjestelmissä, koska “hidas” on liian epätarkka kuvaus ollakseen hyödyllinen.

Jäljitys voi kertoa meille, johtuiko ongelma:

mallin viiveestä
työkalun suoritusajasta
toistuvista uudelleenyrityksistä
yhdestä erityisen kalliista MCP-vuorovaikutuksesta
pitkästä hännästä pieniä operaatioita, jotka näyttivät erikseen harmittomilta

Käytännössä käytämme hook-virtaa ja Tempo-jäljityksiä yhdessä.

Hook-lokit vastaavat: minkälaista asiaa tapahtui?
Jäljitykset vastaavat: mihin aika meni?

Yhdistelmä on se, mikä muuttaa havainnoinnin kojelaudasta selitykseksi.

Mihin Codex sopii

Codex on osa samaa pinoa, mutta se ei ole identtinen Claude Coden kanssa.

Codexille kytkemme kaksi osaa:

Natiivin OTEL:in Codexista Alloyyn
Notify-webhookin osoitteeseen codex_notify.py, joka kartoittaa keskusteluvuorojen päättymiset samaan Loki-skeemaan, jota käytämme hook-tapahtumille

Se antaa meille yhtenäisen suodattimen kuten agent_tool="codex-cli" saman lokivirran sisällä.

Rehellinen varaus: Codexin notify-hyötykuorma on tällä hetkellä vähemmän yksityiskohtainen kuin Claude Coden hook-hyötykuorma, koska kyseessä ei ole samanlainen integraatiorajapinta. Nykyisessä asetuksessamme Codexin keskusteluvuorojen päättymiset voidaan normalisoida jaettuun skeemaan, mutta yksityiskohtainen työkalukohtainen poiminta on yhä parempi natiivissa OTEL-virrassa kuin notify-sillassa.

Se ei ole syy välttää tätä postausta. Se on postauksen pointti. Todelliset havainnointijärjestelmät rakennetaan epätäydellisistä signaaleista.

Grafana MCP:n kautta muuttaa peliä

Suurempi muutos on se, että Grafana ei ole enää vain paikka, jossa ihmiset käyvät selaimessa.

Tässä repositoriossa paljastamme Grafanan myös MCP:n kautta. Se tarkoittaa, että agentti voi kysellä Lokia, Prometheusta ja Tempoa suoraan sen sijaan, että odottaisi ihmisen tarkastavan kojelaudat käsin ensin.

Se muuttaa havainnoinnin aktiiviseksi syötteeksi työnkulkuun.

Agentti voi kysyä:

Mitkä työkaluperheet epäonnistuivat eniten viimeisen tunnin aikana?
Mikä MCP-palvelin hallitsi istuntoa?
Vähensivätkö viimeaikaiset muutokset työkaluepäonnistumisia vai siirsivätkö ne vain työn shell-painotteisempiin polkuihin samoilla virheillä?
Mitkä jäljitykset näyttävät suurimman viiveen tai toistuvat uudelleenyritykset?

Kun sinulla on tuo, olet hyvin lähellä itseparannussilmukkaa.

Kojelaudasta palautesilmukkaan

Tätä osaa pidämme kiinnostavimpana.

Kun havainnointipino on kyseltävissä agenttikerroksesta, telemetria lakkaa olemasta passiivinen raportointipinta ja muuttuu ohjaussignaaliksi.

Silmukka näyttää tältä:

Agentin toiminta lähettää jäljityksiä, metriikoita ja rikastettuja hook-lokeja.
Grafana tallentaa todisteet Lokiin, Tempoon ja Prometheukseen, missä metriikoita on.
Agentit kyselevät noita todisteita Grafana MCP:n kautta.
Järjestelmä tunnistaa huonon työkalusekoituksen, hauraat taidot, heikon reitityksen tai shell-painotteiset työnkulut, jotka jatkavat vältettävien virheiden tuottamista.
Agentit tai operaattorit säätävät kehotteita, agenttikonfiguraatioita, taitokuvauksia, reitityssääntöjä tai työkalupääsyä.
Seuraava istunto tuottaa uuden toimintakuvan telemetriaan, ja kierto toistuu.

Näin siirrytään “mielenkiintoisesta kojelaudasta” “mitattavaan parannusjärjestelmään”.

Tavoite ei ole maksimoida yhtä työkaluluokkaa. Se on löytää oikea sekoitus CLI:tä, sisäänrakennettuja työkaluja, MCP-kutsuja ja taitoja siihen työhön, jota oikeasti tehdään.

Mihin tämä antaa meille vastauksen

Kun molemmat ajoympäristöt päätyvät samaan Grafana-pinoon, voimme vastata operatiivisiin kysymyksiin paljon nopeammin:

Keskittyvätkö epäonnistumiset yhteen työkaluperheeseen?
Luovatko shell-painotteiset työnkulut vältettäviä virheitä, joissa korkeamman tason työkalun pitäisi olla olemassa?
Mitkä MCP-palvelimet kantavat työtaakan?
Maksammeko agenttitoiminnasta, joka ei tuota merkityksellistä edistystä?
Onko istunto epäterve mallin, työkalujen vai orkestrointikerroksen vuoksi?

Tämä on erityisen hyödyllistä moniagenttisissa työnkuluissa, joissa “agentti oli kiireinen” ei kerro melkein mitään.

Jos sama erikoisosaaja lähetetään tehtäviin toistuvasti ja se tuottaa korkeita epäonnistumisasteita, se on reititys- tai kehotemuotoiluongelma.

Jos yksi MCP-palvelin hallitsee kaikkia kutsuja, se saattaa olla hyvää arkkitehtuuria tai merkki siitä, että kaikki muu on tarpeetonta lisäpainoa.

Jos työkaluepäonnistumiset piikkaavat kustannusten pysyessä korkeina, sinulla on operatiivinen ongelma, ei laatuongelma.

Jos shell-työ jatkuvasti epäonnistuu ennustettavilla, vältettävillä tavoilla, joissa korkeamman tason työkalun pitäisi olla olemassa, se on tuotesignaali.

Jos yksi taito aktivoituu jatkuvasti muttei paranna lopputuloksia, se on kehote- tai reitityssignaali.

Todellinen opetus

Syvempi opetus tässä on se, että agenttien havainnointi tarvitsee sekä ajoympäristön telemetriaa että työnkulun telemetriaa.

Ajoympäristön telemetria kertoo, mitä järjestelmä teki.

Työnkulun telemetria kertoo, mitä agentti luuli tekevänsä.

Tarvitsemme molempia.

Jos säilytät vain jäljitykset ja laskurit, menetät semanttisen kerroksen. Jos säilytät vain hook-tapahtumat, menetät viiveen, spanit ja laajemman ajoympäristökuvan.

Ja jos säilytät molemmat mutta et koskaan syötä niitä takaisin agenttikerrokseen, sinulla on valvontaa, ei sopeutumista.

Yhdistelmä on se, mikä tekee järjestelmästä tarpeeksi selitettävän operoitavaksi ja tarpeeksi viritettävän parannettavaksi.

Mikä on yhä epätäydellistä

Järjestelmässä on yhä viimeisteltävää.

Kaikki hook-tapahtumat eivät sisällä kesto- ja token-dataa, jota haluaisimme.
Osa parhaista ajoitusnäkymistä tulee yhä Tempo-jäljityksistä, ei hook-lokeista.
Codex on tänään semanttisesti köyhempi kuin Claude Code rikastetussa tapahtumavirrassa.
Kojelaudan kuvakaappaus on reaaliaikainen operatiivinen näkymä, ei viimeistelty markkinointiartefakti.

Tuo viimeinen kohta on tarkoituksellinen. Näytämme mieluummin todellisen mittaritaulun kuin teeskentelemme agenttijärjestelmien olevan maagisesti itseselittäviä.

Miksi tämä merkitsee Maguyvalle

Maguyva antaa agenteille parempaa koodiälyä. Mutta kun agentit oikeasti tekevät hyödyllistä työtä, uusi vaatimus ilmestyy välittömästi: sinun täytyy nähdä, miten ne käyttäytyvät.

Haun laatu, reitityksen laatu, työkalun valinta ja kontekstin tehokkuus muuttuvat kaikki havaittaviksi ongelmiksi.

Siksi ajattelemme tämän olevan kirjoittamisen arvoinen. Tulevaisuuden agenttipino ei ole vain kehotteita ja työkaluja. Se on kehotteita, työkaluja ja instrumentointikerros, joka kertoo, toimiiko koko homma.

Jos rakennat vakavia agenttityönkulkuja, havainnointi ei ole valinnainen infrastruktuuri. Se on osa tuotetta.

Louhinnan työnkulku: miten muutoksista tulee institutionaalista muistia

Tue, 03 Feb 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (helmikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Jokainen insinööritiimi kohtaa saman haasteen: muutoksia tapahtuu jatkuvasti, mutta niiden takana oleva miksi katoaa. Kuusi kuukautta myöhemmin joku kysyy “miksi otimme DuckDB:n käyttöön putken vaiheissa?”, ja vastaus elää vain sen henkilön päässä, joka teki tuon päätöksen — jos hän on yhä paikalla.

Rakensimme louhintatyönkulun, joka sulkee tämän silmukan. Muutokset virtaavat git-commitien läpi, käsitellään louhintaputkessamme, muuttuvat jäsenneltyiksi muutoslokimerkinnöiksi ja arkkitehtonisiksi päätöstietueiksi, ja syötetään sitten takaisin tekoälyagenteillemme CLI-kyselyjen kautta. Tulos: institutionaalinen muisti, johon sekä ihmiset että tekoäly pääsevät käsiksi.

Ongelma: päätökset haihtuvat

Harkitse tyypillistä skenaariota. Kehittäjä committaa:

feat(canonical): add DuckDB runtime for pipeline stages

Tämä commit edustaa merkittävää arkkitehtonista valintaa. Tiimi arvioi vaihtoehtoja, punnitsi kompromisseja ja päätyi DuckDB:hen tietyistä syistä. Mutta kaikki tuo konteksti elää:

Slack-ketjussa (todennäköisesti poistettu)
jonkun muistissa (varmasti haalistumassa)
kommentissa koodissa (ehkä, jos olet onnekas)

Kolme kuukautta myöhemmin uusi tiimin jäsen kysyy: “Pitäisikö minun käyttää DuckDB:tä vai SQLitea tähän uuteen vaiheeseen?” Ilman institutionaalista muistia he joko keksivät pyörän uudelleen tai tekevät epäjohdonmukaisia valintoja.

Silmukka: commiteista kontekstiin

Louhintatyönkulkumme muuntaa git-historian kyselykelpoiseksi tiedoksi:

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

Avainoivallus: sekä muutoslokit että arkkitehtoniset päätökset virtaavat samasta git-historiasta, käsiteltynä yhtenäisen putken läpi. Tämä varmistaa, ettei mitään jää huomaamatta.

Miten louhinta toimii

Vaihe 1: indeksin synkronointi

uv run orkestra mine sync

Tämä komento skannaa git-historian ja rakentaa indeksin kaikista commiteista. Se poimii jäsenneltyjä signaaleja jokaisesta commitista:

Konventionaalinen commit-tyyppi (feat, fix, chore, docs)
Laajuus (mikä paketti tai alue)
Rikkovan muutoksen merkit
Kosketetut tiedostot ja monimutkaisuusmetriikat

Vaihe 2: kattavuustilan tarkistus

uv run orkestra mine status

Nykyinen tilamme näyttää tältä:

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 commitia käsitelty. 476:sta tuli arkkitehtonisia päätöksiä. 6 799:stä tuli muutoslokimerkintöjä. Jokainen commit luokiteltu.

Vaihe 3: ehdokkaiden hankinta katselmointia varten

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

Tämä nostaa esiin commiteja, joita ei vielä ole käsitelty, täydellä kontekstilla luokittelua varten:

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

Signaalit auttavat ohjaamaan luokittelua: is_releasable_type: true viittaa siihen, että tämän pitäisi näkyä muutoslokissa. Suuri lisäysmäärä ja infrastruktuuritiedostot viittaavat siihen, että se saattaa myös olla arkkitehtoninen päätös.

Vaihe 4: commitien luokittelu

Tässä kohtaa polut haarautuvat kahtia: muutoslokimerkinnät ja arkkitehtoniset päätökset.

Muutoslokimerkinnöille:

uv run orkestra mine classify abc123 --changelog added

Tämä kirjaa, että commitin abc123 pitäisi näkyä muutoslokissa “Added”-kategoriassa.

Arkkitehtonisille päätöksille:

Ensin hanki todellinen päätös-ID:

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

Sitten luokittele päätös-ID:llä:

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

Tämä linkittää commitin päätöstietueeseen, joka luodaan tai päivitetään.

Eräkäsittelylle (mitä oikeasti teemme):

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

JSONL-muoto tukee molempia toimialueita yhdellä läpikäynnillä:

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

Vaihe 5: tulosteiden renderöinti

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

Tämä generoi pakettikohtaiset CHANGELOG.md-tiedostot pääkirjasta. Muutoslokit ovat johdettuja artefakteja — poista ne, ja ne generoituvat täydellisesti uudelleen lähdepääkirjasta.

Päätöstietueen rakenne

Poimitut päätökset muuttuvat YAML-tiedostoiksi, joissa on runsaasti metadataa:

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

Jokainen päätös linkittää takaisin lähdecommiteihinsa. Jokainen päätös määrittelee, mihin tiedostoihin se vaikuttaa. Päätösten väliset suhteet ovat eksplisiittisiä.

CLI-integraatio: institutionaalisen muistin kysely

Tässä kohtaa silmukka sulkeutuu. Agentit voivat kysellä päätöksiä CLI:n kautta:

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

Palauttaa päätöksiä uudelleenyrityslogiikasta, virheenkäsittelystä, palautumismalleista.

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

Palauttaa täydellisen päätöstietueen kontekstilla, perusteluilla ja vaikutuksella.

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

Näyttää, mitä arkkitehtonisia valintoja tehtiin äskettäin.

Miten agentit käyttävät tätä

Orkestraattorimme perusohjeisiin kuuluu:

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

Kun agenttia pyydetään toteuttamaan jotain DuckDB:hen liittyvää, se voi ensin tarkistaa:

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

Ja löytää DEC-PL-142:n, oppien:

Miksi valitsimme DuckDB:n (konteksti)
Miten sitä käytetään oikein (agent_guidance)
Mihin tiedostoihin katsoa (files)
Mitä liittyviä päätöksiä on olemassa (related)

Agentti ei keksi pyörää uudelleen. Se rakentaa vakiintuneiden mallien päälle.

Kolmen kysymyksen testi

Ei jokainen commit ansaitse päätöstietuetta. Käytämme Kolmen kysymyksen testiä suodattamiseen:

Oliko tämä vaikea tehdä? Vaatiko se merkittävää analyysiä, kompromissien arviointia tai keskustelua?
Onko sen muuttaminen kallista? Vaatisiko tämän kumoaminen merkittävää uudelleentyötä?
Onko sillä järjestelmänlaajuinen vaikutus? Vaikuttaako se useisiin paketteihin tai luoko se malleja, joita muut seuraavat?

Jos commit vastaa “kyllä” ainakin yhteen näistä kysymyksistä, se on ehdokas päätöspoiminnalle. Tyypillinen suhteemme: 1–4 päätöstä sataa commitia kohti (noin 1–4 %).

Muutoslokimerkinnöille kynnys on matalampi: mikä tahansa käyttäjälle näkyvä muutos (ominaisuudet, korjaukset, parannukset) kirjataan. Sisäiset ylläpitotehtävät, dokumentaatiopäivitykset ja refaktoroinnit yleensä ohitetaan. Tyypillinen suhteemme: 30–50 muutoslokimerkintää sataa commitia kohti.

Datan tallennus: vain lisäyksiä sallivat lokit

Louhintajärjestelmä käyttää vain lisäyksiä sallivia JSONL-lokeja konfliktitonta moniagenttista toimintaa varten:

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

JSONL-muoto merge=union:lla .gitattributes:ssa tarkoittaa, että useat agentit voivat luokitella commiteja samanaikaisesti ilman yhdistämiskonflikteja. Jokainen rivi on riippumaton.

Validointiportit

Ennen mitä tahansa louhintaistuntoa ajamme validoinnin:

uv run orkestra mine validate --quick

Tämä tarkistaa:

SHA-muodon kelvollisuuden
Päätös-ID-muodon vaatimustenmukaisuuden
Ei duplikaattimerkintöjä samalle SHA:lle
Että viitatut päätökset todella ovat olemassa

Luokittelun jälkeen validoimme uudelleen ennen muutosten committaamista.

Miksi tämä merkitsee

Rakentamamme palautesilmukka ratkaisee useita ongelmia:

Uusille tiimin jäsenille: sen sijaan että kysyisivät “miksi teimme X:n?”, he voivat hakea päätösrekisteristä. Konteksti on säilytetty.

Tekoälyagenteille: ne eivät toimi tyhjiössä. Ne voivat kysellä institutionaalista tietoa ennen suositusten antamista. Kun niitä pyydetään lisäämään uusi putkivaihe, ne voivat löytää DuckDB-mallin ja seurata sitä.

Arkkitehtoniselle johdonmukaisuudelle: päätökset ovat eksplisiittisiä ja haettavissa. Kun joku ehdottaa lähestymistapaa, joka on ristiriidassa olemassa olevan päätöksen kanssa, järjestelmä voi nostaa ristiriidan esiin.

Muutoslokien generoinnille: julkaisumuistiinpanot eivät synny viime hetken kiireessä. Ne ovat sivutuote jatkuvasta luokittelusta kehityksen aikana.

Perehdytykselle: uudet agentit perivät koodikannan täyden kontekstin. Ne eivät vain näe koodia — ne näkevät päätökset, jotka muokkasivat sitä.

Nykytila

Tänään:

15 637 commitia käsitelty putken läpi
476 arkkitehtonista päätöstä poimittu ja dokumentoitu
6 799 muutoslokimerkintää kirjattu
100 %:n kattavuus molemmilla toimialueilla

Jokainen commit siitä lähtien, kun aloitimme, on luokiteltu. Institutionaalinen muisti on täydellinen ja kyselykelpoinen.

Aloittaminen

Jos haluat toteuttaa jotain vastaavaa:

Aloita konventionaalisilla commiteilla. Louhintaputki toimii parhaiten, kun commiteilla on jäsennellyt etuliitteet (feat:, fix:, chore:).
Määrittele toimialueesi. Käytämme toimialueita kuten pipeline, agent-design, observability, data-modeling. Nämä järjestävät päätökset alueen mukaan.
Rakenna luokittelutottumus. Louhinta toimii, kun tiimit luokittelevat commiteja säännöllisesti. Eräkäsittely LLM-avustuksella auttaa skaalautumaan.
Tee päätöksistä kyselykelpoisia. Arvo kasvaa, kun agentit voivat hakea päätöksiä CLI:n kautta. Rakenna tulosteesi koneluettavaksi.
Sulje silmukka. Päätösten pitäisi vaikuttaa tulevaan työhön. Sisällytä päätösviittauksia agenttiohjeisiin ja koodikatselmuslistoihin.

Tavoite ei ole täydellinen dokumentaatio. Se on tehdä muutosten takana oleva miksi saavutettavaksi sekä ihmisille että tekoälylle, tänään ja kuuden kuukauden kuluttua. Kun muutoksista tulee institutionaalista muistia, tiimit rakentavat vakiintuneiden mallien päälle sen sijaan että keksisivät ne uudelleen.

Louhintatyönkulku on osa orkestrointimoottoriamme, erityisesti orkestrointipakettimme kontekstimoottorimoduulia.

Taitojen louhinta: 3 500 ehdokkaasta 466 kyvyksi

Tue, 27 Jan 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

3 500 taidon ongelma

Kun aloimme rakentaa agenttien orkestrointijärjestelmää, kohtasimme kiinnostavan haasteen: tekoälyekosysteemin yli on hajallaan tuhansia mahdollisia taitoja. GitHub-repositoriot, vendor-dokumentaatio, yhteisöprojektit, sisäiset mallit — taitoja on kaikkialla. Mutta mitkä niistä merkitsevät? Mitkä toimivat? Ja miten ylläpidät johdonmukaista taitokirjastoa, jota agentit voivat oikeasti käyttää?

Vastauksemme: systemaattinen louhinta- ja käyttöönottosilmukka.

Luvut tänään

Hieman yli kolme kuukautta sen jälkeen, kun Anthropic julkaisi Agent Skillsin 16. lokakuuta 2025, tilanteemme näytti tältä, kun tämä postaus julkaistiin 27. tammikuuta 2026:

Mittari	Määrä
Tunnistetut ehdokkaat	3 500+
Hyväksytyt taidot	466
Vendor-taidot	373
Sisäiset taidot	93
Aktiiviset vendorit	25+
Keskimääräinen tokenmäärä per taito	2 834
Viitatut työkalut	89
Yksilölliset tagit	635

Olemme katselmoineet yli 3 500 taitoehdokasta. Olemme hyväksyneet 466. Se on 13 %:n hyväksymisaste — ja se valikoivuus on tarkoituksellista.

Tietämystasojärjestelmä

Kaikki taidot eivät ole samanarvoisia. Järjestämme ne viiteen tietämyskerrokseen (K0–K4), joista jokainen edustaa erilaista sovellettavuuden laajuutta:

K0: perusta (universaali)

Taitoja, jotka jokaisella agentilla pitäisi olla. Nämä edustavat “hyvän ajattelijan” kyvykkyyksiä, jotka toimivat missä tahansa.

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

K0-taidot ovat siirrettävissä mihin tahansa projektiin, toimialueeseen tai pinoon. Ne koodaavat universaaleja kognitiivisia malleja.

K1: identiteetit (ammattiala)

“Hyvän insinöörin” tai “hyvän tutkijan” taitoja, jotka soveltuvat projektien yli tietyllä ammattialalla.

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

K2: toimialueet (aihealueen asiantuntemus)

“Hyvän tietokanta-asiantuntijan” tai “hyvän turvallisuusinsinöörin” taitoja, jotka ovat siirrettävissä kentän sisällä.

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: pinot (teknologia)

“Hyvän Supabase-käyttäjän” tai “hyvän Cloudflare-kehittäjän” taitoja tietyille teknologiapinoille.

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

K4: projekti (organisaatio)

Organisaatiollemme ja työnkuluillemme ominaisia taitoja.

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

Louhintasilmukka

Vaihe 1: löytäminen

Taitoja tulee kaikkialta:

Vendor-repositoriot: AWS, Anthropic, Cloudflare, Supabase ja yhteisön avustajat julkaisevat taitokokoelmia. Seuraamme 25+ vendor-juurta.

Yhteisöprojektit: GitHub on täynnä Claude Code -templateja, agenttimalleja ja työnkulkumäärittelyjä.

Sisäiset mallit: kun tiimimme ratkoo ongelmia, malleja syntyy. Nämä muotoillaan taidoiksi.

Dokumentaation louhinta: teknisessä dokumentaatiossa on usein implisiittisiä taitoja — menettelyjä, tarkistuslistoja, päätöspuita.

Löytäminen on jatkuvaa. Käytämme taitojen työjonoa ehdokkaiden seurantaan ennen muodollista arviointia.

Vaihe 2: arviointi

Jokainen ehdokas käy läpi saman arviointikehyksen:

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

Ehdokkaan täytyy täyttää kaikki viisi tuotekriteeriä. Siksi 87 % ehdokkaista hylätään.

Sitten jokainen ehdokas käy läpi erillisen luottamuskatselmuksen. Emme käsittele virallista vendor-repositoriota, tunnettua yhteisön ylläpitäjää ja satunnaista GitHub-repositoriota yhtä luotettavina tiedonlähteinä.

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

Luotetut vendorit saavat kevyemmän alkuperäkatselmuksen, mutteivät vapaakorttia. Luottamattomat tai tuntemattomat lähteet saavat syvemmän manuaalisen auditoinnin, emmekä suorita paketoituja skriptejä ennen kuin ne on luettu, rajattu ja luokiteltu turvallisiksi.

Puutteiden analyysi: ennen käyttöönottoa haemme rekisteristämme:

uv run orkestra skills search "<capability>"

Jos meillä jo on se, emme tarvitse sitä. Jos meillä on jotain lähellä olevaa, saatamme yhdistää sen sijaan että hyväksyisimme uuden.

Syvyys- ja standardipisteytys: pisteytämme myös, kuinka täysimääräisesti ehdokas käyttää agentti-taito-mallia. Yksittäinen SKILL.md voi silti olla hyödyllinen, mutta syvemmät taidot ovat arvokkaampia, kun ne erottavat ohjeet viitteistä, skripteistä ja resursseista tavalla, jota agentskills.io kannustaa.

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

GitHub-tähdet voivat nostaa uskottavuuspistettä hieman, mutta ne eivät koskaan pelasta pinnallista tai epäturvallista taitoa. Korkean tähtimäärän repositorio, jossa on yksi epämääräinen SKILL.md ja läpinäkymättömiä skriptejä, pisteytyy alemmas kuin pienempi repositorio, jossa on tarkka kuvaus, kuratoidut references/ ja atomiset apuohjelmat, jotka todella hyödyntävät täyttä taitokyvykkyyttä.

Rakenteellinen analyysi: tarkistamme taidon laadun:

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

Jos ehdokas sisältää skriptejä, katselmuksesta tulee tiukempi. Hyvä taito ei ole vain hyödyllinen; sen täytyy olla luettavissa, rajattu ja turvallinen antaa agentille. Tuo turvallisuussuodatin yksinään diskvalifioi merkittävän osan muuten kiinnostavista ehdokkaista.

Vaihe 3: käyttöönotto

Kun taito läpäisee arvioinnin, se pääsee rekisteriin. Mutta taitoja ei koskaan hyväksytä muuttumattomina. Ne muokataan sopimaan järjestelmäämme.

Käyttöönoton muokkaukset:

Metadatan normalisointi: jokainen taito saa frontmatter-skeemamme
K-tason osoitus: taidot sijoitetaan sopivaan tietämyskerrokseen
Tagien rikastus: tageja lisätään löydettävyyttä varten
Työkalujulistus: sallitut työkalut julistetaan eksplisiittisesti
Osioiden kohdistus: sisältö rakennetaan uudelleen vastaamaan templateamme

Tyypillinen taito-YAML käyttöönoton jälkeen:

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

Vaihe 4: laajuuden osoitus

Taidot osoitetaan laajuuksiin — kategorioihin, jotka määrittävät, mitkä agentit lataavat mitkä taidot:

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

Agentit julistavat laajuutensa, ja taidot osoitetaan automaattisesti:

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

Vaihe 5: materialisointi

Taidot eivät elä YAML:na tuotannossa. Ne renderöidään SKILL.md-tiedostoiksi, joita Claude Code voi ladata:

uv run orkestra sync

Tämä komento:

Lukee kaikki taitojen YAML-määrittelyt
Renderöi ne Jinja-templatejen läpi
Kirjoittaa SKILL.md-tiedostot kohteeseen .claude/skills/
Järjestää K-tason mukaan (foundations/, identities/, domains/, stacks/, project/)

Lopullinen tulosterakenne:

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

Lepotilan laajuusmalli

Yksi voimakkaimmista malleistamme on “hyväksytty muttei ladattu” -taito. Kutsumme näitä lepotilan laajuuksiksi.

Harkitse tieteellisen laskennan taitoja k-dense-scientific-repositoriosta. Olemme hyväksyneet 120+ taitoa, jotka kattavat bioinformatiikkaa, kemiaa, kvanttilaskentaa ja kliinistä informatiikkaa. Mutta useimmat agenttimme eivät tarvitse molekyylidokkausta tai geeni-ilmentymisanalyysiä.

Sen sijaan että lataisimme kaikki 120 taitoa jokaiseen agenttiin (paisuttaen kontekstiikkunoita), me:

Hyväksymme taidot tietyllä laajuudella (esim. bioinformatics)
Pidämme ne lepotilassa — rekisteröityinä, mutta ei ladattuina
Otamme ne käyttöön vain, kun agentti julistaa tuon laajuuden

# 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

Tämä malli antaa meille 466 taitoa rekisterissä, kun taas tyypilliset agentit lataavat vain 40–60 relevanttia.

Taitotyypit

Taidot esiintyvät kolmena kognitiivisena mallina:

Työnkulku

Järjestetyt menettelylliset askeleet: “1. Tee X, 2. Sitten Y, 3. Lopuksi Z”

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

Kuri

Käyttäytymistä ohjaavat säännöt: “Tee aina X”, “Älä koskaan tee Y”, “Suosi Z:aa”

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

Tarkistuslista

Varmennuskriteerit: “Vahvista X”, “Varmenna Y”, “Tarkista Z”

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

Laatuportit

Jokaisen taidon täytyy läpäistä validointi ennen julkaisua:

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

Kuvausten täytyy olla 50–400 merkkiä laukaisulausekkeilla (“Käytä kun…”, “Kun tarvitset…”), jotta Claude Code tietää, milloin ehdottaa niitä.

Validoimme jatkuvasti:

uv run orkestra validate --show-warnings

Vendor-ekosysteemi

373 vendor-taitomme tulevat:

Toimittaja	Taidot	Toimialue
AWS Agent	19	Pilvipalvelut
Anthropic	12	Dokumenttien generointi
Cloudflare	8	Reunalaskenta
Supabase	5	Tietokanta
k-dense	100+	Tieteellinen laskenta
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Selainautomaatio

Jokainen vendor-juuri julistetaan metadata.yaml:ssa:

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

Kun orkestra sync ajetaan, vendor-taidot symlinkataan kohteeseen .claude/skills/vendor/ niiden toimittajan nimiavaruudella.

Mitä olemme oppineet

Valikoivuus kannattaa. On houkuttelevaa hyväksyä kaikki, mikä näyttää hyödylliseltä. Mutta jokainen taito maksaa tokeneita. 2 834 keskimääräisellä tokenimäärällä per taito sisällön paisuminen kuormittaa kontekstia nopeasti. 13 %:n hyväksymisasteemme pitää agentit ketterinä.

Rakenne mahdollistaa löydettävyyden. K-tasojärjestelmä ei ole vain organisointia — se koskee siirrettävyyttä. K0-taitoja voi käyttää uudelleen missä tahansa. K4-taidot ovat tarkoituksella projektikohtaisia. Tämä selkeys auttaa sekä ihmisiä että agentteja löytämään tarvitsemansa.

Lepotilan laajuudet skaalautuvat. Voit hyväksyä satoja taitoja lataamatta niitä kaikkia. Laajuuksien avulla voit rakentaa kattavan rekisterin pitäen samalla yksittäisten agenttien kontekstiikkunat hallittavina.

Muokkaus käyttöönotossa on välttämätöntä. Raa’at vendor-taidot harvoin sopivat järjestelmääsi. Käyttöönottoprosessi — metadatan lisääminen, tasojen osoitus, tagien rikastus — saa ulkoiset taidot toimimaan sisäisesti.

Louhinta on jatkuvaa. 3 500:n luku kasvaa jatkuvasti. Uusia vendor-repositorioita ilmestyy. Yhteisömalleja syntyy. Sisäiset työnkulut vakiintuvat. Silmukka ei koskaan pysähdy.

Mitä seuraavaksi

Työskentelemme useiden parannusten parissa:

Puutteiden automaattinen tunnistus: hälytä, kun yleiset agenttiepäonnistumiset voitaisiin ratkaista taidolla, jota ei ole vielä otettu käyttöön
Taitojen vanhentumistyönkulut: muodollinen prosessi eläkkeelle jäävien taitojen poistamiseksi, kun ne korvataan tai jäävät käyttämättä
Taitojen väliset riippuvuudet: taidon esivaatimusten eksplisiittinen julistaminen
Käyttöanalytiikka: seuraa, mitä taitoja agentit oikeasti kutsuvat verrattuna vain lataamiseen

Taitojen louhintasilmukka on infrastruktuuria. Se ei ole hohdokasta. Mutta se on se, mikä saa 41 agenttia toimimaan johdonmukaisesti 466 kyvykkyydellä pysyen samalla kontekstirajojen sisällä.

Se on tarina siitä, miten 3 500:sta tulee 466. Ei jättämällä 3 000 huomiotta — vaan arvioimalla ne systemaattisesti ja hyväksymällä vain sen, mikä toimii.

Haluatko nähdä taitojärjestelmän toiminnassa? Käy tutustumassa kohteeseen uv run orkestra skills list tutkiaksesi nykyistä rekisteriämme.

Tietojen asteittainen näyttäminen: CLI-ikkunat agenttijärjestelmiin

Tue, 20 Jan 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Agenttijärjestelmät ovat suunnittelultaan läpinäkymättömiä. Ne tekevät päätöksiä, kutsuvat työkaluja ja koordinoivat työtä kymmenien erikoisosaajien yli. Mutta kun jokin menee pieleen — tai kun haluat yksinkertaisesti ymmärtää, mitä tapahtuu — mistä katsot?

Vastaus on tietojen asteittainen näyttäminen: kerroksellinen rajapinta, joka paljastaa juuri sen verran monimutkaisuutta kuin tarvitset, juuri silloin kun tarvitset sitä.

Läpinäkymättömyysongelma

Modernissa agenttien orkestrointijärjestelmässä saattaa olla:

40+ erikoisosaaja-agenttia, kullakin omat kyvykkyytensä
700+ taitoa, jotka kattavat sisäistä automaatiota ja vendori-integraatioita
470+ arkkitehtonista päätöstä, jotka muokkaavat käyttäytymistä
kymmeniä MCP-työkalupalvelimia, jotka tarjoavat ulkoisia kyvykkyyksiä

Tämä monimutkaisuus on tarkoituksellista. Agentit tarvitsevat pääsyn runsaaseen kontekstiin — toimialuetietämykseen, koodiälyyn, tietokantaskeemoihin — tehdäkseen hyviä päätöksiä. Mutta sama runsaus luo näkyvyysongelman.

Mistä tiedät, mikä agentti käsittelee tietokantamigraatioita? Mitkä päätökset muokkasivat hakujärjestelmän järjestyskäyttäytymistä? Mihin työkaluihin arkkitehtuurineuvonantajalla on pääsy?

Ilman jäsenneltyä pääsyä jäät lukemaan lähdekoodia tai toivomaan, että dokumentaatio on ajan tasalla.

Tietojen asteittainen näyttäminen arkkitehtuurina

Tietojen asteittainen näyttäminen ei ole pelkkä käyttöliittymämalli. Se on arkkitehtoninen periaate: järjestä tieto kerroksiin, joista jokainen on syvempi kuin edellinen, jotta käyttäjät voivat pysähtyä tasolle, joka vastaa heidän kysymykseensä.

Agenttijärjestelmille tämä tarkoittaa CLI-komentoja kasvavilla syvyystasoilla:

Taso	Komento	Kysymys, johon vastataan
1	`orkestra system status`	Onko kaikki kunnossa?
2	`orkestra agents list`	Mitä agentteja on olemassa?
3	`orkestra agents info <name>`	Mitä tämä agentti tekee?
4	`orkestra decisions search`	Miksi se toimii näin?
5	Maguyva MCP -työkalut	Näytä minulle koodi.

Jokainen taso vastaa luonnolliseen jatkokysymykseen. Harvoin tarvitsee hypätä suoraan tasolle 5.

Taso 1: järjestelmän terveys

Ensimmäinen kysymys on aina: toimiiko kaikki?

$ orkestra system status

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

Yksi komento. Neljä lukua. Tarpeeksi tietääkseen, että järjestelmä on konfiguroitu ja rekisterit täytettyjä.

Jos agenttimäärä putoaa odottamatta tai taidot eivät lataudu, näet sen täällä ensin. Ei tarvetta sukeltaa lokeihin.

Taso 2: agenttien inventaario

Kun tiedät, että järjestelmä on terve, seuraava kysymys on: mitä on saatavilla?

$ orkestra agents list

Tämä palauttaa jäsenneltyä dataa — agenttien nimet, kuvaukset, mallimieltymykset, toimialuekattavuuden. Tuloste on oletuksena JSON, mikä helpottaa sen putkittamista jq:ään suodatusta varten:

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

Haluatko agentteja, jotka käsittelevät tietokantatyötä? Hakukomento kaventaa sitä:

$ orkestra agents search "database"

Tämä skannaa nimet, kuvaukset ja kyvykkyydet. Löydät oikean erikoisosaajan lukematta 40 agenttimäärittelyä.

Taso 3: agentin syväsukellus

Löysitkö agentin, joka näyttää relevantilta? Komento info paljastaa kaiken:

$ orkestra agents info architecture-advisor

Tuloste sisältää:

Metadata: nimi, kategoria, mallimieltymys, kuvaus
Toimialueet: mitkä tietämysalueet tämä agentti kattaa
Identiteetti: hahmopiirteet (arkkitehti, strategisti, tietämysarkkitehti)
Työkaluoppaat: mikä työkaludokumentaatio lisätään kontekstiin
Työkalut: täydellinen luettelo tälle agentille saatavilla olevista MCP-työkaluista

Tässä on näyte siitä, mitä näet:

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

Tämä kertoo tarkalleen, mitä agentti pystyy tekemään. Ei lähdekoodia tarvita.

Taso 4: päätösten arkeologia

Agentit käyttäytyvät dokumentoitujen päätösten mukaisesti. Kun sinun täytyy ymmärtää, miksi jokin toimii tietyllä tavalla, päätösrekisteri on totuuden lähde.

$ orkestra decisions search "agent"

Tämä palauttaa täsmääviä arkkitehtonisia päätöksiä:

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

Jokaisella päätöksellä on täysi alkuperä — milloin se tehtiin, miksi, mitä kompromisseja harkittiin, mitkä commitit toteuttivat sen:

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

Tämä on arkkitehtonista dokumentaatiota, joka pysyy ajan tasalla, koska se on louhittu commiteista, ei käsin ylläpidetty.

Taso 5: suora koodiäly

Kun sinun täytyy nähdä varsinainen toteutus — ei metadataa siitä — Maguyvan MCP-työkalut tarjoavat suoran pääsyn.

Agentti-istunnon sisältä:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Tämä reitittää automaattisesti semanttisen, teksti- ja AST-haun yli löytääkseen relevantin koodin. Tietyille symboleille:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Riippuvuusanalyysille:

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

Nämä eivät ole vain grep-korvikkeita. Ne ovat graafia hyödyntäviä, semanttisesti indeksoituja ja integroituja samaan koodiälyyn, joka tehostaa itse agentteja.

Yhtenäinen haku rekisterien yli

Joskus et tiedä, missä rekisterissä vastaus on. Yhtenäinen haku kattaa kaiken:

$ orkestra search "database" --summary

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

254 osumaa viidestä rekisteristä. Yhteenveto kertoo, mihin porautua. Poista --summary yksityiskohtaisia tuloksia varten, tai lisää --limit 5 pitääksesi tulosteen hallittavana.

Miksi tämä merkitsee

Tietojen asteittaisessa näyttämisessä ei ole kyse vain käyttömukavuudesta. Se muuttaa tapaa, jolla vuorovaikutat monimutkaisten järjestelmien kanssa.

Vianetsinnästä tulee hallittavaa. Kun agentti tekee odottamattoman päätöksen, et grep-hae lokeja. Tarkistat, mihin työkaluihin sillä on pääsy (agents info), mitkä päätökset muokkaavat sen käyttäytymistä (decisions search), ja jäljität toteutuksen tarvittaessa (intelligent_search).

Perehdytys nopeutuu. Uusien tiimin jäsenten ei tarvitse lukea koko koodikantaa. He aloittavat komennosta system status, tutkivat komennolla agents list ja menevät syvemmälle vasta, kun kohtaavat jotain, mitä eivät ymmärrä.

Dokumentaatio pysyy ajan tasalla. Koska CLI lukee samoista rekistereistä, jotka konfiguroivat agentit, tuloste on aina tarkka. Dokumentaatio vastaa järjestelmän todellista toimintaa.

CLI rajapintana

Olisimme voineet rakentaa web-kojelaudan. Olisimme voineet kirjoittaa laajan dokumentaation. Sen sijaan rakensimme CLI:n, joka lukee totuuden lähteestä.

CLI:llä on etuja:

Koosteltava: putkita tulostetta jq:n läpi, integroi skripteihin
Skriptattava: automatisoi tarkistuksia, generoi raportteja
Nopea: ei sivulatauksia, ei todennuskulkuja
Tarkka: lukee todellisen konfiguraation, ei välimuistiin tallennettua esitystä

Järjestelmille, joissa oikeellisuus merkitsee enemmän kuin estetiikka, CLI voittaa.

Oman asteittain tarkentuvan käyttöliittymän rakentaminen

Jos rakennat agenttijärjestelmiä, harkitse, miten käyttäjät tarkastelevat niitä:

Aloita terveystarkistuksista. Yksi komento, joka kertoo, toimivatko asiat.
Tarjoa inventaarionäkymät. Listaa, mitä on olemassa, ennen kuin selität, mitä se tekee.
Mahdollista kohdennetut kyselyt. Haku voittaa selailun laajassa mittakaavassa.
Paljasta alkuperä. Anna käyttäjien jäljittää päätökset alkuperäänsä.
Yhdistä koodiälyyn. Lopulta käyttäjien täytyy nähdä toteutus.

Jokainen kerros vastaa jatkokysymykseen. Rakenna ne yleisyysjärjestyksessä — useimmat käyttäjät pysähtyvät tasolle 2 tai 3. Vain tehokäyttäjät saavuttavat tason 5.

Tavoite ei ole paljastaa kaikkea. Se on paljastaa juuri se, mitä tarvitaan, juuri silloin kun sitä tarvitaan. Se on tietojen asteittainen näyttäminen sovellettuna agenttiarkkitehtuuriin.

Ground Truths: tekoälyagenttien ankkurointi todellisuuteen

Tue, 13 Jan 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Tekoälyagentit ovat huomattavan kyvykkäitä. Ne osaavat päätellä, syntetisoida ja generoida. Mutta niillä on perustavanlaatuinen heikkous: ne keksivät asioita. Ei pahantahtoisesti, vaan itsevarmasti. Agentti saattaa keksiä API-parametreja, joita ei ole olemassa, viitata konfiguraatioihin, joita ei koskaan määritelty, tai soveltaa malleja koulutusdatastaan, jotka ovat ristiriidassa todellisen arkkitehtuurisi kanssa.

Vakiokorjaus on “anna agentille lisää kontekstia”. Mutta konteksti voi olla ristiriitainen. Dokumentaatio ajautuu erilleen toteutuksesta. Kommentit valehtelevat. Jopa koodi voi harhauttaa, jos sitä luetaan ymmärtämättä tarkoitusta.

Tarvitsimme jotain eksplisiittisempää. Jotain, mitä ei voisi jättää huomiotta tai tulkita väärin. Jotain, joka ankkuroisi agentit todennettavaan todellisuuteen.

Kutsumme niitä Ground Truthiksi.

Mikä on Ground Truth?

Ground truth on eksplisiittinen, versioitu tosiasiaväite, jota agenttien täytyy kunnioittaa. Se ei ole dokumentaatiota. Se ei ole kommentti. Se on itsenäinen, keskeinen entiteetti järjestelmässä, jolla on:

Yksilöllinen tunniste (kuten GT-MAG-015 tai GT-MAG-036)
Elinkaaren tila (nykyinen, alustava tai vanhentunut)
Laajuus (koko alustan kattava, pakettikohtainen tai toimialuesidonnainen)
Todisteet (tiedostopolut, URL-osoitteet tai viittaukset, jotka todistavat väitteen)
Agenttiohjeistus (eksplisiittiset tee/vältä-ohjeet)

Tässä on esimerkki Maguyva-koodiälyalustaltamme:

- 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

Tämä ei ole proosaa. Se on sopimus. Kun agentti kohtaa tämän ground truthin, se tietää:

Oletusarvo on deterministinen (tyhjät tulokset, ei likimääräisiin osumiin perustuvia arvauksia)
On tiettyjä parametreja (find_similar, exact_match) määritellyllä käyttäytymisellä
Todisteita on olemassa tietyissä tiedostoissa, jotka voidaan varmentaa
Väite varmennettiin tiettynä päivänä

Ground Truth -rekisterin anatomia

Ground truthit elävät YAML-rekistereissä kohdassa ai_assets/reference/ground_truths.yaml. Jokaisella paketilla tai toimialueella voi olla oma rekisterinsä. Rakenne on:

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

Rekisteri sisältää metadataa itse kokoelmasta, renderöintikonfiguraation dokumentaation generointia varten sekä itse väitteet. Jokainen väite noudattaa tiukkaa skeemaa, jonka Pydantic-mallit validoivat:

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

Miten agentit pääsevät käsiksi ground truthiin

Ground truthit paljastetaan useiden kanavien kautta:

1. Renderöity dokumentaatio

Komento orkestra sync muuntaa YAML-rekisterit luettavaksi markdowniksi:

uv run orkestra sync

Tämä generoi GROUND_TRUTHS.md-tiedostoja, jotka sisällytetään agentin kontekstiin. Renderöity tuloste ryhmittelee väitteet tilan ja kategorian mukaan:

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

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

2. CLI-haku

Agentit, joilla on shell-pääsy, voivat hakea ground truthia ohjelmallisesti:

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

Hakufunktio pisteyttää osumat useissa kentissä painotetulla relevanssilla:

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

Kun agentit renderöidään YAML-määrittelyistä, niiden konteksti voi viitata ground truth -rekistereihin:

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

Tämä varmistaa, että relevantit ground truthit ladataan ennen kuin agentti aloittaa työn.

Ground truthien kategoriat

Kun tarkastelemme rekisterejämme, ground truthit ryhmittyvät useisiin malleihin:

Tuoteperiaatteet

Rajoitteet sille, mitä tuote on ja mitä se ei ole:

“Maguyvalla on vain lukuoikeus käyttäjän repositorioihin; ainoa resurssi, jota ei voi rakentaa uudelleen, on maksullinen upotuscache.” (GT-MAG-001)

Arkkitehtuurin rajat

Missä vastuut sijaitsevat ja miksi:

“Putken ja Maguyvan rajat ovat tarkoituksellisia: putki on uudelleenkäytettävä, Maguyva pitää sisällään koodikohtaisen logiikan, ja CQRS erottaa vaiheen kirjoitukset palvelimen lukuoperaatioista.” (GT-MAG-006)

Anti-hallusinaatiosäännöt

Eksplisiittiset toimeksiannot, jotka pitävät työkalusopimukset deterministisinä pääteltyjen sijaan:

“Sumea symbolivastaavuus otetaan käyttöön erikseen find_similar=true:n kautta. Oletuskäyttäytyminen palauttaa tyhjiä tuloksia olemattomille symboleille; exact_match=true pakottaa tarkan vastaavuuden ja poistaa käytöstä kaikki sumeat varajärjestelyt.” (GT-MAG-015)

Laatuportit

Standardit, joita täytyy ylläpitää:

“Muutokset jaettuun infrastruktuuriin (post_filters.py, suhdepoimijat, jaetut käsittelijät) TÄYTYY validoida KAIKKIA tuettuja kieliä vasten täyden manifestin generoinnilla ennen committia. Yhden kielen validointi ei riitä jaetulle koodille.” (GT-MAG-036)

Koodimallit

Toteutusvaatimukset:

“Käytä asyncio.to_thread() CPU-sidonnaiselle työlle asynkronisissa konteksteissa; vanhentunutta loop.run_in_executor()-mallia ei tule käyttää uudessa koodissa.” (GT-MAG-018)

Ground truthin elinkaari

Ground truthit eivät ole staattisia. Ne kehittyvät määritellyn elinkaaren kautta:

Alustava

Ehdotettu totuus arvioinnin alla. Väite on kirjattu, mutta se saattaa muuttua:

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

Nykyinen

Varmennettu totuus, jota agenttien täytyy kunnioittaa. Todisteet on validoitu:

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

Vanhentunut

Totuus, joka ei enää päde. Säilytetty historiallisena viitteenä viittauksella siihen, mikä sen korvasi:

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

Miksi ei vain dokumentaatiota?

Dokumentaatio palvelee eri tarkoitusta. Se selittää. Se opettaa. Se voi olla epämääräistä, se voi käyttää täsmentäjiä kuten “yleensä” tai “tyypillisesti”.

Ground truthit eivät voi olla epämääräisiä. Ne ovat väitteitä. Ne joko pätevät tai eivät.

Tarkastele eroa:

Dokumentaatio: “API palauttaa yleensä tyhjiä tuloksia, kun symbolia ei löydy, vaikka sumea vastaavuus saattaa olla käytössä joissakin konfiguraatioissa.”

Ground Truth: “Oletuskäyttäytyminen palauttaa tyhjiä tuloksia olemattomille symboleille; exact_match=true pakottaa tarkan vastaavuuden ja poistaa käytöstä kaikki sumeat varajärjestelyt.”

Ensimmäinen on hyödyllinen ihmisille, jotka opettelevat järjestelmää. Toinen on toimintakelpoinen agenteille, jotka tekevät päätöksiä.

Agenttiohjeistus: tee ja vältä

Jotkin ground truthit sisältävät eksplisiittistä agenttiohjeistusta:

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

Tämä poistaa epäselvyyden. Tämän lukeva agentti tietää, ei vain mikä on totta, vaan mitä toimia se totuus edellyttää.

Varmennus ja ylläpito

Ground truthit vaativat ylläpitoa. Seuraamme:

last_verified: milloin joku vahvisti väitteen yhä pätevän
evidence: tiedostot, jotka todistavat väitteen (voidaan tarkistaa olemassaolon suhteen)
source: mistä totuus on peräisin (CLI-tarkastus, arkkitehtuurikatselmus, insidentin jälkeinen oppiminen)

Ground truth, jonka varmennuspäivämäärät ovat vanhentuneet tai todistelinkit rikki, on signaali tutkia asiaa. Joko totuus on yhä voimassa ja tarvitsee uudelleenvarmennuksen, tai todellisuus on muuttunut ja totuus tarvitsee päivityksen.

Todellisia esimerkkejä tuotannosta

Turvallisuusraja

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

Tämä ground truth estää luokan harhaanjohtavia “turvallisuusparannuksia”, jotka rikkoisivat tuotteen.

Poiminta-ajan tarkkuus

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

Tämä syntyi tuskallisesta kokemuksesta. Agentit paikkasivat epäonnistuvia kielipaketteja lisäämällä vain validaattorille suunnattuja suodattimia, jotka saivat testitulokset näyttämään paremmilta, kun taas tuotannossa toimiva Maguyva-poimija yhä lähetti vääriä reunoja. Sääntö pakottaa korjaukset takaisin todelliselle polulle: YAML-konfiguraatioon, kyselyihin tai käsittelijöihin.

Monitasoinen suodatus

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

Tämä estää agentteja lisäämästä suodattimia väärään paikkaan, mikä on yleinen virhe, joka aiheutti tarkkuusregressioita.

Integrointi orkestrointijärjestelmään

Ground truthit ovat yksi kerros laajemmassa kontekstijärjestelmässä:

Arkkitehtoniset päätökset (ADR:t) - kirjaavat, miksi valitsimme lähestymistavan A tavan B sijaan
Ground Truthit - toteavat, mikä on ehdottomasti totta juuri nyt
Toimialuemallit - kuvaavat, miten asiat tehdään oikein
Anti-mallit - kuvaavat, mitä välttää ja miksi

Järjestelmässä työskentelevällä agentilla on pääsy kaikkiin neljään. Ground truthit tarjoavat tosiasiallisen ankkurin, kun taas päätökset selittävät historiaa, mallit ohjaavat toteutusta ja anti-mallit varoittavat sudenkuopista.

Vaikutuksen mittaaminen

Ground truthien käyttöönoton jälkeen olemme havainneet:

Vähemmän “korjaa hallusinoitu korjaus” -kiertoja
Itsevarmempaa agentin päätöksentekoa, kun tosiasiat ovat selkeitä
Parempia PR-katselmuksia, koska odotukset ovat eksplisiittisiä
Lyhentynyt perehdytysaika uusille agenteille (ja ihmisille)

Ground truthien ylläpitoon investoiminen maksaa itsensä takaisin vähentyneenä vianetsintänä ja selkeämpinä järjestelmärajoina.

Aloittaminen

Ground truthin lisäämiseksi järjestelmääsi:

Luo ground_truths.yaml pakettisi ai_assets/reference/-hakemistoon
Määrittele metadata ja renderöintikonfiguraatio
Lisää väitteet skeeman mukaisesti
Aja uv run orkestra sync dokumentaation generoimiseksi
Sisällytä rekisteri agentin kontekstin kokoonpanoon

Aloita tosiasioista, jotka aiheuttavat eniten sekaannusta, tai rajoitteista, joita rikotaan useimmin. Ne ovat arvokkaimmat ground truthisi.

Yhteenveto

Tekoälyagentit tulevat hallusinoimaan. Se on niiden luonto. Mutta voimme luoda ympäristöjä, joissa hallusinaatio on rajoitettua, joissa tietyistä tosiasioista ei tingitä, joissa agentit voivat tarkistaa oletuksensa varmennettua todellisuutta vasten.

Ground truthit eivät ole täydellinen ratkaisu. Ne vaativat ylläpitoa. Ne voivat vanhentua. Ne lisäävät yleiskustannuksia kehitysprosessiin.

Mutta ne tarjoavat jotain arvokasta: jaetun tosiasioiden sanaston, johon sekä ihmiset että agentit voivat luottaa. Maailmassa, jossa agentit osallistuvat yhä enemmän ohjelmistokehitykseen, tuosta jaetusta perustasta tulee välttämätön.

Vaihtoehto on loputon kierto agenteista, jotka tekevät itsevarmoja virheitä, ja ihmisistä, jotka korjaavat ne. Ground truthit katkaisevat tuon kierron tekemällä korjauksista eksplisiittisiä ja pysyviä.

Agenttisi ansaitsevat tietää, mikä on totta. Kerro heille.

Orkestra: tekoälyagenttien orkestrointi laajassa mittakaavassa

Tue, 06 Jan 2026 00:00:00 GMT

Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso tiimisivumme ajantasaiset luvut.

Kun aloimme rakentaa Claude Coden kanssa, törmäsimme ongelmaan, jonka jokainen tekoälykoodausavustimia käyttävä tiimi lopulta kohtaa: yksi agentti ei osaa tehdä kaikkea hyvin.

Voit ohjeistaa agentin olemaan tietokanta-asiantuntija. Tai turvallisuusauditoija. Tai frontend-insinööri. Mutta hetkellä, jolloin pyydät sitä olemaan kaikki kolme samanaikaisesti, laatu kärsii. Konteksti laimenee. Ohjeet ovat ristiriidassa. Agentista tulee yleisosaaja, joka on keskinkertainen kaikessa.

Joten rakensimme Orkestran.

Mikä on Orkestra?

Orkestra on agenttien orkestrointijärjestelmä Claude Codelle ja vastaaville tekoälykoodaustyökaluille. Se koordinoi useita erikoistuneita agentteja, joilla kullakin on omat asiantuntemusalueensa, yhden orkestraattorin alaisuudessa, joka reitittää työn oikealle erikoisosaajalle.

Ajattele sitä henkilöstövuokrausyrityksenä tekoälyagenteille. Orkestraattori vastaanottaa tehtävän, tunnistaa, minkä erikoisosaajan pitäisi käsitellä se, ja delegoi sen oikealla kontekstilla. Kun työ on valmis, tulokset virtaavat takaisin orkestraattorille synteesiä varten.

Luvut kertovat tarinan:

Komponentti	Määrä
Erikoisosaaja-agentit	46
Uudelleenkäytettävät taidot	466
Identiteettiarkkityypit	27
Ajattelutavat	11
Kommunikaatiotyylit	10
Tietämysalueet	21

Hahmojärjestelmä: D&D agenteille

Orkestran ydinoivallus on se, että agentin käyttäytyminen syntyy kolmesta yhdisteltävästä primitiivistä:

Identiteetti määrittelee, mitä agentti on. Arkkitehti suunnittelee järjestelmärakenteita. Debuggaaja jäljittää epäonnistumiset juurisyihin. Vartija valvoo vaatimustenmukaisuutta ja turvallisuusrajoja. Meillä on 27 identiteettiarkkityyppiä, joita voi sekoittaa.

Ajattelutapa määrittelee, miten agentti ajattelee. Analyyttinen ajattelutapa perustaa väitteet todisteisiin ja kvantifioi epävarmuutta. Skeptinen ajattelutapa kyseenalaistaa oletukset ja etsii kumoavaa todistusaineistoa. Tutkiva ajattelutapa omaksuu epäselvyyden ja kokeilee useita lähestymistapoja.

Tyyli määrittelee, miten agentti kommunikoi. Tekninen tyyli sisältää tarkat arvot ja viittaa tiettyihin tiedostoihin. Ytimekäs tyyli karsii täytteen ja aloittaa vastauksesta. Diplomaattinen tyyli tasapainottaa rehellisyyden tahdikkuuden kanssa.

Agentti yhdistää nämä primitiivit:

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

Tämä kokoonpano luo agentin, joka suunnittelee järjestelmiä (arkkitehti), yhdistää tietämystä toimialueiden yli (tietämysarkkitehti), asettaa strategisen suunnan (strategisti), ajattelee todisteina ja datana (analyyttinen) ja kommunikoi ilman täytettä (ytimekäs).

Voima on yhdistelmien räjähdysmäisessä määrässä. 27 identiteettiä kertaa 11 ajattelutapaa kertaa 10 tyyliä tuottaa lähes 3 000 mahdollista agenttipersoonallisuutta. Mutta määrittelet vain ne yhdistelmät, jotka merkitsevät työllesi.

Taidot: uudelleenkäytettävät kyvykkyysmoduulit

Taidot ovat tietämystä ja työnkulkuja, joita agentit voivat kutsua. Ne noudattavat porrastettua järjestelmää laajuuden perusteella:

Taso	Nimi	Laajuus	Esimerkki
K0	Perusta	Universaali metodologia	Testivetoinen kuri, näyttöön perustuva valmistuminen
K1	Identiteetit	Roolipohjaiset työnkulut	CLI-rajapintastandardit, suorituskykykäsikirja
K2	Toimialueet	Toimialuekohtainen tietämys	Tietokannan migraatiomallit, todennuksen validointi
K3	Pinot	Teknologiakohtainen	Cloudflare-käyttöönotto, Supabase-operaatiot
K4	Projekti	Vain tämä koodikanta	Projektikohtaiset työnkulut ja käytännöt

Taidot ladataan laiskasti. Agentti näkee taitojen nimet ja kuvaukset käynnistyksessä, mutta täysi taitosisältö latautuu vasta laukaisuhetkellä. Tämä pitää kontekstin kevyenä ja tekee samalla sadoista taidoista löydettäviä.

Jokainen taito sisältää:

Selkeät laukaisuehdot (“Käytä tietokantaskeemoja migroitaessa”)
Askel askeleelta -ohjeistuksen
Työnkululle sallitut työkalut
Onnistumiskriteerit ja epäonnistumisen palautumispolut

Rekisterimme 466 taitoa kattavat kaiken git-worktree-eristyksestä web-tutkimustyönkulkuihin ja käyttöönoton terveystarkistuksiin.

Miksi orkestrointi merkitsee

Yhden agentin arkkitehtuurit törmäävät seiniin nopeasti:

Kontekstin laimeneminen. 200k tokenin kontekstiikkuna kuulostaa suurelta, kunnes lataat tietokantaskeemoja, API-dokumentaatiota, testifixtureita ja toimialuetietämystä. Erikoisosaajat voivat työskennellä kohdennetulla kontekstilla.

Ohjeiden ristiriidat. Agentin ohjeistaminen olemaan “perusteellinen mutta nopea” ja “tarkista kaikki, mutta älä yliteknisoi” luo jännitteen. Erikoisosaajat ratkaisevat tämän selkeällä laajuudella.

Asiantuntemuksen syvyys. Yleisosaaja-agentti tietää vähän kaikesta. Erikoisosaaja-agentti, oikean identiteetin ja taitojen kanssa koottuna, tuntee toimialueensa syvällisesti.

Orkestra toteuttaa litteän orkestroinnin: yksi orkestraattori koordinoi useita erikoisosaajia. Erikoisosaajat eivät voi synnyttää alaerikoisosaajia. Tämä estää monimutkaisuuden räjähdyksen samalla kun se mahdollistaa rinnakkaisen työn.

Orkestraattorilla on pääsy 2,2 miljoonaan tokeniin tehokasta kapasiteettia: sen oma 200k ikkuna plus 10 samanaikaista alaagenttia, joilla kullakin on 200k. Työ, joka kuluttaisi yhden agentin loppuun, kulkee mukavasti koko laivueen yli.

Renderöintiputki

Agenttimäärittelyt elävät YAML:ssä. Claude Code lukee Markdownia. Orkestra siltaa tämän kuilun deterministisellä renderöintiputkella:

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

Operaattorit muokkaavat YAML-lähdettä. Ajavat orkestra sync:n. Renderöity Markdown ilmestyy kohtaan .claude/agents/. Claude Code ottaa muutokset käyttöön.

Tämä erottelu palvelee eri yleisöjä:

YAML-lähde sisältää elinkaarimetadataa, tageja, validointisääntöjä ja vanhentumishuomautuksia työkaluille
Renderöity Markdown sisältää vain sen, mitä malli tarvitsee: kuvauksen, työkalut, taidot ja käyttäytymisohjeistuksen

Putki kokoaa identiteetit, ajattelutavat, tyylit ja taidot yhdeksi yhtenäiseksi kehotteeksi. Arkkitehti-analyyttinen-ytimekäs-agentti saa hyvin erilaisen järjestelmäkehotteen kuin debuggaaja-skeptinen-tekninen-agentti, vaikka ne jakaisivat joitakin taustalla olevia taitoja.

Toimialuetietämys: neljän tiedoston malli

Jokainen tietämysalue noudattaa yhtenäistä rakennetta:

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

Tämä rakenne palvelee agentin kontekstin lataamista. Todennuksen parissa työskentelevä agentti lataa authentication/patterns.md:n ohjeistusta varten ja authentication/anti-patterns.md:n tunnettujen sudenkuoppien välttämiseksi. Tiedostot on mitoitettu tehokasta kontekstin lataamista varten: tarpeeksi kohdennettuja ollakseen hyödyllisiä, tarpeeksi kattavia ollakseen auktoritatiivisia.

Ylläpidämme 21 ylätason toimialuetta, mukaan lukien analytiikka, todennus, data science, infrastruktuuri, koneoppiminen, suorituskyky, turvallisuus ja muut. Jokaisella toimialueella voi olla alitoimialueita hienojakoisempaa tarkkuutta varten.

Arvot: käyttöjärjestelmä

Kaikki agentit jakavat perusarvokerroksen, joka määrittelee, miten ne toimivat:

Yksinkertaisuus edellä. Käytä yksinkertaisinta ratkaisua, joka toimii. Lisää monimutkaisuutta vain perustellusti.

Korjaa juurisyyt. Älä koskaan tyydy peittämään virheitä. Jos putki epäonnistuu, debuggaa putki. Jos testi epäonnistuu, korjaa koodi tai testi.

Näyttöön perustuva. Merkitse väitteet “varmennetuksi” (vertailuarvoilla) tai “arvioiduksi” (oletuksilla). Havaittu kuvio ei tarkoita vahvistettua ongelmaa.

Kontekstitalous. MCP-työkalut maksavat 0,1 % kontekstista. Tiedostojen lukeminen maksaa 2 % kukin. Sovella toimialueasiantuntemusta ennen koodin tutkimista.

Nämä arvot leviävät jokaiseen erikoisosaajaan renderöintiputken kautta. Agentti ei voi ohittaa niitä kokoonpanon kautta.

CLI: ohjaustaso

Orkestra toimitetaan CLI:llä agenttiekosysteemin hallintaan:

# 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 on totuuden lähde sille, mitä agentteja on olemassa, mitä taitoja niillä on ja onko järjestelmä terve. Se ajaa validoinnin ennen synkronointia ongelmien varhaiseksi kiinni saamiseksi.

Avoimen lähdekoodin näkökohdat

Rakensimme Orkestran ratkaisemaan oman ongelmamme: tekoälyagenttien koordinoinnin laajassa mittakaavassa monimutkaiselle koodikannalle. Löytämämme mallit eivät ole erityisiä toimialueellemme.

Hahmojen kokoonpanojärjestelmä (identiteetti + ajattelutapa + tyyli) soveltuu mille tahansa tiimille, joka määrittelee agenttipersoonallisuuksia.

Taitojen tasojärjestelmä (K0–K4) tarjoaa mentaalisen mallin uudelleenkäytettävien kyvykkyyksien järjestämiseen laajuuden mukaan.

Renderöintiputken malli (YAML-lähde + templatet + generoidut artefaktit) erottaa työkalujen tarvitsemat tiedot mallin käyttämästä sisällöstä.

Litteä orkestrointimalli (yksi koordinaattori, monta erikoisosaajaa) välttää monimutkaisuuden mahdollistaen samalla rinnakkaisuuden.

Tuleeko Orkestrasta avoimen lähdekoodin projekti, riippuu siitä, onko näillä malleilla arvoa muille, jotka rakentavat Claude Coden kanssa. Jos törmäät kuvaamiimme seiniin, arkkitehtuuri saattaa auttaa.

Mitä opimme

Orkestran rakentaminen opetti meille, ettei orkestrointi tarkoita agenttien tekemistä älykkäämmiksi. Se tarkoittaa niiden tekemistä keskittyneemmiksi.

Täydellisilläkin ohjeilla toimivan yksittäisen agentin konteksti loppuu silti kesken. Yksi agentti kaikilla taidoilla silti hämmentyy siitä, mitä soveltaa. Yksi agentti, joka yrittää olla kaikkea, tuottaa keskinkertaisia tuloksia kaikkialla.

Neljäkymmentä erikoisosaajaa, kukin erinomainen toimialueellaan, koordinoituna orkestraattorilla, joka tietää milloin delegoida: näin me toimitamme.

Luvut merkitsevät vähemmän kuin arkkitehtuuri. Saatat tarvita viisi agenttia tai viisikymmentä. Periaate pysyy: kokoonpano kyvykkyyden sijaan, erikoistuminen yleisosaamisen sijaan, koordinointi yksilöllisen sankaruuden sijaan.

Orkestra tehostaa Maguyva-palvelun, koodiälyalustamme, takana olevaa agenttiekosysteemiä. Haluatko tietää lisää? Ota yhteyttä tiimiin.