# AGENTS.md vertelt Codex hoe het moet werken. Niet wat er staat.

Canonical source: https://maguyva.ai/nl/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 de werkafspraken vast. Via MCP kan Codex tools aanroepen. Maguyva is de MCP-server die Codex een doorzoekbare kaart van je repo geeft, zodat de eerste wijziging geen gok naar de bestandsstructuur is.

> AGENTS.md is de afspraak. MCP is het kanaal. Maguyva is de kaart.

## De gelaagde stack

Vier ideeën. Elk met precies één taak.

### AGENTS.md

Hoe Codex zich op deze repo moet gedragen.

### MCP

Hoe Codex externe tools en context benadert.

### Maguyva

De MCP-server die gefundeerde repofeiten teruggeeft.

### Per workspace, niet per gebruiker

Voor agents betaal je geen gebruikerslicenties. [Bekijk de prijzen](https://maguyva.ai/nl/pricing)

## AGENTS.md is een werkafspraak. Gebruik het.

Blijvende instructies horen thuis in [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). Dat is de juiste plek voor:

- Build-, test- en lintcommando's die Codex moet draaien.
- “Doe altijd X / doe nooit Y”-regels, afgebakend per directory.
- Naamgevingsconventies en refactorvoorkeuren.
- Verwijzingen naar de canonieke decision logs en architectuurnotities.

Houd het beknopt. Bepaal de scope. Commit het.

Maar `AGENTS.md` was nooit bedoeld als doorzoekbare index van elk symbool, bestand en call site in je repo.

## Waar AGENTS.md alleen statisch wordt op schaal

Vier faalmodi, één per kaart.

### // afspraken zijn geen index

Codex vertellen *hoe het moet werken* vertelt het niet *wat er bestaat*. De eerste wijziging in een onbekend package is een gok naar bestandspaden en functienamen. AGENTS.md kan niet elk symbool opsommen, en dat zou je ook niet willen.

### // de doc raakt los van de code

Een AGENTS.md-blok dat je queue-topologie beschrijft, klopt tot iemand een nieuwe consumer introduceert. De code is nu de source of truth, en de doc is zelfverzekerd verouderd. Codex leest de verkeerde.

### // hernoemen is een graafprobleem

“Wat verwijst naar deze class?” is niet te beantwoorden vanuit een markdown-bestand. Codex grept-en-hoopt door de hele monorepo, of vraagt je om call sites in de chat te plakken.

### // contextvensters zijn niet gratis

AGENTS.md volstoppen tot Codex “genoeg weet” eet tokens op die eigenlijk voor redeneren zouden moeten betalen. Voorbij een paar KB ruil je antwoordkwaliteit in voor statisch contextvolume.

## Hoe de drie lagen samenkomen

Codex-gebruikers denken al in deze vorm. Deze pagina zou dat gewoon duidelijk moeten maken.

- **AGENTS.md**: afspraken (hoe Codex zich gedraagt)
- **MCP**: het kanaal (hoe het verbinding maakt)
- **Maguyva**: codebasefeiten (wat het ziet)

- **AGENTS.md**: hoe Codex zich op deze repo gedraagt.
- **MCP**: hoe Codex tools aanroept en context ophaalt. [(spec)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: wat Codex ziet als het de codebase een vraag stelt. Semantisch zoeken, AST-zoeken, graafzoeken en tekstzoeken, teruggegeven met bestandspaden en regelnummers.

> AGENTS.md vertelt Codex *hoe het moet werken*.
> Maguyva geeft Codex *iets om vanuit te werken*.

## Drie workflows

Codex-specifiek. Gefundeerd op de daadwerkelijke call graph, niet op de grep van Codex.

### 01. Hernoem een gedeelde klasse, vind eerst alle afhankelijke componenten

```text
codex> rename PaymentClient → BillingClient

graph::callers(PaymentClient)            12 referenties in 7 packages
graph::importers(src/payments/client.ts)  9 importers
graph::extends(PaymentClient)             2 subclasses (RetryClient, MockClient)

→ Codex stelt een migratie met 21 wijzigingen voor, met de bestandslijst inline.
[exit 0]
```

Codex vraagt Maguyva om afhankelijke componenten *voordat* het begint te bewerken. De migratielijst is gebaseerd op de daadwerkelijke graaf, niet op het geheugen van Codex.

### 02. Vind de echte implementatie, niet de test-stub

```text
codex> hoe verwerkt 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 liegen. Mocks overschaduwen echte code. Maguyva rangschikt de echte implementatie boven de test-mock.

### 03. Check de impactradius voor een refactor

```text
codex> vanuit welke code wordt QueueDispatcher.publish aangeroepen?

graph::callers(QueueDispatcher.publish)
  3 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]
```

Cross-package call-sites komen inline naar boven. De diff is gefundeerd op echte importers, niet op de grep van Codex.

## Instellen in Codex CLI

Drie stappen. Free-abonnement: 3 repositories, Tot 50K geïndexeerde repo-regels, geen creditcard nodig.

### 01. Indexeer een repo op maguyva.ai

Kies er een die je goed kent, zodat je de antwoorden kunt verifiëren.

### 02. Voeg Maguyva toe als MCP-server in je Codex-configuratie

`~/.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. Stel één vraag waarvan je het antwoord al weet

Begin niet met je hele bedrijf. Begin met één repo en één verifieerbare vraag.

## Indexeer één repo die je al kent.

Verbind Codex via MCP. Stel één vraag waarvan je het antwoord kunt verifiëren.