Maguyva-bloggen

Kontext som följer med dig

Mon, 07 Sep 2026 00:00:00 GMT

Cursors indexerare är utmärkt inuti Cursor. Tab-komplettering, inline-redigering, chatt, och agenten i det fönstret vilar redan på ett projektindex som Cursor driver för det öppna arbetsområdet. Om Cursor är den enda ytan du skriver i, och det indexet redan hittar rätt filer, stanna där. Det är det ärliga ‘stanna där du är’-fallet, och det förtjänar att vara den första meningen på den här sidan.

Den här texten handlar om den andra halvan av en vanlig vecka. Samma repo öppnas också i Claude Code, tillfrågas från Codex CLI, granskas på en andra maskin, eller frågas av en agent som körs i CI. Frågan är inte ‘vilken indexerare är bäst’. Frågan är om kartan agenten litar på i ett fönster är samma karta den litar på i nästa.

Maguyva är den kartan som följer med dig. Det är ett fjärranslutet MCP-lager för kodbaskontext. Agenten frågar den på samma sätt som den frågar vilket annat MCP-verktyg som helst. Resultaten kommer tillbaka som rankade sökvägar med radnummer. Cursor förblir editorn. Det är kontexten som flyttar sig.

Vad Cursors indexerare är till för

Cursors inbyggda indexering finns så att chatt, agent och sökning inuti editorn kan hämta relevant kod istället för att förlita sig enbart på det som får plats i modellens råa kontextfönster. Det är rätt design för en IDE. Det här indexet är nativt för Cursor. Det är ingen MCP-server och är inte nåbart från någon annan klient.

Så fungerar det, enligt Cursors offentliga dokumentation och Cursors egen redogörelse vid tidpunkten för skrivandet: den primära sökvägen är inte längre ett molnbaserat embedding-index. Cursors team har uttalat på sitt community-forum att dedikerad semantisk, embedding-baserad sökning trappas ner till förmån för grep-baserad hämtning, eftersom dagens modeller redan utforskar ett levande träd tillräckligt bra på egen hand. I dess ställe finns Instant Grep, ett lokalt sökindex byggt av n-gram, inverterade listor och Bloom-filter, hållet i en minneskartlagd uppslagstabell, så att förfrågningar löses på utvecklarens egen maskin istället för på en server.

Själva indexet lever i repots egen .git/cursor/-katalog, förankrat till en specifik git-commit; ändringar sedan den commiten läggs ovanpå den istället för att utlösa en ny skanning, och indexet byggs bara om när det lokala tillståndet har avvikit långt från det det byggdes mot. Eftersom det ligger inuti .git spåras det aldrig och pushas aldrig — ta bort mappen, och indexet är borta. .gitignore respekteras genom konstruktion, eftersom bara git-spårat innehåll är kvalificerat, och .cursorignore tillämpas på läsvägen. Det finns inte längre något embedding-steg på serversidan eller någon fjärransluten vektordatabas i den vägen. Tidigare dokumentation beskrev en molnassisterad design — kryptering av chunkar, synkronisering via Merkle-träd, återanvändning av index mellan lagmedlemmar — och Cursors eget team har sedan dess sagt att den designen trappas ner, så den här texten beskriver den inte längre som aktuell.

En framstående styrka inuti editorn är Cursors Explore-subagent. Den kan starta flera parallella sökningar i sitt eget kontextfönster på en snabbare modell och bara returnera de relevanta fynden, så att huvudkonversationen inte sväller av sökresultat. Det är en verklig styrka inuti editorn. Behåll den.

Arbetsytor med flera rotmappar stöds: kontexten för varje öppnad mapp är tillgänglig för Agent. Vissa git-beroende funktioner, som worktrees, är avaktiverade i multi-root-konfigurationer, och Cloud Agents stöder inte alls arbetsytor med flera rotmappar.

Inget av detta är en anledning att lämna Cursor. Det är en exakt beskrivning av en karta som är utmärkt där den lever.

Vad ‘följa med dig’ egentligen betyder

En karta följer med dig när samma frågor returnerar samma typ av svar, med citat du kan öppna, från mer än en klient.

I Cursor: ‘Var är parseConfig definierad, och vem anropar den?’
I Claude Code, på samma repo: samma fråga.
I Codex CLI, på en granskningsmaskin som aldrig öppnat Cursor-fönstret: samma fråga.
I en CI-agent som talar MCP: samma fråga, mot samma värdbaserade ögonblicksbild.

Om varje yta bygger sitt eget privata index har du inte en karta. Du har flera cacher som glider isär. Editorindexet kan vara aktuellt för trädet på disk. CLI-sessionen kan ligga en dag efter. CI-jobbet kan titta på en annan checkout. Och agenten kommer ändå att låta säker.

Cursors indexerare är inte tänkt att lösa det. Eftersom den lever inuti editorn är kontexten den bygger för den editorn. En läsare som också behöver en CLI, en CI-pipeline, eller en annan editor behöver ett separat verktyg för de ytorna. Det är ett faktum om omfattning, inte en brist. Maguyva är det separata verktyget.

Ett publicerat antal språk för Cursors indexerare anges inte i det material den här texten får använda. Maguyva publicerar stöd för över 279 språk och textbaserade teknologier. Cursors priser återges inte heller här; se deras prissida. Maguyva tar betalt per arbetsyta, inte per plats, med publicerade planer på $0, $19, $49 och $149 beroende på indexerad omfattning och arbetsytans storlek.

En värdbaserad karta, varje MCP-klient

Maguyva är en fjärransluten MCP-server. Du kopplar GitHub, väljer repona, och molnpipelinen bygger symboler, grafkanter och en rankad karta. Du lägger till en API-nyckel i MCP-konfigurationen för klienten du redan använder. Maguyva har installationsguider för 24 dokumenterade MCP-klienter — inklusive Cursor — och kan ansluta till andra MCP-kompatibla klienter som stöder standardkonfiguration.

Cursor-installationssidan är den editorspecifika vägen om det är där du arbetar. Samma server svarar Claude Code, VS Code, Windsurf, Codex CLI och resten. Du byter inte editor. Du ger varje agent samma verktygsyta: 11 kundvända MCP-verktyg för sökning, symboler, beroendeanalys, filhämtning, repo-kontext och deterministiska hjälpverktygsflöden. Semantisk, strukturell, graf- och textsökning smälts samman till rankade resultat.

Det är portabilitetsfördelen. Citaten du kontrollerade i Cursor i morse har samma form som citaten Codex CLI returnerar i kväll. Filsökväg och radnummer. Öppna dem. Om de är fel ser du det. Om de är rätt har nästa ändring en plats att landa på. Det godkända påståendet är färre hallucinerade ändringar, inte ett löfte om att varje ändring är korrekt.

Fräschhet publiceras. Ögonblicksbilder är tidsstämplade, så agenten vet vilken version av trädet den läser. Ombyggnadstakten är daglig i gratisplanen och varje timme i betalplanerna. Den ärliga begränsningen är osynkroniserat lokalt arbete: en ändring som bara finns i ett arbetsträd är ännu inte i den värdbaserade kartan. Den begränsningen är densamma oavsett vilken klient du frågar från, och det är precis poängen. Drift mellan klienter är inte längre en andra, dold begränsning.

Dokumentationen ger aktiveringsloopen som gäller för varje klient: indexera ett repo du redan känner till, anslut klienten, ställ en fråga du kan verifiera. Gör det en gång i Cursor. Gör det igen från den CLI du faktiskt använder på granskningsdagar. Om båda svaren citerar samma handler har kartan verkligen följt med dig.

Hur de två kartorna samexisterar

Använd båda. De är inte alternativ i en jämförelsesidas mening.

Låt Cursors indexerare vara på för projektet på disk. Låt Explore, Instant Grep och agenten inuti editorn använda den. Den loopen är nativ och snabb.
Lägg till Maguyva som MCP-server i Cursor så att samma session också kan fråga den värdbaserade arbetsytekartan. Cursor är en dokumenterad Maguyva-klient. Du väljer inte ett index och raderar det andra.
Lägg till samma Maguyva-server till Claude Code, Codex CLI, eller vilken annan MCP-klient som helst som rör repot. En API-nyckelform. En arbetsyta.
Om en CI-agent är MCP-kompatibel, peka den mot samma server. Den läser samma tidsstämplade ögonblicksbild som laptopen läste.

Editorindexet förblir det bästa verktyget för ‘vad finns på disk i det här fönstret, just nu’. Den värdbaserade kartan är det bästa verktyget för ‘hur ser den här arbetsytan ut för varje agent som rör den idag’. De meningarna konkurrerar inte.

Arbetsytekvoter publiceras på prissidan: repon, indexerade rader och användare, fakturerade per arbetsyta. Agenter och människor delar samma användarantal. Börja gratis med ett repo du redan kan bedöma. Höj arbetsytan först efter att citaten har överlevt kontakt med trädet.

Vad den här sidan inte hävdar

Den hävdar inte att Cursors indexerare är svag, ofullständig, eller en anledning att byta editor. Den första meningen i den här texten säger motsatsen.

Den hävdar inte att Maguyva ersätter Instant Grep eller Explore-subagenten. Det är Cursor-funktioner. De stannar i Cursor.

Den hittar inte på ett antal språk, en latenssiffra, eller en tokenbesparing för någon av produkterna. Okända siffror förblir opublicerade.

Den låtsas inte att opushat lokalt arbete finns i den värdbaserade kartan. Tidsstämplade ögonblicksbilder gör den begränsningen synlig. De tar inte bort den.

Testet är vanligt. Indexera ett repo du redan känner till. Ställ en fråga du kan verifiera, först i Cursor, sedan i en andra MCP-klient. Kontext som följer med dig är samma citat på båda ställena.

// same map, wherever you opened it.

Kartan först, granskningen sedan

Mon, 07 Sep 2026 00:00:00 GMT

Två olika uppgifter sitter på var sin sida av en pull request. Innan agenten skriver behöver den en karta över trädet den är på väg att ändra. Efter att agenten öppnat en PR bör något läsa den ändringen mot resten av systemet och lämna kommentarer en människa kan agera på.

De här uppgifterna ser lika ut på avstånd eftersom båda involverar ‘att förstå kodbasen’. Det är inte samma produkt. Den ena svarar på ‘var borde den här ändringen landa?’. Den andra svarar på ‘vad bröt det här diffet som en rad-för-rad-linter kommer att missa?’. Att blanda ihop dem ger ett sämre första utkast och en mer högljudd granskning.

Den här texten är en guide till ett gemensamt arbetsflöde. Maguyva är kartan agenten frågar först. Greptile är granskningsagenten som kommenterar PR:en efteråt. Paret är kompletterande genom konstruktion: Maguyva granskar inte pull requests, och Greptile ersätter inte kontextlagret agenten använde för att skriva dem.

Varför den här uppdelningen är användbar

En kodande agent som utgår från träningspriors plus några inklistrade filer kommer att hitta på en trolig sökväg och redigera den. Det är misslyckandet med ‘fel fil’, och det är ett hämtningsproblem. Maguyva är ett fjärranslutet MCP-lager för kodbaskontext: semantisk, strukturell (AST), graf-/beroende- och textbaserad hämtning smälts samman till rankade resultat, plus symbolsökning och filhämtning. Underbyggda svar kommer tillbaka som path/file.ext:line, så att du kan avvisa en miss innan en patch existerar. Påståendet förblir blygsamt: färre hallucinerade ändringar. Modellen kan fortfarande gissa. Det är bara det första steget som slutar vara en gissning.

Greptile är en AI-kodgranskningsagent. Med deras egna ord granskar den automatiskt varje pull request med full förståelse av kodbasen, och ställer det mot traditionella lintrar som kontrollerar filer isolerat istället för hela systemet. Installationen består i att installera GitHub- eller GitLab-appen och välja repon. Det finns inget lokalt index du behöver driva. Hostingen är Greptile Cloud (de anger SOC 2 Type II-efterlevnad, med en rapport tillgänglig på begäran), med ett självhostat alternativ erbjudet till företag.

Deras eget numrerade flöde är: anslut och bygg en beroendegraf för varje funktion, klass och beroende; vid varje pull request, analysera ändringen med den fullständiga repo-grafen och publicera fynd som PR-kommentarer med föreslagna korrigeringar, på ungefär tre minuter; varje kommentar kan lämna över problemet till en kodande agent teamet redan använder. De anger också att de läser tidigare mänskliga PR-kommentarer över tid för att lära sig ett teams kodstandarder och minska högljudda förslag. Deras inlärningssystem behöver, enligt dem själva, 2-3 veckor för att anpassa sig.

Det är granskning, inte utkastskrivning. Greptiles styrka är kontexten från en fullständig repo-graf på ändringen som redan landat i en PR, följt av en sluten loop som skickar fyndet till Claude Code, Codex, Conductor, Cursor, eller Devin. Maguyvas styrka är den rankade kartan agenten frågade innan den ändringen skrevs. Använd båda. Be inte någon av dem göra den andres jobb.

En förstapartsprodukt-integration mellan Maguyva och Greptile anges inte. Du behöver den inte heller. Maguyva pratar med agenten via MCP. Greptile pratar med GitHub eller GitLab genom sin egen app. De möts vid pull requesten. Inget limskript, ingen cron som kopplar ett verktyg till det andra. Paret klarar sig utan bash eftersom varje produkt redan sitter på ytan den äger.

Vad det här inte är

Det här är inte en rivning av Greptile. Det är inte en ‘byt granskare’-sida. Greptile lanserades på Hacker News den 5 mars 2024 som ett Y Combinator W24-bolag, och den tråden är hur många människor först lärde känna produkten. Om det är så du hittade dem, fortsätt använda dem. Den här sidan är den saknade främre halvan av den loopen: att förankra agenten i förväg så att PR:en Greptile ser redan siktar på rätt filer.

Greptiles marknadsföringsmaterial leder med påståenden om granskningshastighet och att fånga buggar. Behandla dem som Greptiles egna påståenden, inte som oberoende verifierade siffror. Den här texten upprepar dem inte som fakta.

Språktäckning är samma sorts ärlighet. Greptile ramar in stöd som täckning av alla programmeringsspråk istället för en uppräknad lista; ett exakt antal anges inte. Maguyva publicerar stöd för över 279 språk och textbaserade teknologier, med en teknisk uppdelning (parserstödd AST kontra bara text) på sajten när frågan är teknisk. Det är olika produkter som gör olika påståenden. Blanda inte ihop dem.

Greptiles priser anges inte i det material den här texten får använda. Betalplaner finns; se deras prissida. Maguyva tar betalt per arbetsyta, inte per plats. Planer börjar gratis. Prissidan listar de publicerade nivåerna om du behöver arbetsytesiffrorna.

Arbetsflöde

Tre namngivna steg. Utför dem i den här ordningen. Hoppa inte över något av dem första gången du provar paret.

1. Maguyva-kontext

Indexera ett repo du redan känner till. Anslut MCP-klienten du redan skriver i — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, eller en annan MCP-kompatibel klient. Maguyva har installationsguider för 24 dokumenterade MCP-klienter och kan ansluta till andra klienter som stöder standard MCP-konfiguration.

Ställ en fråga du kan bedöma innan någon skriver en rad. ‘Var hanteras sessionsutgång, och vad anropar det?’ är ett bättre första drag än ‘fixa auth’. Kräv citat. Öppna file.ext:line-resultaten. Följ symbolen. Bekräfta beroendet du är på väg att röra.

Maguyva exponerar 11 kundvända MCP-verktyg för sökning, symboler, beroendeanalys, filhämtning, repo-kontext och deterministiska hjälpverktygsflöden. Fyra hämtningslägen smälts samman till rankade resultat; find_symbol är ett separat verktyg när du redan känner till namnet. Dokumentationen beskriver den kortaste vägen: börja gratis, indexera ett repo du redan känner till, anslut klienten, ställ sedan en fråga du kan verifiera.

Ögonblicksbilder är tidsstämplade, så agenten kan avgöra vilken version av trädet den läser. Den ärliga begränsningen är osynkroniserat lokalt arbete. Om ändringen bara finns i ett arbetsträd och inte har pushats innehåller den värdbaserade kartan den ännu inte. Instruktionsfiler (CLAUDE.md, AGENTS.md) hör fortfarande hemma här, för konventioner och det som inte ska röras. De är ingen levande karta. Använd dem för beteende. Använd Maguyva för fakta.

Låt inte agenten öppna en PR innan citaten överlever kontakt med repot. Den grinden är hela poängen med det här steget.

2. Agentens PR

Samma agent skriver nu ändringen i klienten du redan betalar för. Maguyva är varken en editor eller en granskare. Agenten producerar fortfarande diffen. Du öppnar fortfarande pull requesten på GitHub eller GitLab som du redan gör.

Det som borde vara annorlunda är den första filen. PR:en borde namnge handlern som faktiskt implementerar beteendet, anroparen som kommer att gå sönder, och testet som kommer att misslyckas om ändringen är fel. Om steg 1 hoppades över kommer steg 3 att spendera sina kommentarer på en ändring som landat i fel paket. Greptile kan fortfarande hitta systemiska problem. Det borde inte dessutom behöva återhämta sig från en hallucinerad sökväg.

Håll PR:en avgränsad. En underbyggd första fil är inget tillstånd att skriva om modulen. Det här kompletterande paret fungerar när agenten gjorde ett jobb med en karta, och sedan bad en granskare göra ett annat jobb på ett avgränsat diff.

3. Greptile-granskning

Greptile är redan anslutet till repot via GitHub- eller GitLab-appen. På den nya pull requesten analyserar den ändringen med hjälp av den fullständiga repo-grafen den byggt, och publicerar fynd som kommentarer med föreslagna korrigeringar. Deras eget material sätter den genomgången till ungefär tre minuter.

Läs kommentarerna som du skulle läsa en noggrann lagkamrat: öppna den citerade platsen, avgör om fyndet är verkligt, agera sedan. Där Greptile erbjuder ‘Fix with your Agent’ skickar det problemet — filsökvägar, radnummer, föreslagen kod — till Claude Code, Codex, Conductor, Cursor, eller Devin. ‘Fix All’ skickar alla problem i granskningen på en gång. De levererar också en Greptile MCP och en Claude Code-plugin för den överlämningen. Maguyva finns inte på den namngivna mållistan; den frånvaron är inget problem. Maguyva har redan gjort sitt jobb i steg 1. Den kodande agenten som skrev PR:en är den som borde ta emot korrigeringspayloaden.

Förvänta dig brus de första 2-3 veckorna medan Greptiles inlärningssystem anpassar sig till kommentarerna ditt team faktiskt lämnar. Det är deras angivna tidslinje, inte en brist i paret. Mänsklig granskning stannar kvar i loopen. Greptile är den automatiserade första genomgången, inte sammanslagningsknappen.

Om en Greptile-kommentar pekar på en fil agenten aldrig frågade i steg 1 är det en användbar signal. Antingen missade kartan en anropare, eller så hoppade agenten över ett citat. Fixa utkastet enligt kommentaren. Avaktivera inte granskaren.

Hur du håller det här komplementet ärligt

Maguyva alltid först. En granskning av en PR med fel fil är fortfarande en granskning av fel fil.
Greptile alltid efteråt. Ett väl citerat utkast behöver ändå en genomläsning av diffet på hela systemets nivå.
Be inte Maguyva publicera PR-kommentarer. Det gör den inte.
Be inte Greptile vara agentens första hämtningslager medan den fortfarande väljer sökväg. Det är inte jobbet deras GitHub- eller GitLab-app är kopplad för.
Hitta inte på en bash-pipeline som ‘synkroniserar’ dem. PR:en är gränssnittet.
Verifiera båda sidor oberoende. Indexera ett repo du redan känner till. Ställ en fråga du kan verifiera. Öppna sedan en liten PR och läs vad Greptile faktiskt kommenterar.

Loopen är vanlig så snart den får ett namn. Kartan först. Agentens PR. Granskningen sedan. Varje produkt stannar på den sida av pull requesten den är bra på.

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

Ge en AI-agent kontext om ett stort repo utan en lokal indexerare

Fri, 14 Aug 2026 00:00:00 GMT

Ett stort repo får inte plats i ett kontextfönster, och om du någonsin pekat en laptop-indexerare mot ett riktigt monorepo vet du att det inte får bekväm plats där heller — RAM-minnet skjuter i höjden, den första indexeringen tar en timme, och din agent börjar ändå nästa session med att gissa vilka filer som spelar roll.

Det vanliga svaret är att köra en indexerare bredvid editorn, och för ett repo som får bekväm plats på en maskin är det ett bra svar. Om ditt monorepo redan indexeras snabbt i Cursor och det är det enda stället du behöver kartan, har den här texten inget att tillägga — hoppa över den.

Den här texten handlar om det andra fallet — när en agent behöver en sökbar karta över ett stort repo, och du inte vill köra en lokal indexerare för att få den.

När en lokal indexerare är fel verktyg

Ett lokalt index förutsätter att koden lever på maskinen som frågar den, och i verklig monorepo-skala spänns det antagandet även inom en enda editor. Repot är helt enkelt större än du vill hålla ‘varmt’ på en laptop: du arbetar i ett paket medan påverkansradien ligger tre kataloger bort, och en första kall indexering av ett träd på två miljoner rader är inte något du vill genomlida två gånger — varken på din egen maskin, eller på en CI-runner som aldrig tidigare klonat det trädet. Eller så borde en kollega kunna fråga samma karta som du, utan att vänta på att den egna maskinen ska kämpa sig igenom samma index.

Inget av detta är en anledning att kasta bort en bra editor-indexerare. Det är en anledning att dessutom ha en värdbaserad karta som vilken som helst av dina agenter kan fråga via MCP.

Och skalproblemet går djupare än ‘för många filer att klistra in’. På ett stort träd är den intressanta frågan nästan aldrig ‘visa mig den här filen’ — det är vilken fil, vilken symbol, vilka anropare, vilka tester. En agent som börjar med att lista src/ och läsa de tre första träffarna missar glatt handlern i apps/api och den genererade klienten i packages/sdk. Det du behöver är hämtning byggd från hela trädet, sedan rankad, sedan citerad.

Vad ‘kontext om ett stort repo’ egentligen betyder

Att dumpa filer i prompten är inte kontext — det är en mindre, sämre kopia av trädet. Det din agent verkligen behöver är att ställa frågor och få citerade svar tillbaka: var den här symbolen är definierad och vem som anropar den, vad som beror på modulen jag är på väg att ändra, vilken testfil som täcker det här beteendet, och hur trädet ser ut nu, inte förra kvartalet.

De svaren måste komma från ett index byggt från ditt repo, inte från modellens minne av andras repon, och indexet måste leva någonstans utanför agentens kontextfönster. För det här problemet borde det också leva någonstans utanför din laptop.

Ännu en sak instruktionsfiler inte kan göra åt dig: CLAUDE.md och AGENTS.md är rätt plats för konventioner och beteende, men de är inte en levande, rankad, sökbar karta över ett träd på två miljoner rader. Använd regler för beteende; använd repo-intelligens för fakta.

Vi bygger kartan i molnet, frågar den från vilken klient som helst

Maguyva är ett fjärranslutet MCP-lager för kodbaskontext. Du kopplar GitHub, väljer dina repon, och kan gå därifrån medan molnpipelines analyserar trädet, bygger symboler och grafkanter, och underhåller en rankad karta — aldrig en lokal indexerare.

När du pushar kod analyseras ändrade filer inkrementellt, och graf- och rankningslagren byggs om enligt ett schema: dagligen i gratisplanen, varje timme i betalplanerna. Varje ögonblicksbild är tidsstämplad, så din agent kan avgöra vilken version av trädet den läser. Den ärliga begränsningen här är osynkroniserat lokalt arbete — en ändring som bara finns i ditt arbetsträd, aldrig pushad, är ännu inte i den värdbaserade kartan.

Sedan ansluter du vilken klient du än redan använder genom att lägga till en API-nyckel i dess MCP-konfiguration. Det finns installationsguider för 24 dokumenterade MCP-klienter, och vilken annan MCP-kompatibel klient som helst som stöder standardkonfiguration kan också ansluta. Om Cursor är där du bor går Cursor-sidan igenom den vägen; samma server svarar Claude Code, VS Code, Windsurf, Codex CLI och resten.

Du byter inte editor. Du ger din agent en verktygsyta — 11 MCP-verktyg för sökning, symboler, beroendeanalys, filhämtning och repo-kontext — med täckning över 279 fler språk och textbaserade teknologier, vilket betyder mer än du tror på ett monorepo som slutade vara ett enda språk för länge sedan.

Svar kommer tillbaka underbyggda, som filsökvägar med radnummer. Semantisk, strukturell, graf- och textsökning smälts samman till rankade resultat, så att en fråga som ‘vad beror på parseConfig’ varken ger dig en grep-dump eller ett enda semantiskt utdrag, utan den handfull platser som verkligen spelar roll.

En konkret guide

Börja inte med att indexera hela företaget. Här är vägen som fungerar:

Välj ett repo du redan känner väl — ett paket du kan bedöma för hand är värt mer än det största trädet du har.
Börja gratis: 3 repon, 50k indexerade rader, alla 11 verktyg, ingen månatlig frågekvot. Om ditt representativa repo är större listar prissidan arbetsytenivåerna ($0, $19, $49, $149) efter indexerad omfattning — inte efter antal platser.
Anslut GitHub och vänta tills den första indexeringen är klar. Du kompilerar inget lokalt.
Anslut MCP-klienten — några rader konfiguration. Maguyva är en fjärransluten MCP-server, så det finns inga plugins, inga tillägg, och ingen andra editor att anamma.
Ställ en fråga du kan verifiera. ‘Vad beror på parseConfig?’ eller ‘Var hanteras utgången av inloggningssessionen?’ Öppna sedan de citerade file.ext:line-resultaten och kontrollera dem mot trädet framför dig.
Först efter att citaten överlever den kontakten låter du agenten redigera.

Om det första repot passar bra och ditt träd är stort, höj arbetsytan för att matcha dina indexerade rader och ombyggnadstakt. Människor och agenter delar samma användarantal — Maguyva tar betalt per arbetsyta, inte per plats — så att lägga till en tredje agent i loopen kostar dig ingenting.

Aktiveringstestet är detsamma som dokumentationen rekommenderar för varje första körning: indexera ett repo du redan känner till, ställ en fråga du kan verifiera. Ett stort repo förändrar inte testet; det gör bara en felaktig första fil dyrare.

Vad du bör hålla koll på efter anslutning

Håll koll på tre saker. Fräschhet: betalplaner byggs om varje timme, gratisplaner dagligen, och opushat lokalt arbete kommer inte att finnas i kartan — det är avvägningen du gör. Omfattning: indexera en representativ uppsättning repon, inte varje arkiverad fork; gratisnivån är medvetet dimensionerad för att ta reda på om svaren är värda att behålla. Och verifiering: en karta över ett stort repo som inte kan citera sökvägar och radnummer är bara en långsammare gissningsmaskin, så låt din agent visa platsen innan den levererar patchen.

Kör sedan samma test du skulle köra på ett litet repo. Indexera ett repo du redan känner till. Ställ en fråga du kan verifiera. Om kartan är verklig slutar din agent att börja från ett kallt träd.

// no laptop got hot building this map.

Varför din AI-kodande agent hallucinerar filsökvägar

Fri, 14 Aug 2026 00:00:00 GMT

Tecknet är inte en felaktig funktionskropp. Det är en självsäker ändring i en fil som inte finns, eller i en fil som finns men inte är den som implementerar beteendet.

Du bad om en fix för sessionsutgång. Agenten öppnade src/auth/session.ts. Den sökvägen är trolig. Den är också fel. Den verkliga handlern lever i apps/api/src/middleware/expiry.ts, omdöpt för två refaktoreringar sedan. Agenten ljög inte för dig. Den kompletterade en sökvägsformad sträng utifrån träningspriors plus vad som redan fanns i kontextfönstret.

Det här är det vanliga misslyckandemönstret på ett verkligt repo. Modellen kan skriva kod. Missen är att välja fel plats att skriva den på.

Varför agenter hittar på sökvägar

En kodande agent är en modell för nästa-token-förutsägelse med verktyg. När du säger ‘fixa sessionsutgång’ måste den namnge en fil innan den kan läsa eller patcha något. Om den inte redan har en förankrad karta konstruerar den en sökväg från:

Namngivningskonventioner den sett i andra repon. src/auth/session.ts är en vanlig form.
Filer redan i konversationen, som kanske är de du klistrade in förra veckan, inte de som spelar roll nu.
Kataloglistningar den råkade köra, ofullständiga på ett stort träd.
Instruktionsfiler. CLAUDE.md och AGENTS.md berättar för agenten hur den ska bete sig. De är inget levande index över symboler, anropare, eller aktuella sökvägar.

Ingen av dessa källor är en karta över det här repot, idag. Modellen fyller luckan på samma sätt som den fyller varje lucka: med en fortsättning med hög sannolikhet. Den fortsättningen ser ofta ut som en verklig sökväg. Ibland finns filen och ligger bredvid den rätta. Ibland fanns den på en gren som slogs samman förra månaden. Ibland har den aldrig funnits.

Grep räddar dig inte här om agenten aldrig söker efter rätt sträng. Agenten gissade en sökväg, läste sedan vad den sökvägen returnerade, och redigerade den sedan. Det första felsteget var sökvägen, inte patchen.

Att läsa filer är inte heller detsamma som att hitta de rätta. Claude Code, Cursor, Codex, och liknande verktyg kan öppna vad du än pekar dem mot. Frågan är om de tillförlitligt hittar rätt filer, de viktiga symbolerna, beroendena, testerna, och påverkansradien innan de redigerar. Filåtkomst utan en karta börjar fortfarande med en gissning.

Redigering av fel fil är ett hämtningsproblem

Behandla den påhittade sökvägen som en hämtningsmiss, inte som en karaktärsbrist.

Om agenten var tvungen att returnera path/file.ext:line innan den fick lov att redigera skulle två saker hända. För det första skulle du kunna öppna citatet och avvisa arbetet på tio sekunder. För det andra skulle agenten behöva fråga något som verkligen känner till trädet.

Det är jobbet för ett kodbaskontextlager. Enbart semantisk sökning räcker inte. Ett fragment som ‘låter som sessionsutgång’ kan ändå landa i ett avvecklat paket. Du behöver också exakt text när du känner till strängen, symbolsökning när du känner till namnet, strukturell sökning när du känner till formen, och en beroendegraf när du behöver anropare och påverkansradie.

Maguyva är det lagret för MCP-kompatibla kodande agenter. Det är ingen editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, och andra MCP-klienter stannar där de är. Agenten frågar en rankad karta innan den rör en rad.

Påståendet är medvetet blygsamt: färre hallucinerade ändringar. Maguyva tar inte bort modellens förmåga att gissa. Det ändrar standardens första steg från ‘hitta på en trolig sökväg’ till ‘be om rankade, citerade platser’.

Hur ett underbyggt svar ser ut

Ett användbart svar på ‘var hanteras sessionsutgång’ är inte ett stycke. Det är en kort lista med platser:

apps/api/src/middleware/expiry.ts:48 - handlern
apps/web/src/lib/auth-client.ts:112 - anroparen
apps/api/tests/expiry.test.ts:20 - testet som misslyckas om ändringen är fel

Du kan öppna de här raderna. Om de är fel stannar du. Om de är rätt kan agenten redigera. Verifieringen är poängen, inte en slogan.

Maguyva exponerar 11 kundvända MCP-verktyg för sökning, symboler, beroendeanalys, filhämtning, repo-kontext och deterministiska hjälpverktygsflöden. Fyra hämtningslägen (semantiskt, strukturellt, graf/beroende, och text) smälts samman till rankade resultat; symbolsökning är ett separat MCP-verktyg (find_symbol). Underbyggda svar kommer tillbaka med filsökvägar och radnummer, så att du kan bedöma dem mot trädet framför dig.

Dokumentationen beskriver den kortaste vägen: börja gratis, indexera ett repo du redan känner till, anslut klienten, ställ sedan en fråga du kan verifiera.

En loop som förändrar den första ändringen

Du behöver ingen ny arbetsflödesreligion. Du behöver ett extra steg innan den första skrivningen.

Ställ en fråga du redan kan bedöma. ‘Vilken kod hanterar inloggning och sessionsutgång?’ är bättre än ‘fixa auth’.
Kräv citat. Filsökväg och radnummer, inte en sammanfattning av ‘auth-modulen’.
Öppna de citerade filerna. Följ symbolen. Bekräfta beroendet du är på väg att röra.
Först då låter du agenten patcha.

Om steg 2 inte returnerar något användbart har agenten inte rätt att improvisera en sökväg. Den söker igen, eller så pekar du åt den. Precis den enda grinden är vad som ger färre hallucinerade ändringar. Modellen är samma modell. Kartan är vad som har förändrats.

Instruktionsfiler spelar fortfarande roll. Behåll dem. Använd dem för konventioner, granskningsregler, och det som inte ska röras. Be dem inte vara indexet. En CLAUDE.md som listar tre viktiga kataloger blir föråldrad veckan efter en paketuppdelning. En sökbar karta uppdateras när repot uppdateras.

Ett besläktat misslyckande är nästan-rätt-filen: agenten öppnar auth.ts när beteendet lever i auth-client.ts, eller patchar en genererad fil istället för källan, eller redigerar kopian i packages/legacy eftersom namnet stämde. Citat gör inte de här misstagen omöjliga. De gör dem synliga innan diffet landar.

Vad en karta inte fixar åt dig

Var nykter om vad du får. En underbyggd karta gör inte varje ändring korrekt — din agent kan fortfarande skriva en dålig patch i exakt rätt fil. Om din kodbas lutar sig mot dynamisk dispatch, reflektion, eller monkey-patching kommer vissa symbolsökningar att returnera magrare än du skulle vilja, eftersom det är vad körtidsindirektion gör med varje statiskt index. Och om du hoppas på en procentandel — ‘hallucinerade sökvägar minskade med X%’ — hittar du den inte här, eftersom ingen ärligt kan mäta det talet för ditt repo förutom du själv.

Det du kan förvänta dig är smalare och mer användbart: agenten slutar öppna sina ändringar med en gissad sökväg. Det första steget blir förankrat i en verklig karta, och det är därifrån färre hallucinerade ändringar kommer. Allt efter citatet — att läsa diffet, bedöma patchen — är fortfarande ditt jobb, precis som det alltid varit.

Testet kostar dig nästan ingenting: indexera ett repo du redan känner till och ställ en fråga du kan verifiera. Börja med en sökväg du redan blivit bränd av. Om citaten är fel ser du det omedelbart. Om de är rätt har din agents nästa ändring en bättre plats att landa på.

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

Varför vi uppgraderade kodsökningen till voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Benchmarksiffrorna i det här inlägget speglar RTEB-topplistorna vid publicering (juni 2026). Topplistor rör sig; behandla rankningarna som en ögonblicksbild, inte ett permanent faktum.

Semantisk sökning är bara så bra som inbäddningarna under den.

När en agent frågar Maguyva “var hanterar vi återförsök” grepar den inte efter ordet “retry”. Den frågar efter betydelsen — backoff-loopen, circuit breakern, det som omsluter ett instabilt anrop. Den frågan besvaras av en vektormodell som förvandlar kod till en punkt i rymden och hittar grannarna. Väljer man en bättre modell blir varje semantisk sökfråga i produkten bättre utan att det märks.

Så vi bytte vår. Från och med juni 2026 körs Maguyvas kodinbäddningar på voyage-4-large, som ersätter voyage-code-3.

Benchmarket

Vi tog inte det här beslutet på känn. Den offentliga Retrieval Embedding Benchmark (RTEB) rankar inbäddningsmodeller på verkliga hämtningsuppgifter, och på dess Code-topplista ligger voyage-4-large på förstaplats totalt (90,86) — före gemini-embedding-2-preview (90,26) och, anmärkningsvärt, före modellen vi redan använde, voyage-code-3 (89,73, plats 3).

Det är ett litet absolut gap. Men det är ett gap åt rätt håll, på ett offentligt benchmark, på exakt den uppgift vi bryr oss om: att hitta kod utifrån dess betydelse.

Avvägningen vi accepterar: binär kvantisering

Här är delen de flesta “vi uppgraderade vår modell”-inlägg utelämnar.

Maguyva lagrar inte fullprecisionsvektorer. Vi lagrar binärt kvantiserade inbäddningar: varje 2048-dimensionell vektor komprimeras till en 2048-bitars signatur — 256 byte per vektor. De signaturerna söks med Hamming-avstånd, indexerade och partitionerade per tenant.

Det är en avsiktlig avvägning. Binär kvantisering ger upp viss hämtningsprecision i utbyte mot dramatiskt mindre lagring och snabb, billig avståndsmatematik utan en separat vektordatabas att driva. För en produkt som indexerar hela repositorier per arbetsyta väger den ekonomin tyngre än att pressa ut den sista bråkdelen av en benchmarkpoäng.

voyage-4-large passar den här designen utan att tvinga fram en migrering av lagringslagret: den producerar 2048-dimensionell utdata, precis som voyage-code-3, så våra bit(2048)-kolumner och Hamming-sökvägen ändrades inte. Modellen blev bättre; schemat stod kvar.

Kod var bara början

Maguyva är ett kodintelligensverktyg. Men vi är också vår egen första kund, och vi riktar det mot något annat: markdownen som lever i våra repon vid sidan av koden. Arkitekturbeslutsregister, runbooks, kontrakt, finans- och policydokument — allt versionshanterat i Git, allt bakom samma MCP-server, ett semantiskt index över dokumenten, inte bara källkoden.

Det är exakt därför voyage-4-larges bredd spelar roll. På samma RTEB-familj av topplistor ligger den på förstaplats inom finans, förstaplats inom sjukvård, och förstaplats i övergripande texthämtning — före Googles Gemini Embedding, Coheres Embed v4, och OpenAIs text-embedding-3-large. (Voyage är en av skaparna av RTEB, så vi läser det som en stark offentlig signal snarare än en helt neutral domare — men den benchmarkas direkt mot alla stora kommersiella modeller, på privata hold-out-set.) Samma index som hittar rätt funktion åt en agent hittar rätt klausul i ett kontrakt eller rätt rad i en policy — och på de domänerna är voyage-4-large inte en kompromiss, det är ledaren.

Varför vi betalar för premiuminbäddningar

Det finns ett billigare sätt att göra sökning på, och mycket av det är gratis. Lexikal sökning — BM25 och dess släktingar — matchar nyckelord, körs lokalt och kostar ingenting. Öppna inbäddningsmodeller som BGE, Nomic och embeddinggemma ger genuint hyggig semantisk hämtning, och man kan self-hosta dem för priset av en GPU. Maguyva använder den gratis sidan också: varje sökfråga slår ihop text-, AST-, graf- och semantisk sökning. Det vi inte snålar på är det semantiska lagret.

Vi betalar per token för premiuminbäddningar — voyage-4-large — istället för att self-hosta en gratis modell, av två skäl. För det första kan nyckelordssökning ensam inte besvara “var hanterar vi återförsök” när koden säger backoff och circuit breaker och aldrig säger ordet “retry” — mening är hela poängen med inbäddningen, och på de domäner vi betjänar ligger de öppna modellerna efter premiummodellerna: några poäng efter på allmän text, och längre efter inom nischer som kod, kontrakt och finans. För det andra formar hämtningskvaliteten enligt vår erfarenhet det slutgiltiga svaret mer än modellen i andra änden gör — en stark agent som får fel kontext svarar ändå fel, och den ser aldrig dokumentet den aldrig fick.

Så premiuminbäddningar är en per-token-räkning som skalar med varje repo och dokument vi indexerar — och vi betalar den med flit. För resultatet våra användare får, rätt funktion eller rätt klausul, tycker vi att den avvägningen är värd det.

Den ärliga delen

Voyages egen dokumentation märker fortfarande voyage-code-3 som den kodoptimerade modellen. Så varför byta?

Eftersom vi läser det offentliga benchmarket, inte bara leverantörens modelltabell, och benchmarket satte voyage-4-large i topp för kodhämtning. Det här var ett framåtblickande beslut: ta den nyare, generellt starkare modellen och validera den mot en offentlig topplista på de uppgifter som spelar roll. Vi känner oss trygga med den satsningen eftersom beviset är brett — voyage-4-large vinner inte bara inom kod, den leder inom finans, sjukvård och övergripande hämtning också.

Den osynliga grunden

Varje verktyg vi exponerar — semantisk sökning, task-context-insamling, grundade frågor och svar — bygger i grunden på sökning. När hämtaren förbättras får agenten i andra änden bättre bevis, gör färre felaktiga vägval, och förankrar sina svar i rätt kod — eller rätt klausul, eller rätt policy. En skarpare inbäddningsmodell är inte en flashig funktion. Det är grunden för allt annat, och den förbättrade vi just. Du kommer inte märka det. Det är poängen.

Rekursiv självförbättring för språk: att slita fram kodintelligens över ~280 språk

Tue, 26 May 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publicering (maj 2026). Se vår teamsida för aktuella siffror.

Maguyva extraherar symboler, referenser och en beroendegraf ur källkod på ungefär 280 språk. Varje språk har en skräddarsydd tree-sitter-hanterare — queries, heuristik, specialfall — och varje hanterare kan vara subtilt fel på sitt eget sätt. Ett metodanrop som avges som en läsning. En funktion som tillskrivs fel omslutande scope. En relation som helt enkelt inte finns.

Det går inte att granska för hand. Inget team kan läsa extraktionsutdata över 280 grammatiker och upptäcka de dåliga kanterna. Så den intressanta frågan är inte “är vår extraktion korrekt” — den är “hur tar man reda på att den är fel, i den här skalan, utan en människa i varje loop.” Vårt svar är rekursiv självförbättring för språk: en kvalitetsloop driven av språkagenter, en LLM som fungerar som domare, och en regel vi ständigt lär oss om igen: grönt är inte samma sak som korrekt.

Grönt är inte korrekt

Varje språk har en fixture-svit, och en releasegrind poängsätter den över fem dimensioner — noggrannhet, strukturell integritet, fullständighet, kvalitet och prestanda. Ett språk blir GRÖNT bara när precisionen är ≥ 0,95, recall ≥ 0,99 och F1 ≥ 0,97 på dess fixtures, med minst 20 förväntade kanter för statistisk tillförlitlighet. Under det är det GULT eller RÖTT, och det skeppas inte.

Den grinden är nödvändig men inte tillräcklig. Fixtures valideras mot fixtures vi själva skrivit. De kodifierar de fall vi redan tänkt på. En hanterare kan vara felfri på sina fixtures och ändå förvanska ett mönster som bara dyker upp i verklig kod — ett makroidiom, en generisk-bunden metod, en språkfunktion ingen skrev en fixture för. GRÖNT betyder att fixtures godkänns. Det betyder inte att ett verkligt repositorium extraheras rent. Så loopen måste lämna fixtures bakom sig och undersöka kod i verkliga repositorier.

Innerloopen: stickprov, döma, fixa, bevisa

Kärnloopen kör ett språk i taget:

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

Ett par saker gör att det här fungerar istället för att stampa på stället.

Domaren är agenten, inte ett API-anrop. När vi säger “LLM som domare” menar vi att språkagenten själv läser varje utvald kant mot den verkliga källan och klassificerar den enligt en fast bedömningsmall med fem kategorier: är kanten korrekt, en falsk positiv, rätt relation med fel typ, kopplad till fel scope, eller bärande på fel metadata? Den bedömningsmallen är helt avgörande — “23 % felfrekvens” är meningslöst tills man vet om det är verkliga defekter eller domaren som räknar fel.

Fixa en sak, bevisa den sedan. Varje iteration ändrar exakt en redigerbar tillgång, kör sedan om mot ett fast testupplägg och behåller ändringen bara om F1 förbättras och omklassificeringen ser bättre ut. Om inte, återställs den. Ingen bunt spekulativa ändringar, inget “borde bli bättre”. En ändring förtjänar sin plats eller så är den borta. Och när en fix håller, befordras den in i fixture-sviten — så att buggen den fixade aldrig tyst kan komma tillbaka. Det befordringssteget är det som gör loopen rekursiv snarare än bara repetitiv: varje pass stärker testoraklet som nästa pass valideras mot.

Lärdomen vi ständigt lär oss om igen: mätvärden överrapporterar

Här är fällan, och vi gick rakt in i den. De sekundära korpusmätvärdena — hur ofta ett extraherat mål saknar en upplösbar symbol, hur många symboler ser “föräldralösa” ut, och så vidare — överrapporterar problem massivt. De är mestadels paradigmartefakter, inte buggar.

Det renaste exemplet: llvm visade en gång en 73-procentig andel “källa-utan-symbol” och stämplades som katastrofalt. Vi grävde i det. Den verkliga noggrannheten var 98,5 %. De “saknade symbolerna” var nästan uteslutande legitima externa referenser — anrop in i standardbiblioteket, in i ramverk, in i kod som ligger utanför repot. Måttet mätte en egenskap hos språket, inte en defekt i hanteraren. Språk som Zig, COBOL och Odin visar 65–70 % “föräldralösa” och är helt korrekta; COBOL hade noll verkliga fel.

Om vi hade låtit de siffrorna styra arbetet hade vi lagt veckor på att “fixa” hanterare som redan var korrekta och ignorerat de språk som hade tysta, verkliga buggar. Slutsatsen är rättfram: de aggregerade mätvärdena är på sin höjd en grov triage-signal. Den verkliga kvalitetssignalen är stickprovet med kantklassificering — att titta på faktiska kanter i faktiska repositorier och döma dem en och en. Data före intuition, men bara när man vet vilken data som talar sanning.

Ytterloopen: en flotta, inte ett maraton

Ett språk i taget skulle ta en evighet över 280 av dem, så innerloopen omsluts av en ytterloop som kör många parallellt.

   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

Varje agent arbetar i en engångs-worktree så att de inte kan gå på varandras tår. Orkestreraren integrerar deras fixar en i taget, var och en bakom en regressionskontroll mot hela manifestet: en ändring som hjälper sitt eget språk men tyst förstör tre andra landar inte. Integrationen är grindad och bekräftad innan något pushas — regressionsgrinden avgör vad som är säkert, en människa avgör fortfarande vad som skeppas. Sedan roterar poolen till nästa uppsättning språk och alltihop körs igen.

Vad som fortfarande är ofullständigt

Domaren kan ha fel, och felaktigheten har en riktning: en agent som kör med för lite kontext överrapporterar. I en batch flaggades åtta språk med 5–20 % fel; vid granskning var bara ett fall en verklig språkspecifik bugg — resten var domarmisstag från att missa språkets egen semantik (en källkodsrad som legitimt avger flera kanter, parameterbindningar modellerade som tilldelningar, referens-per-identifierare-språk). Det är därför vi tar stickprov med två frön och korskontrollerar, och varför en oenighet mellan domaren och fixtures behandlas som den mest intressanta signalen, inte en avgjord dom — ibland är det fixturen som har fel.

Vi är också ärliga om målet. Målet är noll verkliga fel, punkt slut — men “noll” är en riktning vi sliter oss mot, språk för språk, inte en ruta som bockas av. Det finns alltid ännu ett repo med ännu ett idiom.

Förtjänat, inte påstått

Allt Maguyva gör för en agent — hitta en symbol, spåra ett beroende, besvara en fråga med citerad kod — vilar på att extraktionen under är korrekt. Över 280 språk kan “korrekt” inte påstås; det måste kontinuerligt förtjänas mot verklig kod. Loopen är hur vi förtjänar det: en autonom cykel av stickprov och fix som behandlar sina egna mätvärden med misstänksamhet, bevisar varje ändring och gör varje fix till ett skydd mot nästa regression. Det är inte glamoröst. Det är arbetet som låter oss säga “vi stöder ditt språk” och mena det. Grönt är lätt. Korrekt är förtjänat.

Multimodal fusionssökning: att välja rätt hämtare för varje sökfråga

Wed, 15 Apr 2026 00:00:00 GMT

Historisk designnot: den här artikeln från april 2026 beskriver dåtidens routningsdesign, inte dagens standardbeteende. Rättelsen från september nedan gäller endast ett mätpåstående. För aktuell routning, förval och uttrycklig styrning av modaliteter, se Så fungerar det.

Sökfrågor kan vara av olika slag.

“var är parseConfig definierad” vill ha en exakt symbol — en precis plats, snabbt. “hur fungerar autentisering” vill ha mening — spridningen av relaterad kod som förklarar ett koncept. “vad går sönder om jag ändrar den här funktionen” vill ha beroendegrafen. “hitta strängen ECONNREFUSED” vill ha en bokstavlig träff, ingenting smart.

Grep är utmärkt för bokstavliga träffar och användbart för viss referensjakt, men det är ingen beroendegraf och det förstår inte mening. Inbäddningar täcker den semantiska sidan, men de är fel verktyg för exakta strängar och konsekvensanalys. De flesta kodsökverktyg väljer en motor och tvingar varje sökfråga att leva med det valet. Maguyva låser sig inte vid en enda motor. Det räknar ut vilken typ av fråga du ställde, och blandar sedan fyra hämtare i den proportion frågan förtjänar.

Fyra hämtningslägen

Under huven finns fyra oberoende sätt att hitta kod:

semantisk — vektorsökning över Voyage-binärinbäddningar; hittar kod efter mening.
text — trigrammatchning; hittar bokstavliga strängar, felmeddelanden, exakta identifierare.
strukturell — AST-queries; hittar definitioner, signaturer och språkkonstruktioner.
graf — beroendegrafen; hittar anropare, anropade och påverkansradie.

Var och en är stark på en egen klass av frågor. Konsten ligger i att avgöra hur mycket man ska lita på var och en för sökfrågan framför sig.

Avsiktsklassificering

Innan någon hämtning körs sorterar en lättviktig klassificerare sökfrågan i en av sex avsikter, med en konfidenspoäng. Den är medvetet billig — ordnad heuristik, första träff vinner — eftersom den körs i den tidskritiska kodvägen och bara lägger till en millisekund eller två:

börjar med def , class , func , import … → find_definition (konfidens 0,95)
“who calls”, “usages of”, “references to” (vem anropar, användningar av, referenser till) → find_references (0,90)
“impact”, “blast radius”, “what depends on” (påverkan, påverkansradie, vad som är beroende av något) → impact_analysis (0,90)
en citerad "string" eller ett felmeddelande-token som traceback → exact_match (0,85–0,90)
en identifierare av typen CamelCase eller snake_case → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” (hur, varför, förklara, arkitektur) → understand_code (0,75)
inget matchar → understand_code, låg konfidens (0,40)

Varje avsikt bär en viktprofil över de fyra hämtningslägena. Det här är de verkliga talen:

Avsikt	semantisk	text	strukturell (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å “var är parseConfig definierad” lutar tungt mot AST (0,6). “hur fungerar auth” lutar mot semantiska vektorer (0,5). “vad beror på det här” är nästan helt graf (0,7). “hitta ECONNREFUSED” är nästan helt trigram (0,9), med inbäddningsmodellen helt avstängd — eftersom semantisk likhet är exakt fel verktyg för en exakt sträng.

Den snabba vägen och den sammanslagna vägen

När klassificeraren är säker — poäng ≥ 0,85 — och sökfrågan är en normal sådan, hoppar Maguyva över fusion helt och dirigerar direkt till det enda dominerande hämtningsläget. “var är X definierad” behöver inte fyra hämtare; den behöver AST-indexet, direkt. Den direkta vägen rapporteras tillbaka som fusion_strategy: "direct".

Allt tvetydigt går genom fusion. De fyra (eller tre, i standardinställningen) hämtningslägena körs parallellt, var och en returnerar sin egen rankade lista, och vi kombinerar dem.

Viktad Reciprocal Rank Fusion

Att slå samman heterogena hämtare är svårare än det låter: en cosinuslikhet på 0,82 och en trigrampoäng på 137 och en grafcentralitet på 0,004 ligger inte på samma skala, så man kan inte bara addera dem. Reciprocal Rank Fusion kringgår problemet genom att kasta bort de råa poängen och bara behålla den placering varje motor tilldelade. Ett resultats bidrag från ett hämtningsläge är:

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

där rank är dess position i det hämtningslägets lista och k är en utjämningskonstant. Bidrag summeras över hämtningslägen för varje resultat som mer än en motor hittade — samstämmighet mellan hämtare flyter naturligt upp till toppen. Vi använder k = 40 i standardinställningen och 60 för thorough (quick körs enbart semantiskt, så fusion aktiveras aldrig där). Det ursprungliga RRF-arbetet landade på k = 60 för generell hämtning; vårt standardvärde ger något större tyngd åt resultat som rankas högt i flera hämtningslägen — och vi rekommenderar inte att man finjusterar den för hand.

Utöver det bär resultaten en grafviktighetsboost. Ett nav — en funktion hela kodbasen lutar sig mot — bör rankas högre än en mindre känd lövnod även vid samma textuella relevans, så vi multiplicerar varje bidrag med:

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

Centralitet kommer från pipelinens förberäknade PageRank-/gradmått, och boosten är begränsad till 1,5× så att en populär funktion inte helt kan begrava en mer relevant men obskyr sådan. Slutligen degraderar vi resultat från vendor-, build- och arkivsökvägar, och tar bort dubbletter och behåller det bästa kodavsnittet per fil.

Vad som fortfarande är ofullständigt

Avsiktsklassificeraren är en samling reguljära uttryck, inte en tränad modell. Den hanterar vanliga frågeformer med heuristiker, och en tvetydig sökfråga faller tillbaka på understand_code och en blandning med tonvikt på semantik. En tidigare version av det här inlägget beskrev en minskning av andelen sökningar utan resultat från cirka 15 % till under 5 % som uppnådd. Förslaget från december 2025 angav i själva verket ett uppskattat utgångsläge och ett mål; ingen underbyggande uppsättning sökfrågor eller mätdokumentation har tillhandahållits. Vi drar tillbaka påståendet om en uppnådd förbättring; se källunderlaget och rättelsen (på engelska). Vi har inte ersatt klassificeraren med en tränad modell eftersom den billiga versionen är snabb och tillräckligt bra för sin avsedda routningsuppgift, och eftersom en felaktig men självsäker klassificerare är sämre än ett ärligt reservalternativ. Vikterna är handvalda apriorivärden, inte inlärda från klickdata som vi inte samlar in.

Ställ frågan utan att välja verktyg

En agent ska inte behöva veta om den ska ta till grep eller inbäddningar eller anropsgrafen — den ska ställa sin fråga i vanliga ord och få rätt svar. Multimodal fusion är det som låter find_symbol, semantisk sökning och beroendeanalys ligga bakom en och samma sökyta: systemet läser frågans form och sätter tyst ihop rätt hämtare för den. Modellen som poängsätter inbäddningarna spelar roll, men det gör även att veta när man inte ska använda dem. Att välja rätt verktyg för varje sökfråga är sin egen sorts kvalitet, och det är en vi hellre äger själva än skjuter över på anroparen.

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

Agentobservabilitet: hooks, Alloy och Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agentsystem kraschar på märkliga sätt.

Ibland är modellen problemet. Ibland är verktyget problemet. Ibland fungerar din MCP-server perfekt, men agenten valde fel specialist, eller lade halva sessionen på skalarbete du inte förväntade dig, eller drog på sig kostnader i det tysta i en loop som såg produktiv ut utifrån.

Om du inte kan se skillnaden driver du egentligen inte ett agentsystem. Du gissar.

Så vi byggde en observabilitetsstack för vårt eget arbetsflöde: Claude Code, Codex, Claude-hookhändelser, Codex-notify-händelser, inbyggd OpenTelemetry, Grafana Alloy och Grafana Cloud på andra sidan.

Det intressanta är inte “vi byggde en instrumentpanel”. Det intressanta är att vi var tvungna att dela upp telemetrin i två separata strömmar, eftersom ingen enskild källa gav oss hela bilden.

Problemet: agenttelemetri är fragmenterad

Moderna kodningsagenter avger redan viss telemetri. Det hjälper, men det räcker inte.

Inbyggd OTEL är bra på att besvara frågor som:

Hur många förfrågningar gjorde vi?
Vad kostade en session?
Var finns spannen och spårningarna?
Ökade latensen plötsligt?

Den är betydligt sämre på att besvara frågor som:

Vilken MCP-server lutade agenten sig mot?
Låg det här felet i Bash, ett inbyggt filverktyg, eller ett MCP-anrop?
Vilken skill aktiverades egentligen?
Vilken typ av subagent dirigerades ut?
Utförde sessionen användbart arbete, eller stampade den bara på stället?

Den andra kategorin av frågor ligger närmare hooks än spårningar.

Men motsatsen gäller också: några av de viktigaste prestandafrågorna ligger närmare spårningar än hooks.

Om du vill veta var latensen faktiskt ackumulerades, vilka spann som var långsamma, eller om sessionen brände tid på modellanrop kontra verktygsexekvering, behöver du spårningsdata lika väl som semantiska händelser.

Arkitekturen vi landade i

Vi kör två telemetrivägar parallellt.

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 uppdelningen är avsiktlig.

Den är också asymmetrisk. Claude Code ger oss en mycket rikare yta av livscykelhooks. Codex ger oss inbyggd OTEL plus en notify-yta, så vi normaliserar mindre detaljerade händelser när en agenttur avslutas till samma loggschema istället för att låtsas att båda körtiderna exponerar samma kontroller.

Inbyggd OTEL ger oss basströmmen: loggar och spårningar från själva körtiden, plus mått där körtiden faktiskt avger dem.

Hook- och notify-händelser ger oss det semantiska lagret: sådant som PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, och den klassificerade metadata vi faktiskt bryr oss om när vi felsöker agentbeteende. Claude Code bidrar med den rikare händelseströmmen här. Codex bidrar med en tunnare men fortfarande användbar normaliserad ström.

Varför hooks finns över huvud taget

Vår hook-pipeline berikar händelser innan de når Loki.

Istället för att bara säga “ett verktyg kördes” klassificerar vi händelsen i fält som:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: vilken MCP-backend som hanterade anropet
bash_cli: skalkommandots familj
subagent_type: vilken typ av specialist som dirigerades ut
agent_tool: om källan var Claude Code eller Codex

Det betyder att vi kan ställa frågor som spelar roll operativt:

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

Det där är inte skrytfält. De är skillnaden mellan “agenten kändes långsam” och “agenten spenderade de senaste tio minuterna i skaltunga git-operationer med hög andel verktygsfel”.

En implementationsdetalj som ser konstigare ut än den är: den delade Loki-strömmen använder fortfarande service_name="claude-code-hooks" som etikett även när händelsen kom från Codex. Den verkliga uppdelningen mellan körtiderna sker på agent_tool.

Varför Alloy sitter i mitten

Grafana Alloy är inte bara en vidarebefordrare i den här uppsättningen. Det är policygränsen.

Vi pekar den inbyggda OTEL-strömmen från Claude Code och Codex mot en lokal Alloy-proxy på localhost:4318, och låter sedan Alloy städa upp payloaden innan den vidarebefordras till Grafana Cloud.

Det spelar roll eftersom rå agenttelemetri är full av högkardinalitetsfält som är användbara för analys men förskräckliga som indexerade etiketter:

session_id
prompt_id
tokenantal
varaktigheter
blobbar med verktygsparametrar

Om du indexerar allt får du en etikettexplosion och en dålig dag.

Så Alloy gör tre saker åt oss:

Håller en mycket liten uppsättning lågkardinalitetsetiketter indexerade.
Flyttar brusiga men användbara fält till strukturerad metadata.
Slänger rent brus helt och hållet.

Den viktiga idén är enkel: observera mer, indexera mindre.

Varför hookströmmen går förbi Alloy

Hookströmmen är redan formad för Loki.

När send_event.py skickar en händelse har vi redan bestämt vilka fält som förtjänar etikettbehandling och vilka som hör hemma i den strukturerade JSON-kroppen. Den strömmen går rakt till Grafana Clouds OTLP-gateway istället för att ta ytterligare ett varv genom Alloy.

Systemet har alltså en tydlig arbetsfördelning:

Alloy tämjer den råa inbyggda OTEL-strömmen.
Hook-berikning gör semantiska händelser sökbara.

Det håller arkitekturen enklare än att försöka tvinga allt genom en enda väg.

Vad instrumentpanelen faktiskt visar

Skärmdumpen nedan är från en av observabilitetspanelerna bakom vårt agentarbetsflöde. Det är inte ett benchmark, och siffrorna är bara en ögonblicksbild. Poängen är formen på datan: aktivitetsflöde, verktygsanrop, fel, prompter, och uppdelningar efter agent, inbyggda verktyg, MCP-användning, skalkommandon och skills.

Det användbara är att den här panelen lever på samma Grafana-stack som resten av agenttelemetrin. Vi kan filtrera på källagent och verktygsfamilj och titta över körtiderna utan att behöva uppfinna en separat observabilitetsberättelse för varje system.

En av de skarpa instrumentpanelerna bakom vårt agentarbetsflöde. Den här skärmdumpen är bara ett utsnitt av en delad Grafana-stack som även tar emot telemetri från våra andra agentkörtider och system. Klicka på bilden för full upplösning.

Varför spårningar spelar större roll än de först verkar

Loggar berättar vilken kategori av arbete som skedde. Spårningar berättar hur arbetet utspelade sig över tid.

Den distinktionen spelar roll i agentsystem eftersom “långsamt” är för trubbigt för att vara användbart.

En spårning kan berätta om smärtan kom från:

modellens latens
verktygsexekveringstid
upprepade återförsök
en särskilt kostsam MCP-interaktion
en lång svans av små operationer som såg ofarliga ut var för sig

I praktiken använder vi hookströmmen och Tempo-spårningar tillsammans.

Hook-loggar svarar på: vilken typ av sak hände?
Spårningar svarar på: vart tog tiden vägen?

Kombinationen är det som förvandlar observabilitet från en instrumentpanel till en förklaring.

Var Codex passar in

Codex är en del av samma stack, men det är inte identiskt med Claude Code.

För Codex kopplar vi in två delar:

Inbyggd OTEL från Codex till Alloy
En notify-webhook till codex_notify.py, som mappar avslutade agentturer till samma Loki-schema vi använder för hook-händelser

Det ger oss ett enhetligt filter som agent_tool="codex-cli" inom samma loggström.

Den ärliga brasklappen: Codex notify-payload är i dagsläget tunnare än Claude Codes hook-payload, eftersom det inte är samma typ av integrationsyta. I vår nuvarande uppsättning kan avslutade agentturer i Codex normaliseras till det delade schemat, men rik verktyg-för-verktyg-extraktion är fortfarande bättre i den inbyggda OTEL-strömmen än i notify-bryggan.

Det är inte ett skäl att undvika inlägget. Det är själva poängen med inlägget. Riktiga observabilitetssystem byggs ihop av ofullständiga signaler.

Grafana över MCP ändrar spelplanen

Det större skiftet är att Grafana inte bara är en plats människor besöker i en webbläsare.

I det här repot exponerar vi också Grafana via MCP. Det betyder att en agent kan fråga Loki, Prometheus och Tempo direkt istället för att vänta på att en människa manuellt ska inspektera instrumentpanelerna först.

Det förvandlar observabilitet till ett aktivt underlag i arbetsflödet.

En agent kan fråga:

Vilka verktygsfamiljer misslyckades mest den senaste timmen?
Vilken MCP-server dominerade en session?
Minskade nyligen genomförda ändringar verktygsfelen, eller flyttade de bara arbetet till mer skaltunga vägar med samma misstag?
Vilka spårningar visar högst latens eller upprepade återförsök?

När du har det där är du väldigt nära en självförbättringsloop.

Från instrumentpanel till återkopplingsloop

Det här är den del vi tycker är mest intressant.

När observabilitetsstacken går att fråga från agentlagret slutar telemetrin vara en passiv rapporteringsyta och blir en styrsignal.

Loopen ser ut så här:

Agentaktivitet avger spårningar, mått och berikade hook-loggar.
Grafana lagrar beviset i Loki, Tempo och Prometheus där mått finns.
Agenter söker i det underlaget via Grafana MCP.
Systemet identifierar dålig verktygsmix, sköra skills, svag dirigering eller skaltunga arbetsflöden som fortsätter producera undvikbara misstag.
Agenter eller operatörer justerar prompter, agentkonfigurationer, skill-beskrivningar, dirigeringsregler eller verktygsåtkomst.
Nästa session ger en ny telemetriform, och cykeln upprepas.

Så tar man sig från “intressant instrumentpanel” till “mätbart förbättringssystem”.

Målet är inte att maximera en verktygskategori. Det är att landa i rätt mix av CLI, inbyggda verktyg, MCP-anrop och skills för det arbete som faktiskt utförs.

Vad det här låter oss besvara

När båda körtiderna landar i samma Grafana-stack kan vi besvara operativa frågor mycket snabbare:

Är fel koncentrerade till en verktygsfamilj?
Skapar skaltunga arbetsflöden undvikbara misstag där ett verktyg på högre nivå borde finnas?
Vilka MCP-servrar bär arbetsbördan?
Betalar vi för agentaktivitet som inte producerar meningsfulla framsteg?
Är en session ohälsosam på grund av modellen, verktygen eller orkestreringslagret?

Det här är särskilt användbart i arbetsflöden med flera agenter, där “agenten var upptagen” nästan inte säger någonting.

Om en specialist ständigt dirigeras ut och producerar hög felfrekvens är det ett dirigerings- eller promptutformningsproblem.

Om en MCP-server dominerar alla anrop kan det vara god arkitektur, eller ett tecken på att allt annat är dödvikt.

Om verktygsfel ökar samtidigt som kostnaden förblir hög har du ett operativt problem, inte ett kvalitetsproblem.

Om skalarbete fortsätter misslyckas på förutsägbara, undvikbara sätt där ett verktyg på högre nivå borde finnas, är det en produktsignal.

Om en skill aktiveras ständigt men inte förbättrar utfallet är det en prompt- eller dirigeringssignal.

Den verkliga lärdomen

Den djupare lärdomen här är att agentobservabilitet behöver både körtidstelemetri och arbetsflödestelemetri.

Körtidstelemetri berättar vad systemet gjorde.

Arbetsflödestelemetri berättar vad agenten trodde att den gjorde.

Vi behöver båda.

Om du bara behåller spårningar och räknare missar du det semantiska lagret. Om du bara behåller hook-händelser missar du latens, spann och den bredare körtidsbilden.

Och om du behåller båda men aldrig matar tillbaka dem till agentlagret har du övervakning, inte anpassning.

Kombinationen är det som gör systemet tillräckligt förklarbart för att driva och tillräckligt justerbart för att förbättra.

Vad som fortfarande är ofullständigt

Det finns fortfarande skarpa kanter.

Inte varje hook-händelse innehåller den varaktighets- och tokendata vi skulle vilja ha.
En del av de bästa tidsvyerna kommer fortfarande från Tempo-spårningar, inte hook-loggarna.
Codex är idag mindre semantiskt rikt än Claude Code i den berikade händelseströmmen.
Skärmdumpen av instrumentpanelen är en levande driftsyta, inte en polerad marknadsföringsartefakt.

Den sista punkten är avsiktlig. Vi föredrar att visa den riktiga instrumentpanelen framför att låtsas att agentsystem magiskt förklarar sig själva.

Varför det här spelar roll för Maguyva

Maguyva handlar om att ge agenter bättre kodintelligens. Men när agenter väl utför användbart arbete uppstår omedelbart ett nytt krav: du behöver se hur de beter sig.

Sökkvalitet, dirigeringskvalitet, verktygsval och kontexteffektivitet blir alla observerbara problem.

Det är därför vi tycker att det här är värt att skriva om. Den framtida agentstacken är inte bara prompter och verktyg. Det är prompter, verktyg och instrumenteringslagret som berättar om helheten faktiskt fungerar.

Om du bygger seriösa agentarbetsflöden är observabilitet inte valfri infrastruktur. Det är en del av produkten.

Att sluta loopen med mining: hur ändringar blir institutionellt minne

Tue, 03 Feb 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publicering (februari 2026). Se vår teamsida för aktuella siffror.

Varje utvecklingsteam möter samma utmaning: ändringar sker hela tiden, men skälen bakom dessa ändringar försvinner. Sex månader senare frågar någon “varför valde vi DuckDB för pipeline-steg?” och svaret finns bara i huvudet på den som fattade det beslutet — om personen fortfarande är kvar.

Vi byggde ett mining-arbetsflöde som sluter den här loopen. Ändringar flödar genom git-commits, bearbetas av vår mining-pipeline, blir strukturerade changelog-poster och poster med arkitekturbeslut, och matas sedan tillbaka till våra AI-agenter via CLI-frågor. Resultatet: institutionellt minne som både människor och AI kan komma åt.

Problemet: beslut avdunstar

Betrakta ett typiskt scenario. En utvecklare committar:

feat(canonical): add DuckDB runtime for pipeline stages

Den här commiten representerar ett betydande arkitektoniskt val. Teamet utvärderade alternativ, övervägde avvägningar, och landade i DuckDB av specifika skäl. Men all den kontexten finns bara i:

En Slack-tråd (förmodligen raderad)
Någons minne (garanterat bleknande)
En kommentar i koden (kanske, om du har tur)

Tre månader senare frågar en ny teammedlem: “Ska jag använda DuckDB eller SQLite för det här nya steget?” Utan institutionellt minne uppfinner de antingen hjulet på nytt eller fattar inkonsekventa beslut.

Loopen: från commits till kontext

Vårt mining-arbetsflöde omvandlar git-historik till sökbar kunskap:

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

Den centrala insikten: både changelogs och arkitektoniska beslut flödar från samma git-historik, bearbetade genom en enhetlig pipeline. Det säkerställer att ingenting faller mellan stolarna.

Så fungerar mining

Steg 1: Synka indexet

uv run orkestra mine sync

Det här kommandot skannar git-historiken och bygger ett index över alla commits. Det extraherar strukturerade signaler från varje commit:

Conventional commit-typ (feat, fix, chore, docs)
Scope (vilket paket eller område)
Markörer för brytande ändringar
Berörda filer och komplexitetsmått

Steg 2: Kontrollera täckningsstatus

uv run orkestra mine status

Så här ser vår nuvarande 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 bearbetade. 476 blev arkitektoniska beslut. 6 799 blev changelog-poster. Varje commit klassificerad.

Steg 3: Hämta kandidater för granskning

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

Det här lyfter fram commits som ännu inte bearbetats, med full kontext för klassificering:

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

Signalerna hjälper till att styra klassificeringen: is_releasable_type: true antyder att det här bör synas i changelogen. Det stora antalet insättningar och infrastrukturfilerna antyder att det också kan vara ett arkitektoniskt beslut.

Steg 4: Klassificera commits

Här delar sig två vägar: changelog-poster och arkitektoniska beslut.

För changelog-poster:

uv run orkestra mine classify abc123 --changelog added

Det här registrerar att commit abc123 bör synas i changelogen under kategorin “Added”.

För arkitektoniska beslut:

Skaffa först ett riktigt beslut-ID:

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

Klassificera sedan med beslut-ID:t:

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

Det här länkar commiten till en beslutspost som kommer att skapas eller uppdateras.

För batchbearbetning (vad vi faktiskt gör):

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

JSONL-formatet stödjer båda domänerna i en enda genomgång:

{"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: Rendera utdata

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

Det här genererar CHANGELOG.md-filer per paket från liggaren. Changelogsen är härledda artefakter — radera dem och de återskapas perfekt från källiggaren.

Beslutsregistrets struktur

Extraherade beslut blir YAML-filer med rik 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

Varje beslut länkar tillbaka till sina källcommits. Varje beslut anger vilka filer det påverkar. Relationer mellan beslut är explicita.

CLI-integration: att fråga institutionellt minne

Det är här loopen sluts. Agenter kan fråga beslut via CLI:t:

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

Returnerar beslut om återförsökslogik, felhantering, återhämtningsmönster.

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

Returnerar den fullständiga beslutsposten med kontext, motivering och effekt.

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

Visar vilka arkitektoniska val som gjorts nyligen.

Hur agenter använder det här

Vår orkestrerares grundinstruktioner inkluderar:

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

När en agent ombeds implementera något relaterat till DuckDB kan den först kontrollera:

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

Och upptäcka DEC-PL-142, och lära sig:

Varför vi valde DuckDB (context)
Hur man använder det korrekt (agent_guidance)
Vilka filer man ska titta på (files)
Vilka relaterade beslut som finns (related)

Agenten uppfinner inte hjulet på nytt. Den bygger vidare på etablerade mönster.

Trefrågorstestet

Inte varje commit förtjänar en beslutspost. Vi använder Trefrågorstestet för att filtrera:

Var det svårt att fatta? Krävde det betydande analys, avvägningsutvärdering eller diskussion?
Är det kostsamt att ändra? Skulle det kräva betydande omarbete att göra beslutet ogjort?
Har det systemomfattande påverkan? Påverkar det flera paket eller etablerar det mönster andra kommer att följa?

Om en commit svarar “ja” på minst en av dessa frågor är den en kandidat för beslutsextraktion. Vår typiska andel: 1–4 beslut per 100 commits (cirka 1–4 %).

För changelog-poster är ribban lägre: varje ändring som märks för användaren (funktioner, fixar, förbättringar) registreras. Internt underhåll, dokumentationsuppdateringar och refaktoreringar hoppas vanligtvis över. Vår typiska andel: 30–50 changelog-poster per 100 commits.

Datalagring: append-only-liggare

Mining-systemet använder append-only JSONL-liggare för konfliktfri drift med flera agenter:

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 innebär att flera agenter kan klassificera commits samtidigt utan sammanslagningskonflikter. Varje rad är oberoende.

Valideringsgrindar

Innan varje mining-session kör vi validering:

uv run orkestra mine validate --quick

Det här kontrollerar:

Giltig SHA-formatering
Efterlevnad av beslut-ID-format
Inga dubbletter för samma SHA
Att refererade beslut faktiskt existerar

Efter klassificering validerar vi igen innan vi committar ändringarna.

Varför det här spelar roll

Återkopplingsloopen vi byggt löser flera problem:

För nya teammedlemmar: Istället för att fråga “varför gjorde vi X?” kan de söka i beslutsregistret. Kontexten är bevarad.

För AI-agenter: De verkar inte i ett vakuum. De kan fråga institutionell kunskap innan de ger rekommendationer. När de ombeds lägga till ett nytt pipeline-steg kan de upptäcka DuckDB-mönstret och följa det.

För arkitektonisk konsekvens: Beslut är explicita och sökbara. När någon föreslår en metod som strider mot ett befintligt beslut kan systemet lyfta fram konflikten.

För changelog-generering: Versionsanteckningar är inte en sista-minuten-stress. De är en biprodukt av kontinuerlig klassificering under utveckling.

För onboarding: Nya agenter ärver kodbasens fulla kontext. De ser inte bara koden — de ser besluten som formade den.

Nuvarande läge

Per idag:

15 637 commits bearbetade genom pipelinen
476 arkitektoniska beslut extraherade och dokumenterade
6 799 changelog-poster registrerade
100 % täckning över båda domänerna

Varje commit sedan vi började har klassificerats. Det institutionella minnet är komplett och sökbart.

Komma igång

Om du vill implementera något liknande:

Börja med conventional commits. Mining-pipelinen fungerar bäst när commits har strukturerade prefix (feat:, fix:, chore:).
Definiera dina domäner. Vi använder domäner som pipeline, agent-design, observability, data-modeling. De organiserar beslut efter område.
Bygg upp klassificeringsvanan. Mining fungerar när team regelbundet klassificerar commits. Batchbearbetning med LLM-hjälp gör det skalbart.
Gör besluten sökbara. Värdet växer när agenter kan söka beslut via CLI:t. Strukturera din utdata för maskinkonsumtion.
Slut loopen. Beslut bör påverka framtida arbete. Inkludera beslutsreferenser i agentinstruktioner och checklistor för kodgranskning.

Målet är inte perfekt dokumentation. Det är att göra skälen bakom ändringar tillgängliga för både människor och AI, idag och om sex månader. När ändringar blir institutionellt minne bygger team vidare på etablerade mönster istället för att uppfinna dem på nytt.

Mining-arbetsflödet är en del av vår orkestreringsmotor, närmare bestämt kontextmotor-modulen i vårt orkestreringspaket.

Skill-mining: från 3 500 kandidater till 466 förmågor

Tue, 27 Jan 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publiceringen (januari 2026). Se vår teamsida för aktuella siffror.

3500-skillproblemet

När vi började bygga ett agentorkestreringssystem stod vi inför en intressant utmaning: det finns tusentals potentiella skills utspridda över hela AI-ekosystemet. GitHub-repositorier, leverantörsdokumentation, communityprojekt, interna mönster — skills finns överallt. Men vilka spelar roll? Vilka fungerar? Och hur underhåller man ett sammanhängande skill-bibliotek som agenter faktiskt kan använda?

Vårt svar: en systematisk mining- och intagsloop.

Siffrorna idag

Bara drygt tre månader efter att Anthropic lanserade Agent Skills den 16 oktober 2025 såg det ut så här när det här inlägget publicerades den 27 januari 2026:

Mätvärde	Antal
Identifierade kandidater	3 500+
Antagna skills	466
Leverantörsskills	373
Interna skills	93
Aktiva leverantörer	25+
Genomsnittliga tokens per skill	2 834
Refererade verktyg	89
Unika taggar	635

Vi har granskat över 3 500 skill-kandidater. Vi har antagit 466. Det är en antagandegrad på 13 % — och den selektiviteten är avsiktlig.

Kunskapsnivåsystemet

Alla skills är inte likvärdiga. Vi organiserar dem i fem kunskapslager (K0–K4), där vart och ett har ett eget tillämpningsområde:

K0: Grunder (universellt)

Skills alla agenter bör ha. De representerar “god tänkare”-förmågor som fungerar överallt.

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 är portabla till vilket projekt, vilken domän, vilken stack som helst. De kodifierar universella kognitiva mönster.

K1: Identiteter (disciplin)

“God ingenjör”- eller “god forskare”-skills som gäller över projekt inom en disciplin.

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

K2: Domäner (ämnesexpertis)

“God databasexpert”- eller “god säkerhetsingenjör”-skills portabla inom ett fält.

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: Stackar (teknik)

“God Supabase-användare”- eller “god Cloudflare-utvecklare”-skills för specifika teknikstackar.

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

K4: Projekt (organisation)

Skills specifika för vår organisation och våra arbetsflöden.

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

Fas 1: Upptäckt

Skills kommer från överallt:

Leverantörsrepositorier: AWS, Anthropic, Cloudflare, Supabase och communitybidragsgivare publicerar skill-samlingar. Vi bevakar 25+ leverantörsrötter.

Communityprojekt: GitHub är fullt av Claude Code-mallar, agentmönster och arbetsflödesdefinitioner.

Interna mönster: Allteftersom vårt team löser problem uppstår mönster. De formaliseras till skills.

Dokumentationsmining: Teknisk dokumentation innehåller ofta implicita skills — procedurer, checklistor, beslutsträd.

Upptäckten är kontinuerlig. Vi använder en skill-backlogg för att spåra kandidater innan formell utvärdering.

Fas 2: Utvärdering

Varje kandidat bedöms enligt samma kriterier:

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

Alla fem produktkriterier måste godkännas. Det är därför 87 % av kandidaterna avvisas.

Sedan går varje kandidat igenom en separat förtroendegranskning. Vi behandlar inte ett officiellt leverantörsrepositorium, en välkänd community-underhållare och ett slumpmässigt GitHub-repo som likvärdiga sanningskällor.

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

Betrodda leverantörer får en lättare proveniensgranskning, men inget frikort. Obetrodda eller okända källor får en djupare manuell granskning, och vi kör inte bifogade skript förrän de har lästs, avgränsats och klassificerats som säkra.

Luckanalys: Innan vi antar söker vi i vårt register:

uv run orkestra skills search "<capability>"

Har vi redan det behöver vi det inte. Har vi något liknande kanske vi slår ihop istället för att anta.

Djup- och standardpoängsättning: Vi poängsätter också hur fullt en kandidat använder agent-skill-modellen. En ensam SKILL.md kan fortfarande vara användbar, men djupare skills är mer värdefulla när de separerar instruktioner från referenser, skript och tillgångar på det sätt agentskills.io uppmuntrar.

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-stjärnor kan höja en trovärdighetspoäng lite, men de räddar aldrig en ytlig eller osäker skill. Ett repo med många stjärnor och en vag SKILL.md och opaka skript poängsätts lägre än ett mindre repo med en precis beskrivning, kuraterade references/, och små, avgränsade hjälpskript som faktiskt utnyttjar hela skill-förmågan.

Strukturell analys: Vi kontrollerar 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

Om en kandidat innehåller skript blir den granskningen strängare. En bra skill är inte bara användbar; den måste vara läsbar, avgränsad och säker att lämna över till en agent. Det säkerhetsfiltret ensamt diskvalificerar en betydande andel av annars intressanta kandidater.

Fas 3: Intag

När en skill klarar utvärderingen kommer den in i registret. Men skills antas aldrig oförändrade. De modifieras för att passa vårt system.

Modifieringar vid antagande:

Metadatanormalisering: Varje skill får vårt frontmatter-schema
K-nivåtilldelning: Skills placeras i lämpligt kunskapslager
Taggberikning: Taggar läggs till för upptäckbarhet
Verktygsdeklaration: Tillåtna verktyg deklareras explicit
Sektionsjustering: Innehåll omstruktureras för att matcha vår mall

En typisk skill-YAML efter intag:

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

Fas 4: Scope-tilldelning

Skills tilldelas scopes — kategorier som avgör vilka agenter som laddar vilka 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 deklarerar sina scopes, och skills tilldelas automatiskt:

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

Fas 5: Materialisering

Skills lever inte som YAML i produktion. De renderas till SKILL.md-filer som Claude Code kan ladda:

uv run orkestra sync

Det här kommandot:

Läser alla skill-YAML-definitioner
Renderar dem genom Jinja-mallar
Skriver SKILL.md-filer till .claude/skills/
Organiserar efter K-nivå (foundations/, identities/, domains/, stacks/, project/)

Den slutgiltiga utdatastrukturen:

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

Det vilande scope-mönstret

Ett av våra kraftfullaste mönster är “antagen-men-inte-laddad”-skills. Vi kallar de här vilande scopes.

Betrakta skills för vetenskaplig databehandling från repositoriet k-dense-scientific. Vi har antagit 120+ skills som täcker bioinformatik, kemi, kvantberäkning och klinisk informatik. Men de flesta av våra agenter behöver inte molekylär docking eller genuttrycksanalys.

Istället för att ladda alla 120 skills i varje agent (vilket blåser upp kontextfönstren) gör vi så här:

Antar skills med ett specifikt scope (t.ex. bioinformatics)
Håller dem vilande — registrerade men inte laddade
Aktiverar dem bara när en agent deklarerar det scopet

# 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

Det här mönstret låter oss ha 466 skills i registret medan typiska agenter bara laddar 40–60 relevanta.

Skill-typer

Skills finns i tre kognitiva mönster:

Arbetsflöde

Ordnade procedursteg: “1. Gör X, 2. Sedan Y, 3. Slutligen Z”

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

Disciplin

Beteendemässiga skyddsräcken: “Alltid X”, “Aldrig Y”, “Föredra Z”

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

Checklista

Verifieringskriterier: “Bekräfta X”, “Verifiera Y”, “Kontrollera Z”

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

Kvalitetsgrindar

Varje skill måste klara validering innan den skeppas:

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

Beskrivningar måste vara 50–400 tecken med utlösarfraser (“Använd när…”, “När du behöver…”) så att Claude Code vet när de ska föreslås.

Vi validerar kontinuerligt:

uv run orkestra validate --show-warnings

Leverantörsekosystemet

Våra 373 leverantörsskills kommer från:

Leverantör	Skills	Domän
AWS Agent	19	Molntjänster
Anthropic	12	Dokumentgenerering
Cloudflare	8	Edge computing
Supabase	5	Databas
k-dense	100+	Vetenskaplig databehandling
silvainfm	4	Datavetenskap
Java Developer Kit	45+	Spring/Java
Vercel	1	Webbläsarautomation

Varje leverantörsrot deklareras 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 körs symlänkas leverantörsskills in i .claude/skills/vendor/ under sin leverantörs namnrymd.

Vad vi har lärt oss

Selektivitet lönar sig. Det är frestande att anta allt som ser användbart ut. Men varje skill kostar tokens. Med i genomsnitt 2 834 tokens per skill blir onödig volym snabbt kostsam. Vår antagandegrad på 13 % håller agenterna slimmade.

Struktur möjliggör upptäckt. K-nivåsystemet är inte bara organisation — det handlar om portabilitet. K0-skills kan återanvändas var som helst. K4-skills är avsiktligt projektspecifika. Den här tydligheten hjälper både människor och agenter att hitta det de behöver.

Vilande scopes skalar. Man kan anta hundratals skills utan att ladda dem alla. Scopes låter en bygga ett heltäckande register samtidigt som enskilda agenters kontextfönster hålls hanterbara.

Modifiering vid antagande är avgörande. Råa leverantörsskills passar sällan ens system rakt av. Intagsprocessen — att lägga till metadata, tilldela nivåer, berika taggar — gör att externa skills fungerar internt.

Mining är kontinuerligt. Siffran 3 500 fortsätter växa. Nya leverantörsrepon dyker upp. Communitymönster uppstår. Interna arbetsflöden befästs. Loopen stannar aldrig.

Vad som kommer härnäst

Vi arbetar på flera förbättringar:

Automatiserad luckdetektion: Larm när vanliga agentfel skulle kunna åtgärdas av en icke-antagen skill
Arbetsflöden för utfasning av skills: Formell process för att pensionera skills som ersatts eller inte används
Beroenden mellan skills: Explicit deklaration av skill-förutsättningar
Användningsanalys: Spåra vilka skills agenter faktiskt åberopar kontra bara laddar

Mining-loopen för skills är infrastruktur. Den är inte glamorös. Men det är den som gör att 41 agenter fungerar sammanhängande med 466 förmågor samtidigt som de håller sig inom kontextgränserna.

Det är historien om hur 3 500 blir 466. Inte genom att ignorera 3 000 — utan genom att utvärdera dem systematiskt och bara anta det som fungerar.

Vill du se skill-systemet i praktiken? Kolla in uv run orkestra skills list för att utforska vårt nuvarande register.

Progressiv exponering: CLI-fönster in i agentsystem

Tue, 20 Jan 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publicering (januari 2026). Se vår teamsida för aktuella siffror.

Agentsystem är ogenomskinliga med avsikt. De fattar beslut, anropar verktyg och koordinerar arbete över dussintals specialister. Men när något går fel — eller när man helt enkelt vill förstå vad som händer — var tittar man då?

Svaret är progressiv exponering: ett skiktat gränssnitt som avslöjar exakt så mycket komplexitet som man behöver, exakt när man behöver det.

Ogenomskinlighetsproblemet

Ett modernt agentorkestreringssystem kan ha:

40+ specialistagenter, var och en med distinkta förmågor
700+ skills som spänner över intern automation och leverantörsintegrationer
470+ arkitektoniska beslut som formar beteende
Dussintals MCP-verktygsservrar som tillhandahåller externa förmågor

Den här komplexiteten är avsiktlig. Agenter behöver tillgång till rik kontext — domänkunskap, kodintelligens, databasscheman — för att fatta bra beslut. Men samma rikedom skapar ett synlighetsproblem.

Hur vet man vilken agent som hanterar databasmigreringar? Vilka beslut formade söksystemets rankningsbeteende? Vilka verktyg har arkitekturrådgivaren tillgång till?

Utan strukturerad åtkomst är man hänvisad till att läsa källkod eller hoppas att dokumentationen är aktuell.

Progressiv exponering som arkitektur

Progressiv exponering är inte bara ett UI-mönster. Det är en arkitektonisk princip: organisera information i lager, vart och ett djupare än det förra, så att användare kan stanna på den nivå som besvarar deras fråga.

För agentsystem översätts det här till CLI-kommandon på stigande djup:

Nivå	Kommando	Fråga som besvaras
1	`orkestra system status`	Är allt friskt?
2	`orkestra agents list`	Vilka agenter finns?
3	`orkestra agents info <name>`	Vad gör den här agenten?
4	`orkestra decisions search`	Varför fungerar det på det här sättet?
5	MCP-verktyg i Maguyva	Visa mig koden.

Varje nivå besvarar en naturlig följdfråga. Man behöver sällan hoppa direkt till nivå 5.

Nivå 1: Systemhälsa

Den första frågan är alltid: fungerar allt?

$ orkestra system status

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

Ett kommando. Fyra siffror. Tillräckligt för att veta att systemet är konfigurerat och registren innehåller data.

Om antalet agenter sjunker oväntat eller skills misslyckas med att laddas ser man det här först. Ingen loggdykning krävs.

Nivå 2: Agentinventering

När man väl vet att systemet är friskt är nästa fråga: vad finns tillgängligt?

$ orkestra agents list

Det här returnerar strukturerad data — agentnamn, beskrivningar, modellpreferenser, domäntäckning. Utdatan är JSON som standard, vilket gör det enkelt att leda vidare till jq för filtrering:

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

Vill man ha agenter som hanterar databasarbete? Sökkommandot begränsar urvalet:

$ orkestra agents search "database"

Det här skannar namn, beskrivningar och förmågor. Man hittar rätt specialist utan att läsa 40 agentdefinitioner.

Nivå 3: Djupdykning i agenten

Har man hittat en agent som verkar relevant? Kommandot info avslöjar allt:

$ orkestra agents info architecture-advisor

Utdatan innehåller:

Metadata: Namn, kategori, modellpreferens, beskrivning
Domäner: Vilka kunskapsområden agenten täcker
Identitet: Karaktärsdrag (arkitekt, strateg, kunskapsarkitekt)
Verktygsguider: Vilken verktygsdokumentation som injiceras i kontexten
Verktyg: Den fullständiga listan av MCP-verktyg agenten har tillgång till

Här är ett smakprov på vad man 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",
      ...
    ]
  }
}

Det här berättar exakt vad agenten kan göra. Du behöver inte läsa källkoden.

Nivå 4: Beslutsarkeologi

Agenter beter sig enligt dokumenterade beslut. När man behöver förstå varför något fungerar på ett visst sätt är beslutsregistret sanningskällan.

$ orkestra decisions search "agent"

Det här returnerar matchande arkitektoniska beslut:

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

Varje beslut har full proveniens — när det fattades, varför, vilka avvägningar som övervägdes, vilka commits som implementerade det:

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

Det här är arkitektonisk dokumentation som förblir aktuell eftersom den bryts ut ur commits, inte underhålls manuellt.

Nivå 5: Direkt kodintelligens

När man behöver se den faktiska implementationen — inte metadata om den — ger MCP-verktygen i Maguyva direkt åtkomst.

Inifrån en agentsession:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Det här dirigerar automatiskt över semantisk, text- och AST-sökning för att hitta relevant kod. För specifika symboler:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

För beroendeanalys:

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

Det här är inte bara grep-ersättningar. De är grafmedvetna, semantiskt indexerade, och integrerade med samma kodintelligens som driver agenterna själva.

Enhetlig sökning över register

Ibland vet man inte vilket register som har svaret. Den enhetliga sökningen spänner över allt:

$ orkestra search "database" --summary

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

254 träffar över fem register. Sammanfattningen berättar var man ska gräva djupare. Ta bort --summary för detaljerade resultat, eller lägg till --limit 5 för att hålla utdatan hanterbar.

Varför det här spelar roll

Progressiv exponering handlar inte bara om bekvämlighet. Det förändrar hur man interagerar med komplexa system.

Felsökning blir hanterbar. När en agent fattar ett oväntat beslut behöver man inte grepa genom loggar. Man kontrollerar vilka verktyg den har tillgång till (agents info), vilka beslut som formar dess beteende (decisions search), och spårar implementationen om det behövs (intelligent_search).

Onboarding går snabbare. Nya teammedlemmar behöver inte läsa hela kodbasen. De börjar med system status, utforskar med agents list, och går djupare bara när de stöter på något de inte förstår.

Dokumentationen förblir aktuell. Eftersom CLI:t läser från samma register som konfigurerar agenterna är utdatan alltid korrekt. Det finns ingen glidning mellan vad dokumentationen säger och vad systemet gör.

CLI:t som gränssnitt

Vi kunde ha byggt en webbaserad instrumentpanel. Vi kunde ha skrivit omfattande dokumentation. Istället byggde vi ett CLI som läser från sanningskällan.

CLI:t har fördelar:

Komponerbart: Led utdata genom jq, integrera med skript
Skriptbart: Automatisera kontroller, generera rapporter
Snabbt: Inga sidladdningar, inga autentiseringsflöden
Korrekt: Läser den faktiska konfigurationen, inte en cachad representation

För system där korrekthet spelar större roll än estetik vinner CLI:t.

Att bygga sin egen progressiva exponering

Om man bygger agentsystem, fundera på hur användare kommer att inspektera dem:

Börja med hälsokontroller. Ett kommando som berättar om saker fungerar.
Erbjud inventeringsvyer. Lista vad som finns innan man förklarar vad det gör.
Möjliggör riktade sökningar. Sökning slår bläddring i stor skala.
Exponera proveniens. Låt användare spåra beslut till deras ursprung.
Koppla till kodintelligens. Till slut behöver användare se implementationen.

Varje lager besvarar en följdfråga. Bygg dem i frekvensordning — de flesta användare stannar på lager 2 eller 3. Bara superanvändare når lager 5.

Målet är inte att exponera allt. Det är att exponera exakt det som behövs, exakt när det behövs. Det är progressiv exponering tillämpad på agentarkitektur.

Grundsanningar: att förankra AI-agenter i verkligheten

Tue, 13 Jan 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publicering (januari 2026). Se vår teamsida för aktuella siffror.

AI-agenter är anmärkningsvärt kapabla. De kan resonera, syntetisera och generera. Men de har en grundläggande svaghet: de hittar på saker. Inte illvilligt, men med självförtroende. En agent kan uppfinna API-parametrar som inte existerar, referera till konfigurationer som aldrig definierats, eller tillämpa mönster från sina träningsdata som strider mot din faktiska arkitektur.

Standardåtgärden är “ge agenten mer kontext”. Men kontext kan vara motsägelsefull. Dokumentation glider isär från implementationen. Kommentarer ljuger. Även kod kan vilseleda om den läses utan att man förstår avsikten.

Vi behövde något mer explicit. Något som inte kunde ignoreras eller misstolkas. Något som skulle förankra agenter i verifierbar verklighet.

Vi kallar dem Grundsanningar.

Vad är en grundsanning?

En grundsanning är ett explicit, versionshanterat sakpåstående som agenter måste respektera. Det är inte dokumentation. Det är inte en kommentar. Det är en förstklassig entitet i systemet med:

En unik identifierare (som GT-MAG-015 eller GT-MAG-036)
En livscykelstatus (aktuell, preliminär eller utfasad)
Ett scope (plattformsomfattande, paketspecifikt eller domänbundet)
Bevis (filsökvägar, URL:er eller referenser som styrker påståendet)
Agentvägledning (explicita gör/undvik-instruktioner)

Här är ett exempel från vår Maguyva-kodintelligensplattform:

- 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

Det här är inte löpande text. Det är ett kontrakt. När en agent stöter på den här grundsanningen vet den:

Standardbeteendet är deterministiskt (tomma resultat, inte gissningar baserade på ungefärlig matchning)
Det finns specifika parametrar (find_similar, exact_match) med definierade beteenden
Bevis finns i specifika filer som kan verifieras
Påståendet verifierades ett specifikt datum

Anatomin hos ett grundsanningsregister

Grundsanningar lever i YAML-register under ai_assets/reference/ground_truths.yaml. Varje paket eller domän kan ha sitt eget register. Strukturen är:

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

Registret innehåller metadata om själva samlingen, renderingskonfiguration för dokumentationsgenerering, och själva påståendena. Varje påstående följer ett strikt schema som valideras 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

Hur agenter kommer åt grundsanningar

Grundsanningar exponeras genom flera kanaler:

1. Renderad dokumentation

Kommandot orkestra sync omvandlar YAML-register till läsbar markdown:

uv run orkestra sync

Det här genererar GROUND_TRUTHS.md-filer som ingår i agentens kontext. Den renderade utdatan grupperar påståenden efter status och 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ökning

Agenter med skalåtkomst kan söka i grundsanningar programmatiskt:

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

Sökfunktionen poängsätter träffar över flera fält med viktad 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. Kontextkomposition

När agenter renderas från YAML-definitioner kan deras kontext referera till grundsanningsregister:

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

Det säkerställer att relevanta grundsanningar laddas innan agenten börjar arbeta.

Kategorier av grundsanningar

Om man tittar över våra register grupperar sig grundsanningarna i flera mönster:

Produktprinciper

Begränsningar för vad produkten är och inte är:

“Maguyva är skrivskyddat gentemot användarrepositorier; den enda tillgången som inte kan återskapas är den betalda inbäddningscachen.” (GT-MAG-001)

Arkitekturgränser

Var ansvar ligger och varför:

“Gränserna mellan pipeline och Maguyva är avsiktliga: pipeline är återanvändbar, Maguyva innehåller kodspecifik logik, och CQRS separerar stegskrivningar från serverläsningar.” (GT-MAG-006)

Regler mot hallucinationer

Explicita mandat som håller verktygskontrakt deterministiska istället för härledda:

“Ungefärlig symbolmatchning är opt-in via find_similar=true. Standardbeteendet returnerar tomma resultat för symboler som inte existerar; exact_match=true tvingar fram strikt matchning och inaktiverar alla reservalternativ med ungefärlig matchning.” (GT-MAG-015)

Kvalitetsgrindar

Standarder som måste upprätthållas:

“Ändringar av delad infrastruktur (post_filters.py, relationsextraktorer, delade hanterare) MÅSTE valideras mot ALLA språk som stöds via fullständig manifestgenerering före commit. En enspråkig validering räcker inte för delad kod.” (GT-MAG-036)

Kodmönster

Implementationskrav:

“Använd asyncio.to_thread() för CPU-bundet arbete i asynkrona kontexter; det utfasade mönstret loop.run_in_executor() bör inte användas i ny kod.” (GT-MAG-018)

Livscykeln hos en grundsanning

Grundsanningar är inte statiska. De utvecklas genom en definierad livscykel:

Preliminär

En föreslagen sanning under utvärdering. Påståendet är registrerat men kan komma att ändras:

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

Aktuell

En verifierad sanning som agenter måste respektera. Beviset har validerats:

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

Utfasad

En sanning som inte längre gäller. Behålls som historisk referens med en pekare till vad som ersatte den:

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

Varför inte bara dokumentation?

Dokumentation tjänar ett annat syfte. Den förklarar. Den undervisar. Den kan vara vag, kan använda kvalificerare som “generellt” eller “vanligtvis”.

Grundsanningar kan inte vara vaga. De är påståenden. De gäller antingen eller så gör de inte det.

Betrakta skillnaden:

Dokumentation: “API:et returnerar generellt tomma resultat när en symbol inte hittas, även om ungefärlig matchning kan vara aktiverad i vissa konfigurationer.”

Grundsanning: “Standardbeteendet returnerar tomma resultat för symboler som inte existerar; exact_match=true tvingar fram strikt matchning och inaktiverar alla reservalternativ med ungefärlig matchning.”

Den första är till hjälp för människor som lär sig systemet. Den andra går att omsätta i handling för agenter som fattar beslut.

Agentvägledning: gör och undvik

Vissa grundsanningar innehåller explicit agentvägledning:

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

Det tar bort tvetydighet. En agent som läser det här vet inte bara vad som är sant, utan vilka handlingar den sanningen medför.

Verifiering och underhåll

Grundsanningar kräver underhåll. Vi spårar:

last_verified: När någon bekräftade att påståendet fortfarande gäller
evidence: Filer som styrker påståendet (kan kontrolleras för existens)
source: Var sanningen ursprungligen kom ifrån (CLI-inspektion, arkitekturgranskning, lärdom efter en incident)

En grundsanning med föråldrade verifieringsdatum eller trasiga bevislänkar är en signal att undersöka. Antingen är sanningen fortfarande giltig och behöver omverifieras, eller så har verkligheten förändrats och sanningen behöver uppdateras.

Verkliga exempel från produktion

Säkerhetsgräns

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

Den här grundsanningen förhindrar en klass av missriktade “säkerhetsförbättringar” som skulle förstöra produkten.

Noggrannhet vid extraktionstillfället

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

Det här kom från smärtsam erfarenhet. Agenter brukade lappa ihop misslyckade språkpaket genom att lägga till filter som bara påverkade validatorn och fick testmiljön att se grönare ut, medan den skarpa Maguyva-extraktorn fortfarande producerade felaktiga kanter. Regeln tvingar tillbaka fixar till den verkliga vägen: YAML-konfiguration, queries eller hanterare.

Filtrering i flera 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).

Det här förhindrar att agenter lägger till filter på fel ställe, ett vanligt misstag som försämrade precisionen.

Integration med orkestreringssystemet

Grundsanningar är ett lager i ett bredare kontextsystem:

Arkitektoniska beslut (ADR:er) – Registrerar varför vi valde metod A framför B
Grundsanningar – Anger vad som är definitivt sant just nu
Domänmönster – Beskriver hur man gör saker rätt
Antimönster – Beskriver vad man ska undvika och varför

En agent som arbetar i systemet har tillgång till alla fyra. Grundsanningar utgör den faktabaserade förankringen, medan beslut förklarar historien, mönster vägleder implementationen och antimönster varnar för fallgropar.

Att mäta effekten

Sedan vi introducerade grundsanningar har vi observerat:

Färre cykler av “fixa den hallucinerade fixen”
Säkrare agentbeslut när fakta är tydliga
Bättre PR-granskningar eftersom förväntningarna är explicita
Kortare onboardingtid för nya agenter (och människor)

Investeringen i att underhålla grundsanningar betalar sig i minskad felsökning och tydligare systemgränser.

Komma igång

För att lägga till en grundsanning i ditt system:

Skapa en ground_truths.yaml i ditt pakets ai_assets/reference/-katalog
Definiera metadata och renderingskonfiguration
Lägg till påståenden enligt schemat
Kör uv run orkestra sync för att generera dokumentation
Inkludera registret i agentens kontextkomposition

Börja med de fakta som orsakar mest förvirring, eller de begränsningar som bryts mot oftast. Det är dina mest värdefulla grundsanningar.

Slutsats

AI-agenter kommer att hallucinera. Det ligger i deras natur. Men vi kan skapa miljöer där hallucination begränsas, där vissa fakta inte är förhandlingsbara, där agenter kan pröva sina antaganden mot verifierad verklighet.

Grundsanningar är inte en fullständig lösning. De kräver underhåll. De kan bli föråldrade. De lägger till overhead i utvecklingsprocessen.

Men de ger något värdefullt: ett gemensamt ordförråd av fakta som både människor och agenter kan lita på. I en värld där agenter i allt högre grad deltar i mjukvaruutveckling blir den gemensamma grunden avgörande.

Alternativet är oändliga cykler av agenter som gör självsäkra misstag och människor som rättar till dem. Grundsanningar bryter den cykeln genom att göra rättelserna explicita och varaktiga.

Dina agenter förtjänar att veta vad som är sant. Berätta det för dem.

Orkestra: att orkestrera AI-agenter i stor skala

Tue, 06 Jan 2026 00:00:00 GMT

Siffrorna i det här inlägget speglar systemet vid publiceringen (januari 2026). Se vår teamsida för aktuella siffror.

När vi började bygga med Claude Code stötte vi på ett problem som alla team som använder AI-kodningsassistenter förr eller senare möter: en enda agent kan inte göra allt bra.

Man kan prompta en agent att vara en databasspecialist. Eller en säkerhetsgranskare. Eller en frontend-ingenjör. Men i samma stund man ber den vara alla tre samtidigt sjunker kvaliteten. Kontexten späds ut. Instruktioner krockar. Agenten blir en generalist som är medioker på allt.

Så vi byggde Orkestra.

Vad är Orkestra?

Orkestra är ett agentorkestreringssystem för Claude Code och liknande AI-kodningsverktyg. Det koordinerar flera specialiserade agenter, var och en med egen expertis, under en enda orkestrerare som dirigerar arbete till rätt specialist.

Tänk på det som en bemanningsbyrå för AI-agenter. Orkestreraren tar emot en uppgift, identifierar vilken specialist som bör hantera den, och delegerar med rätt kontext. När arbetet är klart flödar resultaten tillbaka till orkestreraren för sammanställning.

Siffrorna berättar historien:

Komponent	Antal
Specialistagenter	46
Återanvändbara skills	466
Identitetsarketyper	27
Mindset	11
Kommunikationsstilar	10
Kunskapsdomäner	21

Karaktärssystemet: D&D för agenter

Den centrala insikten bakom Orkestra är att agentbeteende uppstår ur tre komponerbara primitiver:

Identitet definierar vad agenten är. En arkitekt designar systemstrukturer. En debugger spårar fel till grundorsaken. En guardian upprätthåller efterlevnad och säkerhetsgränser. Vi har 27 identitetsarketyper som kan kombineras.

Mindset definierar hur agenten tänker. Ett analytiskt mindset förankrar påståenden i bevis och kvantifierar osäkerhet. Ett skeptiskt mindset ifrågasätter antaganden och söker motbevisande fakta. Ett utforskande mindset omfamnar tvetydighet och prövar flera angreppssätt.

Stil definierar hur agenten kommunicerar. En teknisk stil inkluderar exakta värden och refererar till specifika filer. En koncis stil skär bort fluff och leder med svaret. En diplomatisk stil balanserar ärlighet med takt.

En agent kombinerar de här primitiverna:

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

Den här kompositionen skapar en agent som designar system (arkitekt), knyter ihop kunskap över domäner (kunskapsarkitekt), sätter strategisk riktning (strateg), tänker i bevis och data (analytisk), och kommunicerar utan fluff (koncis).

Kraften ligger i den kombinatoriska explosionen. 27 identiteter gånger 11 mindset gånger 10 stilar ger nästan 3 000 möjliga agentpersonligheter. Men man definierar bara de kombinationer som spelar roll för ens arbete.

Skills: återanvändbara förmågemoduler

Skills är den kunskap och de arbetsflöden agenter kan åberopa. De följer ett nivåsystem baserat på scope:

Nivå	Namn	Scope	Exempel
K0	Grunder	Universell metodik	Testdriven disciplin, evidensbaserat slutförande
K1	Identiteter	Rollbaserade arbetsflöden	CLI-gränssnittsstandarder, prestandaplaybook
K2	Domäner	Domänspecifik kunskap	Databasmigreringsmönster, autentiseringsvalidering
K3	Stackar	Teknikspecifikt	Cloudflare-driftsättning, Supabase-drift
K4	Projekt	Endast den här kodbasen	Projektspecifika arbetsflöden och konventioner

Skills laddas först när de behövs. En agent ser skill-namn och beskrivningar vid start, men fullt skill-innehåll laddas bara när det utlöses. Det håller kontexten kompakt samtidigt som hundratals skills görs upptäckbara.

Varje skill innehåller:

Tydliga utlösarvillkor (“Använd när du migrerar databasscheman”)
Steg-för-steg-vägledning
Tillåtna verktyg för arbetsflödet
Framgångskriterier och återhämtningsvägar vid fel

De 466 skills i vårt register täcker allt från git worktree-isolering till webbresearcharbetsflöden till driftsättningshälsovalidering.

Varför orkestrering spelar roll

Arkitekturer med en enda agent stöter snabbt på väggar:

Kontextutspädning. Ett kontextfönster på 200 000 tokens låter stort ända tills man laddar in databasscheman, API-dokumentation, testfixturer och domänkunskap. Specialister kan arbeta med riktad kontext.

Instruktionskonflikter. Att be en agent “vara grundlig men snabb” och “verifiera allt men inte överkonstruera” skapar spänning. Specialister löser det genom att ha tydligt scope.

Expertisdjup. En generalistagent kan lite om allt. En specialistagent, komponerad med rätt identitet och skills, kan sin domän djupt.

Orkestra implementerar platt orkestrering: en orkestrerare koordinerar flera specialister. Specialister kan inte skapa underspecialister. Det förhindrar en komplexitetsexplosion samtidigt som det möjliggör parallellt arbete.

Orkestreraren har tillgång till 2,2 miljoner tokens effektiv kapacitet: sitt eget fönster på 200 000 plus 10 samtidiga subagenter med 200 000 var. Arbete som skulle tömma en enda agent löper bekvämt genom flottan.

Renderingspipelinen

Agentdefinitioner lever i YAML. Claude Code läser Markdown. Orkestra överbryggar det gapet med en deterministisk renderingspipeline:

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

Operatörer redigerar YAML-källan. Kör orkestra sync. Renderad Markdown dyker upp i .claude/agents/. Claude Code tar upp ändringarna.

Den här separationen tjänar olika målgrupper:

YAML-källan innehåller livscykelmetadata, taggar, valideringsregler och utfasningsnoteringar för tooling
Renderad Markdown innehåller bara det modellen behöver: beskrivning, verktyg, skills och beteendevägledning

Pipelinen komponerar identiteter, mindset, stilar och skills till en enda sammanhängande prompt. En arkitekt-analytisk-koncis-agent får en helt annan systemprompt än en debugger-skeptisk-teknisk-agent, även om de delar en del underliggande skills.

Domänkunskap: fyrafilsmönstret

Varje kunskapsdomän följer en konsekvent 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

Den här strukturen betjänar agentens kontextladdning. En agent som arbetar med autentisering laddar authentication/patterns.md för vägledning och authentication/anti-patterns.md för att undvika kända fallgropar. Filerna är dimensionerade för effektiv kontextladdning: tillräckligt fokuserade för att vara användbara, tillräckligt heltäckande för att vara auktoritativa.

Vi underhåller 21 toppnivådomäner, bland annat analys, autentisering, datavetenskap, infrastruktur, maskininlärning, prestanda, säkerhet och mer. Varje domän kan ha underdomäner för finare granularitet.

Värderingar: operativsystemet

Alla agenter delar ett bottenlager av värderingar som definierar hur de opererar:

Enkelhet först. Använd den enklaste lösningen som fungerar. Lägg bara till komplexitet när det är motiverat.

Åtgärda grundorsaker. Lappa aldrig runt fel. Om en pipeline misslyckas, felsök pipelinen. Om ett test misslyckas, åtgärda koden eller testet.

Evidensbaserat. Märk påståenden som “verifierat” (med benchmarks) eller “uppskattat” (med antaganden). Ett upptäckt mönster är inte detsamma som ett bekräftat problem.

Kontextekonomi. MCP-verktyg kostar 0,1 % av kontexten. Filläsningar kostar 2 % var. Tillämpa domänexpertis innan koden utforskas.

De här värderingarna sprids till varje specialist genom renderingspipelinen. En agent kan inte kringgå dem genom komposition.

CLI:t: kontrollplanet

Orkestra levereras med ett CLI för att hantera agentekosystemet:

# 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:t är sanningskällan för vilka agenter som finns, vilka skills de har, och om systemet är friskt. Det kör validering före synk för att fånga problem tidigt.

Överväganden kring öppen källkod

Vi byggde Orkestra för att lösa vårt eget problem: att koordinera AI-agenter i stor skala för en komplex kodbas. Mönstren vi upptäckte är inte specifika för vår domän.

Karaktärskompositionssystemet (identitet + mindset + stil) gäller för alla team som definierar agentpersonligheter.

Skill-nivåsystemet (K0–K4) ger en mental modell för att organisera återanvändbara förmågor efter scope.

Renderingspipelinemönstret (YAML-källa + mallar + genererade artefakter) separerar tooling-hänsyn från modellkonsumtion.

Den platta orkestreringsmodellen (en koordinator, många specialister) undviker komplexitet samtidigt som den möjliggör parallellism.

Om Orkestra blir öppen källkod beror på om de här mönstren har värde för andra som bygger med Claude Code. Om du stöter på väggarna vi beskrev kan arkitekturen kanske hjälpa.

Vad vi lärde oss

Att bygga Orkestra lärde oss att orkestrering inte handlar om att göra agenter smartare. Det handlar om att göra dem mer fokuserade.

En enda agent med perfekta instruktioner får ändå slut på kontext. En enda agent med alla skills blir ändå förvirrad över vilken som ska tillämpas. En enda agent som försöker vara allt ger mediokra resultat överallt.

Fyrtio specialister, var och en skicklig inom sin domän, koordinerade av en orkestrerare som vet när den ska delegera: så levererar vi.

Siffrorna spelar mindre roll än arkitekturen. Man kanske behöver fem agenter eller femtio. Principen kvarstår: komposition före kapacitet, specialisering före generalisering, koordination före enskilda hjältedåd.

Orkestra driver agentekosystemet bakom Maguyva, vår kodintelligensplattform. Vill du veta mer? Hör av dig till teamet.