Maguyva-bloggen

Kontekst som blir med deg

Mon, 07 Sep 2026 00:00:00 GMT

Cursors indekser er utmerket inne i Cursor. Tab-fullføring, inline-redigering, chat, og agenten i det vinduet står allerede på en prosjektindeks Cursor drifter for det åpne arbeidsområdet. Hvis Cursor er den eneste flaten du skriver i, og den indeksen allerede finner de riktige filene, bli der. Det er det ærlige «bli der du er»-tilfellet, og det fortjener å være den første setningen på denne siden.

Denne teksten handler om den andre halvdelen av en vanlig uke. Det samme repoet åpnes også i Claude Code, blir spurt fra Codex CLI, gjennomgått på en annen maskin, eller spurt av en agent som kjører i CI. Spørsmålet er ikke «hvilken indekser er best». Spørsmålet er om kartet agenten stoler på i ett vindu er det samme kartet den stoler på i det neste.

Maguyva er det kartet som blir med deg. Det er et eksternt MCP-lag for kodebase-kontekst. Agenten spør det på samme måte som den spør ethvert annet MCP-verktøy. Resultatene kommer tilbake som rangerte stier med linjenumre. Cursor forblir editoren. Det er konteksten som beveger seg.

Hva Cursors indekser er til for

Cursors innebygde indeksering finnes slik at chat, agent og søk inne i editoren kan hente relevant kode i stedet for å stole bare på det som får plass i modellens rå kontekstvindu. Det er riktig design for en IDE. Denne indeksen er nativ til Cursor. Den er ikke en MCP-server og er ikke tilgjengelig fra noen annen klient.

Slik fungerer det, som beskrevet i Cursors offentlige dokumentasjon og Cursors egen framstilling da dette ble skrevet: hovedsøkeveien er ikke lenger en sky-embeddingindeks. Cursors team har uttalt på fellesskapsforumet sitt at dedikert semantisk/embedding-basert søk trappes ned til fordel for grep-basert henting, fordi dagens modeller allerede utforsker et levende tre godt nok på egen hånd. I stedet kommer Instant Grep, en lokal søkeindeks bygget av n-grammer, inverterte lister og bloomfiltre, holdt i en minnekartlagt oppslagstabell, slik at spørringer løses på utviklerens egen maskin i stedet for på en server.

Selve indeksen bor inne i repoets eget .git/cursor/-katalog, forankret til en bestemt git-commit; endringer siden den commiten legger seg oppå den i stedet for å utløse en ny skanning, og indeksen bygges bare på nytt når den lokale tilstanden har driftet langt fra det den ble bygget mot. Fordi den ligger inne i .git, blir den aldri sporet og aldri pushet — slett mappen, og indeksen er borte. .gitignore respekteres av konstruksjon, siden bare git-sporet innhold er kvalifisert, og .cursorignore håndheves på lesestien. Det finnes ikke lenger noe embedding-steg på serversiden eller ekstern vektordatabase i den stien. Tidligere dokumentasjon beskrev et sky-assistert design — kryptering av chunker, synkronisering via Merkle-tre, gjenbruk av indeks mellom lagmedlemmer — og Cursors eget team har siden sagt at det designet trappes ned, så denne teksten beskriver det ikke lenger som gjeldende.

Et fremtredende trekk inne i editoren er Cursors Explore-subagent. Den kan starte flere parallelle søk i sitt eget kontekstvindu på en raskere modell og bare returnere de relevante funnene, slik at hovedsamtalen ikke svulmer opp av søketreff. Det er en ekte styrke inne i editoren. Behold den.

Arbeidsområder med flere rotmapper støttes: konteksten til hver åpnede mappe er tilgjengelig for Agent. Enkelte git-avhengige funksjoner, som worktrees, er deaktivert i multi-rot-oppsett, og Cloud Agents støtter ikke arbeidsområder med flere rotmapper i det hele tatt.

Ingenting av dette er en grunn til å forlate Cursor. Det er en presis beskrivelse av et kart som er utmerket der det lever.

Hva «bli med deg» faktisk betyr

Et kart blir med deg når de samme spørsmålene returnerer samme type svar, med sitater du kan åpne, fra mer enn én klient.

I Cursor: «Hvor er parseConfig definert, og hvem kaller den?»
I Claude Code, på samme repo: samme spørsmål.
I Codex CLI, på en gjennomgangsmaskin som aldri har åpnet Cursor-vinduet: samme spørsmål.
I en CI-agent som snakker MCP: samme spørsmål, mot det samme hostede øyeblikksbildet.

Hvis hver flate bygger sin egen private indeks, har du ikke ett kart. Du har flere hurtigbuffere som driver fra hverandre. Editorindeksen kan være oppdatert for treet på disk. CLI-sesjonen kan ligge en dag bak. CI-jobben kan se på en annen checkout. Og agenten vil likevel høres selvsikker ut.

Cursors indekser er ikke ment å løse det. Fordi den lever inne i editoren, er konteksten den bygger for den editoren. En leser som også trenger en CLI, en CI-pipeline, eller en annen editor, trenger et eget verktøy for de flatene. Det er et faktum om omfang, ikke en mangel. Maguyva er det egne verktøyet.

Et publisert språkantall for Cursors indekser er ikke oppgitt i materialet denne teksten kan bruke. Maguyva publiserer støtte for over 279 språk og tekstbaserte teknologier. Cursors priser gjengis heller ikke her; se prissiden deres. Maguyva tar betalt per arbeidsområde, ikke per plass, med publiserte planer på $0, $19, $49 og $149 avhengig av indeksert omfang og arbeidsområdets størrelse.

Ett hostet kart, hver MCP-klient

Maguyva er en ekstern MCP-server. Du kobler til GitHub, velger repoene, og sky-pipelinen bygger symboler, grafkanter og et rangert kart. Du legger til en API-nøkkel i MCP-konfigurasjonen til klienten du allerede bruker. Maguyva har oppsettguider for 24 dokumenterte MCP-klienter — inkludert Cursor — og kan koble til andre MCP-kompatible klienter som støtter standardkonfigurasjon.

Cursor-oppsettsiden er den editorspesifikke veien hvis det er der du jobber. Den samme serveren svarer Claude Code, VS Code, Windsurf, Codex CLI og resten. Du bytter ikke editor. Du gir hver agent samme verktøyflate: 11 kundevendte MCP-verktøy på tvers av søk, symboler, avhengighetsanalyse, filhenting, repo-kontekst og deterministiske hjelpeverktøy-arbeidsflyter. Semantisk, strukturell, graf- og tekstsøk smeltes sammen til rangerte resultater.

Det er portabilitetsfordelen. Sitatene du vurderte i Cursor i morges har samme form som sitatene Codex CLI returnerer i kveld. Filsti og linjenummer. Åpne dem. Hvis de er feil, ser du det. Hvis de er riktige, har neste endring et sted å lande. Den godkjente påstanden er færre hallusinerte endringer, ikke et løfte om at hver endring er riktig.

Friskhet er publisert. Øyeblikksbilder er tidsstemplet, slik at agenten vet hvilken versjon av treet den leser. Ombyggingstakten er daglig på gratisplanen og hver time på betalte planer. Den ærlige begrensningen er usynkronisert lokalt arbeid: en endring som bare finnes i et arbeidstre, er ennå ikke i det hostede kartet. Denne begrensningen er den samme uansett hvilken klient du spør fra, og det er nettopp poenget. Drift mellom klienter er ikke lenger en andre, skjult begrensning.

Dokumentasjonen gir aktiveringsløkken som gjelder for hver klient: indekser et repo du allerede kjenner, koble til klienten, still ett spørsmål du kan verifisere. Gjør det én gang i Cursor. Gjør det igjen fra CLI-en du faktisk bruker på gjennomgangsdager. Hvis begge svarene siterer den samme handleren, har kartet faktisk blitt med deg.

Hvordan de to kartene lever side om side

Bruk begge. De er ikke alternativer i sammenligningssideforstand.

Hold Cursors indekser på for prosjektet på disk. La Explore, Instant Grep og agenten inne i editoren bruke den. Den løkken er nativ og rask.
Legg til Maguyva som en MCP-server i Cursor, slik at samme økt også kan spørre det hostede arbeidsområdekartet. Cursor er en dokumentert Maguyva-klient. Du velger ikke én indeks og sletter den andre.
Legg til den samme Maguyva-serveren til Claude Code, Codex CLI, eller en hvilken som helst annen MCP-klient som berører repoet. Én API-nøkkelform. Ett arbeidsområde.
Hvis en CI-agent er MCP-kompatibel, pek den mot den samme serveren. Den vil lese det samme tidsstemplede øyeblikksbildet som laptopen gjorde.

Editorindeksen forblir det beste verktøyet for «hva er på disk i dette vinduet, akkurat nå». Det hostede kartet er det beste verktøyet for «hvordan ser dette arbeidsområdet ut for hver agent som berører det i dag». De setningene konkurrerer ikke.

Arbeidsområdekvoter publiseres på prissiden: repoer, indekserte linjer og brukere, fakturert per arbeidsområde. Agenter og mennesker deler samme brukertall. Start gratis med et repo du allerede kan vurdere. Øk arbeidsområdet først etter at sitatene har overlevd kontakt med treet.

Hva denne siden ikke hevder

Den hevder ikke at Cursors indekser er svak, ufullstendig, eller en grunn til å bytte editor. Den første setningen i denne teksten sier det motsatte.

Den hevder ikke at Maguyva erstatter Instant Grep eller Explore-subagenten. Det er Cursor-funksjoner. De blir værende i Cursor.

Den finner ikke opp et språkantall, et latenstall, eller en token-besparelse for noen av produktene. Ukjente tall forblir upublisert.

Den later ikke som om upushet lokalt arbeid er i det hostede kartet. Tidsstemplede øyeblikksbilder gjør den begrensningen synlig. De fjerner den ikke.

Testen er vanlig. Indekser et repo du allerede kjenner. Still ett spørsmål du kan verifisere, først i Cursor, så i en andre MCP-klient. Kontekst som blir med deg er det samme sitatet på begge steder.

// same map, wherever you opened it.

Kart først, gjennomgang etterpå

Mon, 07 Sep 2026 00:00:00 GMT

To ulike jobber sitter på hver sin side av en pull request. Før agenten skriver, trenger den et kart over treet den er i ferd med å endre. Etter at agenten har åpnet en PR, bør noe lese den endringen mot resten av systemet og legge igjen kommentarer et menneske kan handle på.

Disse jobbene ser like ut på avstand fordi begge involverer «å forstå kodebasen». De er ikke det samme produktet. Den ene svarer på «hvor bør denne endringen lande?». Den andre svarer på «hva ødela dette diffet som en linje-for-linje-linter vil overse?». Å blande dem gir et dårligere førsteutkast og en mer bråkete gjennomgang.

Denne teksten er en guide til en felles arbeidsflyt. Maguyva er kartet agenten spør først. Greptile er gjennomgangsagenten som kommenterer PR-en etterpå. Paret er komplementært av konstruksjon: Maguyva gjennomgår ikke pull requests, og Greptile erstatter ikke kontekstlaget agenten brukte for å skrive dem.

Hvorfor denne oppdelingen er nyttig

En kodende agent som starter fra treningspriorer pluss noen få innlimte filer, vil finne opp en plausibel sti og redigere den. Det er «feil fil»-svikten, og det er et hentingsproblem. Maguyva er et eksternt MCP-lag for kodebase-kontekst: semantisk, strukturell (AST), graf-/avhengighets- og tekstbasert henting smeltes sammen til rangerte resultater, pluss symbolsøk og filhenting. Underbygde svar kommer tilbake som path/file.ext:line, slik at du kan avvise en bom før en patch finnes. Påstanden forblir beskjeden: færre hallusinerte endringer. Modellen kan fortsatt gjette. Det er bare det første steget som slutter å være en gjetning.

Greptile er en AI-kodegjennomgangsagent. I deres egne ord gjennomgår den automatisk hver pull request med full forståelse av kodebasen, og setter det opp mot tradisjonelle lintere som sjekker filer isolert i stedet for hele systemet. Oppsettet består i å installere GitHub- eller GitLab-appen og velge repoer. Det finnes ingen lokal indeks du må drifte. Hosting er Greptile Cloud (de oppgir SOC 2 Type II-samsvar, med en rapport tilgjengelig på forespørsel), med et selvhostet alternativ tilbudt til bedrifter.

Deres egen nummererte flyt er: koble til og bygg en avhengighetsgraf av hver funksjon, klasse og avhengighet; ved hver pull request, analyser endringen ved hjelp av denne fullstendige repo-grafen og publiser funn som PR-kommentarer med foreslåtte rettelser, på omtrent tre minutter; hver kommentar kan overlevere problemet til en kodende agent teamet allerede bruker. De oppgir også at de leser tidligere menneskelige PR-kommentarer over tid for å lære et teams kodestandarder og redusere bråkete forslag. Læringssystemet deres trenger, ifølge dem selv, 2–3 uker for å tilpasse seg.

Det er gjennomgang, ikke utkast. Greptiles fremste styrke er kontekst fra en fullstendig repo-graf på endringen som allerede har landet i en PR, etterfulgt av en lukket løkke som sender funnet til Claude Code, Codex, Conductor, Cursor, eller Devin. Maguyvas fremste styrke er det rangerte kartet agenten spurte før den endringen ble skrevet. Bruk begge. Ikke be noen av dem gjøre den andres jobb.

En førstepartsproduktintegrasjon mellom Maguyva og Greptile er ikke oppgitt. Du trenger heller ikke én. Maguyva snakker med agenten over MCP. Greptile snakker med GitHub eller GitLab gjennom appen sin. De møtes ved pull requesten. Ingen limescript, ingen cron som kobler ett verktøy til det andre. Paret klarer seg uten bash fordi hvert produkt allerede står på flaten det eier.

Hva dette ikke er

Dette er ikke en nedrivning av Greptile. Det er ikke en «bytt anmelder»-side. Greptile lanserte på Hacker News 5. mars 2024 som et Y Combinator W24-selskap, og den tråden er hvordan mange først møtte produktet. Hvis det er slik du fant dem, behold dem. Denne siden er den manglende første halvdelen av den løkken: å forankre agenten på forhånd, slik at PR-en Greptile ser allerede sikter mot de riktige filene.

Greptiles markedsføringsmateriell leder med påstander om gjennomgangshastighet og feilfangst. Behandle dem som Greptiles egne påstander, ikke uavhengig verifiserte tall. Denne teksten gjentar dem ikke som fakta.

Språkdekning er samme type ærlighet. Greptile rammer støtte som dekning av alle programmeringsspråk i stedet for en opplistet liste; et presist tall er ikke oppgitt. Maguyva publiserer støtte for over 279 språk og tekstbaserte teknologier, med en teknisk oppdeling (parserstøttet AST versus bare tekst) på nettsiden når spørsmålet er teknisk. Dette er ulike produkter som kommer med ulike påstander. Ikke bland dem.

Greptiles priser er ikke oppgitt i materialet denne teksten kan bruke. Betalte planer finnes; se prissiden deres. Maguyva tar betalt per arbeidsområde, ikke per plass. Planer starter gratis. Prissiden lister opp de publiserte nivåene hvis du trenger arbeidsområdetallene.

Arbeidsflyt

Tre navngitte trinn. Utfør dem i denne rekkefølgen. Ikke hopp over noen av dem første gang du prøver paret.

1. Maguyva-kontekst

Indekser ett repo du allerede kjenner. Koble til MCP-klienten du allerede skriver i — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, eller en annen MCP-kompatibel klient. Maguyva har oppsettguider for 24 dokumenterte MCP-klienter og kan koble til andre klienter som støtter standard MCP-konfigurasjon.

Still et spørsmål du kan vurdere før noen skriver en linje. «Hvor håndteres øktutløp, og hva kaller det?» er et bedre første trekk enn «fiks auth». Krev sitater. Åpne file.ext:line-resultatene. Følg symbolet. Bekreft avhengigheten du er i ferd med å røre.

Maguyva eksponerer 11 kundevendte MCP-verktøy på tvers av søk, symboler, avhengighetsanalyse, filhenting, repo-kontekst og deterministiske hjelpeverktøy-arbeidsflyter. Fire hentemodi smeltes sammen til rangerte resultater; find_symbol er et eget verktøy når du allerede kjenner navnet. Dokumentasjonen beskriver den korteste veien: start gratis, indekser et repo du allerede kjenner, koble til klienten, still deretter ett spørsmål du kan verifisere.

Øyeblikksbilder er tidsstemplet, slik at agenten kan si hvilken versjon av treet den leser. Den ærlige begrensningen er usynkronisert lokalt arbeid. Hvis endringen bare finnes i et arbeidstre og ikke er pushet, inneholder det hostede kartet den ennå ikke. Instruksjonsfiler (CLAUDE.md, AGENTS.md) hører fortsatt hjemme her, for konvensjoner og hva som ikke skal røres. De er ikke et levende kart. Bruk dem til oppførsel. Bruk Maguyva til fakta.

Ikke la agenten åpne en PR før sitatene overlever kontakt med repoet. Den porten er hele poenget med dette trinnet.

2. Agentens PR

Den samme agenten skriver nå endringen i klienten du allerede betaler for. Maguyva er verken en editor eller en anmelder. Agenten produserer fortsatt diffet. Du åpner fortsatt pull requesten på GitHub eller GitLab slik du allerede gjør.

Det som bør være annerledes, er den første filen. PR-en bør navngi handleren som faktisk implementerer oppførselen, kalleren som vil bryte, og testen som vil feile hvis endringen er feil. Hvis trinn 1 ble hoppet over, vil trinn 3 bruke kommentarene sine på en endring som landet i feil pakke. Greptile kan fortsatt finne systemiske problemer. Den burde ikke i tillegg måtte hente seg inn etter en hallusinert sti.

Hold PR-en avgrenset. En underbygd første fil er ingen lisens til å skrive om modulen. Dette komplementære paret fungerer når agenten gjorde én jobb med et kart, og deretter ba en anmelder gjøre en annen jobb på et avgrenset diff.

3. Greptile-gjennomgang

Greptile er allerede koblet til repoet via GitHub- eller GitLab-appen. På den nye pull requesten analyserer den endringen ved hjelp av den fullstendige repo-grafen den bygde, og publiserer funn som kommentarer med foreslåtte rettelser. Deres eget materiale setter dette passet til omtrent tre minutter.

Les kommentarene slik du ville lest en grundig lagkamerat: åpne det siterte stedet, avgjør om funnet er reelt, og handle deretter. Der Greptile tilbyr «Fix with your Agent», sender den problemet — filstier, linjenumre, foreslått kode — til Claude Code, Codex, Conductor, Cursor, eller Devin. «Fix All» sender alle problemene i gjennomgangen på én gang. De leverer også en Greptile MCP og en Claude Code-plugin for den overleveringen. Maguyva er ikke på den navngitte målisten; det fraværet er ikke et problem. Maguyva har allerede gjort jobben sin i trinn 1. Den kodende agenten som skrev PR-en, er den som bør motta rettelsesnyttelasten.

Forvent støy de første 2–3 ukene mens Greptiles læringssystem tilpasser seg kommentarene teamet ditt faktisk legger igjen. Det er tidslinjen de oppgir, ikke en mangel ved paret. Menneskelig gjennomgang forblir i løkken. Greptile er det automatiserte første passet, ikke sammenslåingsknappen.

Hvis en Greptile-kommentar peker på en fil agenten aldri spurte i trinn 1, er det et nyttig signal. Enten gikk kartet glipp av en kaller, eller agenten hoppet over et sitat. Fiks utkastet i tråd med kommentaren. Ikke deaktiver anmelderen.

Hvordan holde dette komplementet ærlig

Maguyva alltid først. En gjennomgang av en PR med feil fil er fortsatt en gjennomgang av feil fil.
Greptile alltid etterpå. Et godt sitert utkast trenger fortsatt en lesning av diffet på hele systemets nivå.
Ikke be Maguyva publisere PR-kommentarer. Det gjør den ikke.
Ikke be Greptile være agentens første hentelag mens den fortsatt velger sti. Det er ikke jobben GitHub- eller GitLab-appen deres er kablet for.
Ikke finn opp en bash-pipeline som «synkroniserer» dem. PR-en er grensesnittet.
Verifiser begge sider uavhengig. Indekser et repo du allerede kjenner. Still ett spørsmål du kan verifisere. Åpne deretter en liten PR og les hva Greptile faktisk kommenterer.

Løkken er vanlig så snart den får et navn. Kart først. Agentens PR. Gjennomgang etterpå. Hvert produkt blir på den siden av pull requesten det er god på.

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

Gi en AI-agent kontekst om et stort repo uten en lokal indekser

Fri, 14 Aug 2026 00:00:00 GMT

Et stort repo får ikke plass i et kontekstvindu, og hvis du noen gang har pekt en laptop-indekser mot et ekte monorepo, vet du at det heller ikke får komfortabel plass der — RAM-en skyter i været, den første indekseringen tar en time, og agenten din begynner fortsatt neste økt med å gjette hvilke filer som betyr noe.

Det vanlige svaret er å kjøre en indekser ved siden av editoren, og for et repo som får komfortabel plass på én maskin, er det et godt svar. Hvis monorepoet ditt allerede indekseres raskt i Cursor, og det er det eneste stedet du trenger kartet, har denne teksten ikke noe å tilføye — hopp over den.

Denne teksten handler om det andre tilfellet — når en agent trenger et søkbart kart over et stort repo, og du ikke vil kjøre en lokal indekser for å få det.

Når en lokal indekser er feil verktøy

En lokal indeks forutsetter at koden lever på maskinen som spør den, og i reell monorepo-skala strekker denne antagelsen seg selv innenfor én editor. Repoet er rett og slett større enn du vil holde «varmt» på en laptop: du jobber i én pakke mens påvirkningsradiusen ligger tre kataloger unna, og en første kald indeksering av et to-millioners-linjers tre er ikke noe du vil gjennomgå to ganger — verken på din egen maskin, eller på en CI-runner som aldri har klonet treet før. Eller en kollega burde kunne spørre det samme kartet som deg, uten å vente på at deres egen maskin skal kjempe seg gjennom den samme indekseringen.

Ingenting av dette er en grunn til å kaste en god editor-indekser. Det er en grunn til også å ha et hostet kart som hvilken som helst av agentene dine kan spørre over MCP.

Og skalaproblemet går dypere enn «for mange filer å lime inn». På et stort tre er det interessante spørsmålet nesten aldri «vis meg denne filen» — det er hvilken fil, hvilket symbol, hvilke kallere, hvilke tester. En agent som starter med å liste src/ og lese de tre første treffene, vil muntert overse handleren i apps/api og den genererte klienten i packages/sdk. Det du trenger, er henting bygget fra hele treet, deretter rangert, deretter sitert.

Hva «kontekst om et stort repo» faktisk betyr

Å dumpe filer inn i prompten er ikke kontekst — det er en mindre, dårligere kopi av treet. Det agenten din faktisk trenger, er å stille spørsmål og få siterte svar tilbake: hvor dette symbolet er definert og hvem som kaller det, hva som avhenger av modulen jeg er i ferd med å endre, hvilken testfil som dekker denne oppførselen, og hvordan treet ser ut nå, ikke forrige kvartal.

Disse svarene må komme fra en indeks bygget av ditt repo, ikke fra modellens hukommelse om andres repoer, og indeksen må leve et annet sted enn agentens kontekstvindu. For dette problemet bør den også leve et annet sted enn laptopen din.

Enda én ting instruksjonsfiler ikke kan gjøre for deg: CLAUDE.md og AGENTS.md er riktig sted for konvensjoner og oppførsel, men de er ikke et levende, rangert, søkbart kart over et to-millioners-linjers tre. Bruk regler for oppførsel; bruk repo-intelligens for fakta.

Vi bygger kartet i skyen, spør det fra hvilken som helst klient

Maguyva er et eksternt MCP-lag for kodebase-kontekst. Du kobler til GitHub, velger repoene dine, og kan gå din vei mens sky-pipeliner analyserer treet, bygger symboler og grafkanter, og vedlikeholder et rangert kart — aldri en lokal indekser.

Når du pusher kode, analyseres endrede filer inkrementelt, og graf- og rangeringslagene bygges på nytt etter en tidsplan: daglig på gratisplanen, hver time på betalte planer. Hvert øyeblikksbilde er tidsstemplet, slik at agenten din kan si hvilken versjon av treet den leser. Den ærlige begrensningen her er usynkronisert lokalt arbeid — en endring som bare finnes i arbeidstreet ditt, aldri pushet, er ennå ikke i det hostede kartet.

Deretter kobler du til hvilken som helst klient du allerede bruker, ved å legge en API-nøkkel til MCP-konfigurasjonen. Det finnes oppsettguider for 24 dokumenterte MCP-klienter, og enhver annen MCP-kompatibel klient som støtter standardkonfigurasjon kan også koble til. Hvis Cursor er der du bor, følger Cursor-siden den veien; den samme serveren svarer Claude Code, VS Code, Windsurf, Codex CLI og resten.

Du bytter ikke editor. Du gir agenten din en verktøyflate — 11 MCP-verktøy på tvers av søk, symboler, avhengighetsanalyse, filhenting og repo-kontekst — med dekning på tvers av over 279 språk og tekstbaserte teknologier, noe som betyr mer enn du skulle tro på et monorepo som sluttet å være ett språk for mange år siden.

Svar kommer tilbake underbygget, som filstier med linjenumre. Semantisk, strukturell, graf- og tekstsøk smeltes sammen til rangerte resultater, slik at et spørsmål som «hva avhenger av parseConfig» gir deg verken en grep-dump eller ett enkelt semantisk utdrag, men den håndfullen steder som faktisk betyr noe.

En konkret fremgangsmåte

Ikke start med å indeksere hele selskapet. Her er veien som fungerer:

Velg ett repo du allerede kjenner godt — en pakke du kan vurdere for hånd, er verdt mer enn det største treet du har.
Start gratis: 3 repoer, 50k indekserte linjer, alle 11 verktøy, ingen månedlig spørrekvote. Hvis det representative repoet ditt er større, lister prissiden opp arbeidsområdenivåene ($0, $19, $49, $149) etter indeksert omfang — ikke etter antall plasser.
Koble til GitHub og vent til den første indekseringen er ferdig. Du kompilerer ingenting lokalt.
Koble til MCP-klienten — noen få linjer konfigurasjon. Maguyva er en ekstern MCP-server, så det finnes ingen plugins, ingen utvidelser, og ingen andre editor å ta i bruk.
Still ett spørsmål du kan verifisere. «Hva avhenger av parseConfig?» eller «Hvor håndteres utløp av innloggingsøkt?» Åpne deretter de siterte file.ext:line-resultatene og sjekk dem mot treet foran deg.
Først etter at sitatene overlever den kontakten, lar du agenten redigere.

Hvis det første repoet passer bra og treet ditt er stort, øk arbeidsområdet slik at det matcher indekserte linjer og ombyggingstakt. Mennesker og agenter deler samme brukertall — Maguyva tar betalt per arbeidsområde, ikke per plass — så å legge en tredje agent til løkken koster deg ingenting.

Aktiveringstesten er den samme som dokumentasjonen anbefaler for enhver første kjøring: indekser et repo du allerede kjenner, still ett spørsmål du kan verifisere. Et stort repo endrer ikke testen; det gjør bare en feil første fil dyrere.

Hva du bør følge med på etter tilkobling

Hold øye med tre ting. Friskhet: betalte planer bygger på nytt hver time, gratisplaner daglig, og upushet lokalt arbeid vil ikke være i kartet — det er avveiningen du gjør. Omfang: indekser et representativt sett med repoer, ikke hver arkiverte fork; gratisnivået er bevisst dimensjonert for å finne ut om svarene er verdt å beholde. Og verifisering: et kart over et stort repo som ikke kan sitere stier og linjenumre, er bare en tregere gjettemaskin, så la agenten din vise stedet før den leverer patchen.

Kjør deretter den samme testen du ville kjørt på et lite repo. Indekser et repo du allerede kjenner. Still ett spørsmål du kan verifisere. Hvis kartet er ekte, slutter agenten din å starte fra et kaldt tre.

// no laptop got hot building this map.

Hvorfor den AI-kodende agenten din hallusinerer filstier

Fri, 14 Aug 2026 00:00:00 GMT

Tegnet er ikke en feil funksjonskropp. Det er en selvsikker endring i en fil som ikke finnes, eller i en fil som finnes, men som ikke er den som implementerer oppførselen.

Du ba om en fiks for øktutløp. Agenten åpnet src/auth/session.ts. Den stien er plausibel. Den er også feil. Den ekte handleren lever i apps/api/src/middleware/expiry.ts, omdøpt to refaktoreringer tilbake. Agenten løy ikke for deg. Den fullførte en sti-formet streng fra treningspriorer pluss det som allerede var i kontekstvinduet.

Dette er det vanlige feilmønsteret på et ekte repo. Modellen kan skrive kode. Feilen ligger i å velge feil sted å skrive den.

Hvorfor agenter finner opp stier

En kodende agent er en neste-token-modell med verktøy. Når du sier «fiks øktutløp», må den navngi en fil før den kan lese eller patche noe. Hvis den ikke allerede har et forankret kart, konstruerer den en sti fra:

Navnekonvensjoner den har sett i andre repoer. src/auth/session.ts er en vanlig form.
Filer allerede i samtalen, som kanskje er de du limte inn forrige uke, ikke de som betyr noe nå.
Katalogoppføringer den tilfeldigvis kjørte, ufullstendige på et stort tre.
Instruksjonsfiler. CLAUDE.md og AGENTS.md forteller agenten hvordan den skal oppføre seg. De er ikke en levende indeks over symboler, kallere, eller gjeldende stier.

Ingen av disse kildene er et kart over dette repoet, i dag. Modellen fyller hullet på samme måte som den fyller ethvert hull: med en fortsettelse med høy sannsynlighet. Den fortsettelsen ser ofte ut som en ekte sti. Noen ganger finnes filen og ligger ved siden av den riktige. Noen ganger fantes den på en gren som ble slått sammen forrige måned. Noen ganger fantes den aldri.

Grep redder deg ikke her hvis agenten aldri søker etter riktig streng. Agenten gjettet en sti, leste deretter hva den stien returnerte, og redigerte den. Det første feilsteget var stien, ikke patchen.

Å lese filer er heller ikke det samme som å finne de riktige. Claude Code, Cursor, Codex, og lignende verktøy kan åpne hva som helst du peker dem mot. Spørsmålet er om de pålitelig finner de riktige filene, de viktige symbolene, avhengighetene, testene, og påvirkningsradiusen før de redigerer. Filtilgang uten et kart begynner fortsatt med en gjetning.

Redigering av feil fil er et hentingsproblem

Behandle den oppdiktede stien som en henting som bommet, ikke som en personlighetsfeil.

Hvis agenten måtte returnere path/file.ext:line før den fikk lov til å redigere, ville to ting skje. Først kunne du åpne sitatet og avvise arbeidet på ti sekunder. Deretter måtte agenten spørre noe som faktisk kjenner treet.

Det er jobben til et kodebase-kontekstlag. Semantisk søk alene er ikke nok. Et utdrag som «høres ut som øktutløp» kan fortsatt lande i en avviklet pakke. Du trenger også eksakt tekst når du kjenner strengen, symbolsøk når du kjenner navnet, strukturelt søk når du kjenner formen, og en avhengighetsgraf når du trenger kallere og påvirkningsradius.

Maguyva er det laget for MCP-kompatible kodende agenter. Det er ikke en editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, og andre MCP-klienter blir der de er. Agenten spør et rangert kart før den rører en linje.

Påstanden er bevisst beskjeden: færre hallusinerte endringer. Maguyva fjerner ikke modellens evne til å gjette. Den endrer standard første steg fra «finn opp en plausibel sti» til «be om rangerte, siterte steder».

Hvordan et underbygd svar ser ut

Et nyttig svar på «hvor håndteres øktutløp» er ikke et avsnitt. Det er en kort liste over steder:

apps/api/src/middleware/expiry.ts:48 - handleren
apps/web/src/lib/auth-client.ts:112 - kalleren
apps/api/tests/expiry.test.ts:20 - testen som vil feile hvis endringen er feil

Du kan åpne disse linjene. Hvis de er feil, stopper du. Hvis de er riktige, kan agenten redigere. Verifiseringen er poenget, ikke et slagord.

Maguyva eksponerer 11 kundevendte MCP-verktøy på tvers av søk, symboler, avhengighetsanalyse, filhenting, repo-kontekst og deterministiske hjelpeverktøy-arbeidsflyter. Fire hentemodi (semantisk, strukturell, graf/avhengighet, og tekst) smeltes sammen til rangerte resultater; symbolsøk er et eget MCP-verktøy (find_symbol). Underbygde svar kommer tilbake med filstier og linjenumre, slik at du kan vurdere dem mot treet foran deg.

Dokumentasjonen beskriver den korteste veien: start gratis, indekser et repo du allerede kjenner, koble til klienten, still deretter ett spørsmål du kan verifisere.

En løkke som endrer den første endringen

Du trenger ikke en ny arbeidsflytreligion. Du trenger ett ekstra steg før den første skrivingen.

Still et spørsmål du allerede kan vurdere. «Hvilken kode håndterer innlogging og øktutløp?» er bedre enn «fiks auth».
Krev sitater. Filsti og linjenummer, ikke et sammendrag av «auth-modulen».
Åpne de siterte filene. Følg symbolet. Bekreft avhengigheten du er i ferd med å røre.
Først da lar du agenten patche.

Hvis steg 2 ikke returnerer noe nyttig, har ikke agenten lov til å improvisere en sti. Den søker igjen, eller du peker den. Nettopp denne ene porten er det som gir færre hallusinerte endringer. Modellen er den samme modellen. Kartet er det som har endret seg.

Instruksjonsfiler betyr fortsatt noe. Behold dem. Bruk dem til konvensjoner, gjennomgangsregler, og hva som ikke skal røres. Ikke be dem være indeksen. En CLAUDE.md som lister tre viktige kataloger, vil være utdatert uken etter en pakke-splitting. Et søkbart kart oppdateres når repoet oppdateres.

En beslektet svikt er nesten-riktig-filen: agenten åpner auth.ts når oppførselen lever i auth-client.ts, eller patcher en generert fil i stedet for kilden, eller redigerer kopien i packages/legacy fordi navnet stemte. Sitater gjør ikke disse feilene umulige. De gjør dem synlige før diffet lander.

Hva et kart ikke vil fikse for deg

Vær nøktern om hva du får. Et underbygd kart vil ikke gjøre hver endring riktig — agenten din kan fortsatt skrive en dårlig patch i akkurat riktig fil. Hvis kodebasen din lener seg på dynamisk dispatch, refleksjon, eller monkey-patching, vil noen symbolsøk komme tilbake tynnere enn du skulle ønske, fordi det er det kjøretidsindireksjon gjør med enhver statisk indeks. Og hvis du håper på en prosentandel — «hallusinerte stier ned X%» — finner du den ikke her, fordi ingen ærlig kan måle det tallet for repoet ditt bortsett fra deg selv.

Det du kan forvente er smalere og mer nyttig: agenten slutter å åpne endringene sine med en gjettet sti. Det første steget blir forankret i et ekte kart, og det er derfra færre hallusinerte endringer kommer. Alt etter sitatet — å lese diffet, vurdere patchen — er fortsatt jobben din, akkurat som det alltid har vært.

Testen koster deg nesten ingenting: indekser et repo du allerede kjenner og still ett spørsmål du kan verifisere. Start med en sti du har blitt brent av. Hvis sitatene er feil, ser du det umiddelbart. Hvis de er riktige, har agentens neste endring et bedre sted å lande.

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

Hvorfor vi oppgraderte kodesøk til voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Benchmark-tallene i dette innlegget gjenspeiler RTEB-rangeringene ved publisering (juni 2026). Rangeringer endrer seg; behandle dem som et øyeblikksbilde, ikke et permanent faktum.

Semantisk søk er bare så godt som embeddingene under det.

Når en agent spør Maguyva «hvor håndterer vi retries», grepper den ikke etter ordet «retry». Den spør etter meningen — backoff-løkken, circuit breakeren, det som pakker inn et ustabilt kall. Det spørsmålet besvares av en vektormodell som gjør kode om til et punkt i rommet og finner naboene. Velg en bedre modell, og hvert semantiske søk i produktet blir mer presist uten at brukeren merker selve endringen.

Så vi byttet vår. Fra og med juni 2026 kjører Maguyvas kode-embeddinger på voyage-4-large, som erstatter voyage-code-3.

Benchmarken

Vi tok ikke denne avgjørelsen på magefølelse. Den offentlige Retrieval Embedding Benchmark (RTEB) rangerer embedding-modeller på reelle retrieval-oppgaver, og på Code-rangeringen ligger voyage-4-large på 1. plass totalt (90,86) — foran gemini-embedding-2-preview (90,26) og, bemerkelsesverdig nok, foran modellen vi allerede brukte, voyage-code-3 (89,73, 3. plass).

Det er et lite absolutt gap. Men det er et gap i riktig retning, på en offentlig benchmark, på nøyaktig den oppgaven vi bryr oss om: å hente kode etter mening.

Kompromisset vi aksepterer: Binær kvantisering

Her er delen de fleste «vi oppgraderte modellen vår»-innlegg utelater.

Maguyva lagrer ikke fullpresisjonsvektorer. Vi lagrer binært kvantiserte embeddinger: hver 2048-dimensjonale vektor kollapses til en 2048-bits signatur — 256 byte per vektor. Disse signaturene søkes med Hamming-avstand, indeksert og partisjonert per tenant.

Det er et bevisst kompromiss. Binær kvantisering gir opp noe retrieval-presisjon til fordel for dramatisk mindre lagring og raske avstandsberegninger med lav kostnad uten en separat vektordatabase å drifte. For et produkt som indekserer hele repositorier per arbeidsområde, betyr den økonomien mer enn å presse ut den siste brøkdelen av et benchmark-poeng.

voyage-4-large passer inn i dette designet uten å tvinge frem en migrering av lagringslaget: den produserer 2048-dimensjonalt output, akkurat som voyage-code-3, så bit(2048)-kolonnene våre og Hamming-søkestien endret seg ikke. Modellen ble bedre; skjemaet ble stående.

Kode var bare starten

Maguyva er et kodeintelligens-verktøy. Men vi er også vår egen første kunde, og vi peker det mot noe annet: markdown-en som lever i repositoriene våre ved siden av koden. Arkitekturbeslutningsjournaler, runbooks, kontrakter, finans- og policydokumenter — alt versjonskontrollert i Git, alt bak den samme MCP-serveren, en semantisk indeks over dokumentene, ikke bare kildekoden.

Det er nettopp derfor bredden til voyage-4-large betyr noe. På den samme RTEB-familien av rangeringer er den nummer 1 på finans, nummer 1 på helsevesen, og nummer 1 på generell tekstretrieval — foran Googles Gemini Embedding, Coheres Embed v4, og OpenAIs text-embedding-3-large. (Voyage er medskaper av RTEB, så vi leser det som et sterkt offentlig signal snarere enn en perfekt nøytral dommer — men den er sammenlignet direkte med alle de store kommersielle modellene, på private holdout-sett.) Den samme indeksen som finner riktig funksjon for en agent, finner riktig klausul i en kontrakt eller riktig linje i en policy — og på de domenene er ikke voyage-4-large et kompromiss, det er lederen.

Hvorfor vi betaler for premium embeddinger

Det finnes en billigere måte å gjøre søk på, og mye av det er gratis. Leksikalsk søk — BM25 og dets slektninger — matcher nøkkelord, kjører lokalt, og koster ingenting. Embeddingmodeller med åpen kildekode som BGE, Nomic, og embeddinggemma gir faktisk god semantisk retrieval, og du kan selv-hoste dem for prisen av en GPU. Maguyva bruker også den gratis siden: hvert søk fusjonerer tekst-, AST-, graf- og semantisk søk. Det vi ikke sparer på, er det semantiske laget.

Vi betaler per token for premium embeddinger — voyage-4-large — i stedet for å selv-hoste en gratis modell, av to grunner. For det første kan nøkkelordsøk alene ikke svare på «hvor håndterer vi retries» når koden sier backoff og circuit breaker og aldri sier ordet «retry» — mening er hele poenget med embeddingen, og på domenene vi betjener, ligger de åpne modellene bak premiummodellene: et par poeng bak på generell tekst, og enda lenger bak i nisjer som kode, kontrakter, og finans. For det andre former retrieval-kvalitet, etter vår erfaring, det endelige svaret mer enn modellen i den andre enden gjør — en sterk agent som får feil kontekst, svarer fortsatt feil, og den ser aldri dokumentet den aldri ble gitt.

Så premium embeddinger er en per-token-regning som skalerer med hvert repo og dokument vi indekserer — og vi betaler den med vilje. For resultatet brukerne våre får, riktig funksjon eller riktig klausul, mener vi det kompromisset er verdt det.

Den ærlige delen

Voyages egen dokumentasjon merker fortsatt voyage-code-3 som den kodeoptimaliserte modellen. Så hvorfor bytte?

Fordi vi leste den offentlige benchmarken, ikke bare leverandørens modelltabell, og benchmarken satte voyage-4-large på topp for koderetrieval. Dette var en fremtidsrettet avgjørelse: ta den nyere, generelt sterkere modellen og valider den mot en offentlig rangering på oppgavene som betyr noe. Vi er komfortable med å ta det veddemålet fordi bevisene er brede — voyage-4-large vinner ikke bare på kode, den leder også på finans, helsevesen, og generell retrieval.

Det stille fundamentet

Hvert verktøy vi eksponerer — semantisk søk, innsamling av oppgavekontekst, faktabasert Q&A — bunner i retrieval. Når retrieveren forbedres, får agenten i den andre enden bedre bevis, tar færre feilsteg, og forankrer svarene sine i riktig kode — eller riktig klausul, eller riktig policy. En skarpere embeddingmodell er ikke en prangende funksjon. Det er fundamentet under alt annet, og vi har nettopp styrket det. Du vil ikke merke det. Det er poenget.

Rekursiv språkforbedring: Systematisk forbedring av kodeintelligens på tvers av ~280 språk

Tue, 26 May 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (mai 2026). Se teamsiden for gjeldende tall.

Maguyva ekstraherer symboler, referanser og en avhengighetsgraf fra kildekode på rundt 280 språk. Hvert språk er en tilpasset tree-sitter-håndterer — spørringer, heuristikker, edge cases — og hver håndterer kan være subtilt feil på sin egen måte. Et metodekall utstedt som en lesing. En funksjon tilskrevet feil omsluttende scope. En relasjon som rett og slett ikke finnes.

Det kan du ikke manuelt revidere. Ingen team kan lese ekstraksjonsresultater på tvers av 280 grammatikker og fange opp de dårlige kantene (edges). Så det interessante spørsmålet er ikke «er ekstraksjonen vår korrekt» — det er «hvordan finner du ut at den er feil, i denne bredden, uten et menneske i hver løkke». Svaret vårt er rekursiv selvforbedring for språk: en kvalitetsløkke drevet av språkagenter, en LLM som fungerer som dommer, og én regel vi stadig lærer på nytt: grønn er ikke det samme som korrekt.

Grønn er ikke korrekt

Hvert språk har en fixture-suite, og en utgivelsesport (release gate) scorer den langs fem dimensjoner — nøyaktighet, strukturell integritet, fullstendighet, kvalitet og ytelse. Et språk blir GRØNT bare når, på sine fixtures, presisjon ≥ 0,95, recall ≥ 0,99, og F1 ≥ 0,97, med minst 20 forventede edges for statistisk pålitelighet. Under det er det GULT eller RØDT, og det shippes ikke.

Den porten er nødvendig, men ikke tilstrekkelig. Fixtures valideres mot fixtures vi selv skrev. De koder for tilfellene vi allerede har tenkt på. En håndterer kan være feilfri på sine fixtures og likevel ødelegge et mønster som bare dukker opp i ekte kode — et makro-idiom, en metode med begrensninger på generiske typer, en språkfunksjon ingen skrev en fixture for. GRØNT betyr at fixturene passerer. Det betyr ikke at et ekte repository ekstraheres rent. Så løkken må forlate fixturene og undersøke virkelige kodebaser.

Den indre løkken: stikkprøve, dømme, fikse, bevise

Kjerneløkken kjører ett språk om gangen:

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

Noen ting gjør at dette fungerer i stedet for å tråkke vann.

Dommeren er agenten, ikke et API-kall. Når vi sier «LLM som dommer», mener vi at selve språkagenten leser hver samplede edge mot den ekte kildekoden og klassifiserer den med et fast vurderingsskjema med fem kategorier: er denne edgen korrekt, et falskt positivt funn, riktig relasjon med feil type, festet til feil scope, eller bærer den feil metadata? Det vurderingsskjemaet er avgjørende — «23 % feilrate» er meningsløst inntil du vet om det er ekte defekter eller dommeren som teller feil.

Fiks én ting, bevis den så. Hver iterasjon endrer nøyaktig én redigerbar ressurs, kjører deretter på nytt mot en fast test-rigg, og beholder endringen bare hvis F1 forbedres og den nye klassifiseringen ser bedre ut. Hvis ikke, rulles den tilbake. Ingen bunke med spekulative endringer, ingen «burde bli bedre». En endring må fortjene plassen sin, ellers fjernes den. Og når en fiks holder, blir den forfremmet inn i fixture-suiten — slik at feilen den fikset aldri kan komme snikende tilbake. Det forfremmelsestrinnet er det som gjør løkken rekursiv snarere enn bare repeterende: hver runde styrker referansegrunnlaget som neste runde valideres mot.

Lærdommen vi stadig lærer på nytt: metrikker overrapporterer

Her er fellen, og vi gikk rett i den. De sekundære korpusmetrikkene — hvor ofte et ekstrahert mål mangler et løsbart symbol, hvor mange symboler som ser «foreldreløse» ut, og så videre — overrapporterer problemer massivt. De er for det meste utslag av språkets programmeringsmodell, ikke feil.

Det klareste eksempelet: llvm viste en gang en 73 % «kilde-uten-symbol»-rate og ble stemplet som katastrofalt. Vi gravde i det. Reell nøyaktighet var 98,5 %. De «manglende symbolene» var nesten alle legitime eksterne referanser — kall inn i standardbiblioteket, inn i rammeverk, inn i kode som lever utenfor repoet. Metrikken målte en egenskap ved språket, ikke en defekt i håndtereren. Språk som Zig, COBOL og Odin viser 65–70 % «foreldreløs»-rate og er helt korrekte; COBOL hadde null reelle feil.

Hvis vi hadde latt de tallene styre arbeidet, ville vi ha brukt uker på å «fikse» håndterere som allerede var riktige og ignorert språkene med stille, ekte feil. Konklusjonen er brutal: de aggregerte metrikkene er i beste fall et grovt triage-signal. Det ekte kvalitetssignalet er stikkprøven med edge-klassifisering — å se på faktiske edges i faktiske repositorier og dømme dem én for én. Data foran intuisjon, men bare når du vet hvilke data som forteller sannheten.

Den ytre løkken: en flåte, ikke et maraton

Ett språk om gangen ville tatt evigheter på tvers av 280 av dem, så den indre løkken er pakket inn i en ytre løkke som kjører mange parallelt.

   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

Hver agent jobber i et engangs-worktree slik at de ikke kan tråkke i hverandres bed. Orkestratoren integrerer fiksene deres én om gangen, hver bak en full-manifest regresjonssjekk: en endring som hjelper sitt eget språk, men stille ødelegger tre andre, lander ikke. Integrasjonen kontrolleres og bekreftes før noe pushes — regresjonsporten avgjør hva som er trygt, et menneske avgjør fortsatt hva som shippes. Deretter roterer poolen til neste sett med språk, og hele greia kjører igjen.

Hva som fortsatt er ufullkomment

Dommeren kan ta feil, og feilen har en retning: en agent som kjører med for lite kontekst, overrapporterer. I én batch ble åtte språk flagget med 5–20 % feil; ved nærmere ettersyn hadde bare ett språk en reell språkspesifikk feil — resten var dommerfeil fra å gå glipp av språkets egen semantikk (én kildekodelinje som legitimt sender ut flere edges, parameterbindinger modellert som tilordninger, referanse-per-identifikator-språk). Det er derfor vi sampler med to seeds og krysssjekker, og hvorfor en uenighet mellom dommeren og fixturene behandles som det mest interessante signalet, ikke en avgjort dom — noen ganger er det fixturen som er feil.

Vi er også ærlige om målet. Målet er null reelle feil, punktum — men «null» er en retning vi arbeider oss mot, språk for språk, ikke en boks som krysses av. Det finnes alltid et nytt repo med et nytt idiom.

Fortjent, ikke påstått

Alt Maguyva gjør for en agent — å finne et symbol, spore en avhengighet, svare på et spørsmål med sitert kode — hviler på at ekstraksjonen under er riktig. På tvers av 280 språk kan «riktig» ikke påstås; det må kontinuerlig fortjenes mot ekte kode. Løkken er hvordan vi fortjener det: en autonom stikkprøve-og-fiks-syklus som behandler sine egne metrikker med mistenksomhet, beviser hver endring, og gjør hver fiks til en vakt mot neste regresjon. Det er ikke glamorøst. Det er arbeidet som lar oss si «vi støtter språket ditt» og mene det. Grønt er lett. Korrekt er fortjent.

Multimodalt fusjonssøk: Velge riktig retriever for hvert søk

Wed, 15 Apr 2026 00:00:00 GMT

Merknad om historisk design: Denne artikkelen fra april 2026 beskriver rutingsdesignet på den tiden, ikke dagens standardatferd. Rettelsen fra september nedenfor gjelder bare en målepåstand. Se Slik fungerer det for gjeldende ruting, forhåndsinnstillinger og eksplisitte modalitetsvalg.

Et søk er ikke bare én ting.

«hvor er parseConfig definert» vil ha et eksakt symbol — ett presist sted, raskt. «hvordan fungerer autentisering» vil ha mening — spredningen av relatert kode som forklarer et konsept. «hva ryker hvis jeg endrer denne funksjonen» vil ha avhengighetsgrafen. «finn strengen ECONNREFUSED» vil ha et bokstavelig treff, ikke noe smart.

Grep er utmerket for bokstavelige treff og nyttig for enkelte referansejakter, men det er ikke en avhengighetsgraf, og det forstår ikke mening. Embeddinger dekker den semantiske siden, men de er feil verktøy for eksakte strenger og konsekvensanalyse. De fleste kodesøkverktøy velger én motor og lar hvert søk leve med det valget. Maguyva låser seg ikke til én motor. Det finner ut hva slags spørsmål du stilte, og blander deretter fire retrievere i den andelen spørsmålet fortjener.

Fire modaliteter

Under panseret finnes det fire uavhengige måter å finne kode på:

semantisk — vektorsøk over Voyage binære embeddinger; finner kode etter mening.
tekst — trigram-matching; finner literaler, feilstrenger, eksakte identifikatorer.
strukturelt — AST-spørringer; finner definisjoner, signaturer og språkkonstruksjoner.
graf — avhengighetsgrafen; finner kallere, kalte, og påvirkningsradiusen.

Hver er sterk på en annen klasse spørsmål. Trikset er å avgjøre hvor mye man skal stole på hver enkelt for søket foran deg.

Intensjonsklassifisering

Før noen retrieval kjører, sorterer en lettvekts-klassifiserer søket inn i én av seks intensjoner, med en konfidensscore. Den er bevisst billig — ordnede heuristikker, første treff vinner — fordi den kjører på den kritiske stien og bare legger til ett eller to millisekunder:

starter med def , class , func , import … → find_definition (konfidens 0,95)
«who calls», «usages of», «references to» → find_references (0,90)
«impact», «blast radius», «what depends on» → impact_analysis (0,90)
en streng i anførselstegn som "string" eller et feiltoken som traceback → exact_match (0,85–0,90)
en CamelCase- eller snake_case-identifikator → find_definition (0,60–0,80)
«how», «why», «explain», «architecture» → understand_code (0,75)
ingenting matcher → understand_code, lav konfidens (0,40)

Hver intensjon har en vektprofil på tvers av de fire modalitetene. Dette er de reelle tallene:

Intensjon	semantisk	tekst	strukturelt (AST)	graf
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

Så «hvor er parseConfig definert» lener seg tungt på AST (0,6). «hvordan fungerer autentisering» lener seg på semantiske vektorer (0,5). «hva avhenger av dette» er nesten bare graf (0,7). «finn ECONNREFUSED» er nesten bare trigram (0,9), med embedding-modellen helt slått av — fordi semantisk likhet er akkurat feil verktøy for en eksakt streng.

Hurtigstien, og den fusjonerte stien

Når klassifiseringen er sikker — score ≥ 0,85 — og søket har en vanlig form, hopper Maguyva over fusjon helt og ruter rett til den ene dominerende modaliteten. «hvor er X definert» trenger ikke fire retrievere; det trenger AST-indeksen, nå. Den direkte stien rapporteres tilbake som fusion_strategy: "direct".

Alt som er tvetydig går gjennom fusjon. De fire (eller tre, på standardoppsettet) modalitetene kjører parallelt, hver returnerer sin egen rangerte liste, og vi kombinerer dem.

Vektet Reciprocal Rank Fusion

Å fusjonere heterogene retrievere er vanskeligere enn det høres ut som: en kosinuslikhet på 0,82 og en trigram-score på 137 og en graf-sentralitet på 0,004 er ikke på samme skala, så du kan ikke bare legge dem sammen. Reciprocal Rank Fusion omgår problemet ved å kaste bort de rå scorene og bare beholde rangeringen hver motor tildelte. Et resultats bidrag fra én modalitet er:

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

hvor rank er dets posisjon i den modalitetens liste, og k er en utjevningskonstant. Bidrag summeres på tvers av modaliteter for ethvert resultat som mer enn én motor fant — enighet mellom retrievere flyter naturlig til toppen. Vi bruker k = 40 på standardoppsettet og 60 på thorough (quick kjører kun semantisk, så fusjon utløses aldri der). Det originale RRF-arbeidet landet på k = 60 for generell retrieval; standardverdien vår gir litt mer vekt til resultater som flere modaliteter plasserer høyt — og vi anbefaler ikke å håndjustere den.

I tillegg får resultater en graf-viktighetsboost. Et knutepunkt — en funksjon hele kodebasen lener seg på — bør rangere høyere enn en lite kjent bladnode selv ved samme tekstlige relevans, så vi multipliserer hvert bidrag med:

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

Sentraliteten kommer fra pipelinens forhåndsberegnede PageRank/grad-metrikker, og boosten er begrenset til 1,5× slik at en populær funksjon ikke helt kan begrave en mer relevant, men lite kjent funksjon. Til slutt nedgraderer vi resultater fra vendor-, build- og arkivstier, og fjerner duplikater slik at kun det beste utdraget per fil beholdes.

Hva som fortsatt er ufullkomment

Intensjonsklassifikatoren er en samling regex-er, ikke en trent modell. Den håndterer vanlige spørringsformer med heuristikker, og en tvetydig spørring faller tilbake til understand_code og en semantisk orientert blanding. En tidligere versjon av dette innlegget beskrev en reduksjon i andelen søk uten resultater fra omtrent 15 % til under 5 % som oppnådd. Forslaget fra desember 2025 oppga i virkeligheten et estimert utgangspunkt og et mål; det er ikke lagt frem noe støttende spørresett eller noen målerapport. Vi trekker tilbake påstanden om at denne forbedringen var oppnådd; se kildedokumentasjonen og rettelsen. Vi har ikke erstattet klassifikatoren med en trent modell fordi den billige versjonen er rask og god nok for den tiltenkte rutingsrollen, og fordi en selvsikker klassifikator som tar feil, er verre enn en ærlig fallback. Vektene er i seg selv manuelt valgte priorer, ikke lært fra klikkdata vi ikke samler inn.

Still spørsmålet uten å velge verktøy

En agent burde ikke måtte vite om den skal gripe til grep eller embeddinger eller kallgrafen — den burde stille spørsmålet sitt med enkle ord og få riktig svar. Multimodal fusjon er det som lar find_symbol, semantisk søk og avhengighetsanalyse sitte bak ett søkegrensesnitt: systemet leser formen på spørsmålet og setter stille sammen riktig retriever for det. Modellen som scorer embeddingene betyr noe, men det gjør også det å vite når man ikke skal bruke dem. Å velge riktig verktøy for hvert søk er sin egen type kvalitet, og det er en vi heller vil eie selv enn å skyve over på den som kaller.

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

Agentobservabilitet: Hooks, Alloy og Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agentsystemer feiler på merkelige måter.

Noen ganger er modellen problemet. Noen ganger er verktøyet problemet. Noen ganger er MCP-serveren din helt fin, men agenten valgte feil spesialist, eller brukte halve økten på shell-arbeid du ikke forventet, eller brukte opp budsjett i det stille i en løkke som så produktiv ut utenfra.

Hvis du ikke kan se forskjellen, driver du ikke egentlig et agentsystem. Du gjetter.

Så vi bygde en observability-stack for vår egen arbeidsflyt: Claude Code, Codex, Claude hook-hendelser, Codex notify-hendelser, native OpenTelemetry, Grafana Alloy, og Grafana Cloud i den andre enden.

Det interessante er ikke «vi laget et dashbord». Det interessante er at vi måtte dele telemetrien i to forskjellige strømmer fordi ingen enkelt kilde ga oss hele bildet.

Problemet: Agenttelemetri er fragmentert

Moderne kodeagenter sender allerede noe telemetri. Det hjelper, men det er ikke nok.

Native OTEL er god til å svare på spørsmål som:

Hvor mange forespørsler gjorde vi?
Hvor mye kostet en økt?
Hvor er spanene og sporene (traces)?
Var det en latenstopp?

Den er mye dårligere til å svare på spørsmål som:

Hvilken MCP-server lente agenten seg på?
Skjedde denne feilen i Bash, et innebygd filverktøy, eller et MCP-kall?
Hvilken skill ble faktisk aktivert?
Hvilken subagent-type ble dispatchet?
Gjorde økten nyttig arbeid, eller bare tråkket den på stedet?

Den andre klassen spørsmål hører hjemme nærmere hooks enn spor.

Men det motsatte er også sant: noen av de viktigste ytelsesspørsmålene hører hjemme nærmere spor enn hooks.

Hvis du vil vite hvor latensen faktisk hopet seg opp, hvilke spans som var trege, eller om økten brukte tid på modellkall versus verktøyutførelse, trenger du sporingsdata i tillegg til semantiske hendelser.

Arkitekturen vi endte opp med

Vi kjører to telemetriløyper side om side.

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

Den delingen er bevisst.

Den er også asymmetrisk. Claude Code gir oss et mye rikere hook-grensesnitt gjennom livssyklusen. Codex gir oss native OTEL pluss et notify-grensesnitt, så vi normaliserer hendelser med færre detaljer om avsluttede samtalerunder inn i det samme loggskjemaet i stedet for å late som om begge runtimene eksponerer de samme kontrollene.

Native OTEL gir oss basisstrømmen: logger og spor fra selve runtimen, pluss metrikker der runtimen faktisk sender dem.

Hook- og notify-hendelser gir oss det semantiske laget: ting som PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, og de klassifiserte metadataene vi faktisk bryr oss om når vi feilsøker agentatferd. Claude Code bidrar med den rikere hendelsesstrømmen her. Codex bidrar med en normalisert strøm med færre detaljer, men som fortsatt er nyttig.

Hvorfor hooks i det hele tatt finnes

Hook-pipelinen vår beriker hendelser før de treffer Loki.

I stedet for bare å si «et verktøy kjørte», klassifiserer vi hendelsen i felt som:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: hvilken MCP-backend som håndterte kallet
bash_cli: shell-kommandofamilien
subagent_type: hva slags spesialist som ble dispatchet
agent_tool: om kilden var Claude Code eller Codex

Det betyr at vi kan stille spørsmål som betyr noe operasjonelt:

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

Dette er ikke pyntefelt. De er forskjellen mellom «agenten føltes treg» og «agenten brukte de siste ti minuttene på shell-tunge git-operasjoner med høy feilrate på verktøy».

En implementasjonsdetalj som ser merkeligere ut enn den er: den delte Loki-strømmen bruker fortsatt service_name="claude-code-hooks" som etikett selv når hendelsen kom fra Codex. Den reelle skillelinjen mellom runtimene skjer på agent_tool.

Hvorfor Alloy sitter i midten

Grafana Alloy er ikke bare en videresender i dette oppsettet. Det er policygrensen.

Vi peker den native OTEL-strømmen fra Claude Code og Codex mot en lokal Alloy-proxy på localhost:4318, og lar deretter Alloy rydde opp i nyttelasten før den videresendes til Grafana Cloud.

Det betyr noe fordi rå agenttelemetri er full av felt med høy kardinalitet som er nyttige for analyse, men forferdelige som indekserte etiketter:

session_id
prompt_id
antall tokens
varigheter
verktøyparameter-blobber

Hvis du indekserer alt, får du en eksplosjon i antall etiketter og driftsproblemer.

Så Alloy gjør tre ting for oss:

Holder et svært lite sett med lav-kardinalitets-etiketter indeksert.
Flytter støyende, men nyttige felt inn i strukturerte metadata.
Dropper ren støy helt.

Den viktige ideen er enkel: observer mer, indekser mindre.

Hvorfor hook-strømmen går utenom Alloy

Hook-strømmen er allerede formet for Loki.

Når send_event.py pusher en hendelse, har vi allerede bestemt hvilke felt som fortjener etikettbehandling og hvilke som hører hjemme i den strukturerte JSON-kroppen. Den strømmen går rett til Grafana Clouds OTLP-gateway i stedet for å gå gjennom Alloy en gang til.

Så systemet har en klar arbeidsdeling:

Alloy temmer den rå native OTEL-strømmen.
Hook-berikelse gjør semantiske hendelser søkbare.

Det holder arkitekturen enklere enn å prøve å tvinge alt gjennom én sti.

Hva dashbordet faktisk viser

Skjermbildet under er fra ett av observability-dashbordene bak agentarbeidsflyten vår. Det er ikke en benchmark, og tallene er bare et øyeblikksbilde. Poenget er formen på dataene: aktivitetsstrøm, verktøykall, feil, prompter, og oppdelinger etter agent, innebygde verktøy, MCP-bruk, shell-kommandoer og skills.

Det nyttige er at dette dashbordet lever på samme Grafana-stack som resten av agenttelemetrien. Vi kan filtrere etter kildeagent og verktøyfamilie og se på tvers av runtimer uten å finne opp en egen observability-historie for hvert system.

Ett av de aktive dashbordene bak agentarbeidsflyten vår. Dette skjermbildet er bare ett øyeblikksbilde av en delt Grafana-stack som også mottar telemetri fra våre andre agent-runtimer og systemer. Klikk på bildet for versjonen i full oppløsning.

Hvorfor spor betyr mer enn man først skulle tro

Logger forteller oss hvilken kategori arbeid som skjedde. Spor forteller oss hvordan arbeidet utfoldet seg over tid.

Det skillet betyr noe i agentsystemer fordi «treg» er for grovt til å være nyttig.

Et spor kan fortelle oss om problemet kom fra:

modell-latens
verktøyutførelsestid
gjentatte forsøk (retries)
én spesielt kostbar MCP-interaksjon
en lang hale av små operasjoner som virket ufarlige hver for seg

I praksis bruker vi hook-strømmen og Tempo-spor sammen.

Hook-logger svarer på: hva slags ting skjedde?
Spor svarer på: hvor gikk tiden?

Kombinasjonen er det som gjør observability om fra et dashbord til en forklaring.

Hvor Codex passer inn

Codex er en del av samme stack, men er ikke identisk med Claude Code.

For Codex kobler vi to deler:

Native OTEL fra Codex inn i Alloy
En notify-webhook inn i codex_notify.py, som mapper fullførte samtalerunder til det samme Loki-skjemaet vi bruker for hook-hendelser

Det gir oss et samlet filter som agent_tool="codex-cli" i den samme loggstrømmen.

Det ærlige forbeholdet: Codex sin notify-nyttelast inneholder for øyeblikket færre detaljer enn Claude Codes hook-nyttelast, fordi det ikke er samme type integrasjonsgrensesnitt. I oppsettet vårt i dag kan fullførte samtalerunder i Codex normaliseres inn i det delte skjemaet, men rik uttrekking verktøy for verktøy er fortsatt bedre i den native OTEL-strømmen enn i notify-broen.

Vi bruker ikke denne begrensningen som en unnskyldning. Det er poenget med innlegget. Ekte observability-systemer er satt sammen av ufullkomne signaler.

Grafana over MCP endrer spillet

Det større skiftet er at Grafana ikke bare er et sted mennesker besøker i en nettleser.

I dette repoet eksponerer vi også Grafana gjennom MCP. Det betyr at en agent kan spørre Loki, Prometheus og Tempo direkte, i stedet for å vente på at et menneske manuelt skal inspisere dashbordene først.

Det gjør observability til et aktivt input til arbeidsflyten.

En agent kan spørre:

Hvilke verktøyfamilier feilet mest den siste timen?
Hvilken MCP-server dominerte en økt?
Reduserte nylige endringer verktøyfeil, eller flyttet de bare arbeidet inn i mer shell-tunge stier med de samme feilene?
Hvilke spor viser høyest latens eller gjentatte forsøk?

Når du har det, er du veldig nær en selvforbedringsløkke.

Fra dashbord til tilbakemeldingsløkke

Dette er delen vi synes er mest interessant.

Når observability-stacken er søkbar fra agentlaget, slutter telemetri å være et passivt rapporteringsverktøy og blir et kontrollsignal.

Løkken ser slik ut:

Agentaktivitet sender ut spor, metrikker og berikede hook-logger.
Grafana lagrer bevisene i Loki, Tempo og Prometheus der metrikker finnes.
Agenter søker i denne dokumentasjonen gjennom Grafana MCP.
Systemet identifiserer dårlig verktøymiks, skjøre skills, svak ruting, eller shell-tunge arbeidsflyter som fortsetter å produsere unngåelige feil.
Agenter eller operatører justerer prompter, agentkonfigurasjoner, skill-beskrivelser, rutingregler, eller verktøytilgang.
Neste økt produserer en ny telemetriform, og syklusen gjentar seg.

Det er slik du beveger deg fra «interessant dashbord» til «målbart forbedringssystem».

Målet er ikke å maksimere én verktøykategori. Det er å lande på riktig miks av CLI, innebygde verktøy, MCP-kall og skills for arbeidet som faktisk gjøres.

Hva dette lar oss svare på

Når begge runtimene lander i samme Grafana-stack, kan vi svare på operasjonelle spørsmål mye raskere:

Er feilene konsentrert i én verktøyfamilie?
Skaper shell-tunge arbeidsflyter unngåelige feil der et verktøy på høyere nivå burde finnes?
Hvilke MCP-servere bærer arbeidsmengden?
Betaler vi for agentaktivitet som ikke gir meningsfull fremgang?
Er en økt usunn på grunn av modellen, verktøyene, eller orkestreringslaget?

Dette er spesielt nyttig i multi-agent-arbeidsflyter, der «agenten var opptatt» nesten ikke forteller deg noe.

Hvis én spesialist stadig blir dispatchet og produserer høye feilrater, er det et rutings- eller promptformingsproblem.

Hvis én MCP-server dominerer alle kall, kan det være god arkitektur eller et tegn på at alt annet er dødvekt.

Hvis antallet verktøyfeil skyter i været mens kostnaden holder seg høy, har du et operasjonelt problem, ikke et kvalitetsproblem.

Hvis shell-arbeid fortsetter å feile på forutsigbare, unngåelige måter der et verktøy på høyere nivå burde finnes, er det et produktsignal.

Hvis én skill aktiveres konstant, men ikke forbedrer resultatene, er det et prompt- eller rutingsignal.

Den egentlige lærdommen

Den dypere lærdommen her er at agentobservability trenger både runtime-telemetri og arbeidsflyt-telemetri.

Runtime-telemetri forteller deg hva systemet gjorde.

Arbeidsflyt-telemetri forteller deg hva agenten trodde den holdt på med.

Vi trenger begge deler.

Hvis du bare beholder spor og tellere, går du glipp av det semantiske laget. Hvis du bare beholder hook-hendelser, går du glipp av latens, spans, og det bredere runtime-bildet.

Og hvis du beholder begge, men aldri mater dem tilbake til agentlaget, har du overvåking, ikke tilpasning.

Kombinasjonen er det som gjør systemet forklarlig nok til å drifte og justerbart nok til å forbedre.

Hva som fortsatt er ufullkomment

Det finnes fortsatt forbedringspunkter.

Ikke alle hook-hendelser inneholder varighets- og token-dataene vi skulle ønske.
Noen av de beste tidsvisningene kommer fortsatt fra Tempo-spor, ikke hook-loggene.
Codex er i dag mindre semantisk rikt enn Claude Code i den berikede hendelsesstrømmen.
Dashbord-skjermbildet er en skjerm som brukes i den faktiske driften, ikke et polert markedsføringsprodukt.

Det siste punktet er bevisst. Vi vil heller vise det virkelige instrumentpanelet enn å late som om agentsystemer er magisk selvforklarende.

Hvorfor dette betyr noe for Maguyva

Maguyva handler om å gi agenter bedre kodeintelligens. Men når agenter faktisk gjør nyttig arbeid, dukker det umiddelbart opp et nytt krav: du må se hvordan de oppfører seg.

Søkekvalitet, rutingkvalitet, verktøyvalg og konteksteffektivitet blir alle observerbare problemer.

Det er derfor vi mener dette er verdt å skrive om. Den fremtidige agent-stacken er ikke bare prompter og verktøy. Det er prompter, verktøy, og instrumenteringslaget som forteller deg om det hele fungerer.

Hvis du bygger seriøse agentarbeidsflyter, er observability ikke valgfri infrastruktur. Det er en del av produktet.

Mining som lukker løkken: Hvordan endringer blir institusjonell hukommelse

Tue, 03 Feb 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (februar 2026). Se teamsiden for gjeldende tall.

Hvert ingeniørteam møter den samme utfordringen: endringer skjer hele tiden, men hvorfor-et bak de endringene forsvinner. Seks måneder senere spør noen «hvorfor tok vi i bruk DuckDB for pipeline-stadier?», og svaret finnes bare i hodet til den som tok den avgjørelsen — hvis de fortsatt er der.

Vi bygde en mining-arbeidsflyt som lukker denne løkken. Endringer flyter gjennom git-commits, prosesseres av mining-pipelinen vår, blir strukturerte endringslogg-oppføringer og arkitekturbeslutningsjournaler, og mates deretter tilbake til AI-agentene våre gjennom CLI-spørringer. Resultatet: institusjonell hukommelse som både mennesker og AI kan få tilgang til.

Problemet: Beslutninger fordamper

Se for deg et typisk scenario. En utvikler committer:

feat(canonical): add DuckDB runtime for pipeline stages

Denne commiten representerer et betydelig arkitekturvalg. Teamet vurderte alternativer, vurderte avveininger, og landet på DuckDB av spesifikke grunner. Men all den konteksten lever i:

En Slack-tråd (sannsynligvis slettet)
Noens hukommelse (definitivt falmende)
En kommentar i koden (kanskje, hvis du er heldig)

Tre måneder senere spør et nytt teammedlem: «Bør jeg bruke DuckDB eller SQLite for dette nye stadiet?» Uten institusjonell hukommelse finner de enten opp hjulet på nytt eller tar inkonsistente valg.

Løkken: Fra commits til kontekst

Mining-arbeidsflyten vår omdanner git-historikk til søkbar kunnskap:

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

Kjerneinnsikten: både endringslogger og arkitekturbeslutninger flyter fra den samme git-historikken, prosessert gjennom en samlet pipeline. Dette sikrer at ingenting faller mellom to stoler.

Hvordan mining fungerer

Steg 1: Synkroniser indeksen

uv run orkestra mine sync

Denne kommandoen skanner git-historikken og bygger en indeks over alle commits. Den ekstraherer strukturerte signaler fra hver commit:

Konvensjonell commit-type (feat, fix, chore, docs)
Scope (hvilken pakke eller hvilket område)
Markører for brytende endringer
Berørte filer og kompleksitetsmetrikker

Steg 2: Sjekk dekningsstatus

uv run orkestra mine status

Slik ser vår nåværende status ut:

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 commits prosessert. 476 ble arkitekturbeslutninger. 6 799 ble endringslogg-oppføringer. Hver eneste commit klassifisert.

Steg 3: Hent kandidater for gjennomgang

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

Dette henter frem commits som ennå ikke er behandlet, med full kontekst for klassifisering:

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

Signalene hjelper til å veilede klassifiseringen: is_releasable_type: true antyder at denne bør vises i endringsloggen. Det store antallet innsettinger og infrastrukturfilene antyder at den også kan være en arkitekturbeslutning.

Steg 4: Klassifiser commits

To stier deler seg her: endringslogg-oppføringer og arkitekturbeslutninger.

For endringslogg-oppføringer:

uv run orkestra mine classify abc123 --changelog added

Dette registrerer at commit abc123 bør vises i endringsloggen under kategorien «Added».

For arkitekturbeslutninger:

Først, hent en reell beslutnings-ID:

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

Klassifiser deretter med beslutnings-ID-en:

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

Dette knytter commiten til en beslutningsjournal som vil bli opprettet eller oppdatert.

For batch-prosessering (det vi faktisk gjør):

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

JSONL-formatet støtter begge domenene i én omgang:

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

Steg 5: Rendre resultater

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

Dette genererer CHANGELOG.md-filer for hver pakke fra journalen (ledger). Endringsloggene er avledede artefakter — slett dem, og de genereres perfekt på nytt fra kildejournalen.

Strukturen på en beslutningsjournal

Ekstraherte beslutninger blir YAML-filer med innholdsrike metadata:

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

Hver beslutning lenker tilbake til kildecommitene sine. Hver beslutning spesifiserer hvilke filer den påvirker. Sammenhenger mellom beslutninger er eksplisitte.

CLI-integrasjon: Spørring mot institusjonell hukommelse

Dette er der løkken lukkes. Agenter kan spørre mot beslutninger gjennom CLI-et:

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

Returnerer beslutninger om retry-logikk, feilhåndtering, gjenopprettingsmønstre.

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

Returnerer hele beslutningsjournalen med kontekst, begrunnelse og konsekvens.

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

Viser hvilke arkitekturvalg som ble tatt nylig.

Hvordan agenter bruker dette

Orkestratorens grunnleggende instruksjoner inkluderer:

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

Når en agent blir bedt om å implementere noe relatert til DuckDB, kan den først sjekke:

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

Og oppdage DEC-PL-142, og lære:

Hvorfor vi valgte DuckDB (context)
Hvordan bruke det riktig (agent_guidance)
Hvilke filer man skal se på (files)
Hvilke relaterte beslutninger som finnes (related)

Agenten finner ikke opp hjulet på nytt. Den bygger på etablerte mønstre.

Tre-spørsmåls-testen

Ikke hver commit fortjener en beslutningsjournal. Vi bruker Tre-spørsmåls-testen for å filtrere:

Var dette vanskelig å ta stilling til? Krevde det betydelig analyse, avveining, eller diskusjon?
Er det kostbart å endre? Ville det å reversere denne beslutningen krevd betydelig omarbeiding?
Har det systemomfattende konsekvenser? Påvirker det flere pakker eller etablerer det mønstre andre vil følge?

Hvis en commit svarer «ja» på minst ett av disse spørsmålene, er den en kandidat for beslutningsekstraksjon. Vår typiske rate: 1–4 beslutninger per 100 commits (rundt 1–4 %).

For endringslogg-oppføringer er terskelen lavere: enhver brukerrettet endring (funksjoner, feilrettinger, forbedringer) blir registrert. Interne gjøremål, dokumentasjonsoppdateringer og refaktoreringer hoppes typisk over. Vår typiske rate: 30–50 endringslogg-oppføringer per 100 commits.

Datalagring: Append-only journaler

Mining-systemet bruker append-only JSONL-journaler for konfliktfri multi-agent-drift:

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-formatet med merge=union i .gitattributes betyr at flere agenter kan klassifisere commits samtidig uten sammenslåingskonflikter. Hver linje er uavhengig.

Valideringsporter

Før hver mining-økt kjører vi validering:

uv run orkestra mine validate --quick

Dette sjekker:

Gyldighet av SHA-format
Samsvar med beslutnings-ID-format
Ingen duplikate oppføringer for samme SHA
At refererte beslutninger faktisk finnes

Etter klassifisering validerer vi på nytt før vi committer endringene.

Hvorfor dette betyr noe

Tilbakemeldingsløkken vi har bygget, løser flere problemer:

For nye teammedlemmer: I stedet for å spørre «hvorfor gjorde vi X?», kan de søke i beslutningsregisteret. Konteksten er bevart.

For AI-agenter: De opererer ikke i et vakuum. De kan spørre mot institusjonell kunnskap før de kommer med anbefalinger. Når de blir bedt om å legge til et nytt pipeline-stadium, kan de oppdage DuckDB-mønsteret og følge det.

For arkitektonisk konsistens: Beslutninger er eksplisitte og søkbare. Når noen foreslår en tilnærming som motsier en eksisterende beslutning, kan systemet synliggjøre konflikten.

For endringsloggenerering: Release notes er ikke et hastverksarbeid i siste liten. De er et biprodukt av kontinuerlig klassifisering underveis i utviklingen.

For onboarding: Nye agenter arver hele konteksten til kodebasen. De ser ikke bare koden — de ser beslutningene som formet den.

Nåværende status

Per i dag:

15 637 commits prosessert gjennom pipelinen
476 arkitekturbeslutninger ekstrahert og dokumentert
6 799 endringslogg-oppføringer registrert
100 % dekning på tvers av begge domener

Hver commit siden vi startet, er klassifisert. Den institusjonelle hukommelsen er komplett og søkbar.

Kom i gang

Hvis du vil implementere noe lignende:

Start med konvensjonelle commits. Mining-pipelinen fungerer best når commits har strukturerte prefikser (feat:, fix:, chore:).
Definer domenene dine. Vi bruker domener som pipeline, agent-design, observability, data-modeling. Disse organiserer beslutninger etter område.
Bygg klassifiseringsvanen. Mining fungerer når team klassifiserer commits regelmessig. Batch-prosessering med LLM-assistanse hjelper med å skalere.
Gjør beslutninger søkbare. Verdien øker når agenter kan søke i beslutninger via CLI. Strukturer resultatet for maskinkonsum.
Lukk løkken. Beslutninger bør påvirke fremtidig arbeid. Inkluder beslutningsreferanser i agentinstruksjoner og sjekklister for kodegjennomgang.

Målet er ikke perfekt dokumentasjon. Det er å gjøre hvorfor-et bak endringene tilgjengelig for både mennesker og AI, i dag og seks måneder frem i tid. Når endringer blir institusjonell hukommelse, bygger team videre på etablerte mønstre i stedet for å finne dem opp på nytt.

Mining-arbeidsflyten er en del av orkestreringsmotoren vår, nærmere bestemt context engine-modulen i orkestreringspakken vår.

Skill mining: Fra 3500 kandidater til 466 evner

Tue, 27 Jan 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

3500-skill-problemet

Da vi begynte å bygge et orkestreringssystem for agenter, sto vi overfor en interessant utfordring: det finnes tusenvis av potensielle skills spredt utover AI-økosystemet. GitHub-repositorier, leverandørdokumentasjon, community-prosjekter, interne mønstre — skills finnes overalt. Men hvilke betyr noe? Hvilke fungerer? Og hvordan vedlikeholder man et sammenhengende skill-bibliotek som agenter faktisk kan bruke?

Svaret vårt: en systematisk mining- og innlemmingsløkke.

Tallene i dag

Bare litt over tre måneder etter at Anthropic lanserte Agent Skills 16. oktober 2025, var dette stillingen da dette innlegget ble publisert 27. januar 2026:

Metrikk	Antall
Identifiserte kandidater	3500+
Adopterte skills	466
Leverandørskills (vendor)	373
Interne skills	93
Aktive leverandører	25+
Gjennomsnittlige tokens per skill	2834
Refererte verktøy	89
Unike tagger	635

Vi har gjennomgått over 3500 skill-kandidater. Vi har adoptert 466. Det er en adopsjonsrate på 13 % — og den selektiviteten er bevisst.

Kunnskapsnivåsystemet

Skills har ulik kvalitet og ulikt bruksområde. Vi organiserer dem i fem kunnskapslag (K0–K4), hvert med et forskjellig anvendelsesomfang:

K0: Foundations (universelt)

Skills alle agenter bør ha. Disse representerer «god tenker»-kapabiliteter som fungerer overalt.

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-skills er portable til ethvert prosjekt, ethvert domene, enhver stack. De koder for universelle kognitive mønstre.

K1: Identities (disiplin)

«God ingeniør»- eller «god forsker»-skills som gjelder på tvers av prosjekter innenfor en disiplin.

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

K2: Domains (fagekspertise)

«God databaseekspert»- eller «god sikkerhetsingeniør»-skills, portable innenfor et felt.

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

K3: Stacks (teknologi)

«God Supabase-bruker»- eller «god Cloudflare-utvikler»-skills for spesifikke teknologistacker.

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

K4: Project (organisasjon)

Skills spesifikke for vår organisasjon og våre arbeidsflyter.

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

Mining-løkken

Fase 1: Oppdagelse

Skills kommer fra overalt:

Leverandørrepositorier: AWS, Anthropic, Cloudflare, Supabase, og community-bidragsytere publiserer skill-samlinger. Vi følger 25+ leverandørrøtter.

Community-prosjekter: GitHub er fullt av Claude Code-maler, agentmønstre og arbeidsflytdefinisjoner.

Interne mønstre: Etter hvert som teamet vårt løser problemer, oppstår mønstre. Disse formaliseres til skills.

Dokumentasjonsmining: Teknisk dokumentasjon inneholder ofte implisitte skills — prosedyrer, sjekklister, beslutningstrær.

Oppdagelse er kontinuerlig. Vi bruker en skill-backlog for å spore kandidater før formell evaluering.

Fase 2: Evaluering

Hver kandidat vurderes etter de samme kriteriene:

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

Alle fem produktkriterier må være oppfylt. Det er derfor 87 % av kandidatene avvises.

Deretter går hver kandidat gjennom en separat tillitsgjennomgang. Vi behandler ikke et offisielt leverandørrepositorium, en velkjent community-vedlikeholder, og et tilfeldig GitHub-repo som likeverdige sannhetskilder.

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

Betrodde leverandører får en lettere herkomstgjennomgang, men ikke fribillett. Ikke-betrodde eller ukjente kilder får en dypere manuell revisjon, og vi kjører ikke medfølgende skript før de er lest, avgrenset, og klassifisert som trygge.

Gap-analyse: Før vi adopterer, søker vi i registeret vårt:

uv run orkestra skills search "<capability>"

Hvis vi allerede har det, trenger vi det ikke. Hvis vi har noe likt, kan vi heller slå sammen enn å adoptere.

Dybde- og standardscoring: Vi scorer også hvor fullt ut en kandidat bruker agent-skill-modellen. Et ensomt SKILL.md kan fortsatt være nyttig, men dypere skills er mer verdifulle når de skiller instruksjoner fra referanser, skript og ressurser på den måten agentskills.io oppmuntrer til.

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-stjerner kan løfte en troverdighetsscore litt, men de redder aldri en overfladisk eller utrygg skill. Et repo med mange stjerner og én vag SKILL.md og uklare skript scorer under et mindre repo med en presis beskrivelse, kuraterte references/, og små hjelpeprogrammer med én avgrenset oppgave som faktisk utnytter hele skill-kapabiliteten.

Strukturell analyse: Vi sjekker skill-kvalitet:

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

Hvis en kandidat inkluderer skript, blir den gjennomgangen strengere. En god skill er ikke bare nyttig; den må være lesbar, avgrenset, og trygg å overlate til en agent. Det sikkerhetsfilteret alene diskvalifiserer en betydelig andel av ellers interessante kandidater.

Fase 3: Innlemming

Når en skill består evalueringen, går den inn i registeret. Men skills adopteres aldri uendret. De modifiseres for å passe systemet vårt.

Modifikasjoner ved adopsjon:

Metadatanormalisering: Hver skill får frontmatter-skjemaet vårt
K-nivå-tildeling: Skills plasseres i riktig kunnskapslag
Tag-berikelse: Tagger legges til for oppdagbarhet
Verktøydeklarasjon: Tillatte verktøy deklareres eksplisitt
Seksjonstilpasning: Innhold restruktureres til å matche malen vår

En typisk skill-YAML etter innlemming:

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

Fase 4: Omfangstildeling

Skills tildeles omfang (scopes) — kategorier som avgjør hvilke agenter som laster hvilke skills:

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

Agenter deklarerer sine omfang, og skills tildeles automatisk:

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

Fase 5: Materialisering

Skills lever ikke som YAML i produksjon. De rendres til SKILL.md-filer som Claude Code kan laste:

uv run orkestra sync

Denne kommandoen:

Leser alle skill-YAML-definisjoner
Rendrer dem gjennom Jinja-maler
Skriver SKILL.md-filer til .claude/skills/
Organiserer etter K-nivå (foundations/, identities/, domains/, stacks/, project/)

Den endelige resultatstrukturen:

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

Det sovende omfangs-mønsteret

Ett av våre kraftigste mønstre er «adoptert-men-ikke-lastet»-skills. Vi kaller disse sovende omfang (dormant scopes).

Ta for eksempel vitenskapelige databehandlings-skills fra k-dense-scientific-repositoriet. Vi har adoptert 120+ skills som dekker bioinformatikk, kjemi, kvantedatabehandling, og klinisk informatikk. Men de fleste av agentene våre trenger ikke molekylær docking eller genuttrykksanalyse.

I stedet for å laste alle 120 skillsene inn i hver agent (som blåser opp kontekstvinduene), gjør vi:

Adopterer skillsene med et spesifikt omfang (f.eks. bioinformatics)
Holder dem sovende — registrert, men ikke lastet
Aktiverer dem bare når en agent deklarerer det omfanget

# 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

Dette mønsteret lar oss ha 466 skills i registeret mens typiske agenter bare laster 40–60 relevante.

Skill-typer

Skills kommer i tre kognitive mønstre:

Workflow

Ordnede prosedyrale steg: «1. Gjør X, 2. Deretter Y, 3. Til slutt Z»

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

Discipline

Atferdsvern: «Alltid X», «Aldri Y», «Foretrekk Z»

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

Checklist

Verifiseringskriterier: «Bekreft X», «Verifiser Y», «Sjekk Z»

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

Kvalitetsporter

Hver skill må bestå validering før den shippes:

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

Beskrivelser må være 50–400 tegn med utløserfraser («Use when…», «When you need…») slik at Claude Code vet når den skal foreslå dem.

Vi validerer kontinuerlig:

uv run orkestra validate --show-warnings

Leverandørøkosystemet

Våre 373 leverandørskills kommer fra:

Leverandør	Skills	Domene
AWS Agent	19	Skytjenester
Anthropic	12	Dokumentgenerering
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Vitenskapelig databehandling
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Nettleserautomatisering

Hver leverandørrot deklareres i metadata.yaml:

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

Når orkestra sync kjører, symlinkes leverandørskills inn i .claude/skills/vendor/ med sitt leverandørnavnerom.

Hva vi har lært

Selektivitet lønner seg. Det er fristende å adoptere alt som ser nyttig ut. Men hver skill koster tokens. Med 2834 tokens i gjennomsnitt per skill, fyller unødvendig innhold raskt kontekstvinduet. Vår adopsjonsrate på 13 % holder agenter slanke.

Struktur muliggjør oppdagelse. K-nivåsystemet handler ikke bare om organisering — det handler om portabilitet. K0-skills kan gjenbrukes hvor som helst. K4-skills er bevisst prosjektspesifikke. Denne klarheten hjelper både mennesker og agenter å finne det de trenger.

Sovende omfang skalerer. Du kan adoptere hundrevis av skills uten å laste dem alle. Omfang lar deg bygge et omfattende register samtidig som du holder den enkelte agents kontekstvindu håndterlig.

Tilpasning ved innføring er avgjørende. Rå leverandørskills passer sjelden systemet ditt. Innlemmingsprosessen — å legge til metadata, tildele nivåer, berike tagger — gjør at eksterne skills fungerer internt.

Mining er kontinuerlig. Antallet kandidater fortsetter å vokse fra 3500. Nye leverandørrepositorier dukker opp. Community-mønstre oppstår. Interne arbeidsflyter befestes. Løkken stopper aldri.

Hva som kommer

Vi jobber med flere forbedringer:

Automatisert gap-deteksjon: Varsle når vanlige agentfeil kunne vært løst av en ikke-adoptert skill
Arbeidsflyter for utfasing av skills: Formell prosess for å pensjonere skills som er erstattet eller ubrukt
Avhengigheter på tvers av skills: Eksplisitt deklarering av skill-forutsetninger
Bruksanalyse: Spor hvilke skills agenter faktisk påkaller versus bare laster

Mining-løkken for skills er infrastruktur. Den er ikke glamorøs. Men det er den som gjør at 41 agenter fungerer sammenhengende med 466 kapabiliteter, samtidig som de holder seg innenfor kontekstgrensene.

Det er historien om hvordan 3500 blir 466. Ikke ved å ignorere 3000 — men ved å evaluere dem systematisk og bare adoptere det som fungerer.

Vil du se skill-systemet i aksjon? Sjekk ut uv run orkestra skills list for å utforske det gjeldende registeret vårt.

Progressiv avdekking: CLI-vinduer inn i agentsystemer

Tue, 20 Jan 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

Agentsystemer er ugjennomsiktige av design. De tar beslutninger, påkaller verktøy, og koordinerer arbeid på tvers av dusinvis av spesialister. Men når noe går galt — eller når du bare vil forstå hva som skjer — hvor ser du da?

Svaret er progressiv avdekking: et lagdelt grensesnitt som avslører nøyaktig så mye kompleksitet som du trenger, nøyaktig når du trenger det.

Ugjennomsiktighetsproblemet

Et moderne orkestreringssystem for agenter kan ha:

40+ spesialistagenter, hver med distinkte kapabiliteter
700+ skills som spenner over intern automatisering og leverandørintegrasjoner
470+ arkitekturbeslutninger som former atferd
Dusinvis av MCP-verktøyservere som tilbyr eksterne kapabiliteter

Denne kompleksiteten er tilsiktet. Agenter trenger tilgang til rik kontekst — domenekunnskap, kodeintelligens, databaseskjemaer — for å ta gode beslutninger. Men den samme rikdommen skaper et synlighetsproblem.

Hvordan vet du hvilken agent som håndterer databasemigrasjoner? Hvilke beslutninger formet søkesystemets rangeringsatferd? Hvilke verktøy har arkitekturrådgiveren tilgang til?

Uten strukturert tilgang blir du sittende igjen med å lese kildekode eller håpe at dokumentasjonen er oppdatert.

Progressiv avdekking som arkitektur

Progressiv avdekking er ikke bare et UI-mønster. Det er et arkitektonisk prinsipp: organiser informasjon i lag, hvert dypere enn det forrige, slik at brukere kan stoppe på nivået som svarer på spørsmålet deres.

For agentsystemer oversettes dette til CLI-kommandoer med økende dybde:

Nivå	Kommando	Spørsmål som besvares
1	`orkestra system status`	Er alt sunt?
2	`orkestra agents list`	Hvilke agenter finnes?
3	`orkestra agents info <name>`	Hva gjør denne agenten?
4	`orkestra decisions search`	Hvorfor fungerer det slik?
5	Maguyva MCP-verktøy	Vis meg koden.

Hvert nivå svarer på et naturlig oppfølgingsspørsmål. Du trenger sjelden å hoppe rett til nivå 5.

Nivå 1: Systemhelse

Det første spørsmålet er alltid: fungerer alt?

$ orkestra system status

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

Én kommando. Fire tall. Nok til å vite at systemet er konfigurert og registrene er fylt.

Hvis et agentantall faller uventet, eller skills ikke laster, ser du det her først. Ingen loggdykking nødvendig.

Nivå 2: Agentinventar

Når du vet at systemet er sunt, er det neste spørsmålet: hva er tilgjengelig?

$ orkestra agents list

Dette returnerer strukturerte data — agentnavn, beskrivelser, modellpreferanser, domenedekning. Resultatet er JSON som standard, noe som gjør det enkelt å pipe inn i jq for filtrering:

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

Vil du ha agenter som håndterer databasearbeid? Søkekommandoen snevrer det inn:

$ orkestra agents search "database"

Dette skanner navn, beskrivelser og kapabiliteter. Du finner riktig spesialist uten å lese 40 agentdefinisjoner.

Nivå 3: Dypdykk i agent

Fant du en agent som ser relevant ut? Kommandoen info avslører alt:

$ orkestra agents info architecture-advisor

Resultatet inkluderer:

Metadata: Navn, kategori, modellpreferanse, beskrivelse
Domener: Hvilke kunnskapsområder denne agenten dekker
Identity: Karaktertrekk (architect, strategist, knowledge-architect)
Verktøyguider: Hvilken verktøydokumentasjon som injiseres i konteksten
Verktøy: Den fullstendige listen over MCP-verktøy tilgjengelig for denne agenten

Her er et utdrag av hva du ser:

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

Dette forteller deg nøyaktig hva agenten kan gjøre. Ingen kildekode nødvendig.

Nivå 4: Beslutningsarkeologi

Agenter oppfører seg i henhold til dokumenterte beslutninger. Når du trenger å forstå hvorfor noe fungerer på en bestemt måte, er beslutningsregisteret sannhetskilden.

$ orkestra decisions search "agent"

Dette returnerer matchende arkitekturbeslutninger:

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

Hver beslutning har full herkomst — når den ble tatt, hvorfor, hvilke avveininger som ble vurdert, hvilke commits som implementerte den:

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

Dette er arkitekturdokumentasjon som forblir oppdatert fordi den er utvunnet fra commits, ikke manuelt vedlikeholdt.

Nivå 5: Direkte kodeintelligens

Når du trenger å se selve implementasjonen — ikke metadata om den — gir Maguyvas MCP-verktøy direkte tilgang.

Fra innsiden av en agentøkt:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Dette ruter automatisk på tvers av semantisk, tekst- og AST-søk for å finne relevant kode. For spesifikke symboler:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

For avhengighetsanalyse:

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

Dette er ikke bare grep-erstatninger. De er grafbevisste, semantisk indekserte og integrerte med den samme kodeintelligensen som driver agentene selv.

Samlet søk på tvers av registre

Noen ganger vet du ikke hvilket register som har svaret. Det samlede søket dekker alt:

$ orkestra search "database" --summary

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

254 treff på tvers av fem registre. Sammendraget forteller deg hvor du bør grave dypere. Fjern --summary for detaljerte resultater, eller legg til --limit 5 for å holde resultatet håndterlig.

Hvorfor dette betyr noe

Progressiv avdekking handler ikke bare om bekvemmelighet. Det endrer hvordan du samhandler med komplekse systemer.

Feilsøking blir håndterlig. Når en agent tar en uventet beslutning, grepper du ikke gjennom logger. Du sjekker hvilke verktøy den har tilgang til (agents info), hvilke beslutninger som former atferden (decisions search), og sporer implementasjonen om nødvendig (intelligent_search).

Onboarding går raskere. Nye teammedlemmer trenger ikke å lese hele kodebasen. De starter med system status, utforsker med agents list, og går dypere bare når de støter på noe de ikke forstår.

Dokumentasjonen forblir oppdatert. Fordi CLI-et leser fra de samme registrene som konfigurerer agentene, er resultatet alltid nøyaktig. Det er ingen avvik mellom det dokumentasjonen sier, og det systemet faktisk gjør.

CLI-et som grensesnitt

Vi kunne ha bygget et webdashbord. Vi kunne ha skrevet omfattende dokumentasjon. I stedet bygde vi en CLI som leser fra sannhetskilden.

CLI-et har fordeler:

Komponerbart: Pipe resultatet gjennom jq, integrer med skript
Skriptbart: Automatiser sjekker, generer rapporter
Raskt: Ingen sideinnlastinger, ingen autentiseringsflyt
Nøyaktig: Leser den faktiske konfigurasjonen, ikke en mellomlagret representasjon

For systemer der korrekthet betyr mer enn estetikk, vinner CLI.

Bygg din egen progressive avdekking

Hvis du bygger agentsystemer, bør du vurdere hvordan brukere vil inspisere dem:

Start med helsesjekker. Én kommando som forteller deg om ting fungerer.
Tilby inventaroversikter. List opp hva som finnes før du forklarer hva det gjør.
Muliggjør målrettede spørringer. Søk slår manuell blaing i store samlinger.
Eksponer herkomst. La brukere spore beslutninger til deres opprinnelse.
Koble til kodeintelligens. Til slutt trenger brukere å se implementasjonen.

Hvert lag svarer på et oppfølgingsspørsmål. Bygg dem i frekvensrekkefølge — de fleste brukere stopper på nivå 2 eller 3. Bare avanserte brukere når nivå 5.

Målet er ikke å eksponere alt. Det er å eksponere nøyaktig det som trengs, nøyaktig når det trengs. Det er progressiv avdekking anvendt på agentarkitektur.

Ground Truths: Forankring av AI-agenter i virkeligheten

Tue, 13 Jan 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

AI-agenter er bemerkelsesverdig dyktige. De kan resonnere, syntetisere og generere. Men de har en grunnleggende svakhet: de finner på ting. Ikke ondsinnet, men med stor selvtillit. En agent kan finne opp API-parametere som ikke finnes, referere til konfigurasjoner som aldri ble definert, eller anvende mønstre fra treningsdataene sine som motsier din faktiske arkitektur.

Standardtiltaket er «gi agenten mer kontekst». Men kontekst kan være motstridende. Dokumentasjonen kommer ut av takt med implementasjonen. Kommentarer lyver. Selv kode kan villede når den leses uten å forstå intensjonen.

Vi trengte noe mer eksplisitt. Noe som ikke kunne ignoreres eller mistolkes. Noe som ville forankre agenter i verifiserbar virkelighet.

Vi kaller dem Ground Truths.

Hva er en Ground Truth?

En Ground Truth er en eksplisitt, versjonert faktapåstand som agenter må respektere. Det er ikke dokumentasjon. Det er ikke en kommentar. Det er en førsteklasses entitet i systemet med:

En unik identifikator (som GT-MAG-015 eller GT-MAG-036)
En livssyklusstatus (current, tentative, eller deprecated)
Et omfang (plattformomfattende, pakkespesifikt, eller domenebundet)
Bevis (filstier, URL-er, eller referanser som beviser påstanden)
Agentveiledning (eksplisitte gjør/unngå-instruksjoner)

Her er et eksempel fra vår Maguyva kodeintelligens-plattform:

- 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

Dette er ikke prosa. Det er en kontrakt. Når en agent støter på denne Ground Truth-en, vet den:

Standardverdien er deterministisk (tomme resultater, ikke gjetninger basert på omtrentlig matching)
Det finnes spesifikke parametere (find_similar, exact_match) med definert atferd
Bevis finnes i spesifikke filer som kan verifiseres
Påstanden ble verifisert på en bestemt dato

Anatomien til et Ground Truth-register

Ground truths lever i YAML-registre under ai_assets/reference/ground_truths.yaml. Hver pakke eller hvert domene kan ha sitt eget register. Strukturen er:

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

Registeret inneholder metadata om selve samlingen, renderingskonfigurasjon for dokumentasjonsgenerering, og selve påstandene. Hver påstand følger et strengt skjema validert av Pydantic-modeller:

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

Hvordan agenter får tilgang til Ground Truths

Ground truths eksponeres gjennom flere kanaler:

1. Rendret dokumentasjon

Kommandoen orkestra sync transformerer YAML-registre til lesbar markdown:

uv run orkestra sync

Dette genererer GROUND_TRUTHS.md-filer som inkluderes i agentkonteksten. Det rendrede resultatet grupperer påstander etter status og kategori:

## 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-søk

Agenter med shell-tilgang kan søke i ground truths programmatisk:

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

Søkefunksjonen scorer treff på tvers av flere felt med vektet relevans:

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

Når agenter rendres fra YAML-definisjoner, kan konteksten deres referere til Ground Truth-registre:

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

Dette sikrer at relevante ground truths lastes inn før agenten begynner arbeidet.

Kategorier av Ground Truths

Når vi ser på tvers av registrene våre, klynger ground truths seg i flere mønstre:

Produktprinsipper

Begrensninger på hva produktet er og ikke er:

«Maguyva er read-only med hensyn til brukerrepositorier; den eneste ressursen som ikke kan gjenoppbygges, er den betalte embeddings-cachen.» (GT-MAG-001)

Arkitekturgrenser

Hvor ansvar hører hjemme, og hvorfor:

«Grensene mellom pipeline og Maguyva er tilsiktede: pipeline er gjenbrukbar, Maguyva holder kodespesifikk logikk, og CQRS skiller stage-skriving fra server-lesing.» (GT-MAG-006)

Anti-hallusinasjonsregler

Eksplisitte påbud som holder verktøykontrakter deterministiske i stedet for utledet:

«Omtrentlig symbolmatching (fuzzy matching) er opt-in via find_similar=true. Standardatferd returnerer tomme resultater for symboler som ikke finnes; exact_match=true håndhever streng matching og deaktiverer alle fallbacker med omtrentlig matching.» (GT-MAG-015)

Kvalitetsporter

Standarder som må opprettholdes:

«Endringer i delt infrastruktur (post_filters.py, relasjonsekstraktorer, delte håndterere) MÅ valideres mot ALLE støttede språk gjennom full manifestgenerering før commit. Enkeltspråksvalidering er ikke tilstrekkelig for delt kode.» (GT-MAG-036)

Kodemønstre

Implementasjonskrav:

«Bruk asyncio.to_thread() for CPU-tungt arbeid i asynkrone kontekster; det utfasede loop.run_in_executor()-mønsteret skal ikke brukes i ny kode.» (GT-MAG-018)

Livssyklusen til en Ground Truth

Ground truths er ikke statiske. De utvikler seg gjennom en definert livssyklus:

Tentative

En foreslått sannhet under vurdering. Påstanden er registrert, men kan endres:

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

Current

En verifisert sannhet som agenter må respektere. Bevisene er validert:

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

Deprecated

En sannhet som ikke lenger gjelder. Beholdt for historisk referanse med en henvisning til det som erstattet den:

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

Hvorfor ikke bare dokumentasjon?

Dokumentasjon tjener et annet formål. Den forklarer. Den lærer bort. Den kan være vag, kan bruke kvalifikatorer som «generelt» eller «vanligvis».

Ground truths kan ikke være vage. De er påstander. De gjelder enten, eller så gjør de ikke det.

Se på forskjellen:

Dokumentasjon: «API-et returnerer generelt tomme resultater når et symbol ikke finnes, selv om omtrentlig matching kan være aktivert i enkelte konfigurasjoner.»

Ground Truth: «Standardatferd returnerer tomme resultater for symboler som ikke finnes; exact_match=true håndhever streng matching og deaktiverer alle fallbacker med omtrentlig matching.»

Den første er nyttig for mennesker som lærer systemet. Den andre er handlingsrettet for agenter som skal ta beslutninger.

Agentveiledning: Gjør og unngå

Noen ground truths inkluderer eksplisitt agentveiledning:

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

Dette fjerner tvetydighet. En agent som leser dette, vet ikke bare hva som er sant, men hvilke handlinger den sannheten innebærer.

Verifisering og vedlikehold

Ground truths krever vedlikehold. Vi sporer:

last_verified: Når noen bekreftet at påstanden fortsatt gjelder
evidence: Filer som beviser påstanden (kan sjekkes for eksistens)
source: Hvor sannheten stammer fra (CLI-inspeksjon, arkitekturgjennomgang, læring etter hendelser)

En Ground Truth med utdaterte verifiseringsdatoer eller ødelagte bevislenker er et signal om å undersøke. Enten er sannheten fortsatt gyldig og trenger re-verifisering, eller virkeligheten har endret seg og sannheten trenger oppdatering.

Ekte eksempler fra produksjon

Sikkerhetsgrense

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

Denne Ground Truth-en forhindrer en klasse av feilslåtte «sikkerhetsforbedringer» som ville ødelagt produktet.

Nøyaktighet ved ekstraksjonstidspunktet

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

Dette kom fra en smertefull erfaring. Agenter pleide å lappe feilende språkpakker ved å legge til filtre som bare påvirket validatoren, som fikk testriggen til å se grønnere ut, mens Maguyva-ekstraktoren i produksjon fortsatt sendte ut de feilaktige edgene. Regelen tvinger fikser tilbake til den reelle stien: YAML-konfigurasjon, spørringer, eller håndterere.

Filtrering i flere nivåer

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

Dette forhindrer agenter fra å legge til filtre på feil sted, en vanlig feil som forårsaket nøyaktighetsregresjoner.

Integrasjon med orkestreringssystemet

Ground truths er ett lag i et bredere kontekstsystem:

Arkitekturbeslutninger (ADR-er) - Registrerer hvorfor vi valgte tilnærming A fremfor B
Ground Truths - Sier hva som definitivt er sant akkurat nå
Domenemønstre - Beskriver hvordan man gjør ting riktig
Antimønstre - Beskriver hva man skal unngå, og hvorfor

En agent som jobber i systemet, har tilgang til alle fire. Ground truths gir det faktabaserte ankeret, mens beslutninger forklarer historien, mønstre veileder implementasjonen, og antimønstre advarer mot fallgruver.

Måling av effekt

Siden vi introduserte ground truths, har vi observert:

Færre «fiks den hallusinerte fiksen»-sykluser
Mer selvsikker agentbeslutningstaking når faktaene er klare
Bedre PR-gjennomganger fordi forventningene er eksplisitte
Redusert onboarding-tid for nye agenter (og mennesker)

Investeringen i å vedlikeholde ground truths betaler seg i redusert feilsøking og klarere systemgrenser.

Kom i gang

For å legge til en Ground Truth i systemet ditt:

Opprett en ground_truths.yaml i pakkens ai_assets/reference/-katalog
Definer metadata og renderingskonfigurasjon
Legg til påstander som følger skjemaet
Kjør uv run orkestra sync for å generere dokumentasjon
Inkluder registeret i agentens kontekstkomposisjon

Start med faktaene som skaper mest forvirring, eller begrensningene som brytes oftest. Det er dine mest verdifulle ground truths.

Konklusjon

AI-agenter vil hallusinere. Det ligger i deres natur. Men vi kan skape miljøer der hallusinasjon er begrenset, der visse fakta ikke er til forhandling, der agenter kan sjekke antakelsene sine mot verifisert virkelighet.

Ground truths er ikke en komplett løsning. De krever vedlikehold. De kan bli utdaterte. De legger til overhead i utviklingsprosessen.

Men de gir noe verdifullt: et delt vokabular av fakta som både mennesker og agenter kan stole på. I en verden der agenter i økende grad deltar i programvareutvikling, blir det delte fundamentet essensielt.

Alternativet er endeløse sykluser med agenter som gjør selvsikre feil og mennesker som retter dem opp. Ground truths bryter den syklusen ved å gjøre rettelsene eksplisitte og varige.

Agentene dine fortjener å vite hva som er sant. Fortell dem det.

Orkestra: Orkestrering av AI-agenter i stor skala

Tue, 06 Jan 2026 00:00:00 GMT

Tallene i dette innlegget gjenspeiler systemet ved publisering (januar 2026). Se teamsiden for gjeldende tall.

Da vi begynte å bygge med Claude Code, støtte vi på et problem som alle team som bruker AI-kodeassistenter til slutt møter: én enkelt agent kan ikke gjøre alt bra.

Du kan prompte en agent til å være en databasespesialist. Eller en sikkerhetsrevisor. Eller en frontend-utvikler. Men i det øyeblikket du ber den være alle tre samtidig, lider kvaliteten. Konteksten blir utvannet. Instruksjoner kolliderer. Agenten blir en generalist som er middelmådig på alt.

Så vi bygde Orkestra.

Hva er Orkestra?

Orkestra er et orkestreringssystem for agenter for Claude Code og lignende AI-kodeverktøy. Det koordinerer flere spesialiserte agenter, hver med distinkt ekspertise, under én orkestrator som ruter arbeid til riktig spesialist.

Tenk på det som et bemanningsbyrå for AI-agenter. Orkestratoren mottar en oppgave, identifiserer hvilken spesialist som bør håndtere den, og delegerer med riktig kontekst. Når arbeidet er gjort, flyter resultatene tilbake til orkestratoren for syntese.

Tallene forteller historien:

Komponent	Antall
Spesialistagenter	46
Gjenbrukbare skills	466
Identitetsarketyper	27
Mindsets	11
Kommunikasjonsstiler	10
Kunnskapsdomener	21

Karaktersystemet: D&D for agenter

Kjerneinnsikten bak Orkestra er at agentatferd oppstår fra tre kombinerbare byggeklosser:

Identity definerer hva agenten er. En arkitekt designer systemstrukturer. En feilsøker sporer feil til rotårsaker. En vokter håndhever etterlevelse og sikkerhetsgrenser. Vi har 27 identitetsarketyper som kan blandes.

Mindset definerer hvordan agenten tenker. En analytisk tenkemåte forankrer påstander i bevis og kvantifiserer usikkerhet. En skeptisk tenkemåte stiller spørsmål ved antakelser og søker motbevis. En utforskende tenkemåte omfavner tvetydighet og prøver flere tilnærminger.

Style definerer hvordan agenten kommuniserer. En teknisk stil inkluderer eksakte verdier og refererer til spesifikke filer. En kortfattet stil kutter fyllstoff og starter med svaret. En diplomatisk stil balanserer ærlighet med takt.

En agent kombinerer disse byggeklossene:

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

Denne komposisjonen skaper en agent som designer systemer (architect), knytter kunnskap på tvers av domener (knowledge-architect), setter strategisk retning (strategist), tenker i bevis og data (analytical), og kommuniserer uten fyllstoff (concise).

Kraften ligger i den kombinatoriske eksplosjonen. 27 identiteter ganger 11 mindsets ganger 10 stiler gir nesten 3000 mulige agentpersonligheter. Men du definerer bare kombinasjonene som betyr noe for arbeidet ditt.

Skills: Gjenbrukbare kapabilitetsmoduler

Skills er kunnskapen og arbeidsflytene agenter kan påkalle. De følger et lagdelt system basert på omfang:

Nivå	Navn	Omfang	Eksempel
K0	Foundations	Universell metodikk	Testdrevet disiplin, evidensbasert fullføring
K1	Identities	Rollebaserte arbeidsflyter	CLI-grensesnittstandarder, ytelseshåndbok
K2	Domains	Domenespesifikk kunnskap	Databasemigreringsmønstre, autentiseringsvalidering
K3	Stacks	Teknologispesifikt	Cloudflare-driftsetting, Supabase-drift
K4	Project	Kun denne kodebasen	Prosjektspesifikke arbeidsflyter og konvensjoner

Skills lastes ved behov (lazy-loaded). En agent ser skill-navn og -beskrivelser ved oppstart, men det fulle skill-innholdet lastes bare inn når det utløses. Dette holder konteksten slank samtidig som hundrevis av skills gjøres oppdagbare.

Hver skill inkluderer:

Klare utløserbetingelser («Bruk ved migrering av databaseskjemaer»)
Steg-for-steg-veiledning
Tillatte verktøy for arbeidsflyten
Suksesskriterier og gjenopprettingsstier ved feil

De 466 skillsene i registeret vårt dekker alt fra git worktree-isolasjon til arbeidsflyter for nettresearch til validering av driftshelse.

Hvorfor orkestrering betyr noe

Enkeltagent-arkitekturer treffer veggen raskt:

Kontekstutvanning. Et kontekstvindu på 200 000 tokens høres stort ut helt til du laster inn databaseskjemaer, API-dokumentasjon, testfixturer og domenekunnskap. Spesialister kan jobbe med målrettet kontekst.

Instruksjonskonflikter. Å be en agent være «grundig, men rask» og «verifiser alt, men ikke gjør løsningen unødvendig komplisert» skaper spenning. Spesialister løser dette ved å ha et klart omfang.

Ekspertisedybde. En generalistagent kan litt om alt. En spesialistagent, satt sammen med riktig identitet og skills, kjenner domenet sitt dypt.

Orkestra implementerer flat orkestrering: én orkestrator koordinerer flere spesialister. Spesialister kan ikke spawne underspesialister. Dette forhindrer en kompleksitetseksplosjon samtidig som det muliggjør parallelt arbeid.

Orkestratoren har tilgang til 2,2 millioner tokens effektiv kapasitet: sitt eget vindu på 200 000, pluss 10 samtidige subagenter med 200 000 hver. Arbeid som ville tømt en enkeltagent, kjører komfortabelt på tvers av flåten.

Renderingspipelinen

Agentdefinisjoner lever i YAML. Claude Code leser Markdown. Orkestra bygger bro over dette gapet med en deterministisk renderingspipeline:

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

Operatører redigerer YAML-kilden. Kjør orkestra sync. Rendret Markdown vises i .claude/agents/. Claude Code plukker opp endringene.

Denne separasjonen betjener forskjellige målgrupper:

YAML-kilden inkluderer livssyklusmetadata, tagger, valideringsregler, og utfasingsnotater for verktøy
Rendret Markdown inkluderer bare det modellen trenger: beskrivelse, verktøy, skills, og atferdsveiledning

Pipelinen setter sammen identiteter, mindsets, stiler og skills til én sammenhengende prompt. En architect-analytical-concise-agent får en svært annerledes systemprompt enn en debugger-skeptical-technical-agent, selv om de deler noen underliggende skills.

Domenekunnskap: Fire-filers-mønsteret

Hvert kunnskapsdomene følger en konsistent struktur:

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

Denne strukturen betjener agentens kontekstlasting. En agent som jobber med autentisering, laster authentication/patterns.md for veiledning og authentication/anti-patterns.md for å unngå kjente fallgruver. Filene er dimensjonert for effektiv kontekstlasting: fokuserte nok til å være nyttige, omfattende nok til å være autoritative.

Vi vedlikeholder 21 toppnivådomener, inkludert analytics, authentication, data science, infrastruktur, maskinlæring, ytelse, sikkerhet, og mer. Hvert domene kan ha underdomener for finere granularitet.

Values: Operativsystemet

Alle agenter deler et grunnleggende verdilag som definerer hvordan de opererer:

Enkelhet først. Bruk den enkleste løsningen som fungerer. Legg til kompleksitet bare når det er begrunnet.

Fiks rotårsaker. Aldri lapp rundt feil. Hvis en pipeline feiler, feilsøk pipelinen. Hvis en test feiler, fiks koden eller testen.

Evidensbasert. Merk påstander som «verified» (med benchmarks) eller «estimated» (med antakelser). Et oppdaget mønster er ikke det samme som et bekreftet problem.

Kontekstøkonomi. MCP-verktøy koster 0,1 % av konteksten. Fillesing koster 2 % hver. Anvend domeneekspertise før du utforsker kode.

Disse verdiene forplanter seg til hver spesialist gjennom renderingspipelinen. Måten agenten settes sammen på, hindrer den i å omgå dem.

CLI: Kontrollplanet

Orkestra leveres med en CLI for å administrere agentøkosystemet:

# 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-et er sannhetskilden for hvilke agenter som finnes, hvilke skills de har, og om systemet er sunt. Det kjører validering før synkronisering for å fange problemer tidlig.

Betraktninger om åpen kildekode

Vi bygde Orkestra for å løse vårt eget problem: å koordinere AI-agenter i stor skala for en kompleks kodebase. Mønstrene vi oppdaget er ikke spesifikke for vårt domene.

Karakterkomposisjonssystemet (identity + mindset + style) gjelder for ethvert team som definerer agentpersonligheter.

Skill-nivåsystemet (K0–K4) gir en mental modell for å organisere gjenbrukbare kapabiliteter etter omfang.

Renderingspipeline-mønsteret (YAML-kilde + maler + genererte artefakter) skiller ansvar mellom verktøy og modellens bruk av innholdet.

Den flate orkestreringsmodellen (én koordinator, mange spesialister) unngår kompleksitet samtidig som den muliggjør parallellitet.

Om Orkestra blir åpen kildekode, avhenger av om disse mønstrene har verdi for andre som bygger med Claude Code. Hvis du treffer veggene vi beskrev, kan arkitekturen kanskje hjelpe.

Hva vi lærte

Å bygge Orkestra lærte oss at orkestrering ikke handler om å gjøre agenter smartere. Det handler om å gjøre dem mer fokuserte.

En enkeltagent med perfekte instruksjoner går fortsatt tom for kontekst. En enkeltagent med alle skills blir fortsatt forvirret om hvilken som skal brukes. En enkeltagent som prøver å være alt, produserer middelmådige resultater overalt.

Førti spesialister, hver utmerket i sitt domene, koordinert av en orkestrator som vet når den skal delegere: det er slik vi shipper.

Tallene betyr mindre enn arkitekturen. Du trenger kanskje fem agenter eller femti. Prinsippet består: komposisjon fremfor kapasitet, spesialisering fremfor generalisering, koordinering fremfor individuell heltemodighet.

Orkestra driver agentøkosystemet bak Maguyva, vår kodeintelligens-plattform. Vil du vite mer? Ta kontakt med teamet.