Maguyva-Blog

Kontext, der mitreist

Mon, 07 Sep 2026 00:00:00 GMT

Cursors Indexer ist hervorragend – innerhalb von Cursor. Tab-Vervollständigung, Inline-Edit, Chat und der Agent in diesem Fenster sitzen bereits auf einem Projektindex, den Cursor für den geöffneten Workspace betreibt. Wenn Cursor die einzige Oberfläche ist, in der du schreibst, und dieser Index bereits die richtigen Dateien findet, bleib dort. Das ist der ehrliche Bleib-wo-du-bist-Fall, und er gehört zu Recht in den ersten Satz dieser Seite.

Dieser Beitrag handelt von der anderen Hälfte einer gewöhnlichen Woche. Dasselbe Repository wird auch in Claude Code geöffnet, von Codex CLI befragt, auf einer zweiten Maschine geprüft oder von einem Agenten in CI abgefragt. Die Frage ist nicht „welcher Indexer ist besser“. Die Frage ist, ob die Karte, der der Agent in einem Fenster vertraut, dieselbe ist wie die im nächsten.

Maguyva ist diese mitreisende Karte. Es ist eine entfernte MCP-Codebase-Context-Schicht. Der Agent fragt sie genauso ab wie jedes andere MCP-Tool. Ergebnisse kommen als gerankte Pfade mit Zeilennummern zurück. Cursor bleibt der Editor. Der Kontext ist das, was sich bewegt.

Wofür Cursors Indexer da ist

Cursors eingebaute Indexierung existiert, damit Chat, Agent und Suche im Editor relevanten Code abrufen können, statt sich nur auf das zu verlassen, was ins rohe Kontextfenster des Modells passt. Das ist das richtige Design für eine IDE. Der Index ist nativ zu Cursor. Er ist kein MCP-Server und von keinem anderen Client aus erreichbar.

So funktioniert es, wie in Cursors öffentlicher Dokumentation und Cursors eigener Darstellung zum Zeitpunkt dieses Textes beschrieben: Der primäre Suchpfad ist keine Cloud-Embedding-Index mehr. Cursors Team erklärte in seinem Community-Forum, dass die dedizierte semantische/Embedding-basierte Suche zugunsten grep-basierten Retrievals zurückgefahren wird, weil aktuelle Modelle einen lebenden Baum von sich aus gut genug durchsuchen. An ihrer Stelle steht Instant Grep, ein lokaler Suchindex aus n-Grammen, invertierten Listen und Bloomfiltern, gehalten in einer memory-gemappten Lookup-Tabelle, sodass Abfragen auf der eigenen Maschine des Entwicklers aufgelöst werden statt auf einem Server.

Der Index selbst liegt im eigenen .git/cursor/-Verzeichnis des Repositorys, verankert an einem bestimmten Git-Commit; Änderungen seit diesem Commit legen sich als Schicht darüber, statt einen erneuten Scan auszulösen, und der Index baut sich nur neu auf, wenn der lokale Zustand weit von dem abgewichen ist, wogegen er gebaut wurde. Weil er in .git liegt, wird er nie versioniert und nie gepusht – lösche den Ordner, und der Index ist weg. .gitignore wird konstruktionsbedingt respektiert, da nur git-verfolgter Inhalt infrage kommt, und .cursorignore wird auf dem Lesepfad durchgesetzt. Es gibt in diesem Pfad keinen serverseitigen Embedding-Schritt und keine entfernte Vektordatenbank mehr. Frühere Dokumentation beschrieb ein Cloud-unterstütztes Design – Chunk-Verschlüsselung, einen Merkle-Tree-Abgleich, teamübergreifende Indexwiederverwendung – und Cursors eigenes Team hat inzwischen gesagt, dass dieses Design zurückgefahren wird, weshalb dieser Beitrag es nicht mehr als aktuell beschreibt.

Eine Besonderheit im Editor ist Cursors Explore-Subagent. Er kann mehrere parallele Suchen in seinem eigenen Kontextfenster auf einem schnelleren Modell starten und nur die relevanten Funde zurückgeben, sodass sich das Hauptgespräch nicht mit Suchtreffern aufbläht. Das ist eine echte Stärke innerhalb des Editors. Behalte sie.

Multi-Root-Workspaces werden unterstützt: Der Kontext jedes geöffneten Ordners steht dem Agent zur Verfügung. Manche git-abhängigen Funktionen wie Worktrees sind in Multi-Root-Setups deaktiviert, und Cloud Agents unterstützen Multi-Root-Workspaces überhaupt nicht.

Nichts davon ist ein Grund, Cursor zu verlassen. Es ist eine präzise Beschreibung einer Karte, die dort hervorragend ist, wo sie lebt.

Was „mitreisen“ wirklich bedeutet

Eine Karte reist mit, wenn dieselben Fragen aus mehr als einem Client dieselbe Art von Antwort liefern, mit Zitaten, die du öffnen kannst.

In Cursor: „Wo ist parseConfig definiert, und wer ruft es auf?“
In Claude Code, im selben Repo: dieselbe Frage.
In Codex CLI, auf einer Review-Maschine, die das Cursor-Fenster nie geöffnet hat: dieselbe Frage.
In einem CI-Agenten, der MCP spricht: dieselbe Frage, gegen denselben gehosteten Snapshot.

Wenn jede Oberfläche ihren eigenen privaten Index baut, hast du keine eine Karte. Du hast mehrere Caches, die auseinanderdriften. Der Editor-Index kann aktuell für den Baum auf der Festplatte sein. Die CLI-Sitzung kann einen Tag hinterherhängen. Der CI-Job kann auf einen anderen Checkout blicken. Der Agent klingt trotzdem weiterhin überzeugt.

Cursors Indexer soll das nicht lösen. Weil er im Editor lebt, ist der Kontext, den er baut, für diesen Editor. Ein Leser, der auch eine CLI, eine CI-Pipeline oder einen anderen Editor braucht, braucht ein separates Werkzeug für diese Oberflächen. Das ist eine Frage des Geltungsbereichs, kein Mangel. Maguyva ist dieses separate Werkzeug.

Eine veröffentlichte Sprachanzahl für Cursors Indexer ist in den Notizen, die dieser Entwurf verwenden darf, nicht angegeben. Maguyva veröffentlicht 279+ Sprachen und textbasierte Technologien. Preise für Cursor werden hier ebenfalls nicht übernommen; siehe deren Preisseite. Maguyva berechnet pro Workspace, nicht pro Sitzplatz, mit veröffentlichten Plänen bei $0, $19, $49 und $149, je nach indiziertem Umfang und Workspace-Größe.

Eine gehostete Karte, jeder MCP-Client

Maguyva ist ein entfernter MCP-Server. Du verbindest GitHub, wählst die Repositories, und die Cloud-Pipeline baut Symbole, Graphkanten und eine gerankte Karte. Du fügst einen API-Schlüssel zur MCP-Konfiguration des Clients hinzu, den du bereits nutzt. Maguyva hat Einrichtungsanleitungen für 24 dokumentierte MCP-Clients – Cursor eingeschlossen – und kann sich mit anderen MCP-kompatiblen Clients verbinden, die die Standard-MCP-Konfiguration unterstützen.

Die Cursor-Einrichtungsseite ist der editor-spezifische Weg, falls du dort arbeitest. Derselbe Server bedient Claude Code, VS Code, Windsurf, Codex CLI und den Rest. Du wechselst den Editor nicht. Du gibst jedem Agenten dieselbe Werkzeugoberfläche: 11 kundenseitige MCP-Tools über Suche, Symbole, Abhängigkeitsanalyse, Dateiabruf, Repository-Kontext und deterministische Utility-Workflows. Semantisches, strukturelles, Graph- und Textretrieval werden zu gerankten Ergebnissen fusioniert.

Das ist der Portabilitätsvorteil. Die Zitate, die du heute Morgen in Cursor geprüft hast, haben dieselbe Form wie die Zitate, die Codex CLI heute Abend liefert. Dateipfad und Zeilennummer. Öffne sie. Wenn sie falsch sind, siehst du es. Wenn sie richtig sind, hat die nächste Änderung einen Platz zum Landen. Das freigegebene Versprechen sind weniger halluzinierte Änderungen, nicht das Versprechen, dass jede Änderung korrekt ist.

Aktualität ist veröffentlicht. Snapshots sind zeitgestempelt, sodass der Agent weiß, welche Version des Baums er liest. Der Rebuild-Rhythmus ist täglich im kostenlosen Plan und stündlich in bezahlten Plänen. Die ehrliche Grenze ist unsynchronisierte lokale Arbeit: Eine Änderung, die nur im Arbeitsverzeichnis existiert, ist noch nicht in der gehosteten Karte. Diese Grenze ist dieselbe, egal aus welchem Client du abfragst, und genau das ist der Punkt. Drift zwischen Clients ist keine zweite, versteckte Grenze mehr.

Die Docs geben die Aktivierungsschleife an, die für jeden Client gilt: ein Repo indizieren, das du schon kennst, den Client verbinden, eine Frage stellen, die du prüfen kannst. Mach das einmal in Cursor. Mach es noch einmal von der CLI, die du an Review-Tagen tatsächlich nutzt. Wenn beide Antworten denselben Handler zitieren, ist die Karte mitgereist.

Wie die beiden Karten nebeneinander bestehen

Nutze beide. Sie sind keine Alternativen im Sinne einer Vergleichsseite.

Lass Cursors Indexer für das Projekt auf der Festplatte an. Lass Explore, Instant Grep und den Agenten im Editor ihn nutzen. Diese Schleife ist nativ und schnell.
Füge Maguyva als MCP-Server in Cursor hinzu, sodass dieselbe Sitzung auch die gehostete Workspace-Karte abfragen kann. Cursor ist ein dokumentierter Maguyva-Client. Du wählst nicht einen Index und löschst den anderen.
Füge denselben Maguyva-Server zu Claude Code, Codex CLI oder jedem anderen MCP-Client hinzu, der das Repo berührt. Eine API-Schlüsselform. Ein Workspace.
Wenn ein CI-Agent MCP-kompatibel ist, richte ihn auf denselben Server. Er liest denselben zeitgestempelten Snapshot, den auch der Laptop las.

Der Editor-Index bleibt das beste Werkzeug für „was liegt gerade auf der Festplatte in diesem Fenster“. Die gehostete Karte ist das beste Werkzeug für „wie sieht dieser Workspace für jeden Agenten aus, der ihn heute berührt“. Diese Sätze stehen nicht in Konkurrenz.

Workspace-Kontingente sind auf der Preisseite veröffentlicht: Repos, indizierte Zeilen und Nutzer, abgerechnet pro Workspace. Agenten und Menschen teilen sich dieselbe Nutzerzahl. Starte kostenlos mit einem Repo, das du schon beurteilen kannst. Erhöhe den Workspace erst, nachdem die Zitate den Kontakt mit dem Baum überstanden haben.

Was diese Seite nicht behauptet

Sie behauptet nicht, dass Cursors Indexer schwach, unvollständig oder ein Grund zum Editorwechsel ist. Der erste Satz dieses Entwurfs ist das Gegenteil.

Sie behauptet nicht, dass Maguyva Instant Grep oder den Explore-Subagenten ersetzt. Das sind Cursor-Funktionen. Sie bleiben in Cursor.

Sie erfindet keine Sprachanzahl, keine Latenzzahl und keine Token-Ersparnis für eines der beiden Produkte. Unbekannte Zahlen bleiben unveröffentlicht.

Sie tut nicht so, als sei ungepushte lokale Arbeit in der gehosteten Karte. Zeitgestempelte Snapshots machen diese Grenze sichtbar. Sie beseitigen sie nicht.

Der Test ist gewöhnlich. Indiziere ein Repo, das du schon kennst. Stelle eine Frage, die du prüfen kannst, zuerst in Cursor, dann in einem zweiten MCP-Client. Kontext, der mitreist, ist an beiden Orten dasselbe Zitat.

// same map, wherever you opened it.

Erst die Karte, dann das Review

Mon, 07 Sep 2026 00:00:00 GMT

Zwei verschiedene Aufgaben stehen auf beiden Seiten eines Pull Requests. Bevor der Agent schreibt, braucht er eine Karte des Baums, den er gleich ändert. Nachdem der Agent einen PR eröffnet hat, sollte etwas diese Änderung gegen den Rest des Systems lesen und Kommentare hinterlassen, nach denen ein Mensch handeln kann.

Diese Aufgaben sehen aus der Ferne ähnlich aus, weil beide „das Codebase verstehen“ beinhalten. Sie sind nicht dasselbe Produkt. Die eine beantwortet „wo sollte diese Änderung landen?“. Die andere beantwortet „was hat dieser Diff kaputtgemacht, das ein zeilenweiser Linter übersehen wird?“. Sie zu vermischen ergibt einen schlechteren ersten Entwurf und ein lauteres Review.

Dieser Beitrag ist ein Guide für ein gemeinsames Workflow. Maguyva ist die Karte, die der Agent zuerst abfragt. Greptile ist der Review-Agent, der danach den PR kommentiert. Das Paar ist von Natur aus komplementär: Maguyva reviewt keine Pull Requests, und Greptile ersetzt nicht die Context-Schicht, die der Agent zum Schreiben genutzt hat.

Warum die Aufteilung nützlich ist

Ein Coding-Agent, der von Trainingspriors plus ein paar eingefügten Dateien ausgeht, erfindet einen plausiblen Pfad und editiert ihn. Das ist das Falsche-Datei-Versagen, und es ist ein Retrieval-Problem. Maguyva ist eine entfernte MCP-Codebase-Context-Schicht: Semantisches, strukturelles (AST), Graph-/Abhängigkeits- und Textretrieval, fusioniert zu gerankten Ergebnissen, plus Symbol-Lookup und Dateiabruf. Fundierte Antworten kommen als path/file.ext:line zurück, sodass du einen Fehltreffer ablehnen kannst, bevor ein Patch existiert. Das Versprechen bleibt bescheiden: weniger halluzinierte Änderungen. Das Modell kann trotzdem raten. Der erste Schritt hört nur auf, ein Raten zu sein.

Greptile ist ein KI-Code-Review-Agent. In ihren eigenen Worten reviewt es automatisch jeden Pull Request mit vollständigem Verständnis der Codebase, und es positioniert das gegen traditionelle Linter, die Dateien isoliert statt das ganze System prüfen. Die Einrichtung besteht darin, die GitHub- oder GitLab-App zu installieren und Repositories auszuwählen. Es gibt keinen lokalen Index, den du betreiben musst. Gehostet wird auf Greptile Cloud (sie geben SOC-2-Typ-II-Konformität an, mit einem Bericht auf Anfrage), mit einer Self-Hosted-Option für Unternehmen.

Ihr eigener nummerierter Ablauf ist: verbinden und einen Dependency-Graphen jeder Funktion, Klasse und Abhängigkeit bauen; bei jedem Pull Request die Änderung anhand dieses Gesamt-Repo-Graphen analysieren und Befunde als PR-Kommentare mit Änderungsvorschlägen posten, in etwa drei Minuten; jeder Kommentar kann das Problem an einen Coding-Agenten übergeben, den das Team bereits nutzt. Sie geben außerdem an, frühere menschliche PR-Kommentare über die Zeit zu lesen, um die Coding-Standards eines Teams zu lernen und störende Vorschläge zu reduzieren. Ihr Lernsystem soll laut eigener Angabe 2–3 Wochen zum Anpassen brauchen.

Das ist Review, kein Entwurf. Greptiles Stärke ist der Gesamt-Repo-Graph-Kontext auf die Änderung, die bereits in einem PR gelandet ist, dann eine geschlossene Schleife, die den Befund an Claude Code, Codex, Conductor, Cursor oder Devin sendet. Maguyvas Stärke ist die gerankte Karte, die der Agent abgefragt hat, bevor diese Änderung geschrieben wurde. Nutze beide. Verlang von keinem der beiden, den Job des anderen zu machen.

Eine Erstanbieter-Integration Maguyva–Greptile ist nicht angegeben. Du brauchst auch keine. Maguyva spricht über MCP mit dem Agenten. Greptile spricht über deren App mit GitHub oder GitLab. Sie treffen sich beim Pull Request. Kein Glue-Script, kein Cron, der das eine Werkzeug ins andere leitet. Das Paar kommt ohne Bash aus, weil jedes Produkt bereits auf der Oberfläche sitzt, die ihm gehört.

Was das hier nicht ist

Das ist kein Verriss von Greptile. Es ist keine „Wechsle deinen Reviewer“-Seite. Greptile startete am 5. März 2024 auf Hacker News als Y-Combinator-W24-Unternehmen, und dieser Thread ist, wie viele Leute das Produkt zuerst kennengelernt haben. Wenn du sie so gefunden hast, behalte sie. Diese Seite ist die fehlende vordere Hälfte dieser Schleife: den Agenten so verankern, dass der PR, den Greptile sieht, schon auf die richtigen Dateien zielt.

Greptiles Marketingmaterial führt mit Review-Geschwindigkeits- und Bug-Fang-Behauptungen. Behandle diese als Greptiles eigene Behauptungen, nicht als unabhängig verifizierte Zahlen. Dieser Entwurf gibt sie nicht als Fakten wieder.

Sprachabdeckung ist dieselbe Art von Ehrlichkeit. Greptile rahmt Unterstützung als Abdeckung aller Programmiersprachen statt einer aufgezählten Liste; eine genaue Zahl ist nicht angegeben. Maguyva veröffentlicht 279+ Sprachen und textbasierte Technologien, mit einer technischen Aufteilung (parser-gestütztes AST versus reiner Text) auf der Seite, wenn die Frage technisch ist. Das sind unterschiedliche Produkte mit unterschiedlichen Behauptungen. Vermisch sie nicht.

Preise für Greptile sind in den Notizen, die dieser Entwurf verwenden darf, nicht angegeben. Bezahlte Pläne existieren; siehe deren Preisseite. Maguyva berechnet pro Workspace, nicht pro Sitzplatz. Pläne starten kostenlos. Die Preisseite listet die veröffentlichten Stufen, falls du die Workspace-Zahlen brauchst.

Workflow

Drei benannte Stufen. Führe sie in dieser Reihenfolge aus. Überspring beim ersten Versuch dieser Paarung keine davon.

1. Maguyva-Kontext

Indiziere ein Repository, das du schon kennst. Verbinde den MCP-Client, in dem du schon schreibst – Claude Code, Cursor, Codex CLI, VS Code, Windsurf oder einen anderen MCP-kompatiblen Client. Maguyva hat Einrichtungsanleitungen für 24 dokumentierte MCP-Clients und kann sich mit anderen Clients verbinden, die die Standard-MCP-Konfiguration unterstützen.

Stell eine Frage, die du beurteilen kannst, bevor irgendjemand eine Zeile schreibt. „Wo wird der Ablauf der Sitzung behandelt, und was ruft das auf?“ ist ein besserer erster Zug als „repariere die Auth“. Verlange Zitate. Öffne die file.ext:line-Ergebnisse. Folge dem Symbol. Bestätige die Abhängigkeit, die du gleich anfasst.

Maguyva stellt 11 kundenseitige MCP-Tools über Suche, Symbole, Abhängigkeitsanalyse, Dateiabruf, Repository-Kontext und deterministische Utility-Workflows bereit. Vier Retrieval-Modi werden zu gerankten Ergebnissen fusioniert; find_symbol ist ein separates Tool, wenn du den Namen schon kennst. Die Docs beschreiben den kürzesten Weg: kostenlos starten, ein Repo indizieren, das du schon kennst, den Client verbinden, dann eine Frage stellen, die du prüfen kannst.

Snapshots sind zeitgestempelt, sodass der Agent erkennen kann, welche Version des Baums er liest. Die ehrliche Grenze ist unsynchronisierte lokale Arbeit. Wenn die Änderung nur in einem Arbeitsverzeichnis existiert und nicht gepusht wurde, enthält die gehostete Karte sie noch nicht. Instruktionsdateien (CLAUDE.md, AGENTS.md) gehören auch weiterhin hierher, für Konventionen und was nicht angefasst werden soll. Sie sind keine lebendige Karte. Nutze sie für Verhalten. Nutze Maguyva für Fakten.

Lass den Agenten keinen PR eröffnen, bevor die Zitate den Kontakt mit dem Repo überstanden haben. Dieses Gate ist der ganze Sinn dieser Stufe.

2. Agent-PR

Derselbe Agent schreibt die Änderung nun in dem Client, für den du bereits bezahlst. Maguyva ist kein Editor und kein Reviewer. Der Agent produziert weiterhin den Diff. Du eröffnest den Pull Request weiterhin auf GitHub oder GitLab, so wie du es schon tust.

Was anders sein sollte, ist die erste Datei. Der PR sollte den Handler benennen, der das Verhalten tatsächlich implementiert, den Aufrufer, der brechen wird, und den Test, der fehlschlagen wird, wenn die Änderung falsch ist. Wenn Stufe 1 übersprungen wurde, verbringt Stufe 3 ihre Kommentare mit einer Änderung, die im falschen Paket gelandet ist. Greptile kann trotzdem systemische Probleme finden. Es sollte sich nicht auch noch von einem halluzinierten Pfad erholen müssen.

Halte den PR eng gefasst. Eine fundierte erste Datei ist keine Lizenz, das Modul umzuschreiben. Das komplementäre Paar funktioniert, wenn der Agent einen Job mit einer Karte erledigt hat und dann einen Reviewer gebeten hat, einen anderen Job an einem begrenzten Diff zu machen.

3. Greptile-Review

Greptile ist bereits über die GitHub- oder GitLab-App mit dem Repository verbunden. Beim neuen Pull Request analysiert es die Änderung anhand des gebauten Gesamt-Repo-Graphen und postet Befunde als Kommentare mit Änderungsvorschlägen. Ihr eigenes Material setzt diesen Durchgang bei etwa drei Minuten an.

Lies die Kommentare so, wie du einen sorgfältigen Teamkollegen lesen würdest: die zitierte Stelle öffnen, entscheiden, ob der Befund echt ist, dann handeln. Wo Greptile „Fix with your Agent“ anbietet, sendet es das Problem – Dateipfade, Zeilennummern, vorgeschlagenen Code – an Claude Code, Codex, Conductor, Cursor oder Devin. „Fix All“ sendet alle Probleme im Review auf einmal. Sie liefern außerdem einen Greptile-MCP und ein Claude-Code-Plugin für diese Übergabe. Maguyva steht nicht auf dieser benannten Zielliste; diese Abwesenheit ist kein Problem. Maguyva hat seine Arbeit schon in Stufe 1 erledigt. Der Coding-Agent, der den PR geschrieben hat, ist derjenige, der die Fix-Payload erhalten sollte.

Erwarte in den ersten 2–3 Wochen Rauschen, während sich Greptiles Lernsystem an die Kommentare anpasst, die dein Team tatsächlich hinterlässt. Das ist ihr angegebener Zeitrahmen, kein Mangel in der Paarung. Menschliches Review bleibt Teil der Schleife. Greptile ist der automatisierte erste Durchgang, nicht der Merge-Button.

Wenn ein Greptile-Kommentar auf eine Datei zeigt, die der Agent in Stufe 1 nie abgefragt hat, ist das ein nützliches Signal. Entweder hat die Karte einen Aufrufer verpasst, oder der Agent hat ein Zitat übersprungen. Repariere den Entwurf gegen den Kommentar. Deaktiviere nicht den Reviewer.

Wie man das Zusammenspiel ehrlich hält

Maguyva zuerst, immer. Ein Review eines Falsche-Datei-PRs ist immer noch ein Review der falschen Datei.
Greptile danach, immer. Ein gut zitierter Entwurf braucht trotzdem eine Gesamtsystem-Lesung des Diffs.
Bitte Maguyva nicht, PR-Kommentare zu posten. Das tut es nicht.
Bitte Greptile nicht, die erste Retrieval-Schicht des Agenten zu sein, während der noch einen Pfad wählt. Das ist nicht der Job, für den deren GitHub- oder GitLab-App gebaut ist.
Erfinde keine Bash-Pipeline, die die beiden „synchronisiert“. Der PR ist die Schnittstelle.
Prüfe beide Seiten unabhängig. Indiziere ein Repo, das du schon kennst. Stelle eine Frage, die du prüfen kannst. Öffne dann einen kleinen PR und lies, was Greptile tatsächlich kommentiert.

Die Schleife ist gewöhnlich, sobald man sie benennt. Erst die Karte. Dann der Agent-PR. Dann das Review. Jedes Produkt bleibt auf der Seite des Pull Requests, in der es gut ist.

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

Einem KI-Agenten Kontext eines großen Repos geben, ohne lokalen Indexer

Fri, 14 Aug 2026 00:00:00 GMT

Ein großes Repository passt nicht in ein Kontextfenster, und wenn du je einen Laptop-Indexer auf ein echtes Monorepo losgelassen hast, weißt du, dass es dort auch nicht bequem hineinpasst – der RAM schnellt hoch, der erste Index dauert eine Stunde, und dein Agent rät in der nächsten Sitzung immer noch, welche Dateien wichtig sind.

Die übliche Antwort ist, einen Indexer neben dem Editor laufen zu lassen, und für ein Repo, das bequem auf eine Maschine passt, ist das eine gute Antwort. Wenn dein Monorepo in Cursor schon schnell indiziert und das der einzige Ort ist, an dem du die Karte brauchst, hat dieser Beitrag nichts hinzuzufügen – überspring ihn.

Dieser Beitrag handelt vom anderen Fall – wenn ein Agent eine abfragbare Karte eines großen Repos braucht und du dafür keinen lokalen Indexer laufen lassen willst.

Wann ein lokaler Indexer das falsche Werkzeug ist

Ein lokaler Index setzt voraus, dass der Code auf der Maschine liegt, die ihn abfragt, und bei echter Monorepo-Größe gerät diese Annahme selbst innerhalb eines einzigen Editors ins Wanken. Das Repo ist schlicht größer, als du auf einem Laptop warmhalten willst: Du arbeitest in einem Paket, während der Auswirkungsradius drei Verzeichnisse weiter liegt, und einen kalten Erstindex eines Zwei-Millionen-Zeilen-Baums willst du dir nicht zweimal antun – weder auf deiner Maschine noch auf einem CI-Runner, der den Baum nie zuvor geklont hat. Oder ein Teammitglied sollte dieselbe Karte abfragen können wie du, ohne darauf zu warten, dass die eigene Maschine sich erst durch denselben Index arbeitet.

Nichts davon ist ein Grund, einen guten Editor-Indexer wegzuwerfen. Es ist ein Grund, zusätzlich eine gehostete Karte zu haben, die jeder deiner Agenten über MCP abfragen kann.

Und das Skalierungsproblem reicht tiefer als „zu viele Dateien zum Einfügen“. Auf einem großen Baum ist die interessante Frage fast nie „zeig mir diese Datei“ – sondern welche Datei, welches Symbol, welche Aufrufer, welche Tests. Ein Agent, der damit anfängt, src/ aufzulisten und die ersten drei Treffer zu lesen, verpasst mit Freude den Handler in apps/api und den generierten Client in packages/sdk. Was du brauchst, ist Retrieval, das aus dem gesamten Baum gebaut, dann gerankt, dann zitiert wurde.

Was „Kontext eines großen Repos“ wirklich bedeutet

Dateien in den Prompt zu kippen ist kein Kontext – es ist eine kleinere, schlechtere Kopie des Baums. Was dein Agent tatsächlich braucht, ist, Fragen zu stellen und zitierte Antworten zurückzubekommen: Wo ist dieses Symbol definiert und wer ruft es auf, was hängt von dem Modul ab, das ich gerade ändern will, welche Testdatei deckt dieses Verhalten ab, und wie sieht der Baum jetzt aus, nicht letztes Quartal.

Diese Antworten müssen aus einem Index kommen, der aus deinem Repo gebaut wurde, statt aus der Erinnerung des Modells an fremde Repos, und der Index muss anderswo leben als im Kontextfenster des Agenten. Für dieses Problem sollte er auch anderswo leben als auf deinem Laptop.

Noch etwas, was Instruktionsdateien nicht für dich leisten können: CLAUDE.md und AGENTS.md sind der richtige Ort für Konventionen und Verhalten, aber sie sind keine lebendige, gerankte, abfragbare Karte eines Zwei-Millionen-Zeilen-Baums. Nutze Regeln für Verhalten; nutze Repo-Intelligenz für Fakten.

Die Karte in der Cloud bauen, von jedem Client abfragen

Maguyva ist eine entfernte MCP-Codebase-Context-Schicht. Du verbindest GitHub, wählst deine Repositories, und gehst weg, während Cloud-Pipelines den Baum parsen, die Symbole und Graphkanten bauen und eine gerankte Karte pflegen – nie ein lokaler Indexer.

Wenn du Code pushst, werden geänderte Dateien inkrementell geparst, und die Graph- und Ranking-Schichten bauen sich nach einem Zeitplan neu auf: täglich im kostenlosen Plan, stündlich in bezahlten Plänen. Jeder Snapshot ist zeitgestempelt, sodass dein Agent erkennen kann, welche Version des Baums er liest. Die ehrliche Grenze hier ist unsynchronisierte lokale Arbeit – eine Änderung, die nur in deinem Arbeitsverzeichnis existiert und nie gepusht wurde, ist noch nicht in der gehosteten Karte.

Dann verkabelst du, welchen Client du auch nutzt, indem du einen API-Schlüssel zu dessen MCP-Konfiguration hinzufügst. Es gibt Einrichtungsanleitungen für 24 dokumentierte MCP-Clients, und jeder andere MCP-kompatible Client, der Standardkonfiguration unterstützt, kann sich ebenfalls verbinden. Wenn Cursor dein Zuhause ist, geht die Cursor-Seite diesen Weg; derselbe Server bedient Claude Code, VS Code, Windsurf, Codex CLI und den Rest.

Du wechselst den Editor nicht. Du gibst deinem Agenten eine Werkzeugoberfläche – 11 MCP-Tools über Suche, Symbole, Abhängigkeitsanalyse, Dateiabruf und Repository-Kontext – mit Abdeckung über 279+ Sprachen und textbasierte Technologien, was auf einem Monorepo, das schon lange keine einzelne Sprache mehr ist, mehr zählt, als man denkt.

Antworten kommen fundiert zurück, als Dateipfade mit Zeilennummern. Semantisches, strukturelles, Graph- und Textretrieval werden zu gerankten Ergebnissen fusioniert, sodass eine Frage wie „was hängt von parseConfig ab“ weder einen Grep-Dump noch einen einzelnen semantischen Chunk liefert, sondern die Handvoll Stellen, die tatsächlich zählen.

Eine konkrete Anleitung

Fang nicht damit an, die ganze Firma zu indizieren. Hier ist der Weg, der funktioniert:

Wähle ein Repository, das du schon gut kennst – ein Paket, das du von Hand beurteilen kannst, schlägt den größten Baum, den du hast.
Starte kostenlos: 3 Repos, 50.000 indizierte Zeilen, alle 11 Tools, kein monatliches Abfragelimit. Wenn dein repräsentatives Repo größer ist, listet die Preisseite die Workspace-Stufen ($0, $19, $49, $149) nach indiziertem Umfang – nicht nach Sitzplatzzahl.
Verbinde GitHub und warte, bis der erste Index fertig ist. Du kompilierst dabei nichts lokal.
Verkabele den MCP-Client – ein paar Zeilen Konfiguration. Maguyva ist ein entfernter MCP-Server, also gibt es keine Plugins, keine Erweiterungen und keinen zweiten Editor, den du übernehmen musst.
Stelle eine Frage, die du prüfen kannst. „Was hängt von parseConfig ab?“ oder „Wo wird der Ablauf der Login-Sitzung behandelt?“ Öffne dann die zitierten file.ext:line-Ergebnisse und prüfe sie gegen den Baum vor dir.
Erst wenn die Zitate diesen Kontakt überstehen, lässt du den Agenten editieren.

Wenn das erste Repo gut passt und dein Baum groß ist, erhöhe den Workspace passend zu deinen indizierten Zeilen und dem Rebuild-Rhythmus. Menschen und Agenten teilen sich dieselbe Nutzerzahl – Maguyva berechnet pro Workspace, nicht pro Sitzplatz –, sodass ein dritter Agent in der Schleife dich nichts kostet.

Der Aktivierungstest ist derselbe, den die Docs für jeden ersten Lauf empfehlen: ein Repo indizieren, das du schon kennst, eine Frage stellen, die du prüfen kannst. Ein großes Repo ändert den Test nicht; es macht nur eine falsche erste Datei teurer.

Worauf nach dem Verkabeln achten

Behalte drei Dinge im Blick. Aktualität: bezahlte Pläne bauen stündlich neu, kostenlose täglich, und ungepushte lokale Arbeit wird nicht in der Karte sein – das ist der Kompromiss, den du eingehst. Umfang: indiziere eine repräsentative Menge an Repos, nicht jeden archivierten Fork; die kostenlose Stufe ist bewusst so bemessen, dass du herausfindest, ob die Antworten das Behalten wert sind. Und Verifikation: eine Große-Repo-Karte, die keine Pfade und Zeilennummern zitieren kann, ist nur eine langsamere Rate-Maschine, also lass deinen Agenten den Ort zeigen, bevor er den Patch ausliefert.

Dann führe denselben Test durch, den du bei einem kleinen Repo durchführen würdest. Indiziere ein Repo, das du schon kennst. Stelle eine Frage, die du prüfen kannst. Wenn die Karte echt ist, hört dein Agent auf, von einem kalten Baum aus zu starten.

// no laptop got hot building this map.

Warum dein KI-Coding-Agent Dateipfade halluziniert

Fri, 14 Aug 2026 00:00:00 GMT

Das Verräterische ist nicht ein falscher Funktionskörper. Es ist eine selbstsichere Änderung an einer Datei, die nicht existiert, oder an einer Datei, die zwar existiert, aber nicht diejenige ist, die das Verhalten implementiert.

Du hast um eine Reparatur des Sitzungsablaufs gebeten. Der Agent hat src/auth/session.ts geöffnet. Dieser Pfad ist plausibel. Er ist auch falsch. Der echte Handler lebt in apps/api/src/middleware/expiry.ts, umbenannt vor zwei Refactorings. Der Agent hat dich nicht angelogen. Er hat einen pfadförmigen String aus Trainingspriors plus was auch immer schon im Kontextfenster war vervollständigt.

Das ist das übliche Versagensmuster auf einem echten Repository. Das Modell kann Code schreiben. Der Fehler liegt darin, den falschen Ort zum Schreiben zu wählen.

Warum Agenten Pfade erfinden

Ein Coding-Agent ist ein Next-Token-Modell mit Werkzeugen. Wenn du sagst „repariere den Sitzungsablauf“, muss er eine Datei benennen, bevor er irgendetwas lesen oder patchen kann. Wenn er noch keine verankerte Karte hat, konstruiert er einen Pfad aus:

Namenskonventionen, die er in anderen Repositories gesehen hat. src/auth/session.ts ist eine häufige Form.
Dateien, die schon im Gespräch sind, die vielleicht die sind, die du letzte Woche eingefügt hast, nicht die, die jetzt zählen.
Verzeichnislistings, die er zufällig ausgeführt hat, die auf einem großen Baum unvollständig sind.
Instruktionsdateien. CLAUDE.md und AGENTS.md sagen dem Agenten, wie er sich verhalten soll. Sie sind kein lebendiger Index von Symbolen, Aufrufern oder aktuellen Pfaden.

Keine dieser Quellen ist eine Karte dieses Repos, heute. Das Modell füllt die Lücke so, wie es jede Lücke füllt: mit einer hochwahrscheinlichen Fortsetzung. Diese Fortsetzung sieht oft wie ein echter Pfad aus. Manchmal existiert die Datei und liegt neben der richtigen. Manchmal existierte sie auf einem Branch, der letzten Monat gemergt wurde. Manchmal hat sie nie existiert.

Grep rettet dich hier nicht, wenn der Agent nie nach dem richtigen String sucht. Der Agent hat einen Pfad geraten, dann gelesen, was dieser Pfad zurückgab, dann editiert. Der erste falsche Schritt war der Pfad, nicht der Patch.

Dateien zu lesen ist auch nicht dasselbe wie die richtigen zu finden. Claude Code, Cursor, Codex und ähnliche Werkzeuge können öffnen, worauf du sie zeigst. Die Frage ist, ob sie zuverlässig die richtigen Dateien finden, die wichtigen Symbole, die Abhängigkeiten, die Tests und den Auswirkungsradius, bevor sie editieren. Dateizugriff ohne Karte fängt immer noch mit einem Raten an.

Die Falsche-Datei-Änderung ist ein Retrieval-Problem

Behandle den erfundenen Pfad als Retrieval-Fehltreffer, nicht als Charakterfehler.

Wenn der Agent path/file.ext:line zurückgeben müsste, bevor er editieren darf, würden zwei Dinge passieren. Erstens könntest du das Zitat öffnen und die Arbeit in zehn Sekunden ablehnen. Zweitens müsste der Agent etwas abfragen, das den Baum tatsächlich kennt.

Das ist der Job einer Codebase-Context-Schicht. Semantische Suche allein reicht nicht. Ein Chunk, der „nach Sitzungsablauf klingt“, kann trotzdem in einem veralteten Paket landen. Du brauchst auch exakten Text, wenn du den String kennst, Symbol-Lookup, wenn du den Namen kennst, strukturelle Suche, wenn du die Form kennst, und einen Dependency-Graphen, wenn du Aufrufer und Auswirkungsradius brauchst.

Maguyva ist diese Schicht für MCP-kompatible Coding-Agenten. Es ist kein Editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf und andere MCP-Clients bleiben, wo sie sind. Der Agent fragt eine gerankte Karte ab, bevor er eine Zeile anfasst.

Das Versprechen ist absichtlich bescheiden: weniger halluzinierte Änderungen. Maguyva nimmt dem Modell nicht die Fähigkeit zu raten. Es ändert den Standard-ersten-Schritt von „einen plausiblen Pfad erfinden“ zu „nach gerankten, zitierten Orten fragen“.

Wie eine fundierte Antwort aussieht

Eine nützliche Antwort auf „wo wird der Sitzungsablauf behandelt“ ist kein Absatz. Es ist eine kurze Liste von Orten:

apps/api/src/middleware/expiry.ts:48 - der Handler
apps/web/src/lib/auth-client.ts:112 - der Aufrufer
apps/api/tests/expiry.test.ts:20 - der Test, der fehlschlägt, wenn die Änderung falsch ist

Du kannst diese Zeilen öffnen. Wenn sie falsch sind, stoppst du. Wenn sie richtig sind, darf der Agent editieren. Die Verifikation ist der Punkt, kein Slogan.

Maguyva stellt 11 kundenseitige MCP-Tools über Suche, Symbole, Abhängigkeitsanalyse, Dateiabruf, Repository-Kontext und deterministische Utility-Workflows bereit. Vier Retrieval-Modi (semantisch, strukturell, Graph/Abhängigkeit und Text) werden zu gerankten Ergebnissen fusioniert; Symbol-Lookup ist ein separates MCP-Tool (find_symbol). Fundierte Antworten kommen mit Dateipfaden und Zeilennummern zurück, sodass du sie gegen den Baum vor dir beurteilen kannst.

Die Docs beschreiben den kürzesten Weg: kostenlos starten, ein Repo indizieren, das du schon kennst, den Client verbinden, dann eine Frage stellen, die du prüfen kannst.

Eine Schleife, die die erste Änderung ändert

Du brauchst keine neue Workflow-Religion. Du brauchst einen zusätzlichen Schritt vor dem ersten Schreiben.

Stell eine Frage, die du schon beurteilen kannst. „Welcher Code behandelt Login und Sitzungsablauf?“ ist besser als „repariere die Auth“.
Verlange Zitate. Dateipfad und Zeilennummer, keine Zusammenfassung von „dem Auth-Modul“.
Öffne die zitierten Dateien. Folge dem Symbol. Bestätige die Abhängigkeit, die du gleich anfasst.
Erst dann lass den Agenten patchen.

Wenn Schritt 2 nichts Nützliches liefert, darf der Agent keinen Pfad improvisieren. Er sucht erneut, oder du zeigst ihm den Weg. Dieses eine Gate ist es, was weniger halluzinierte Änderungen erzeugt. Das Modell ist dasselbe Modell. Die Karte ist, was sich geändert hat.

Instruktionsdateien zählen weiterhin. Behalte sie. Nutze sie für Konventionen, Review-Regeln und was nicht angefasst werden soll. Bitte sie nicht, der Index zu sein. Ein CLAUDE.md, das drei wichtige Verzeichnisse auflistet, ist die Woche nach einem Paket-Split veraltet. Eine abfragbare Karte aktualisiert sich, wenn sich das Repo aktualisiert.

Ein verwandtes Versagen ist die Beinahe-Treffer-Datei: Der Agent öffnet auth.ts, wenn das Verhalten in auth-client.ts lebt, oder patcht eine generierte Datei statt der Quelle, oder editiert die Kopie in packages/legacy, weil der Name gepasst hat. Zitate machen diese Fehler nicht unmöglich. Sie machen sie sichtbar, bevor der Diff landet.

Was eine Karte nicht für dich löst

Sei ehrlich zu dir selbst, was du bekommst. Eine fundierte Karte macht nicht jede Änderung korrekt – dein Agent kann trotzdem einen schlechten Patch in genau der richtigen Datei schreiben. Wenn dein Codebase auf dynamischem Dispatch, Reflection oder Monkey-Patching aufbaut, kommen manche Symbol-Lookups dünner zurück, als dir lieb ist, weil das nun mal ist, was Laufzeit-Indirektion mit jedem statischen Index macht. Und wenn du auf eine Prozentzahl hoffst – „halluzinierte Pfade um X% reduziert“ – wirst du sie hier nicht finden, weil niemand diese Zahl für dein Repo ehrlich messen kann außer dir selbst.

Was du erwarten kannst, ist enger gefasst und nützlicher: Der Agent hört auf, seine Änderungen mit einem geratenen Pfad zu beginnen. Dieser erste Schritt ist in einer echten Karte verankert, und daher kommen weniger halluzinierte Änderungen. Alles nach dem Zitat – den Diff lesen, den Patch beurteilen – ist immer noch dein Job, genau wie es immer war.

Der Test kostet dich fast nichts: ein Repo indizieren, das du schon kennst, und eine Frage stellen, die du prüfen kannst. Fang mit einem Pfad an, mit dem du schon einmal auf die Nase gefallen bist. Wenn die Zitate falsch sind, siehst du es sofort. Wenn sie richtig sind, hat die nächste Änderung deines Agenten einen besseren Ort zum Landen.

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

Warum wir unsere Code-Suche auf voyage-4-large upgegradet haben

Tue, 09 Jun 2026 00:00:00 GMT

Die Benchmark-Zahlen in diesem Beitrag spiegeln die RTEB-Ranglisten zum Veröffentlichungszeitpunkt (Juni 2026) wider. Ranglisten verändern sich; betrachte die Platzierungen als Momentaufnahme, nicht als dauerhafte Tatsache.

Semantische Suche ist immer nur so gut wie die Embeddings, die ihr zugrunde liegen.

Wenn ein Agent Maguyva fragt, “wo behandeln wir Retries”, sucht er nicht per grep nach dem Wort “retry”. Er fragt nach der Bedeutung – der Backoff-Schleife, dem Circuit Breaker, dem Ding, das einen instabilen Aufruf umhüllt. Diese Frage wird von einem Vektormodell beantwortet, das Code in einen Punkt im Raum verwandelt und dessen Nachbarn findet. Wähle ein besseres Modell, und jede semantische Abfrage im Produkt wird still und leise präziser.

Also haben wir unseres geändert. Seit Juni 2026 laufen die Code-Embeddings von Maguyva auf voyage-4-large und ersetzen voyage-code-3.

Der Benchmark

Wir haben diese Entscheidung nicht aus dem Bauch heraus getroffen. Der öffentliche Retrieval Embedding Benchmark (RTEB) bewertet Embedding-Modelle anhand realer Retrieval-Aufgaben, und auf seiner Code-Rangliste steht voyage-4-large auf Platz 1 insgesamt (90,86) – vor gemini-embedding-2-preview (90,26) und, bemerkenswerterweise, vor dem Modell, das wir zuvor verwendet haben, voyage-code-3 (89,73, Platz 3).

Das ist eine kleine absolute Differenz. Aber es ist eine Differenz in die richtige Richtung, auf einem öffentlichen Benchmark, bei genau der Aufgabe, die uns wichtig ist: Code anhand seiner Bedeutung wiederzufinden.

Der Kompromiss, den wir eingehen: Binäre Quantisierung

Das ist der Teil, den die meisten “Wir haben unser Modell aktualisiert”-Beiträge auslassen.

Maguyva speichert keine Vektoren in voller Präzision. Wir speichern binär quantisierte Embeddings: Jeder 2048-dimensionale Vektor wird zu einer 2048-Bit-Signatur komprimiert – 256 Byte pro Vektor. Diese Signaturen werden per Hamming-Distanz durchsucht, indiziert und pro Mandant partitioniert.

Das ist ein bewusster Kompromiss. Binäre Quantisierung gibt einen Teil der Retrieval-Präzision auf, im Austausch für drastisch kleineren Speicherbedarf und schnelle, günstige Distanzberechnungen, ohne eine separate Vektordatenbank zu betreiben. Für ein Produkt, das ganze Repositories pro Workspace indiziert, zählt diese Wirtschaftlichkeit mehr, als den letzten Bruchteil eines Benchmark-Punkts herauszupressen.

voyage-4-large fügt sich in dieses Design ein, ohne eine Migration der Speicherschicht zu erzwingen: Es erzeugt eine 2048-dimensionale Ausgabe, genau wie voyage-code-3, sodass sich unsere bit(2048)-Spalten und der Hamming-Suchpfad nicht geändert haben. Das Modell wurde besser; das Schema blieb, wie es war.

Code war nur der Anfang

Maguyva ist ein Code-Intelligence-Tool. Aber wir sind auch Kunde Nummer eins und richten es auch auf etwas anderes: das Markdown, das in unseren Repos neben dem Code liegt. Architekturentscheidungsprotokolle, Runbooks, Verträge, Finanz- und Richtliniendokumente – alles versionskontrolliert in Git, alles hinter demselben MCP-Server, ein semantischer Index über die Dokumente, nicht nur über den Quellcode.

Genau deshalb zählt die Breite von voyage-4-large. Auf derselben RTEB-Familie von Ranglisten steht es auf Platz 1 im Bereich Finanzen, Platz 1 im Bereich Gesundheitswesen und Platz 1 beim gesamten Text-Retrieval – vor Gemini Embedding von Google, Embed v4 von Cohere und text-embedding-3-large von OpenAI. (Voyage ist Mitentwickler von RTEB, daher lesen wir das als starkes öffentliches Signal, nicht als perfekt neutralen Schiedsrichter – aber es wird direkt gegen jedes große kommerzielle Modell auf privaten Hold-out-Datensätzen gemessen.) Derselbe Index, der für einen Agenten die richtige Funktion findet, findet auch die richtige Klausel in einem Vertrag oder die richtige Zeile in einer Richtlinie – und in diesen Bereichen ist voyage-4-large kein Kompromiss, sondern der Spitzenreiter.

Warum wir für Premium-Embeddings bezahlen

Es gibt einen günstigeren Weg, Suche zu betreiben, und vieles davon ist kostenlos. Lexikalische Suche – BM25 und Verwandte – gleicht Schlüsselwörter ab, läuft lokal und kostet nichts. Open-Source-Embedding-Modelle wie BGE, Nomic und embeddinggemma liefern durchaus ordentliches semantisches Retrieval, und man kann sie zum Preis einer GPU selbst hosten. Maguyva nutzt auch die kostenlose Seite: Jede Abfrage vereint Text-, AST-, Graph- und semantische Suche. Wo wir nicht sparen, ist bei der semantischen Schicht.

Wir bezahlen pro Token für Premium-Embeddings – voyage-4-large – statt ein kostenloses Modell selbst zu hosten, aus zwei Gründen. Erstens kann reine Schlüsselwortsuche die Frage “wo behandeln wir Retries” nicht beantworten, wenn der Code backoff und circuit breaker sagt und nie das Wort “retry” verwendet – Bedeutung ist der ganze Sinn des Embeddings, und in den Bereichen, die wir bedienen, liegen die offenen Modelle hinter den Premium-Modellen zurück: ein paar Punkte bei allgemeinem Text, und noch weiter zurück in Nischen wie Code, Verträgen und Finanzen. Zweitens prägt Retrieval-Qualität unserer Erfahrung nach die finale Antwort stärker als das Modell am anderen Ende – ein starker Agent, dem der falsche Kontext gegeben wird, antwortet trotzdem falsch, und er sieht nie das Dokument, das ihm nie gegeben wurde.

Premium-Embeddings sind also eine Pro-Token-Rechnung, die mit jedem Repo und Dokument skaliert, das wir indizieren – und wir bezahlen sie bewusst. Für das Ergebnis, das unsere Nutzer bekommen, die richtige Funktion oder die richtige Klausel, ist uns dieser Kompromiss das wert.

Der ehrliche Teil

Die Dokumentation von Voyage selbst führt voyage-code-3 nach wie vor als das code-optimierte Modell. Warum also wechseln?

Weil wir den öffentlichen Benchmark gelesen haben, nicht nur die Modelltabelle des Anbieters, und der Benchmark hat voyage-4-large beim Code-Retrieval an die Spitze gesetzt. Das war eine vorausschauende Entscheidung: das neuere, insgesamt stärkere Modell nehmen und es anhand eines öffentlichen Leaderboards bei den Aufgaben validieren, auf die es ankommt. Wir fühlen uns mit dieser Wette wohl, weil die Evidenz breit ist – voyage-4-large gewinnt nicht nur bei Code, es führt auch bei Finanzen, Gesundheitswesen und Gesamt-Retrieval.

Das unsichtbare Fundament

Jedes Tool, das wir bereitstellen – semantische Suche, das Sammeln von Task-Kontext, quellenbelegte Fragen und Antworten – läuft letztlich auf Retrieval hinaus. Wenn sich der Retriever verbessert, bekommt der Agent am anderen Ende bessere Belege, macht weniger Fehltritte und verankert seine Antworten im richtigen Code – oder in der richtigen Klausel, oder in der richtigen Richtlinie. Ein schärferes Embedding-Modell ist kein spektakuläres Feature. Es ist das Fundament für alles andere, und wir haben es gerade verbessert. Du wirst es nicht bemerken. Das ist der Punkt.

Rekursive Selbstverbesserung der Sprachunterstützung: Code Intelligence über ~280 Sprachen hinweg verbessern

Tue, 26 May 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Mai 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

Maguyva extrahiert Symbole, Referenzen und einen Dependency-Graphen aus Quellcode in rund 280 Sprachen. Jede Sprache ist ein maßgeschneiderter tree-sitter-Handler — Queries, Heuristiken, Edge Cases — und jeder Handler kann auf seine eigene, subtile Weise falsch liegen. Ein Methodenaufruf, der als Read ausgegeben wird. Eine Funktion, die dem falschen umschließenden Scope zugeordnet wird. Eine Beziehung, die es schlicht nicht gibt.

Das kannst du nicht von Hand auditieren. Kein Team kann Extraktionsergebnisse über 280 Grammatiken hinweg lesen und die schlechten Kanten erkennen. Die interessante Frage ist also nicht „ist unsere Extraktion korrekt“ — sie lautet „wie findest du in dieser Breite heraus, dass sie falsch ist, ohne einen Menschen in jeder Schleife.“ Unsere Antwort ist die rekursive Selbstverbesserung der Sprachunterstützung: eine Qualitätsschleife, angetrieben von Sprach-Agenten, einem LLM als Judge, und einer Lektion, die wir immer wieder neu lernen: Grün ist nicht dasselbe wie korrekt.

Grün ist nicht korrekt

Jede Sprache hat eine Fixture-Suite, und ein Release-Gate bewertet sie über fünf Dimensionen — Genauigkeit, strukturelle Integrität, Vollständigkeit, Qualität und Performance. Eine Sprache wird nur GRÜN, wenn auf ihren Fixtures Precision ≥ 0,95, Recall ≥ 0,99 und F1 ≥ 0,97 gilt, bei mindestens 20 erwarteten Kanten für statistische Zuverlässigkeit. Darunter ist sie GELB oder ROT und wird nicht ausgeliefert.

Dieses Gate ist notwendig, aber nicht hinreichend. Fixtures validieren gegen Fixtures, die wir geschrieben haben. Sie kodieren die Fälle, an die wir bereits gedacht haben. Ein Handler kann auf seinen Fixtures makellos sein und trotzdem ein Muster verstümmeln, das nur in echtem Code auftaucht — ein Makro-Idiom, eine Methode mit generischen Typbeschränkungen, ein Sprachfeature, für das niemand eine Fixture geschrieben hat. GRÜN bedeutet, dass die Fixtures bestehen. Es bedeutet nicht, dass ein echtes Repository sauber extrahiert wird. Also muss die Schleife die Fixtures hinter sich lassen und in die Wildnis schauen.

Die innere Schleife: Stichprobe, Urteil, Fix, Beweis

Die Kernschleife läuft jeweils für eine Sprache:

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

Einige Dinge sorgen dafür, dass das funktioniert, statt nur im Kreis zu drehen.

Der Richter ist der Agent, kein API-Call. Wenn wir „LLM-as-Judge“ sagen, meinen wir, dass der Sprach-Agent selbst jede gesampelte Kante gegen die echte Quelle liest und sie mit einer festen Fünf-Kategorien-Rubrik klassifiziert: Ist diese Kante korrekt, ein False Positive, die richtige Beziehung mit dem falschen Typ, dem falschen Scope zugeordnet, oder trägt sie falsche Metadaten? Diese Rubrik ist das ganze Spiel — „23 % Fehlerrate“ ist bedeutungslos, solange du nicht weißt, ob das echte Defekte sind oder der Richter falsch zählt.

Eine Sache reparieren, dann beweisen. Jede Iteration ändert genau ein editierbares Asset, läuft dann erneut gegen einen festen Prüfstand und behält die Änderung nur, wenn F1 sich verbessert und die Neuklassifizierung besser aussieht. Wenn nicht, wird zurückgesetzt. Kein Batch spekulativer Edits, kein „müsste besser sein“. Eine Änderung verdient sich ihren Platz, oder sie ist weg. Und wenn ein Fix hält, wird er in die Fixture-Suite aufgenommen — sodass der behobene Bug niemals still zurückkehren kann. Dieser Promotion-Schritt macht die Schleife rekursiv statt nur repetitiv: Jeder Durchlauf härtet das Orakel, gegen das der nächste Durchlauf validiert.

Die Lektion, die wir immer wieder neu lernen: Metriken übertreiben

Hier ist die Falle, in die wir direkt hineingelaufen sind. Die sekundären Corpus-Metriken — wie oft ein extrahiertes Ziel kein auflösbares Symbol hat, wie viele Symbole „verwaist“ aussehen, und so weiter — übertreiben Probleme massiv. Sie sind größtenteils Paradigma-Artefakte, keine Bugs.

Das klarste Beispiel: llvm zeigte einmal eine 73%ige „Quelle-ohne-Symbol“-Rate und wurde als katastrophal gebrandmarkt. Wir haben nachgegraben. Die echte Genauigkeit lag bei 98,5 %. Die „fehlenden Symbole“ waren fast alle legitime externe Referenzen — Aufrufe in die Standardbibliothek, in Frameworks, in Code, der außerhalb des Repos lebt. Die Metrik hat eine Eigenschaft der Sprache gemessen, keinen Defekt im Handler. Sprachen wie Zig, COBOL und Odin zeigen 65–70 % „Waisen“-Raten und sind vollkommen korrekt; COBOL hatte null echte Fehler.

Hätten wir diese Zahlen die Arbeit steuern lassen, hätten wir Wochen damit verbracht, Handler zu „reparieren“, die bereits richtig waren, und die Sprachen mit stillen, echten Bugs ignoriert. Die Schlussfolgerung ist unverblümt: Die Aggregatmetriken sind bestenfalls ein grobes Triage-Signal. Das echte Qualitätssignal ist die Stichprobe mit Kantenklassifizierung — echte Kanten in echten Repositories anschauen und sie einzeln beurteilen. Daten vor Intuition, aber erst, wenn du weißt, welche Daten die Wahrheit sagen.

Die äußere Schleife: eine Flotte, kein Marathon

Eine Sprache nach der anderen würde bei 280 von ihnen ewig dauern, also ist die innere Schleife in eine äußere eingebettet, die viele parallel laufen lässt.

   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

Jeder Agent arbeitet in einem Wegwerf-Worktree, damit sie sich nicht gegenseitig ins Gehege kommen. Der Orchestrator integriert ihre Fixes einen nach dem anderen, jeweils hinter einem Full-Manifest-Regressionscheck: Eine Änderung, die ihrer eigenen Sprache hilft, aber still drei andere kaputt macht, wird nicht gelandet. Integration wird gated und bestätigt, bevor irgendetwas gepusht wird — das Regressions-Gate entscheidet, was sicher ist, ein Mensch entscheidet weiterhin, was ausgeliefert wird. Dann rotiert der Pool zur nächsten Menge an Sprachen, und das Ganze läuft erneut.

Was noch unperfekt ist

Der Richter kann sich irren, und der Irrtum hat eine Richtung: Ein Agent, der mit zu wenig Kontext läuft, übertreibt. In einem Batch wurden acht Sprachen mit 5–20 % Fehlerrate markiert; bei genauerer Prüfung war nur eine ein echter sprachspezifischer Bug — der Rest waren Richterfehler, weil die eigene Semantik der Sprache übersehen wurde (eine Quellzeile, die legitim mehrere Kanten erzeugt, Parameterbindungen, die als Zuweisungen modelliert werden, Reference-per-Identifier-Sprachen). Deshalb samplen wir mit zwei Seeds und gleichen ab, und deshalb wird eine Abweichung zwischen Richter und Fixtures als das interessanteste Signal behandelt, nicht als endgültiges Urteil — manchmal ist die Fixture das, was falsch ist.

Wir sind auch ehrlich, was das Ziel angeht. Das Ziel ist null echte Fehler, Punkt — aber „null“ ist eine Richtung, auf die wir Sprache für Sprache hinarbeiten, keine abgehakte Checkbox. Es gibt immer noch ein weiteres Repo mit einem weiteren Idiom.

Verdient, nicht behauptet

Alles, was Maguyva für einen Agenten tut — ein Symbol finden, eine Abhängigkeit verfolgen, eine Frage mit zitiertem Code beantworten — beruht darauf, dass die Extraktion darunter stimmt. Über 280 Sprachen hinweg lässt sich „richtig“ nicht behaupten; es muss gegen echten Code kontinuierlich verdient werden. Die Schleife ist, wie wir es verdienen: ein autonomer Stichproben-und-Fix-Zyklus, der seinen eigenen Metriken misstraut, jede Änderung beweist und jeden Fix in eine Schutzmaßnahme gegen die nächste Regression verwandelt. Es ist nicht glamourös. Es ist die Arbeit, die uns erlaubt zu sagen „wir unterstützen deine Sprache“ — und das auch so zu meinen. Grün ist einfach. Korrekt ist verdient.

Mehrmodale Fusionssuche: Für jede Query den richtigen Retriever wählen

Wed, 15 Apr 2026 00:00:00 GMT

Hinweis zum historischen Design: Dieser Artikel vom April 2026 beschreibt das damalige Routing-Design, nicht das aktuelle Standardverhalten. Die Korrektur vom September unten betrifft ausschließlich eine Messbehauptung. Aktuelles Routing, Voreinstellungen und die explizite Steuerung der Suchmodalitäten beschreibt So funktioniert es.

Eine Suchanfrage ist nicht eine einzige Sache.

„wo ist parseConfig definiert“ will ein exaktes Symbol — einen präzisen Ort, schnell. „wie funktioniert Authentifizierung“ will Bedeutung — die Streuung an verwandtem Code, die ein Konzept erklärt. „was bricht, wenn ich diese Funktion ändere“ will den Dependency-Graphen. „finde den String ECONNREFUSED“ will einen literalen Treffer, nichts Cleveres.

Grep ist hervorragend für literale Treffer und nützlich für manche Referenzsuchen, aber es ist kein Dependency-Graph und versteht keine Bedeutung. Embeddings decken die semantische Seite ab, sind aber das falsche Werkzeug für exakte Strings und Impact-Analyse. Die meisten Code-Search-Tools wählen eine Engine und zwingen jede Query, mit dieser Wahl zu leben. Maguyva wählt nicht. Es findet heraus, welche Art von Frage du gestellt hast, und mischt dann vier Retriever in der Gewichtung, die diese Frage verdient.

Vier Modalitäten

Unter der Haube gibt es vier unabhängige Wege, Code zu finden:

semantic — Vektorsuche über binäre Voyage-Embeddings; findet Code nach Bedeutung.
text — Trigram-Matching; findet Literale, Fehler-Strings, exakte Identifier.
structural — AST-Queries; findet Definitionen, Signaturen und Sprachkonstrukte.
graph — der Dependency-Graph; findet Aufrufer, Aufgerufene und den Auswirkungsradius.

Jede ist stark bei einer anderen Klasse von Fragen. Der Trick ist zu entscheiden, wie sehr man jeder für die vorliegende Query vertraut.

Intent-Klassifizierung

Bevor überhaupt ein Retrieval läuft, sortiert ein leichtgewichtiger Klassifizierer die Query in eine von sechs Intentionen, mit einem Konfidenzwert. Das ist bewusst billig gehalten — geordnete Heuristiken, der erste Treffer gewinnt — weil es auf dem Hot Path läuft und nur ein bis zwei Millisekunden hinzufügt:

beginnt mit def , class , func , import … → find_definition (Konfidenz 0,95)
„who calls“ (wer ruft auf), „usages of“ (Verwendungen von), „references to“ (Referenzen auf) → find_references (0,90)
„impact“ (Auswirkungen), „blast radius“ (Auswirkungsradius), „what depends on“ (was hängt davon ab) → impact_analysis (0,90)
ein zitiertes "string" oder ein Fehler-Token wie traceback → exact_match (0,85–0,90)
ein CamelCase- oder snake_case-Identifier → find_definition (0,60–0,80)
„how“ (wie), „why“ (warum), „explain“ (erkläre), „architecture“ (Architektur) → understand_code (0,75)
nichts passt → understand_code, niedrige Konfidenz (0,40)

Jede Intention trägt ein Gewichtungsprofil über die vier Modalitäten. Das sind die echten Zahlen:

Intent	semantic	text	structural (AST)	graph
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

Also stützt sich „wo ist parseConfig definiert“ stark auf AST (0,6). „wie funktioniert Auth“ stützt sich auf semantische Vektoren (0,5). „was hängt davon ab“ ist fast ausschließlich Graph (0,7). „finde ECONNREFUSED“ ist fast ausschließlich Trigram (0,9), wobei das Embedding-Modell komplett ausgeschaltet ist — weil semantische Ähnlichkeit genau das falsche Werkzeug für einen exakten String ist.

Der schnelle Pfad und der fusionierte Pfad

Wenn der Klassifizierer sicher ist — Score ≥ 0,85 — und die Query normal ist, überspringt Maguyva die Fusion komplett und routet direkt zur einzelnen dominanten Modalität. „wo ist X definiert“ braucht keine vier Retriever; es braucht sofort den AST-Index. Dieser direkte Pfad wird als fusion_strategy: "direct" zurückgemeldet.

Alles Mehrdeutige durchläuft die Fusion. Die vier (oder drei, im Standard-Preset) Modalitäten laufen parallel, jede liefert ihre eigene Rangliste zurück, und wir kombinieren sie.

Gewichtete Reciprocal Rank Fusion

Heterogene Retriever zu fusionieren ist schwieriger, als es klingt: Eine Cosine-Similarity von 0,82, ein Trigram-Score von 137 und eine Graph-Zentralität von 0,004 liegen nicht auf derselben Skala, du kannst sie also nicht einfach addieren. Reciprocal Rank Fusion umgeht das Problem, indem es die Rohwerte verwirft und nur den Rang behält, den jede Engine vergeben hat. Der Beitrag eines Ergebnisses aus einer Modalität ist:

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

wobei rank seine Position in der Rangliste dieser Modalität ist und k eine Glättungskonstante. Beiträge werden über Modalitäten hinweg summiert für jedes Ergebnis, das mehr als eine Engine gefunden hat — Übereinstimmung zwischen Retrievern schwimmt natürlich nach oben. Wir verwenden k = 40 im Standard-Preset und 60 bei thorough (quick läuft nur semantisch, sodass Fusion dort nie greift). Die ursprüngliche RRF-Arbeit landete bei k = 60 für allgemeines Retrieval; wir setzen den Standard etwas schärfer, was Top-Rang-Übereinstimmung zwischen Modalitäten etwas mehr Gewicht gibt — und wir empfehlen nicht, von Hand daran zu drehen.

Zusätzlich erhalten Ergebnisse eine Graph-Relevanzgewichtung. Ein Hub — eine Funktion, auf die sich die gesamte Codebase stützt — sollte selbst bei gleicher textueller Relevanz einen wenig bekannten Blattknoten überholen, also multiplizieren wir jeden Beitrag mit:

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

Die Zentralität kommt aus den vorberechneten PageRank-/Degree-Metriken der Pipeline, und der Boost ist bei 1,5× gedeckelt, damit eine populäre Funktion eine relevantere, wenig bekannte Funktion nicht komplett verdrängen kann. Schließlich degradieren wir Ergebnisse aus Vendor-, Build- und Archiv-Pfaden und dedupen auf den besten Chunk pro Datei.

Was noch unperfekt ist

Der Intent-Klassifikator ist eine Sammlung regulärer Ausdrücke, kein trainiertes Modell. Er behandelt gängige Abfragemuster mit Heuristiken; eine mehrdeutige Abfrage fällt auf understand_code und eine semantisch gewichtete Mischung zurück. Eine frühere Fassung dieses Beitrags beschrieb einen Rückgang ergebnisloser Suchanfragen von etwa 15 % auf unter 5 % als erreicht. Der Vorschlag vom Dezember 2025 nannte tatsächlich einen geschätzten Ausgangswert und ein Ziel; ein unterstützender Abfragesatz oder Messnachweis liegt nicht vor. Wir ziehen die Behauptung einer erzielten Verbesserung zurück; siehe Quellennachweise und Korrektur. Wir haben den Klassifikator nicht durch ein trainiertes Modell ersetzt, weil die günstige Variante schnell und für ihre vorgesehene Routing-Aufgabe ausreichend ist und weil ein falscher, aber selbstsicherer Klassifikator schlechter ist als ein ehrlicher Fallback. Die Gewichte selbst sind von Hand gewählte Vorannahmen, nicht aus Klickdaten gelernt, die wir ohnehin nicht erfassen.

Stell die Frage, nicht das Werkzeug

Ein Agent sollte nicht wissen müssen, ob er zu grep, Embeddings oder dem Call-Graphen greifen soll — er sollte seine Frage in einfachen Worten stellen und die richtige Antwort bekommen. Multi-Modal Fusion ist das, was find_symbol, semantische Suche und Abhängigkeitsanalyse hinter einer einzigen Query-Oberfläche vereint: Das System liest die Form der Frage und stellt still den richtigen Retriever dafür zusammen. Das Modell, das die Embeddings bewertet, zählt, aber genauso zählt es, zu wissen, wann man sie nicht verwenden sollte. Für jede Query das richtige Werkzeug zu wählen, ist eine eigene Art von Qualität — und eine, die wir lieber selbst verantworten, als sie an den Aufrufer abzuschieben.

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

Agent-Observability: Hooks, Alloy und Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agent-Systeme versagen auf seltsame Weise.

Manchmal ist das Modell das Problem. Manchmal ist das Tool das Problem. Manchmal ist dein MCP-Server völlig in Ordnung, aber der Agent hat den falschen Spezialisten gewählt, oder die halbe Session mit Shell-Arbeit verbracht, die du nicht erwartet hast, oder stillschweigend Kosten in einer Schleife verbrannt, die von außen produktiv aussah.

Wenn du den Unterschied nicht sehen kannst, betreibst du kein Agent-System — du rätst.

Deshalb haben wir einen Observability-Stack für unseren eigenen Workflow gebaut: Claude Code, Codex, Claude-Hook-Events, Codex-Notify-Events, natives OpenTelemetry, Grafana Alloy und auf der anderen Seite Grafana Cloud.

Der interessante Teil ist nicht „wir haben ein Dashboard gebaut“. Der interessante Teil ist, dass wir Telemetrie in zwei unterschiedliche Streams aufteilen mussten, weil kein einzelner Feed das ganze Bild lieferte.

Das Problem: Agent-Telemetrie ist fragmentiert

Moderne Coding-Agenten senden bereits etwas Telemetrie. Das hilft, reicht aber nicht.

Natives OTEL beantwortet Fragen wie diese gut:

Wie viele Requests haben wir gemacht?
Wie viel hat eine Session gekostet?
Wo liegen die Spans und Traces?
Gab es einen Latenz-Spike?

Es ist deutlich schlechter darin, Fragen zu beantworten wie:

Auf welchen MCP-Server hat sich der Agent gestützt?
Lag dieser Fehler in Bash, einem eingebauten Datei-Tool oder einem MCP-Call?
Welcher Skill wurde tatsächlich aktiviert?
Welcher Subagent-Typ wurde eingesetzt?
Hat die Session sinnvolle Arbeit geleistet oder sich nur im Kreis gedreht?

Diese zweite Klasse von Fragen liegt näher an Hooks als an Traces.

Aber das Umgekehrte gilt auch: Einige der wichtigsten Performance-Fragen liegen näher an Traces als an Hooks.

Wenn du wissen willst, wo sich Latenz tatsächlich angesammelt hat, welche Spans langsam waren, oder ob die Session Zeit in Modellaufrufen statt in Tool-Ausführung verbrannt hat, brauchst du Trace-Daten genauso wie semantische Events.

Die Architektur, bei der wir gelandet sind

Wir betreiben zwei Telemetrie-Pfade parallel.

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

Diese Trennung ist bewusst.

Sie ist auch asymmetrisch. Claude Code liefert uns eine deutlich reichhaltigere Lifecycle-Hook-Schnittstelle. Codex liefert uns natives OTEL plus eine Notify-Schnittstelle, weshalb wir dünnere Turn-Completion-Events in dasselbe Log-Schema normalisieren, statt so zu tun, als würden beide Runtimes dieselben Kontrollmöglichkeiten bieten.

Natives OTEL liefert uns den Basis-Stream: Logs und Traces direkt aus der Runtime, plus Metriken, wo die Runtime sie tatsächlich ausgibt.

Hook- und Notify-Events liefern uns die semantische Schicht: Dinge wie PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated und die klassifizierten Metadaten, die uns beim Debuggen von Agent-Verhalten tatsächlich interessieren. Claude Code liefert hier den reichhaltigeren Event-Stream. Codex liefert einen dünneren, aber immer noch nützlichen normalisierten Stream.

Warum es Hooks überhaupt gibt

Unsere Hook-Pipeline reichert Events an, bevor sie bei Loki ankommen.

Statt nur zu sagen „ein Tool ist gelaufen“, klassifizieren wir das Event in Felder wie:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: welches MCP-Backend den Call bearbeitet hat
bash_cli: die Shell-Befehlsfamilie
subagent_type: welche Art von Spezialist eingesetzt wurde
agent_tool: ob die Quelle Claude Code oder Codex war

Das bedeutet, wir können Fragen stellen, die operativ wichtig sind:

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

Das sind keine Eitelkeitsfelder. Sie sind der Unterschied zwischen „der Agent fühlte sich langsam an“ und „der Agent hat die letzten zehn Minuten in shell-lastigen Git-Operationen mit hoher Tool-Fehlerrate verbracht“.

Ein Implementierungsdetail, das seltsamer wirkt, als es ist: Der gemeinsame Loki-Stream verwendet weiterhin service_name="claude-code-hooks" als Label, selbst wenn das Event von Codex stammt. Die eigentliche Trennung zwischen den Runtimes passiert bei agent_tool.

Warum Alloy in der Mitte sitzt

Grafana Alloy ist in diesem Setup nicht nur ein Forwarder. Es ist die Policy-Grenze.

Wir richten den nativen OTEL-Stream von Claude Code und Codex auf einen lokalen Alloy-Proxy auf localhost:4318, und lassen Alloy dann den Payload bereinigen, bevor er an Grafana Cloud weitergeleitet wird.

Das ist wichtig, weil rohe Agent-Telemetrie voller High-Cardinality-Felder ist, die für die Analyse nützlich, aber als indizierte Labels furchtbar sind:

session_id
prompt_id
Token-Zahlen
Dauern
Werkzeugparameter-Pakete

Wenn du alles indizierst, bekommst du eine Label-Explosion und einen schlechten Tag.

Alloy erledigt für uns also drei Dinge:

Hält eine sehr kleine Menge Low-Cardinality-Labels indiziert.
Verschiebt verrauschte, aber nützliche Felder in strukturierte Metadaten.
Verwirft reines Rauschen vollständig.

Die wichtige Idee ist einfach: mehr beobachten, weniger indizieren.

Warum der Hook-Stream Alloy umgeht

Der Hook-Stream ist bereits für Loki zugeschnitten.

Wenn send_event.py ein Event pusht, haben wir bereits entschieden, welche Felder eine Label-Behandlung verdienen und welche in den strukturierten JSON-Body gehören. Dieser Stream geht direkt zum OTLP-Gateway von Grafana Cloud, statt noch einmal durch Alloy zu laufen.

Das System hat also eine klare Arbeitsteilung:

Alloy bändigt den rohen nativen OTEL-Stream.
Hook-Anreicherung macht semantische Events abfragbar.

Das hält die Architektur einfacher, als zu versuchen, alles durch einen einzigen Pfad zu zwingen.

Was das Dashboard tatsächlich zeigt

Der Screenshot unten stammt von einem der Observability-Dashboards hinter unserem Agent-Workflow. Es ist kein Benchmark, und die Zahlen sind nur eine Momentaufnahme. Der Punkt ist die Form der Daten: Activity Feed, Tool Calls, Fehler, Prompts und Aufschlüsselungen nach Agent, eingebauten Tools, MCP-Nutzung, Shell-Befehlen und Skills.

Der nützliche Teil ist, dass dieses Dashboard auf demselben Grafana-Stack lebt wie der Rest der Agent-Telemetrie. Wir können nach Quell-Agent und Tool-Familie filtern und über Runtimes hinweg schauen, ohne für jedes System eine eigene Observability-Geschichte zu erfinden.

Eines der Live-Dashboards hinter unserem Agent-Workflow. Dieser Screenshot ist nur ein Ausschnitt eines gemeinsamen Grafana-Stacks, der auch Telemetrie von unseren anderen Agent-Runtimes und -Systemen empfängt. Klicke auf das Bild für die Version in voller Auflösung.

Warum Traces wichtiger sind, als sie zunächst wirken

Logs sagen uns, welche Kategorie von Arbeit stattgefunden hat. Traces sagen uns, wie sich die Arbeit über die Zeit entfaltet hat.

Dieser Unterschied ist in Agent-Systemen wichtig, weil „langsam“ zu stumpf ist, um nützlich zu sein.

Ein Trace kann uns zeigen, ob die Probleme von Folgendem herrühren:

Modell-Latenz
Tool-Ausführungszeit
wiederholten Retries
einer besonders teuren MCP-Interaktion
einer langen Reihe kleiner Operationen, die isoliert betrachtet harmlos aussahen

In der Praxis nutzen wir den Hook-Stream und Tempo-Traces zusammen.

Hook-Logs beantworten: Was für eine Art von Sache ist passiert?
Traces beantworten: Wo ist die Zeit hingegangen?

Die Kombination ist das, was Observability von einem Dashboard in eine Erklärung verwandelt.

Wo Codex hineinpasst

Codex ist Teil desselben Stacks, aber nicht identisch mit Claude Code.

Für Codex verdrahten wir zwei Teile:

Natives OTEL von Codex in Alloy
Ein Notify-Webhook in codex_notify.py, der Turn-Completions auf dasselbe Loki-Schema abbildet, das wir für Hook-Events verwenden

Das gibt uns einen einheitlichen Filter wie agent_tool="codex-cli" innerhalb desselben Log-Streams.

Der ehrliche Vorbehalt: Codex’ Notify-Payload ist derzeit dünner als Claude Codes Hook-Payload, weil es nicht dieselbe Art von Integrationsschnittstelle ist. In unserem heutigen Setup können Codex-Turn-Completions in das gemeinsame Schema normalisiert werden, aber eine reichhaltige Tool-für-Tool-Extraktion ist im nativen OTEL-Stream immer noch besser als in der Notify-Bridge.

Das ist kein Grund, den Post zu meiden. Es ist der Punkt des Posts. Echte Observability-Systeme werden aus unperfekten Signalen zusammengesetzt.

Grafana über MCP verändert das Spiel

Die größere Verschiebung ist, dass Grafana nicht nur ein Ort ist, den Menschen im Browser besuchen.

In diesem Repo exponieren wir Grafana auch über MCP. Das bedeutet, ein Agent kann Loki, Prometheus und Tempo direkt abfragen, statt darauf zu warten, dass ein Mensch zuerst manuell die Dashboards inspiziert.

Das macht Observability zu einem aktiven Input für den Workflow.

Ein Agent kann fragen:

Welche Tool-Familien sind in der letzten Stunde am häufigsten fehlgeschlagen?
Welcher MCP-Server hat eine Session dominiert?
Haben aktuelle Änderungen Tool-Fehler reduziert, oder die Arbeit nur in shell-lastigere Pfade mit denselben Fehlern verschoben?
Welche Traces zeigen die höchste Latenz oder wiederholte Retries?

Sobald du das hast, bist du sehr nah an einer Self-Improvement-Loop.

Vom Dashboard zur Feedback-Loop

Das ist der Teil, den wir am interessantesten finden.

Sobald der Observability-Stack von der Agent-Schicht aus abfragbar ist, hört Telemetrie auf, eine passive Reporting-Oberfläche zu sein, und wird zu einem Kontrollsignal.

Die Loop sieht so aus:

Agent-Aktivität erzeugt Traces, Metriken und angereicherte Hook-Logs.
Grafana speichert die Evidenz in Loki, Tempo und Prometheus, wo Metriken existieren.
Agenten fragen diese Evidenz über Grafana MCP ab.
Das System identifiziert schlechte Tool-Mischungen, brüchige Skills, schwaches Routing oder shell-lastige Workflows, die weiterhin vermeidbare Fehler produzieren.
Agenten oder Operatoren passen Prompts, Agent-Configs, Skill-Beschreibungen, Routing-Regeln oder Tool-Zugriff an.
Die nächste Session erzeugt eine neue Telemetrie-Form, und der Zyklus wiederholt sich.

So kommt man von „interessantes Dashboard“ zu „messbares Verbesserungssystem“.

Das Ziel ist nicht, eine Tool-Kategorie zu maximieren. Es ist, für die tatsächlich geleistete Arbeit auf die richtige Mischung aus CLI, eingebauten Tools, MCP-Calls und Skills zu kommen.

Was uns das zu beantworten erlaubt

Sobald beide Runtimes im selben Grafana-Stack landen, können wir operative Fragen viel schneller beantworten:

Konzentrieren sich Fehler auf eine Tool-Familie?
Erzeugen shell-lastige Workflows vermeidbare Fehler, wo eigentlich ein High-Level-Tool existieren sollte?
Welche MCP-Server tragen die Arbeitslast?
Zahlen wir für Agent-Aktivität, die keinen sinnvollen Fortschritt erzeugt?
Ist eine Session ungesund wegen des Modells, der Tools oder der Orchestrierungsschicht?

Das ist besonders nützlich in Multi-Agent-Workflows, wo „der Agent war beschäftigt“ fast nichts aussagt.

Wenn ein Spezialist ständig eingesetzt wird und hohe Fehlerraten produziert, ist das ein Routing- oder Prompt-Shaping-Problem.

Wenn ein MCP-Server alle Calls dominiert, kann das gute Architektur sein oder ein Zeichen, dass alles andere unnötiger Ballast ist.

Wenn Tool-Fehler ansteigen, während die Kosten hoch bleiben, hast du ein operatives Problem, kein Qualitätsproblem.

Wenn Shell-Arbeit weiterhin auf vorhersehbare, vermeidbare Weise fehlschlägt, wo eigentlich ein High-Level-Tool existieren sollte, ist das ein Produktsignal.

Wenn ein Skill ständig aktiviert wird, aber die Ergebnisse nicht verbessert, ist das ein Prompt- oder Routing-Signal.

Die eigentliche Lektion

Die tiefere Lektion hier ist, dass Agent-Observability sowohl Runtime-Telemetrie als auch Workflow-Telemetrie braucht.

Runtime-Telemetrie sagt dir, was das System getan hat.

Workflow-Telemetrie sagt dir, was der Agent dachte, dass er tut.

Wir brauchen beides.

Wenn du nur Traces und Zähler behältst, verpasst du die semantische Schicht. Wenn du nur Hook-Events behältst, verpasst du Latenz, Spans und das größere Runtime-Bild.

Und wenn du beides behältst, sie aber nie in die Agent-Schicht zurückspielst, hast du Monitoring, keine Anpassung.

Die Kombination ist das, was das System erklärbar genug macht, um es zu betreiben, und feinjustierbar genug, um es zu verbessern.

Was noch unperfekt ist

Es gibt immer noch raue Kanten.

Nicht jedes Hook-Event enthält die Dauer- und Token-Daten, die wir gerne hätten.
Einige der besten Timing-Ansichten kommen immer noch von Tempo-Traces, nicht von den Hook-Logs.
Codex ist heute im angereicherten Event-Stream semantisch weniger reichhaltig als Claude Code.
Der Dashboard-Screenshot ist eine echte Betriebsoberfläche, kein poliertes Marketing-Artefakt.

Der letzte Punkt ist beabsichtigt. Wir zeigen lieber das echte Instrumentenbrett, als so zu tun, als würden sich Agent-Systeme magisch von selbst erklären.

Warum das für Maguyva wichtig ist

Bei Maguyva geht es darum, Agenten bessere Code Intelligence zu geben. Aber sobald Agenten tatsächlich nützliche Arbeit leisten, taucht sofort eine neue Anforderung auf: Du musst sehen, wie sie sich verhalten.

Suchqualität, Routing-Qualität, Tool-Auswahl und Context-Effizienz werden allesamt zu beobachtbaren Problemen.

Deshalb glauben wir, dass es sich lohnt, darüber zu schreiben. Der zukünftige Agent-Stack besteht nicht nur aus Prompts und Tools. Es sind Prompts, Tools und die Instrumentierungsschicht, die dir sagt, ob das Ganze funktioniert.

Wenn du ernsthafte Agent-Workflows baust, ist Observability keine optionale Infrastruktur. Sie ist Teil des Produkts.

Mining im Kreislauf: Wie Änderungen zu institutionellem Gedächtnis werden

Tue, 03 Feb 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Februar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

Jedes Engineering-Team steht vor derselben Herausforderung: Änderungen passieren ständig, aber das Warum dahinter verschwindet. Sechs Monate später fragt jemand „warum haben wir DuckDB für Pipeline-Stages eingeführt?“, und die Antwort lebt nur im Kopf der Person, die diese Entscheidung getroffen hat — falls diese Person noch da ist.

Wir haben einen Mining-Workflow gebaut, der diese Lücke schließt. Änderungen fließen durch Git-Commits, werden von unserer Mining-Pipeline verarbeitet, werden zu strukturierten Changelog-Einträgen und Architectural Decision Records, und fließen dann über CLI-Abfragen zurück in unsere KI-Agenten. Das Ergebnis: institutionelles Gedächtnis, auf das sowohl Menschen als auch KI zugreifen können.

Das Problem: Entscheidungen verdunsten

Stell dir ein typisches Szenario vor. Ein Entwickler committet:

feat(canonical): add DuckDB runtime for pipeline stages

Dieser Commit stellt eine bedeutende Architekturentscheidung dar. Das Team hat Optionen bewertet, Trade-offs abgewogen und ist bei DuckDB aus bestimmten Gründen gelandet. Aber der ganze Kontext lebt in:

Einem Slack-Thread (wahrscheinlich gelöscht)
Der Erinnerung von jemandem (definitiv verblassend)
Einem Kommentar im Code (vielleicht, wenn du Glück hast)

Drei Monate später fragt ein neues Teammitglied: „Sollte ich DuckDB oder SQLite für diese neue Stage verwenden?“ Ohne institutionelles Gedächtnis erfinden sie entweder das Rad neu oder treffen inkonsistente Entscheidungen.

Die Loop: Von Commits zu Kontext

Unser Mining-Workflow verwandelt Git-History in abfragbares Wissen:

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

Die zentrale Erkenntnis: Sowohl Changelogs als auch Architekturentscheidungen fließen aus derselben Git-History, verarbeitet durch eine einheitliche Pipeline. Das stellt sicher, dass nichts durch die Maschen fällt.

Wie Mining funktioniert

Schritt 1: Den Index synchronisieren

uv run orkestra mine sync

Dieser Befehl scannt die Git-History und baut einen Index aller Commits. Er extrahiert strukturierte Signale aus jedem Commit:

Conventional-Commit-Typ (feat, fix, chore, docs)
Scope (welches Paket oder welcher Bereich)
Breaking-Change-Markierungen
Angefasste Dateien und Komplexitätsmetriken

Schritt 2: Coverage-Status prüfen

uv run orkestra mine status

So sieht unser aktueller Status aus:

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 verarbeitet. 476 wurden zu Architekturentscheidungen. 6.799 wurden zu Changelog-Einträgen. Jeder Commit klassifiziert.

Schritt 3: Kandidaten für die Review holen

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

Das bringt Commits an die Oberfläche, die noch nicht verarbeitet wurden, mit vollständigem Kontext für die Klassifizierung:

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

Die Signale helfen bei der Klassifizierung: is_releasable_type: true legt nahe, dass das im Changelog erscheinen sollte. Die große Anzahl an Insertions und die Infrastruktur-Dateien legen nahe, dass es auch eine Architectural Decision sein könnte.

Schritt 4: Commits klassifizieren

Hier trennen sich zwei Pfade: Changelog-Einträge und Architekturentscheidungen.

Für Changelog-Einträge:

uv run orkestra mine classify abc123 --changelog added

Das protokolliert, dass Commit abc123 im Changelog unter der Kategorie „Added“ erscheinen sollte.

Für Architekturentscheidungen:

Zuerst eine echte Decision-ID holen:

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

Dann mit der Decision-ID klassifizieren:

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

Das verknüpft den Commit mit einem Decision-Record, der erstellt oder aktualisiert wird.

Für Batch-Verarbeitung (was wir tatsächlich tun):

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

Das JSONL-Format unterstützt beide Domänen in einem Durchgang:

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

Schritt 5: Outputs rendern

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

Das generiert pro-Paket-CHANGELOG.md-Dateien aus dem Ledger. Die Changelogs sind abgeleitete Artefakte — lösche sie, und sie regenerieren sich perfekt aus dem Quell-Ledger.

Die Struktur des Decision-Records

Extrahierte Decisions werden zu YAML-Dateien mit reichhaltigen Metadaten:

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

Jede Decision verlinkt zurück zu ihren Quell-Commits. Jede Decision spezifiziert, welche Dateien sie betrifft. Beziehungen zwischen Decisions sind explizit.

CLI-Integration: Institutionelles Gedächtnis abfragen

Hier schließt sich die Loop. Agenten können Decisions über die CLI abfragen:

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

Liefert Decisions über Retry-Logik, Fehlerbehandlung, Recovery-Muster.

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

Liefert den vollständigen Decision-Record mit Kontext, Begründung und Auswirkung.

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

Zeigt, welche Architekturentscheidungen kürzlich getroffen wurden.

Wie Agenten das nutzen

Die Baseline-Instruktionen unseres Orchestrators enthalten:

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

Wenn ein Agent gebeten wird, etwas im Zusammenhang mit DuckDB zu implementieren, kann er zuerst prüfen:

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

Und DEC-PL-142 entdecken und lernen:

Warum wir DuckDB gewählt haben (context)
Wie man es richtig verwendet (agent_guidance)
Welche Dateien man sich ansehen sollte (files)
Welche verwandten Decisions existieren (related)

Der Agent erfindet das Rad nicht neu. Er baut auf etablierten Mustern auf.

Der Drei-Fragen-Test

Nicht jeder Commit verdient einen Decision-Record. Wir verwenden den Drei-Fragen-Test zum Filtern:

War das schwer zu entscheiden? Erforderte es signifikante Analyse, Trade-off-Bewertung oder Debatte?
Ist es teuer zu ändern? Würde eine Umkehrung dieser Entscheidung signifikante Nacharbeit erfordern?
Hat es systemweite Auswirkungen? Betrifft es mehrere Pakete oder etabliert es Muster, denen andere folgen werden?

Wenn ein Commit mindestens eine dieser Fragen mit „ja“ beantwortet, ist er ein Kandidat für die Decision-Extraktion. Unsere typische Rate: 1–4 Decisions pro 100 Commits (etwa 1–4 %).

Für Changelog-Einträge liegt die Hürde niedriger: Jede nutzersichtbare Änderung (Features, Fixes, Verbesserungen) wird erfasst. Interne Chores, Dokumentations-Updates und Refactorings werden typischerweise übersprungen. Unsere typische Rate: 30–50 Changelog-Einträge pro 100 Commits.

Datenspeicherung: Append-Only-Ledger

Das Mining-System verwendet Append-Only-JSONL-Ledger für konfliktfreien Multi-Agent-Betrieb:

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

Das JSONL-Format mit merge=union in .gitattributes bedeutet, dass mehrere Agenten Commits gleichzeitig klassifizieren können, ohne Merge-Konflikte. Jede Zeile ist unabhängig.

Validierungs-Gates

Vor jeder Mining-Session führen wir eine Validierung durch:

uv run orkestra mine validate --quick

Das prüft:

Gültigkeit des SHA-Formats
Einhaltung des Decision-ID-Formats
Keine doppelten Einträge für denselben SHA
Referenzierte Decisions existieren tatsächlich

Nach der Klassifizierung validieren wir erneut, bevor Änderungen committet werden.

Warum das wichtig ist

Die Feedback-Loop, die wir gebaut haben, löst mehrere Probleme:

Für neue Teammitglieder: Statt zu fragen „warum haben wir X gemacht?“, können sie die Decisions-Registry durchsuchen. Der Kontext bleibt erhalten.

Für KI-Agenten: Sie operieren nicht im luftleeren Raum. Sie können institutionelles Wissen abfragen, bevor sie Empfehlungen aussprechen. Wenn sie gebeten werden, eine neue Pipeline-Stage hinzuzufügen, können sie das DuckDB-Muster entdecken und ihm folgen.

Für Architekturkonsistenz: Decisions sind explizit und durchsuchbar. Wenn jemand einen Ansatz vorschlägt, der einer bestehenden Decision widerspricht, kann das System den Konflikt sichtbar machen.

Für die Changelog-Generierung: Release Notes sind kein Last-Minute-Gehetze. Sie sind ein Nebenprodukt kontinuierlicher Klassifizierung während der Entwicklung.

Für Onboarding: Neue Agenten erben den vollen Kontext der Codebase. Sie sehen nicht nur den Code — sie sehen die Entscheidungen, die ihn geformt haben.

Aktueller Stand

Stand heute:

15.637 Commits durch die Pipeline verarbeitet
476 Architekturentscheidungen extrahiert und dokumentiert
6.799 Changelog-Einträge erfasst
100 % Coverage über beide Domänen hinweg

Jeder Commit seit unserem Start wurde klassifiziert. Das institutionelle Gedächtnis ist vollständig und abfragbar.

Erste Schritte

Wenn du etwas Ähnliches umsetzen willst:

Beginne mit Conventional Commits. Die Mining-Pipeline funktioniert am besten, wenn Commits strukturierte Präfixe haben (feat:, fix:, chore:).
Definiere deine Domänen. Wir verwenden Domänen wie pipeline, agent-design, observability, data-modeling. Diese organisieren Decisions nach Bereich.
Baue die Klassifizierungs-Gewohnheit auf. Mining funktioniert, wenn Teams regelmäßig Commits klassifizieren. Batch-Verarbeitung mit LLM-Unterstützung hilft bei der Skalierung.
Mache Decisions abfragbar. Der Wert verstärkt sich, wenn Agenten Decisions über die CLI durchsuchen können. Strukturiere deine Ausgabe für maschinellen Konsum.
Schließe die Loop. Decisions sollten zukünftige Arbeit beeinflussen. Nimm Decision-Referenzen in Agent-Instruktionen und Code-Review-Checklisten auf.

Das Ziel ist nicht perfekte Dokumentation. Es ist, das Warum hinter Änderungen sowohl für Menschen als auch für KI zugänglich zu machen, heute und in sechs Monaten. Wenn Änderungen zu institutionellem Gedächtnis werden, bauen Teams auf etablierten Mustern auf, statt sie neu zu erfinden.

Der Mining-Workflow ist Teil unserer Orchestrierungs-Engine, genauer gesagt des Context-Engine-Moduls in unserem Orchestration-Paket.

Skill Mining: Von 3.500 Kandidaten zu 466 Fähigkeiten

Tue, 27 Jan 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

Das 3.500-Skill-Problem

Als wir angefangen haben, ein Agent-Orchestrierungssystem zu bauen, standen wir vor einer interessanten Herausforderung: Es gibt Tausende potenzielle Skills, verstreut über das gesamte KI-Ökosystem. GitHub-Repositories, Vendor-Dokumentation, Community-Projekte, interne Muster — Skills existieren überall. Aber welche zählen? Welche funktionieren? Und wie pflegst du eine kohärente Skill-Bibliothek, die Agenten tatsächlich nutzen können?

Unsere Antwort: eine systematische Mining- und Ingestion-Loop.

Die Zahlen heute

Etwas mehr als drei Monate nachdem Anthropic am 16. Oktober 2025 Agent Skills gestartet hat, sah unser Stand am Veröffentlichungsdatum dieses Beitrags, dem 27. Januar 2026, so aus:

Metrik	Anzahl
Identifizierte Kandidaten	3.500+
Übernommene Skills	466
Vendor-Skills	373
Interne Skills	93
Aktive Vendors	25+
Durchschnittliche Tokens pro Skill	2.834
Referenzierte Tools	89
Eindeutige Tags	635

Wir haben über 3.500 Skill-Kandidaten geprüft. Wir haben 466 übernommen. Das ist eine Übernahmequote von 13 % — und diese Selektivität ist Absicht.

Das Knowledge-Tier-System

Nicht alle Skills sind gleich. Wir organisieren sie in fünf Wissensschichten (K0–K4), jede repräsentiert einen anderen Geltungsbereich der Anwendbarkeit:

K0: Foundations (Universell)

Skills, die jeder Agent haben sollte. Diese repräsentieren „guter Denker“-Fähigkeiten, die überall funktionieren.

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 sind auf jedes Projekt, jede Domäne, jeden Stack portabel. Sie kodieren universelle kognitive Muster.

K1: Identities (Fachdisziplin)

„Guter Engineer“- oder „guter Researcher“-Skills, die über Projekte hinweg innerhalb einer Disziplin gelten.

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

K2: Domains (Fachexpertise)

„Guter Datenbankexperte“- oder „guter Security-Engineer“-Skills, portabel innerhalb eines Fachbereichs.

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

K3: Stacks (Technologie)

„Guter Supabase-Nutzer“- oder „guter Cloudflare-Entwickler“-Skills für bestimmte Technologie-Stacks.

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

K4: Project (Organisation)

Skills, die spezifisch für unsere Organisation und unsere Workflows sind.

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

Die Mining-Loop

Phase 1: Entdeckung

Skills kommen von überall her:

Vendor-Repositories: AWS, Anthropic, Cloudflare, Supabase und Community-Contributor veröffentlichen Skill-Sammlungen. Wir verfolgen 25+ Vendor-Roots.

Community-Projekte: GitHub ist voll von Claude-Code-Templates, Agent-Mustern und Workflow-Definitionen.

Interne Muster: Während unser Team Probleme löst, entstehen Muster. Diese werden zu Skills formalisiert.

Dokumentations-Mining: Technische Dokumentation enthält oft implizite Skills — Prozeduren, Checklisten, Entscheidungsbäume.

Entdeckung ist kontinuierlich. Wir nutzen einen Skill-Backlog, um Kandidaten vor der formalen Bewertung zu verfolgen.

Phase 2: Bewertung

Jeder Kandidat durchläuft dieselbe Rubrik:

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

Alle fünf Produktkriterien müssen erfüllt sein. Deshalb werden 87 % der Kandidaten abgelehnt.

Dann durchläuft jeder Kandidat ein separates Trust-Review. Wir behandeln ein offizielles Vendor-Repository, einen bekannten Community-Maintainer und ein zufälliges GitHub-Repo nicht als gleichwertige Quellen der Wahrheit.

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

Vertrauenswürdige Vendors bekommen ein leichteres Provenienz-Review, aber keinen Freifahrtschein. Nicht vertrauenswürdige oder unbekannte Quellen bekommen ein tieferes manuelles Audit, und wir führen keine gebündelten Skripte aus, bevor sie gelesen, eingegrenzt und als sicher klassifiziert wurden.

Gap-Analyse: Vor der Übernahme durchsuchen wir unsere Registry:

uv run orkestra skills search "<capability>"

Wenn wir es schon haben, brauchen wir es nicht. Wenn wir etwas Ähnliches haben, mergen wir vielleicht, statt zu übernehmen.

Tiefen- und Standards-Scoring: Wir bewerten auch, wie vollständig ein Kandidat das Agent-Skill-Modell nutzt. Ein einsames SKILL.md kann trotzdem nützlich sein, aber tiefere Skills sind wertvoller, wenn sie Anweisungen von Referenzen, Skripten und Assets trennen, so wie agentskills.io es fördert.

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-Sterne können einen Glaubwürdigkeits-Score etwas anheben, aber sie retten nie einen flachen oder unsicheren Skill. Ein Repo mit vielen Sternen und einem vagen SKILL.md sowie undurchsichtigen Skripten schneidet schlechter ab als ein kleineres Repo mit präziser Beschreibung, kuratierten references/ und atomaren Helpern, die die volle Skill-Capability tatsächlich nutzen.

Strukturelle Analyse: Wir prüfen die Skill-Qualität:

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

Wenn ein Kandidat Skripte enthält, wird dieses Review strenger. Ein guter Skill ist nicht nur nützlich; er muss lesbar, abgegrenzt und sicher genug sein, um ihn einem Agenten zu übergeben. Allein dieser Sicherheitsfilter disqualifiziert einen bedeutenden Teil ansonsten interessanter Kandidaten.

Phase 3: Einlesung

Wenn ein Skill die Bewertung besteht, kommt er in die Registry. Aber Skills werden nie unverändert übernommen. Sie werden angepasst, um in unser System zu passen.

Modifikationen bei der Übernahme:

Metadaten-Normalisierung: Jeder Skill bekommt unser Frontmatter-Schema
K-Tier-Zuweisung: Skills werden der passenden Wissensschicht zugeordnet
Tag-Anreicherung: Tags werden für die Auffindbarkeit hinzugefügt
Tool-Deklaration: Erlaubte Tools werden explizit deklariert
Abschnitts-Angleichung: Inhalt wird umstrukturiert, um zu unserem Template zu passen

Eine typische Skill-YAML nach der Ingestion:

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

Phase 4: Scope-Zuweisung

Skills werden Scopes zugewiesen — Kategorien, die bestimmen, welche Agenten welche Skills laden:

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

Agenten deklarieren ihre Scopes, und Skills werden automatisch zugewiesen:

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

Phase 5: Materialisierung

Skills leben nicht als YAML in Produktion. Sie werden in SKILL.md-Dateien gerendert, die Claude Code laden kann:

uv run orkestra sync

Dieser Befehl:

Liest alle Skill-YAML-Definitionen
Rendert sie durch Jinja-Templates
Schreibt SKILL.md-Dateien nach .claude/skills/
Organisiert nach K-Tier (foundations/, identities/, domains/, stacks/, project/)

Die finale Ausgabestruktur:

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

Das Dormant-Scope-Muster

Eines unserer mächtigsten Muster sind „übernommen, aber nicht geladen“-Skills. Wir nennen diese Dormant Scopes.

Betrachte Scientific-Computing-Skills aus dem k-dense-scientific-Repository. Wir haben 120+ Skills übernommen, die Bioinformatik, Chemie, Quantencomputing und klinische Informatik abdecken. Aber die meisten unserer Agenten brauchen weder molekulares Docking noch Genexpressionsanalyse.

Statt alle 120 Skills in jeden Agenten zu laden (was die Kontextfenster aufbläht), tun wir Folgendes:

Wir übernehmen die Skills mit einem spezifischen Scope (z. B. bioinformatics)
Wir halten sie dormant — registriert, aber nicht geladen
Wir aktivieren sie nur, wenn ein Agent diesen Scope deklariert

# 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

Dieses Muster erlaubt uns, 466 Skills in der Registry zu haben, während typische Agenten nur 40–60 relevante laden.

Skill-Typen

Skills kommen in drei kognitiven Mustern:

Workflow

Geordnete prozedurale Schritte: „1. Mach X, 2. Dann Y, 3. Schließlich Z“

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

Verhaltensregeln

Verhaltens-Leitplanken: „Immer X“, „Nie Y“, „Bevorzuge Z“

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

Checkliste

Verifikationskriterien: „Bestätige X“, „Verifiziere Y“, „Prüfe Z“

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

Qualitätsgates

Jeder Skill muss vor dem Ausliefern eine Validierung bestehen:

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

Beschreibungen müssen 50–400 Zeichen mit Auslösephrasen sein („Verwenden, wenn…“, „Wenn du… brauchst“), damit Claude Code weiß, wann sie vorgeschlagen werden sollen.

Wir validieren kontinuierlich:

uv run orkestra validate --show-warnings

Das Vendor-Ökosystem

Unsere 373 Vendor-Skills kommen von:

Anbieter	Skills	Domäne
AWS Agent	19	Cloud-Services
Anthropic	12	Dokumentengenerierung
Cloudflare	8	Edge-Infrastruktur
Supabase	5	Datenbank
k-dense	100+	Wissenschaftliches Computing
silvainfm	4	Datenwissenschaft
Java Developer Kit	45+	Spring/Java
Vercel	1	Browser-Automatisierung

Jede Vendor-Root wird in metadata.yaml deklariert:

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

Wenn orkestra sync läuft, werden Vendor-Skills mit ihrem Provider-Namespace nach .claude/skills/vendor/ symlinkt.

Was wir gelernt haben

Selektivität zahlt sich aus. Es ist verlockend, alles zu übernehmen, was nützlich aussieht. Aber jeder Skill kostet Tokens. Bei 2.834 durchschnittlichen Tokens pro Skill schadet Aufblähung schnell. Unsere Übernahmequote von 13 % hält Agenten schlank.

Struktur ermöglicht Auffindbarkeit. Das K-Tier-System ist nicht nur Organisation — es geht um Portabilität. K0-Skills können überall wiederverwendet werden. K4-Skills sind absichtlich projektspezifisch. Diese Klarheit hilft sowohl Menschen als auch Agenten, zu finden, was sie brauchen.

Dormant Scopes skalieren. Du kannst Hunderte von Skills übernehmen, ohne sie alle zu laden. Scopes lassen dich eine umfassende Registry aufbauen, während die Kontextfenster einzelner Agenten überschaubar bleiben.

Modifikation bei der Übernahme ist essenziell. Rohe Vendor-Skills passen selten zu deinem System. Der Ingestion-Prozess — Metadaten hinzufügen, Tiers zuweisen, Tags anreichern — macht externe Skills intern nutzbar.

Mining ist kontinuierlich. Die Zahl 3.500 wächst weiter. Neue Vendor-Repos tauchen auf. Community-Muster entstehen. Interne Workflows verfestigen sich. Die Loop hört nie auf.

Was als Nächstes kommt

Wir arbeiten an mehreren Verbesserungen:

Automatisierte Gap-Erkennung: Alarm, wenn häufige Agent-Fehler durch einen nicht übernommenen Skill adressiert werden könnten
Skill-Ausmusterungsprozesse: Formaler Prozess für das Ausmustern von Skills, die abgelöst oder ungenutzt sind
Cross-Skill-Abhängigkeiten: Explizite Deklaration von Skill-Voraussetzungen
Nutzungs-Analytik: Verfolgen, welche Skills Agenten tatsächlich aufrufen versus nur laden

Die Skill-Mining-Loop ist Infrastruktur. Sie ist nicht glamourös. Aber sie ist das, was 41 Agenten erlaubt, kohärent mit 466 Capabilities zu funktionieren, während sie innerhalb der Kontextgrenzen bleiben.

Das ist die Geschichte, wie aus 3.500 466 werden. Nicht, indem man 3.000 ignoriert — indem man sie systematisch bewertet und nur übernimmt, was funktioniert.

Willst du das Skill-System in Aktion sehen? Schau dir uv run orkestra skills list an, um unsere aktuelle Registry zu erkunden.

Progressive Disclosure: CLI-Fenster in Agent-Systeme

Tue, 20 Jan 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Werte findest du auf unserer Team-Seite.

Agentensysteme sind von Natur aus undurchsichtig. Sie treffen Entscheidungen, rufen Tools auf und koordinieren Arbeit über Dutzende Spezialisten hinweg. Aber wenn etwas schiefgeht – oder du einfach verstehen willst, was gerade passiert – wo schaust du dann nach?

Die Antwort lautet Progressive Disclosure: eine geschichtete Oberfläche, die genau so viel Komplexität offenlegt, wie du brauchst, genau dann, wenn du sie brauchst.

Das Undurchsichtigkeits-Problem

Ein modernes Agenten-Orchestrierungssystem kann Folgendes umfassen:

40+ Spezialagenten, jeder mit eigenen Fähigkeiten
700+ Skills, die interne Automatisierung und Drittanbieter-Integrationen abdecken
470+ Architekturentscheidungen, die das Verhalten prägen
Dutzende MCP-Tool-Server, die externe Fähigkeiten bereitstellen

Diese Komplexität ist beabsichtigt. Agenten brauchen Zugriff auf reichhaltigen Kontext – Fachwissen, Code Intelligence, Datenbankschemata –, um gute Entscheidungen zu treffen. Aber genau dieser Reichtum schafft ein Sichtbarkeitsproblem.

Woher weißt du, welcher Agent Datenbankmigrationen übernimmt? Welche Entscheidungen haben das Ranking-Verhalten des Suchsystems geprägt? Auf welche Tools hat der Architektur-Advisor Zugriff?

Ohne strukturierten Zugriff bleibt dir nur, den Quellcode zu lesen oder zu hoffen, dass die Dokumentation aktuell ist.

Progressive Disclosure als Architektur

Progressive Disclosure ist nicht nur ein UI-Muster. Es ist ein Architekturprinzip: Informationen in Schichten organisieren, jede tiefer als die vorherige, sodass Nutzer auf der Ebene stehen bleiben können, die ihre Frage beantwortet.

Für Agentensysteme übersetzt sich das in CLI-Befehle mit zunehmender Tiefe:

Ebene	Befehl	Beantwortete Frage
1	`orkestra system status`	Ist alles gesund?
2	`orkestra agents list`	Welche Agenten gibt es?
3	`orkestra agents info <name>`	Was macht dieser Agent?
4	`orkestra decisions search`	Warum funktioniert es so?
5	MCP-Tools von Maguyva	Zeig mir den Code.

Jede Ebene beantwortet eine natürliche Anschlussfrage. Du musst nur selten direkt zu Ebene 5 springen.

Ebene 1: Systemzustand

Die erste Frage lautet immer: Läuft alles?

$ orkestra system status

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

Ein Befehl. Vier Zahlen. Genug, um zu wissen, dass das System konfiguriert und die Registries befüllt sind.

Wenn eine Agentenzahl unerwartet sinkt oder Skills nicht laden, siehst du das hier zuerst. Keine Log-Wühlerei nötig.

Ebene 2: Agenten-Inventar

Sobald du weißt, dass das System gesund ist, lautet die nächste Frage: Was ist verfügbar?

$ orkestra agents list

Das liefert strukturierte Daten – Agentennamen, Beschreibungen, Modellpräferenzen, Domänenabdeckung. Die Ausgabe ist standardmäßig JSON, sodass sie sich leicht in jq zum Filtern weiterleiten lässt:

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

Du suchst Agenten, die Datenbankarbeit übernehmen? Der Suchbefehl grenzt das ein:

$ orkestra agents search "database"

Das durchsucht Namen, Beschreibungen und Fähigkeiten. Du findest den richtigen Spezialisten, ohne 40 Agentendefinitionen zu lesen.

Ebene 3: Agenten im Detail

Einen Agenten gefunden, der relevant aussieht? Der Befehl info zeigt alles:

$ orkestra agents info architecture-advisor

Die Ausgabe umfasst:

Metadaten: Name, Kategorie, Modellpräferenz, Beschreibung
Domänen: Welche Wissensbereiche dieser Agent abdeckt
Identität: Charaktereigenschaften (Architekt, Stratege, Knowledge-Architect)
Werkzeugleitfäden: Welche Tool-Dokumentation in den Kontext eingespeist wird
Tools: Die vollständige Liste der MCP-Tools, auf die dieser Agent Zugriff hat

Hier ein Ausschnitt dessen, was du siehst:

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

Das sagt dir genau, was der Agent kann. Kein Quellcode nötig.

Ebene 4: Entscheidungsarchäologie

Agenten verhalten sich gemäß dokumentierten Entscheidungen. Wenn du verstehen willst, warum etwas auf eine bestimmte Weise funktioniert, ist die Decisions-Registry die maßgebliche Quelle.

$ orkestra decisions search "agent"

Das liefert passende Architekturentscheidungen:

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

Jede Entscheidung hat eine vollständige Herkunftsangabe – wann sie getroffen wurde, warum, welche Kompromisse abgewogen wurden, welche Commits sie umgesetzt haben:

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

Das ist Architekturdokumentation, die aktuell bleibt, weil sie aus Commits gewonnen wird, nicht manuell gepflegt.

Ebene 5: Direkte Code Intelligence

Wenn du die tatsächliche Implementierung sehen musst – nicht nur Metadaten darüber –, liefern die MCP-Tools von Maguyva direkten Zugriff.

Aus einer Agenten-Session heraus:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Das routet automatisch über semantische, textbasierte und AST-Suche, um relevanten Code zu finden. Für konkrete Symbole:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Für Abhängigkeitsanalysen:

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

Das sind nicht einfach nur grep-Ersatzwerkzeuge. Sie sind graphbewusst, semantisch indiziert und in dieselbe Code Intelligence eingebunden, die auch die Agenten selbst antreibt.

Einheitliche Suche über alle Registries

Manchmal weißt du nicht, welche Registry die Antwort enthält. Die einheitliche Suche deckt alles ab:

$ orkestra search "database" --summary

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

254 Treffer über fünf Registries hinweg. Die Zusammenfassung zeigt dir, wo du tiefer einsteigen solltest. Entferne --summary für detaillierte Ergebnisse, oder füge --limit 5 hinzu, um die Ausgabe überschaubar zu halten.

Warum das wichtig ist

Progressive Disclosure ist nicht nur eine Frage der Bequemlichkeit. Es verändert, wie du mit komplexen Systemen umgehst.

Debugging wird handhabbar. Wenn ein Agent eine unerwartete Entscheidung trifft, durchsuchst du nicht Logs mit grep. Du prüfst, auf welche Tools er Zugriff hat (agents info), welche Entscheidungen sein Verhalten prägen (decisions search), und verfolgst bei Bedarf die Implementierung (intelligent_search).

Onboarding wird schneller. Neue Teammitglieder müssen nicht die gesamte Codebasis lesen. Sie starten mit system status, erkunden mit agents list und gehen erst tiefer, wenn sie auf etwas stoßen, das sie nicht verstehen.

Dokumentation bleibt aktuell. Weil die CLI aus denselben Registries liest, die auch die Agenten konfigurieren, ist die Ausgabe immer korrekt. Es gibt keine Diskrepanz zwischen dem, was die Dokumentation sagt, und dem, was das System tut.

Die CLI als Schnittstelle

Wir hätten ein Web-Dashboard bauen können. Wir hätten ausführliche Dokumentation schreiben können. Stattdessen haben wir eine CLI gebaut, die aus der maßgeblichen Quelle liest.

Die CLI hat Vorteile:

Kombinierbar: Ausgabe durch jq leiten, in Skripte integrieren
Scriptbar: Prüfungen automatisieren, Berichte erzeugen
Schnell: Keine Seitenaufrufe, keine Authentifizierungs-Umwege
Präzise: Liest die tatsächliche Konfiguration, keine zwischengespeicherte Darstellung

Für Systeme, bei denen Korrektheit wichtiger ist als Ästhetik, gewinnt die CLI.

Deine eigene Progressive Disclosure bauen

Wenn du Agentensysteme baust, überlege dir, wie Nutzer sie inspizieren werden:

Mit Health-Checks beginnen. Ein Befehl, der dir sagt, ob alles läuft.
Inventaransichten bereitstellen. Zeige, was existiert, bevor du erklärst, was es tut.
Gezielte Abfragen ermöglichen. Suche schlägt Durchblättern im großen Maßstab.
Herkunft offenlegen. Lass Nutzer Entscheidungen zu ihrem Ursprung zurückverfolgen.
Mit Code Intelligence verbinden. Irgendwann müssen Nutzer die Implementierung sehen.

Jede Schicht beantwortet eine Anschlussfrage. Baue sie in der Reihenfolge ihrer Häufigkeit auf – die meisten Nutzer bleiben bei Ebene 2 oder 3 stehen. Nur Power-User erreichen Ebene 5.

Das Ziel ist nicht, alles offenzulegen. Es geht darum, genau das offenzulegen, was gebraucht wird, genau dann, wenn es gebraucht wird. Das ist Progressive Disclosure, angewendet auf Agentenarchitektur.

Grundwahrheiten: KI-Agenten in der Realität verankern

Tue, 13 Jan 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

KI-Agenten sind bemerkenswert leistungsfähig. Sie können schlussfolgern, synthetisieren und generieren. Aber sie haben eine grundlegende Schwäche: Sie erfinden Dinge. Nicht böswillig, aber mit großer Überzeugung. Ein Agent könnte API-Parameter erfinden, die nicht existieren, Konfigurationen referenzieren, die nie definiert wurden, oder Muster aus seinen Trainingsdaten anwenden, die deiner tatsächlichen Architektur widersprechen.

Die Standardlösung lautet „gib dem Agenten mehr Kontext“. Aber Kontext kann widersprüchlich sein. Dokumentation driftet von der Implementierung ab. Kommentare lügen. Selbst Code kann irreführen, wenn er ohne Verständnis der Intention gelesen wird.

Wir brauchten etwas Expliziteres. Etwas, das nicht ignoriert oder falsch interpretiert werden konnte. Etwas, das Agenten an überprüfbarer Realität verankert.

Wir nennen sie Grundwahrheiten.

Was ist eine Grundwahrheit?

Eine Grundwahrheit (Ground Truth) ist eine explizite, versionierte Tatsachenaussage, die Agenten respektieren müssen. Sie ist keine Dokumentation und kein Kommentar, sondern eine eigenständige Entität im System mit:

Einer eindeutigen ID (wie GT-MAG-015 oder GT-MAG-036)
Einem Lifecycle-Status (current, tentative oder deprecated)
Einem Scope (plattformweit, paketspezifisch oder domänengebunden)
Evidenz (Dateipfade, URLs oder Referenzen, die die Aussage belegen)
Agent-Guidance (explizite Do/Avoid-Anweisungen)

Hier ist ein Beispiel aus unserer Maguyva-Code-Intelligence-Plattform:

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

Das ist keine Prosa. Es ist ein Vertrag. Wenn ein Agent auf diese Grundwahrheit trifft, weiß er:

Der Standard ist deterministisch (leere Ergebnisse, keine unscharfen Vermutungen)
Es gibt bestimmte Parameter (find_similar, exact_match) mit definiertem Verhalten
Es gibt Evidenz in bestimmten Dateien, die überprüft werden kann
Die Aussage wurde an einem bestimmten Datum verifiziert

Die Anatomie einer Ground-Truth-Registry

Grundwahrheiten leben in YAML-Registries unter ai_assets/reference/ground_truths.yaml. Jedes Paket oder jede Domäne kann seine eigene Registry haben. Die Struktur ist:

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

Die Registry enthält Metadaten über die Sammlung selbst, eine Render-Konfiguration für die Dokumentationsgenerierung, und die Aussagen selbst. Jede Aussage folgt einem strikten, durch Pydantic-Modelle validierten Schema:

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

Wie Agenten auf Grundwahrheiten zugreifen

Grundwahrheiten werden über mehrere Kanäle bereitgestellt:

1. Gerenderte Dokumentation

Der Befehl orkestra sync wandelt YAML-Registries in lesbares Markdown um:

uv run orkestra sync

Das erzeugt GROUND_TRUTHS.md-Dateien, die in den Agent-Kontext einbezogen werden. Die gerenderte Ausgabe gruppiert Aussagen nach Status und Kategorie:

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

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

2. CLI-Suche

Agenten mit Shell-Zugriff können Grundwahrheiten programmatisch durchsuchen:

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

Die Suchfunktion bewertet Treffer über mehrere Felder hinweg mit gewichteter Relevanz:

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

Wenn Agenten aus YAML-Definitionen gerendert werden, kann ihr Kontext auf Ground-Truth-Registries verweisen:

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

Das stellt sicher, dass relevante Grundwahrheiten geladen werden, bevor der Agent mit der Arbeit beginnt.

Kategorien von Grundwahrheiten

Betrachtet man unsere Registries im Ganzen, clustern sich Grundwahrheiten in mehrere Muster:

Produktprinzipien

Einschränkungen darüber, was das Produkt ist und was nicht:

„Maguyva ist gegenüber Nutzer-Repositories rein lesend; das einzige nicht wiederherstellbare Asset ist der bezahlte Embeddings-Cache.“ (GT-MAG-001)

Architekturgrenzen

Wo Verantwortlichkeiten liegen und warum:

„Die Grenzen zwischen Pipeline und Maguyva sind beabsichtigt: Pipeline ist wiederverwendbar, Maguyva enthält codespezifische Logik, und CQRS trennt Stage-Writes von Server-Reads.“ (GT-MAG-006)

Anti-Halluzinations-Regeln

Explizite Vorgaben, die Tool-Contracts deterministisch statt erraten halten:

„Unscharfes Symbol-Matching ist über find_similar=true Opt-in. Das Standardverhalten liefert leere Ergebnisse für nicht existierende Symbole; exact_match=true erzwingt striktes Matching und deaktiviert alle Fuzzy-Fallbacks.“ (GT-MAG-015)

Qualitätsgates

Standards, die eingehalten werden müssen:

„Änderungen an gemeinsam genutzter Infrastruktur (post_filters.py, Relationship-Extraktoren, gemeinsame Handler) MÜSSEN vor dem Commit per Full-Manifest-Generierung gegen ALLE unterstützten Sprachen validiert werden. Eine Einzelsprachen-Validierung reicht für gemeinsam genutzten Code nicht aus.“ (GT-MAG-036)

Code-Muster

Implementierungsanforderungen:

„Verwende asyncio.to_thread() für CPU-lastige Arbeit in Async-Kontexten; das veraltete loop.run_in_executor()-Muster sollte in neuem Code nicht mehr verwendet werden.“ (GT-MAG-018)

Der Lebenszyklus einer Grundwahrheit

Grundwahrheiten sind nicht statisch. Sie durchlaufen einen definierten Lebenszyklus:

Tentative

Eine vorgeschlagene Wahrheit unter Bewertung. Die Aussage ist festgehalten, kann sich aber noch ändern:

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

Current

Eine verifizierte Wahrheit, die Agenten respektieren müssen. Die Evidenz wurde validiert:

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

Deprecated

Eine Wahrheit, die nicht mehr gilt. Zur historischen Referenz aufbewahrt, mit einem Verweis darauf, was sie ersetzt hat:

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

Warum nicht einfach Dokumentation?

Dokumentation dient einem anderen Zweck. Sie erklärt. Sie lehrt. Sie kann vage sein, kann Qualifizierer wie „im Allgemeinen“ oder „typischerweise“ verwenden.

Grundwahrheiten dürfen nicht vage sein. Sie sind Behauptungen. Sie gelten entweder, oder sie gelten nicht.

Betrachte den Unterschied:

Dokumentation: „Die API liefert im Allgemeinen leere Ergebnisse, wenn ein Symbol nicht gefunden wird, obwohl in manchen Konfigurationen Fuzzy-Matching aktiviert sein kann.“

Grundwahrheit: „Das Standardverhalten liefert leere Ergebnisse für nicht existierende Symbole; exact_match=true erzwingt striktes Matching und deaktiviert alle Fuzzy-Fallbacks.“

Die erste ist hilfreich für Menschen, die das System lernen. Die zweite ist umsetzbar für Agenten, die Entscheidungen treffen.

Agent-Guidance: Do und Avoid

Manche Grundwahrheiten enthalten explizite Agent-Guidance:

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

Das entfernt Mehrdeutigkeit. Ein Agent, der das liest, weiß nicht nur, was wahr ist, sondern auch, welche Handlungen diese Wahrheit impliziert.

Verifikation und Wartung

Grundwahrheiten brauchen Wartung. Wir verfolgen:

last_verified: Wann jemand bestätigt hat, dass die Aussage noch gilt
evidence: Dateien, die die Aussage belegen (können auf Existenz geprüft werden)
source: Wo die Wahrheit herstammt (CLI-Inspektion, Architektur-Review, Learning nach einem Vorfall)

Eine Grundwahrheit mit veralteten Verifikationsdaten oder defekten Evidenz-Links ist ein Signal zum Nachforschen. Entweder ist die Wahrheit noch gültig und braucht erneute Verifikation, oder die Realität hat sich geändert und die Wahrheit muss aktualisiert werden.

Echte Beispiele aus der Produktion

Sicherheitsgrenze

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

Diese Grundwahrheit verhindert eine Klasse von fehlgeleiteten „Sicherheitsverbesserungen“, die das Produkt kaputt machen würden.

Genauigkeit zur Extraktionszeit

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

Das kam aus schmerzhafter Erfahrung. Agenten patchten fehlschlagende Language-Packs, indem sie nur-Validator-Filter hinzufügten, die den Testharness grüner aussehen ließen, während der Live-Maguyva-Extraktor weiterhin die falschen Kanten ausgab. Die Regel zwingt Fixes zurück in den echten Pfad: YAML-Konfiguration, Queries oder Handler.

Mehrstufiges Filtering

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

Das verhindert, dass Agenten Filter am falschen Ort hinzufügen — ein häufiger Fehler, der Genauigkeits-Regressionen verursacht hat.

Integration mit dem Orchestrierungssystem

Grundwahrheiten sind eine Schicht eines größeren Kontextsystems:

Architekturentscheidungen (ADRs) – Dokumentieren, warum wir Ansatz A statt B gewählt haben
Grundwahrheiten – Sagen aus, was gerade definitiv wahr ist
Domain Patterns – Beschreiben, wie man Dinge richtig macht
Anti-Patterns – Beschreiben, was zu vermeiden ist und warum

Ein Agent, der im System arbeitet, hat Zugriff auf alle vier. Grundwahrheiten liefern den faktischen Anker, während Decisions die Geschichte erklären, Patterns die Implementierung anleiten und Anti-Patterns vor Fallstricken warnen.

Wirkung messen

Seit der Einführung von Grundwahrheiten haben wir beobachtet:

Weniger „den halluzinierten Fix reparieren“-Zyklen
Selbstbewusstere Agent-Entscheidungen, wenn Fakten klar sind
Bessere PR-Reviews, weil Erwartungen explizit sind
Kürzere Onboarding-Zeit für neue Agenten (und Menschen)

Die Investition in die Pflege von Grundwahrheiten zahlt sich in weniger Debugging und klareren Systemgrenzen aus.

Erste Schritte

Um eine Grundwahrheit zu deinem System hinzuzufügen:

Erstelle ein ground_truths.yaml im ai_assets/reference/-Verzeichnis deines Pakets
Definiere Metadaten und Render-Konfiguration
Füge Aussagen nach dem Schema hinzu
Führe uv run orkestra sync aus, um Dokumentation zu generieren
Binde die Registry in die Agent-Kontext-Komposition ein

Beginne mit den Fakten, die die meiste Verwirrung stiften, oder den Einschränkungen, die am häufigsten verletzt werden. Das sind deine wertvollsten Grundwahrheiten.

Fazit

KI-Agenten werden halluzinieren. Das liegt in ihrer Natur. Aber wir können Umgebungen schaffen, in denen Halluzination eingegrenzt ist, in denen bestimmte Fakten nicht verhandelbar sind, in denen Agenten ihre Annahmen gegen verifizierte Realität abgleichen können.

Grundwahrheiten sind keine vollständige Lösung. Sie brauchen Wartung. Sie können veralten. Sie fügen dem Entwicklungsprozess Overhead hinzu.

Aber sie liefern etwas Wertvolles: ein gemeinsames Vokabular an Fakten, dem sowohl Menschen als auch Agenten vertrauen können. In einer Welt, in der Agenten zunehmend an der Softwareentwicklung teilnehmen, wird dieses gemeinsame Fundament essenziell.

Die Alternative sind endlose Zyklen, in denen Agenten selbstbewusst Fehler machen und Menschen sie korrigieren. Grundwahrheiten durchbrechen diesen Zyklus, indem sie die Korrekturen explizit und dauerhaft machen.

Deine Agenten haben es verdient zu wissen, was wahr ist. Sag es ihnen.

Orkestra: KI-Agenten im großen Maßstab orchestrieren

Tue, 06 Jan 2026 00:00:00 GMT

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Januar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

Als wir angefangen haben, mit Claude Code zu bauen, sind wir auf ein Problem gestoßen, dem jedes Team, das KI-Coding-Assistenten nutzt, irgendwann begegnet: Ein einzelner Agent kann nicht alles gut können.

Du kannst einen Agenten zu einem Datenbank-Spezialisten machen. Oder zu einem Security-Auditor. Oder zu einem Frontend-Engineer. Aber in dem Moment, in dem du ihn bittest, alle drei gleichzeitig zu sein, leidet die Qualität. Kontext verwässert. Anweisungen widersprechen sich. Der Agent wird zu einem Generalisten, der in allem mittelmäßig ist.

Also haben wir Orkestra gebaut.

Was ist Orkestra?

Orkestra ist ein Agent-Orchestrierungssystem für Claude Code und ähnliche KI-Coding-Tools. Es koordiniert mehrere spezialisierte Agenten, jeder mit eigener Expertise, unter einem einzigen Orchestrator, der Arbeit an den richtigen Spezialisten routet.

Stell es dir wie eine Personalvermittlung für KI-Agenten vor. Der Orchestrator erhält eine Aufgabe, identifiziert, welcher Spezialist sie bearbeiten soll, und delegiert mit dem richtigen Kontext. Wenn die Arbeit erledigt ist, fließen die Ergebnisse zur Synthese zurück zum Orchestrator.

Die Zahlen erzählen die Geschichte:

Komponente	Anzahl
Spezialisierte Agenten	46
Wiederverwendbare Skills	466
Identitäts-Archetypen	27
Mindsets	11
Kommunikationsstile	10
Wissensdomänen	21

Das Charaktersystem: D&D für Agenten

Die Kernerkenntnis hinter Orkestra ist, dass Agent-Verhalten aus drei kombinierbaren Primitiven entsteht:

Identity definiert was der Agent ist. Ein Architect entwirft Systemstrukturen. Ein Debugger verfolgt Fehler zu ihren Grundursachen. Ein Guardian setzt Compliance- und Sicherheitsgrenzen durch. Wir haben 27 Identitäts-Archetypen, die gemischt werden können.

Mindset definiert wie der Agent denkt. Ein analytisches Mindset verankert Aussagen in Evidenz und quantifiziert Unsicherheit. Ein skeptisches Mindset hinterfragt Annahmen und sucht widerlegende Evidenz. Ein exploratives Mindset umarmt Mehrdeutigkeit und probiert mehrere Ansätze.

Style definiert wie der Agent kommuniziert. Ein technischer Style enthält exakte Werte und referenziert konkrete Dateien. Ein knapper Style streicht Füllwörter und führt mit der Antwort. Ein diplomatischer Style balanciert Ehrlichkeit mit Taktgefühl.

Ein Agent kombiniert diese Primitiven:

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

Diese Komposition erzeugt einen Agenten, der Systeme entwirft (architect), Wissen über Domänen hinweg verbindet (knowledge-architect), strategische Richtung vorgibt (strategist), in Evidenz und Daten denkt (analytical) und ohne Füllwörter kommuniziert (concise).

Die Stärke liegt in der kombinatorischen Explosion. 27 Identities mal 11 Mindsets mal 10 Styles ergeben fast 3.000 mögliche Agent-Persönlichkeiten. Aber du definierst nur die Kombinationen, die für deine Arbeit zählen.

Skills: Wiederverwendbare Fähigkeitsmodule

Skills sind das Wissen und die Workflows, die Agenten aufrufen können. Sie folgen einem gestuften System basierend auf Geltungsbereich:

Tier	Name	Geltungsbereich	Beispiel
K0	Foundations	Universelle Methodik	Test-First-Disziplin, evidenzbasierte Fertigstellung
K1	Identities	Rollenbasierte Workflows	CLI-Schnittstellenstandards, Performance-Leitfaden
K2	Domains	Domänenspezifisches Wissen	Datenbank-Migrationsmuster, Authentifizierungs-Validierung
K3	Stacks	Technologiespezifisch	Cloudflare-Deployment, Supabase-Operationen
K4	Project	Nur diese Codebase	Projektspezifische Workflows und Konventionen

Skills werden Lazy-Loaded. Ein Agent sieht Skill-Namen und -Beschreibungen beim Start, aber der vollständige Skill-Inhalt lädt erst, wenn er ausgelöst wird. Das hält den Kontext schlank, während Hunderte von Skills auffindbar bleiben.

Jeder Skill enthält:

Klare Auslösebedingungen („Verwenden, wenn Datenbankschemas migriert werden“)
Schritt-für-Schritt-Anleitung
Erlaubte Tools für den Workflow
Erfolgskriterien und Recovery-Pfade bei Fehlern

Die 466 Skills in unserer Registry decken alles ab, von Git-Worktree-Isolation über Web-Research-Workflows bis zu Deployment-Health-Validierung.

Warum Orchestrierung wichtig ist

Single-Agent-Architekturen stoßen schnell an Grenzen:

Kontext-Verwässerung. Ein 200k-Token-Kontextfenster klingt groß, bis du Datenbankschemas, API-Dokumentation, Test-Fixtures und Domänenwissen lädst. Spezialisten können mit gezieltem Kontext arbeiten.

Widersprüchliche Anweisungen. Einem Agenten zu sagen, „sei gründlich, aber schnell“ und „verifiziere alles, aber übertreibe es nicht“, erzeugt Spannung. Spezialisten lösen das, indem sie einen klaren Scope haben.

Expertise-Tiefe. Ein Generalist-Agent weiß ein bisschen über alles. Ein Spezialist-Agent, komponiert mit der richtigen Identity und den richtigen Skills, kennt seine Domäne tiefgehend.

Orkestra implementiert flache Orchestrierung: Ein Orchestrator koordiniert mehrere Spezialisten. Spezialisten können keine Sub-Spezialisten erzeugen. Das verhindert eine Komplexitätsexplosion, während parallele Arbeit möglich bleibt.

Der Orchestrator hat Zugriff auf 2,2 Millionen Token effektive Kapazität: sein eigenes 200k-Fenster plus 10 gleichzeitige Subagents mit je 200k. Arbeit, die einen einzelnen Agenten erschöpfen würde, läuft komfortabel über die gesamte Flotte.

Die Rendering-Pipeline

Agent-Definitionen leben in YAML. Claude Code liest Markdown. Orkestra überbrückt diese Lücke mit einer deterministischen Rendering-Pipeline:

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

Operatoren bearbeiten die YAML-Quelle und führen orkestra sync aus. Gerendertes Markdown erscheint in .claude/agents/. Claude Code übernimmt die Änderungen.

Diese Trennung bedient unterschiedliche Zielgruppen:

YAML-Quelle enthält Lifecycle-Metadaten, Tags, Validierungsregeln und Deprecation-Hinweise für Tooling
Gerendertes Markdown enthält nur, was das Modell braucht: Beschreibung, Tools, Skills und Verhaltensanleitung

Die Pipeline komponiert Identities, Mindsets, Styles und Skills zu einem einzigen kohärenten Prompt. Ein architect-analytical-concise-Agent bekommt einen ganz anderen System-Prompt als ein debugger-skeptical-technical-Agent, selbst wenn sie einige zugrunde liegende Skills teilen.

Domänenwissen: Das Vier-Datei-Muster

Jede Wissensdomäne folgt einer konsistenten 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

Diese Struktur dient dem Laden von Agent-Kontext. Ein Agent, der an Authentifizierung arbeitet, lädt authentication/patterns.md für Anleitung und authentication/anti-patterns.md, um bekannte Fallstricke zu vermeiden. Die Dateien sind auf effizientes Kontext-Laden zugeschnitten: fokussiert genug, um nützlich zu sein, umfassend genug, um maßgeblich zu sein.

Wir pflegen 21 Top-Level-Domänen einschließlich Analytics, Authentifizierung, Datenwissenschaft, Infrastruktur, Machine Learning, Performance, Security und mehr. Jede Domäne kann Sub-Domänen für feinere Granularität haben.

Werte: Das Betriebssystem

Alle Agenten teilen eine Basisschicht an Werten, die definieren, wie sie operieren:

Einfachheit zuerst. Verwende die einfachste Lösung, die funktioniert. Füge Komplexität nur hinzu, wenn sie gerechtfertigt ist.

Grundursachen beheben. Nie um Fehler herumpatchen. Wenn eine Pipeline fehlschlägt, debugge die Pipeline. Wenn ein Test fehlschlägt, repariere den Code oder den Test.

Evidenzbasiert. Kennzeichne Behauptungen als „verifiziert“ (mit Benchmarks) oder „geschätzt“ (mit Annahmen). Ein erkanntes Muster ist nicht gleich ein bestätigtes Problem.

Context-Ökonomie. MCP-Tools kosten 0,1 % des Kontexts. Datei-Reads kosten je 2 %. Wende Domänenexpertise an, bevor du Code erkundest.

Diese Werte pflanzen sich über die Rendering-Pipeline zu jedem Spezialisten fort. Ein Agent kann sie nicht durch Komposition umgehen.

CLI: Die Steuerungsebene

Orkestra wird mit einer CLI zur Verwaltung des Agent-Ökosystems ausgeliefert:

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

Die CLI ist die Quelle der Wahrheit dafür, welche Agenten existieren, welche Skills sie haben, und ob das System gesund ist. Sie führt Validierung vor dem Sync aus, um Probleme früh zu erkennen.

Open-Source-Überlegungen

Wir haben Orkestra gebaut, um unser eigenes Problem zu lösen: KI-Agenten im großen Maßstab für eine komplexe Codebase zu koordinieren. Die Muster, die wir entdeckt haben, sind nicht spezifisch für unsere Domäne.

Das Character-Kompositionssystem (Identity + Mindset + Style) gilt für jedes Team, das Agent-Persönlichkeiten definiert.

Das Skill-Tier-System (K0–K4) liefert ein mentales Modell zur Organisation wiederverwendbarer Capabilities nach Geltungsbereich.

Das Rendering-Pipeline-Muster (YAML-Quelle + Templates + generierte Artefakte) trennt Belange zwischen Tooling und Modell-Konsum.

Das flache Orchestrierungsmodell (ein Koordinator, viele Spezialisten) vermeidet Komplexität, während es Parallelität ermöglicht.

Ob Orkestra Open Source wird, hängt davon ab, ob diese Muster für andere, die mit Claude Code bauen, einen Wert haben. Wenn du an die Grenzen stößt, die wir beschrieben haben, könnte die Architektur helfen.

Was wir gelernt haben

Der Bau von Orkestra hat uns gelehrt, dass es bei Orchestrierung nicht darum geht, Agenten intelligenter zu machen. Es geht darum, sie fokussierter zu machen.

Ein einzelner Agent mit perfekten Anweisungen schöpft trotzdem irgendwann sein Kontextfenster aus. Ein einzelner Agent mit allen Skills wird trotzdem verwirrt darüber, welchen er anwenden soll. Ein einzelner Agent, der versucht, alles zu sein, produziert überall mittelmäßige Ergebnisse.

Vierzig Spezialisten, jeder exzellent in seiner Domäne, koordiniert von einem Orchestrator, der weiß, wann er delegieren muss: So liefern wir aus.

Die Zahlen zählen weniger als die Architektur. Du brauchst vielleicht fünf Agenten oder fünfzig. Das Prinzip bleibt: Komposition vor Capability, Spezialisierung vor Generalisierung, Koordination vor individuellem Heldentum.

Orkestra treibt das Agent-Ökosystem hinter Maguyva an, unserer Code-Intelligence-Plattform. Willst du mehr erfahren? Kontaktiere das Team.