// accordo
AGENTS.md
Come Codex dovrebbe comportarsi in questo repo.
Per gli utenti di Codex CLI
AGENTS.md dice a Codex come lavorare.
Non cosa c'è.
AGENTS.md stabilisce l'accordo di lavoro. MCP permette a Codex di accedere agli strumenti. Maguyva è il server MCP che dà a Codex una mappa consultabile del tuo repo, così la prima modifica non è un'ipotesi sulla struttura dei file.
Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta.
AGENTS.md è l'accordo. MCP è il canale. Maguyva è la mappa.Lo stack a livelli
Quattro idee. Ognuna fa un lavoro.
// trasporto
MCP
Come Codex accede a strumenti e contesto esterni.
// codebase
Maguyva
Il server MCP che restituisce fatti fondati sul repo.
// chi paga
Workspace, non postazioni
Gli agenti non pagano postazioni. Vedi i prezzi
AGENTS.md è un accordo di lavoro. Usalo.
Le istruzioni persistenti vanno in AGENTS.md. È il posto giusto per:
- Comandi di build, test e lint che Codex dovrebbe eseguire.
- Regole del tipo “fai sempre X / non fare mai Y” con ambito su una directory.
- Convenzioni di denominazione e preferenze di refactoring.
- Riferimenti ai log delle decisioni canoniche e alle note di architettura.
Tienilo conciso. Delimitane l'ambito. Fanne commit.
Ma AGENTS.md non è mai stato pensato per essere un indice consultabile di ogni simbolo, file e punto di chiamata nel tuo repo.
Dove AGENTS.md da solo diventa statico su larga scala
Quattro modalità di fallimento, una per scheda.
// gli accordi non sono un indice
Dire a Codex come lavorare non gli dice cosa esiste. La prima modifica su un pacchetto sconosciuto è un'ipotesi su percorsi dei file e nomi delle funzioni. AGENTS.md non può elencare ogni simbolo, e non lo vorresti comunque.
// il documento si allontana dal codice
Un blocco di AGENTS.md che descrive la topologia delle tue code è corretto finché qualcuno non introduce un nuovo consumer. Ora il codice è la fonte di verità e il documento è sicuro di sé ma obsoleto. Codex legge quello sbagliato.
// rinominare è un problema di grafo
“Cosa fa riferimento a questa classe?” non ha risposta in un file markdown. Codex fa grep e prega in tutto il monorepo, oppure ti chiede di incollare i punti di chiamata nella chat.
// le finestre di contesto non sono gratis
Riempire AGENTS.md finché Codex “ne sa abbastanza” consuma token che dovrebbero finanziare il ragionamento. Oltre pochi KB, scambi la qualità della risposta con volume di contesto statico.
Come si incastrano i tre livelli
Gli utenti di Codex pensano già in questi termini. La pagina dovrebbe renderlo evidente.
AGENTS.md
accordi
come si comporta Codex
MCP
il canale
come accede
Maguyva
fatti sul codebase
cosa vede
- AGENTS.md come Codex si comporta in questo repo.
- MCP come Codex accede a strumenti e contesto. (specifica)
- Maguyva cosa vede Codex quando fa una domanda al codebase. Ricerca semantica, AST, a grafo e testuale, restituita con percorsi di file e numeri di riga.
AGENTS.md dice a Codex come lavorare.
Maguyva dà a Codex qualcosa da cui partire.
Tre flussi di lavoro
Specifico per Codex. Fondato sul grafo di chiamate reale, non sul grep di Codex.
// workflow 01
Rinomina una classe condivisa, trova prima ogni dipendente
codex> rinomina PaymentClient → BillingClient graph::callers(PaymentClient) 12 riferimenti in 7 pacchetti graph::importers(src/payments/client.ts) 9 importatori graph::extends(PaymentClient) 2 sottoclassi (RetryClient, MockClient) → Codex propone una migrazione di 21 modifiche con l'elenco dei file inline. [exit 0]
Codex chiede a Maguyva i dipendenti prima di iniziare a modificare. L'elenco di migrazione torna fondato sul grafo reale, non sul ricordo di Codex.
// workflow 02
Trova l'implementazione reale, non lo stub di test
codex> come gestisce normalizePhoneNumber il formato E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← impl reale test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0]
I nomi mentono. I mock oscurano il codice reale. Maguyva classifica l'implementazione reale sopra il mock di test.
// workflow 03
Controlla il raggio d'impatto prima di un refactoring
codex> cosa chiama QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 in src/billing/* 1 in src/audit/* 1 in src/notifications/* [exit 0]
I punti di chiamata tra pacchetti emergono inline. Il diff è fondato su importatori reali, non sul grep di Codex.
Configurazione in Codex CLI
Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta.
// step 01
Indicizza un repo su maguyva.ai
Scegline uno che conosci bene, così puoi verificare le risposte.
// step 02
Aggiungi Maguyva come server MCP nella tua configurazione di Codex
$ 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
Fai una domanda di cui conosci già la risposta
Non iniziare con tutta la tua azienda. Inizia con un repo e una domanda verificabile.