// acuerdo
AGENTS.md
Cómo debe comportarse Codex en este repo.
Para usuarios de Codex CLI
AGENTS.md le dice a Codex cómo trabajar.
No qué hay ahí.
AGENTS.md establece el acuerdo de trabajo. MCP le permite a Codex alcanzar 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.
Nivel Free: 3 repositorios, Hasta 50 mil líneas de repo indexadas, sin tarjeta.
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.
// transporte
MCP
Cómo alcanza Codex herramientas y contexto externos.
// codebase
Maguyva
El servidor MCP que devuelve hechos fundamentados del repo.
// quién paga
Workspaces, no asientos
Los agentes no pagan asientos. Ver precios
AGENTS.md es un acuerdo de trabajo. Úsalo.
Las instrucciones persistentes van en AGENTS.md. Es el lugar correcto para:
- Comandos de build, test y lint que Codex debería ejecutar.
- Guardrails de “siempre haz X / nunca hagas Y” acotados 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. Commitealo.
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 está confiadamente desactualizado. 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 esta forma. La página solo debería hacerlo evidente.
AGENTS.md
acuerdos
cómo se comporta Codex
MCP
el canal
cómo alcanza
Maguyva
hechos del codebase
qué ve
- AGENTS.md cómo se comporta Codex en este repo.
- MCP cómo alcanza Codex herramientas y contexto. (especificación)
- Maguyva qué ve Codex cuando le hace una pregunta al codebase. 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 algo desde dónde trabajar.
Tres flujos de trabajo
Específico de Codex. Fundamentado en el grafo de llamadas real, no en el grep de Codex.
// workflow 01
Renombra una clase compartida, encuentra primero cada dependiente
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.
// workflow 02
Encuentra la implementación real, no el stub de prueba
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.
// workflow 03
Revisa el radio de impacto antes de un refactor
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.
// step 01
Indexa un repo en maguyva.ai
Elige uno que conozcas bien, para poder verificar las respuestas.
// step 02
Agrega Maguyva como servidor MCP en tu configuración de 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
Haz una pregunta cuya respuesta ya conozcas
No empieces con toda tu empresa. Empieza con un repo y una pregunta verificable.