# AGENTS.md sagt Codex, wie es arbeiten soll. Nicht, was da ist.

Canonical source: https://maguyva.ai/de/for-codex

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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.

> AGENTS.md ist die Vereinbarung. MCP ist der Kanal. Maguyva ist die Karte.

## Der geschichtete Stack

Vier Ideen. Jede erfüllt eine Aufgabe.

### AGENTS.md

Wie Codex sich in diesem Repo verhalten soll.

### MCP

Wie Codex nach externen Tools und Kontext greift.

### Maguyva

Der MCP-Server, der quellenbelegte Repo-Fakten liefert.

### Workspaces, keine Seats

Agents zahlen keine Seats. [Preise ansehen](https://maguyva.ai/de/pricing)

## AGENTS.md ist eine Arbeitsvereinbarung. Nutz sie.

Dauerhafte Anweisungen gehören in [`AGENTS.md`](https://developers.openai.com/codex/guides/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 durchsucht entweder das gesamte Monorepo mit grep und hofft auf das Beste 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)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **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-Graphen, nicht in Codex' Grep.

### 01. Eine gemeinsam genutzte Klasse umbenennen, zuerst alle davon abhängigen Stellen finden

```text
codex> PaymentClient → BillingClient umbenennen

graph::callers(PaymentClient)            12 Referenzen über 7 Packages
graph::importers(src/payments/client.ts)  9 importierende Module
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 den davon abhängigen Stellen, *bevor* es mit dem Editieren beginnt. Die Migrationsliste kommt verankert im echten Graphen zurück, nicht in Codex' Erinnerung.

### 02. Die echte Implementierung finden, nicht den Test-Stub

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

### 03. Auswirkungsradius prüfen, bevor ein Refactoring beginnt

```text
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 in den tatsächlich importierenden Modulen verankert, nicht in Codex' Grep.

## Einrichtung in Codex CLI

Drei Schritte. Free-Stufe: 3 Repositories, Bis zu 50K indexierte Repo-Zeilen, keine Kreditkarte.

### 01. Ein Repo auf maguyva.ai indexieren

Wähl eines, das du gut kennst, damit du die Antworten überprüfen kannst.

### 02. Maguyva als MCP-Server in deiner Codex-Konfiguration hinzufügen

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

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

## Indexiere ein Repo, das du schon kennst.

Verbinde Codex über MCP. Stell eine Frage, deren Antwort du überprüfen kannst.