# AGENTS.md le dice a Codex cómo trabajar. No qué hay ahí. Canonical source: https://maguyva.ai/es/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 establece el acuerdo de trabajo. MCP le permite a Codex acceder a herramientas. Maguyva es el servidor MCP que le da a Codex un mapa consultable de tu repo, para que la primera edición no sea una adivinanza sobre la estructura de archivos. > AGENTS.md es el acuerdo. MCP es el canal. Maguyva es el mapa. ## El stack en capas Cuatro ideas. Cada una cumple una función. ### AGENTS.md Cómo debe comportarse Codex en este repo. ### MCP Cómo accede Codex a herramientas y contexto externos. ### Maguyva El servidor MCP que devuelve hechos fundamentados del repo. ### Por espacio de trabajo, no por usuario Los agentes no generan cargos por usuario. [Ver precios](https://maguyva.ai/es/pricing) ## AGENTS.md es un acuerdo de trabajo. Úsalo. Las instrucciones persistentes van en [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). Es el lugar correcto para: - Comandos de build, test y lint que Codex debería ejecutar. - Reglas de “siempre haz X / nunca hagas Y” acotadas a un directorio. - Convenciones de nomenclatura y preferencias de refactor. - Referencias a los registros de decisiones canónicos y notas de arquitectura. Mantenlo conciso. Acótalo. Guárdalo en un commit. Pero `AGENTS.md` nunca fue pensado para ser un índice consultable de cada símbolo, archivo y punto de llamada en tu repo. ## Dónde AGENTS.md solo se queda estático a gran escala Cuatro modos de falla, uno por tarjeta. ### // los acuerdos no son un índice Decirle a Codex *cómo trabajar* no le dice *qué existe*. La primera edición en un paquete desconocido es una adivinanza sobre rutas de archivo y nombres de función. AGENTS.md no puede listar cada símbolo, y tampoco querrías que lo hiciera. ### // el doc se desalinea del código Un bloque de AGENTS.md que describe la topología de tus colas está bien hasta que alguien introduce un nuevo consumer. El código es ahora la fuente de verdad y el doc afirma con total seguridad información desactualizada. Codex lee el equivocado. ### // renombrar es un problema de grafo “¿Qué referencia esta clase?” no se puede responder desde un archivo markdown. Codex hace grep-y-reza en todo el monorepo, o te pide que pegues los puntos de llamada en el chat. ### // las ventanas de contexto no son gratis Rellenar AGENTS.md hasta que Codex “sepa lo suficiente” consume tokens que deberían pagar por el razonamiento. Pasadas unas pocas KB, cambias calidad de respuesta por volumen de contexto estático. ## Cómo encajan las tres capas Los usuarios de Codex ya piensan en estos términos. La página solo debería hacerlo evidente. - **AGENTS.md**: acuerdos (cómo se comporta Codex) - **MCP**: el canal (cómo accede) - **Maguyva**: hechos de la base de código (qué ve) - **AGENTS.md**: cómo se comporta Codex en este repo. - **MCP**: cómo accede Codex a herramientas y contexto. [(especificación)](https://modelcontextprotocol.io/docs/getting-started/intro) - **Maguyva**: qué ve Codex cuando le hace una pregunta a la base de código. Búsqueda semántica, de AST, de grafo y de texto, devuelta con rutas de archivo y números de línea. > AGENTS.md le dice a Codex *cómo trabajar*. > Maguyva le da a Codex *una base sobre la que trabajar*. ## Tres flujos de trabajo Específico de Codex. Fundamentado en el grafo de llamadas real, no en el grep de Codex. ### 01. Renombra una clase compartida, encuentra primero cada dependiente ```text codex> renombrar PaymentClient → BillingClient graph::callers(PaymentClient) 12 referencias en 7 paquetes graph::importers(src/payments/client.ts) 9 importadores graph::extends(PaymentClient) 2 subclases (RetryClient, MockClient) → Codex propone una migración de 21 ediciones con la lista de archivos inline. [exit 0] ``` Codex le pregunta a Maguyva por los dependientes *antes* de empezar a editar. La lista de migración vuelve fundamentada en el grafo real, no en el recuerdo de Codex. ### 02. Encuentra la implementación real, no el stub de prueba ```text codex> ¿cómo maneja normalizePhoneNumber el formato E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← impl real test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0] ``` Los nombres mienten. Los mocks tapan el código real. Maguyva ubica la implementación real por encima del mock de prueba. ### 03. Revisa el radio de impacto antes de un refactor ```text codex> ¿qué llama a QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 en src/billing/* 1 en src/audit/* 1 en src/notifications/* [exit 0] ``` Los puntos de llamada entre paquetes aparecen inline. El diff está fundamentado en importadores reales, no en el grep de Codex. ## Configuración en Codex CLI Tres pasos. Nivel Free: 3 repositorios, Hasta 50 mil líneas de repo indexadas, sin tarjeta. ### 01. Indexa un repo en maguyva.ai Elige uno que conozcas bien, para poder verificar las respuestas. ### 02. Agrega Maguyva como servidor MCP en tu configuración de 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. Haz una pregunta cuya respuesta ya conozcas No empieces con toda tu empresa. Empieza con un repo y una pregunta verificable. ## Indexa un repo que ya conozcas. Conecta Codex vía MCP. Haz una pregunta cuya respuesta puedas verificar.