# AGENTS.md dice a Codex come lavorare. Non cosa c'è. Canonical source: https://maguyva.ai/it/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 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. > AGENTS.md è l'accordo. MCP è il canale. Maguyva è la mappa. ## Lo stack a livelli Quattro idee. Ognuna ha un compito. ### AGENTS.md Come Codex dovrebbe comportarsi in questo repo. ### MCP Come Codex accede a strumenti e contesto esterni. ### Maguyva Il server MCP che restituisce fatti fondati sul repo. ### Workspace, non utenti Gli agenti non comportano costi per utente. [Vedi i prezzi](https://maguyva.ai/it/pricing) ## AGENTS.md è un accordo di lavoro. Usalo. Le istruzioni persistenti vanno in [`AGENTS.md`](https://developers.openai.com/codex/guides/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” valide per una specifica directory. - Convenzioni di denominazione e preferenze di refactoring. - Riferimenti ai log delle decisioni canoniche e alle note di architettura. Tienilo conciso. Delimitane l'ambito. Salvalo in un 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)](https://modelcontextprotocol.io/docs/getting-started/intro) - **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 Specifici per Codex. Basati sul grafo di chiamate reale, non sul grep di Codex. ### 01. Rinomina una classe condivisa, trova prima tutto ciò che ne dipende ```text codex> rinomina PaymentClient → BillingClient graph::callers(PaymentClient) 12 riferimenti in 7 pacchetti graph::importers(src/payments/client.ts) 9 moduli che lo importano 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 tutto ciò che dipende dalla classe *prima* di iniziare a modificare. L'elenco delle modifiche da apportare si basa sul grafo reale, non sul ricordo di Codex. ### 02. Trova l'implementazione reale, non lo stub di test ```text 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. ### 03. Controlla il raggio d'impatto prima di un refactoring ```text 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 si basa sui moduli che effettuano davvero gli import, non sul grep di Codex. ## Configurazione in Codex CLI Tre passaggi. Piano Free: 3 repository, Fino a 50K righe di repository indicizzate, senza carta di credito. ### 01. Indicizza un repo su maguyva.ai Scegline uno che conosci bene, così puoi verificare le risposte. ### 02. Aggiungi Maguyva come server MCP nella tua configurazione di Codex `~/.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. Fai una domanda di cui conosci già la risposta Non iniziare con tutta la tua azienda. Inizia con un repo e una domanda verificabile. ## Indicizza un repo che già conosci. Collega Codex via MCP. Fai una domanda di cui puoi verificare la risposta.