// vereinbarung
AGENTS.md
Wie Codex sich in diesem Repo verhalten soll.
Für Codex CLI-Nutzer
AGENTS.md sagt Codex, wie es arbeiten soll.
Nicht, was da ist.
AGENTS.md legt die Arbeitsvereinbarung fest. MCP lässt Codex nach Tools greifen. Maguyva ist der MCP-Server, der Codex eine abfragbare Karte deines Repos liefert, damit der erste Edit keine Vermutung über die Dateistruktur ist.
Free-Stufe: 3 Repositories, Bis zu 50K indexierte Repo-Zeilen, keine Karte.
AGENTS.md ist die Vereinbarung. MCP ist der Kanal. Maguyva ist die Karte.Der geschichtete Stack
Vier Ideen. Jede erfüllt eine Aufgabe.
// transport
MCP
Wie Codex nach externen Tools und Kontext greift.
// codebase
Maguyva
Der MCP-Server, der verankerte Repo-Fakten liefert.
// wer zahlt
Workspaces, keine Seats
Agenten zahlen keine Seats. Preise ansehen
AGENTS.md ist eine Arbeitsvereinbarung. Nutz sie.
Dauerhafte Anweisungen gehören in AGENTS.md. Das ist der richtige Ort für:
- Build-, Test- und Lint-Befehle, die Codex ausführen soll.
- „Immer X / nie Y“-Guardrails, die auf ein Verzeichnis begrenzt sind.
- Namenskonventionen und Refactoring-Präferenzen.
- Verweise auf die kanonischen Entscheidungsprotokolle und Architekturnotizen.
Halte es kompakt. Begrenze den Scope. Committe es.
Aber AGENTS.md war nie dafür gedacht, ein abfragbarer Index jedes Symbols, jeder Datei und jeder Aufrufstelle in deinem Repo zu sein.
Wo AGENTS.md allein bei Skalierung statisch wird
Vier Fehlermodi, einer pro Karte.
// vereinbarungen sind kein index
Codex zu sagen, wie es arbeiten soll, sagt ihm nicht, was existiert. Der erste Edit an einem unbekannten Package ist eine Vermutung über Dateipfade und Funktionsnamen. AGENTS.md kann nicht jedes Symbol auflisten, und das sollte es auch nicht.
// das doc driftet vom code weg
Ein AGENTS.md-Block, der deine Queue-Topologie beschreibt, stimmt, bis jemand einen neuen Consumer einführt. Der Code ist jetzt die Quelle der Wahrheit, und das Doc ist zuverlässig veraltet. Codex liest das falsche.
// umbenennen ist ein graph-problem
„Was referenziert diese Klasse?“ lässt sich aus einer Markdown-Datei nicht beantworten. Codex greift entweder grep-und-hofft im gesamten Monorepo oder bittet dich, Aufrufstellen in den Chat zu pasten.
// context windows sind nicht kostenlos
AGENTS.md so lange aufzublähen, bis Codex „genug weiß“, frisst Tokens, die für Reasoning bezahlen sollten. Ab ein paar KB tauschst du Antwortqualität gegen statisches Kontextvolumen.
Wie die drei Schichten zusammenpassen
Codex-Nutzer denken schon in dieser Struktur. Die Seite sollte das nur sichtbar machen.
AGENTS.md
vereinbarungen
wie Codex sich verhält
MCP
der kanal
wie es zugreift
Maguyva
codebase-fakten
was es sieht
- AGENTS.md wie Codex sich in diesem Repo verhält.
- MCP wie Codex nach Tools und Kontext greift. (Spezifikation)
- Maguyva was Codex sieht, wenn es der Codebase eine Frage stellt. Semantische, AST-, Graph- und Textsuche, geliefert mit Dateipfaden und Zeilennummern.
AGENTS.md sagt Codex, wie es arbeiten soll.
Maguyva gibt Codex etwas, womit es arbeiten kann.
Drei Workflows
Codex-spezifisch. Verankert im echten Call-Graph, nicht in Codex' Grep.
// workflow 01
Eine gemeinsam genutzte Klasse umbenennen, zuerst jede Abhängigkeit finden
codex> PaymentClient → BillingClient umbenennen graph::callers(PaymentClient) 12 Referenzen über 7 Packages graph::importers(src/payments/client.ts) 9 Importeure graph::extends(PaymentClient) 2 Subklassen (RetryClient, MockClient) → Codex schlägt eine 21-Edit-Migration mit der Dateiliste inline vor. [exit 0]
Codex fragt Maguyva nach Abhängigkeiten, bevor es mit dem Editieren beginnt. Die Migrationsliste kommt verankert im echten Graph zurück, nicht in Codex' Erinnerung.
// workflow 02
Die echte Implementierung finden, nicht den Test-Stub
codex> wie behandelt normalizePhoneNumber E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← echte impl test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0]
Namen lügen. Mocks überschatten echten Code. Maguyva reiht die echte Implementierung über dem Test-Mock ein.
// workflow 03
Auswirkungsradius prüfen, bevor ein Refactoring beginnt
codex> was ruft QueueDispatcher.publish auf? graph::callers(QueueDispatcher.publish) 3 in src/billing/* 1 in src/audit/* 1 in src/notifications/* [exit 0]
Paketübergreifende Aufrufstellen tauchen inline auf. Der Diff ist an echten Importeuren verankert, nicht an Codex' Grep.
Einrichtung in Codex CLI
Drei Schritte. Free-Stufe: 3 Repositories, Bis zu 50K indexierte Repo-Zeilen, keine Karte.
// step 01
Ein Repo auf maguyva.ai indexieren
Wähl eines, das du gut kennst, damit du die Antworten überprüfen kannst.
// step 02
Maguyva als MCP-Server in deiner Codex-Konfiguration hinzufügen
$ export MAGUYVA_API_KEY=mgv_xxxx $ codex mcp add maguyva --url https://maguyva.tools/mcp \ --bearer-token-env-var MAGUYVA_API_KEY # equivalent ~/.codex/config.toml [mcp_servers.maguyva] url = "https://maguyva.tools/mcp" bearer_token_env_var = "MAGUYVA_API_KEY"// step 03
Eine Frage stellen, deren Antwort du schon kennst
Fang nicht mit deiner ganzen Firma an. Fang mit einem Repo und einer überprüfbaren Frage an.