AGENTS.md para Codex: la guía completa de configuración (2026)
El AGENTS.md es el archivo de instrucciones persistentes de Codex (OpenAI Codex CLI), que se lee automáticamente antes de que trabaje en un repositorio. Codex lo busca en un orden de búsqueda fijo (global y, luego, desde la raíz de git hacia abajo hasta tu directorio actual), concatena todo lo que encuentra y limita el tamaño combinado a 32 KiB: si te pasas, el resto se descarta en silencio. Algo que conviene recordar: Codex no lee el CLAUDE.md. En esta guía te explico la mecánica: el orden de búsqueda, cómo se combinan los archivos, el límite de tamaño y un AGENTS.md real que puedes copiar.
- La mecánica del AGENTS.md en Codex cambia rápido; los detalles de abajo se contrastaron con la documentación oficial en el momento de escribir (ago 2026): verifica la documentación actual antes de depender de ella.
Qué hace el AGENTS.md en Codex (y el asunto del CLAUDE.md)
El AGENTS.md es el archivo de instrucciones persistentes que Codex carga en el contexto cada vez que abres una sesión: convenciones del proyecto, comandos de test/build y reglas que no debe romper, para que no tengas que repetirlas en cada prompt. Según la documentación oficial en learn.chatgpt.com/codex/agent-configuration/agents-md, Codex encuentra y carga los archivos AGENTS.md mediante un mecanismo fijo, pero esa misma página no menciona el CLAUDE.md ni una sola vez. Para ser directa: por ahora, Codex no lee el CLAUDE.md, aunque el CLAUDE.md y el AGENTS.md representen exactamente la misma idea.
Una frase para evitar confusiones: el AGENTS.md (el archivo de configuración de Codex) es distinto de AgentKit (el kit que corre dentro de Codex/Claude Code, agentkit.best) y de OpenAI AgentKit (el Agent Builder/ChatKit de OpenAI).
Si además usas Claude Code y quieres saber si un archivo de contexto largo realmente ayuda, mira AGENTS.md vs CLAUDE.md — y si los archivos largos sirven de algo: ese texto cubre la investigación; este trata sobre la mecánica de configuración del propio Codex.
Dónde busca Codex el AGENTS.md — el orden de búsqueda exacto
Codex no lee un único archivo AGENTS.md: recorre varios niveles, en este orden exacto (según la documentación oficial):
- Nivel global: Codex comprueba primero
~/.codex/AGENTS.override.md; si existe, lo usa en lugar de~/.codex/AGENTS.md. Sin override, lee~/.codex/AGENTS.md. - Nivel de directorio (recorriendo desde la raíz de git hacia abajo hasta tu directorio actual): Codex encuentra la raíz del repositorio git y luego baja por cada nivel de directorio hasta el
cwd(desde donde estés ejecutando Codex). En cada nivel aplica la misma regla de override: unAGENTS.override.mden ese nivel gana; si no, usaAGENTS.md.
Ejemplo: estás en ~/projects/shop/apps/web y la raíz de git es ~/projects/shop. Codex comprueba, en orden: global (~/.codex/) → ~/projects/shop/AGENTS.md (raíz de git) → ~/projects/shop/apps/AGENTS.md (si existe) → ~/projects/shop/apps/web/AGENTS.md (cwd). Lo que falta simplemente se omite, sin error.
Para qué sirve de verdad el archivo de override: mantener un AGENTS.md compartido y commiteado en git para todo el equipo, mientras dejas los ajustes personales o propios de tu máquina en un .override.md al mismo nivel, sin tocar el archivo que todos comparten.
Conviene recordar: esto no es 'el archivo más cercano gana y los demás se ignoran'; todo archivo encontrado se combina junto (siguiente sección), no se elige solo uno.
Cómo se combinan los archivos — concatenación de la raíz hacia abajo, gana el archivo más cercano
Una vez que los encuentra, Codex no elige un archivo: concatena todo lo que halló en un único bloque de contexto, en el mismo orden de la búsqueda: primero el global, luego la raíz de git y después cada subdirectorio, separados por líneas en blanco. Como un archivo más cercano al cwd se añade el último, queda al final del contexto; y cuando dos instrucciones entran en conflicto, la que aparece después (más cerca del cwd) suele ser la que el agente sigue.
Un ejemplo con 3 archivos y cuál gana en el conflicto:
~/.codex/AGENTS.md(global): «Ejecuta siempre la suite de tests completa antes de hacer commit.»~/projects/shop/AGENTS.md(raíz de git): «Usa pnpm, no npm.»~/projects/shop/apps/web/AGENTS.md(cwd): «Ejecuta solo los tests unitarios (pnpm test:unit) al editar este directorio: la suite completa es demasiado lenta para iterar.»
Estos tres no se contradicen del todo, pero la regla 3 sí choca de verdad con la regla 1. Como la regla 3 se añade el último, Codex tiende a seguirla mientras trabaja dentro de apps/web. Justo por eso, el archivo más cercano a ti debe llevar instrucciones específicas y locales, mientras que el archivo global/raíz debe quedarse con convenciones amplias y estables. En la práctica, esto también significa que un AGENTS.md de subdirectorio no puede 'anular' del todo una regla global: solo puede añadir una instrucción posterior y más específica, que el agente tiende a ponderar más en ese contexto.
El límite de 32 KiB — project_doc_max_bytes
El tamaño combinado de todos los archivos AGENTS.md encontrados (no de cada archivo por separado) está limitado por project_doc_max_bytes, cuyo valor por defecto es 32 KiB. Según la documentación config-advanced, Codex omite los archivos vacíos y deja de añadir contenido en el momento en que el tamaño combinado alcanza el límite: lo que pasa de ahí nunca llega al contexto, sin error ni aviso en el TUI.
Para subir el límite, añade esto a ~/.codex/config.toml:
project_doc_max_bytes = 65536(65536 bytes = 64 KiB es solo un ejemplo: ponlo en el valor que de verdad necesites. No lo subas 'por si acaso': cuanto más largo el archivo, más tiende el agente a excederse con cada línea; mira el ejemplo escueto de abajo.)
| Ajuste | Valor |
|---|---|
| Por defecto | 32 KiB (se aplica a todos los archivos AGENTS.md combinados) |
| Se configura con | project_doc_max_bytes en ~/.codex/config.toml |
| Por encima del límite | Deja de añadir contenido: sin error, sin aviso |
| Archivos vacíos | Se omiten, no cuentan para el total |
La trampa del truncamiento silencioso (un reporte de bug real)
Esta es la parte que la mayoría de las otras guías se salta. La GitHub Issue #7138 (abierta el 22/11/2025, cerrada como 'not planned') documenta justo esto: el AGENTS.md combinado de un usuario llegó a unos 40 KB, y Codex lo recortó en silencio a 32 KB, sin aviso en el TUI ni en /stats. La issue contrasta esto de forma explícita con Claude Code, que sí avisa cuando un archivo de contexto se pasa del presupuesto.
Nota: al momento de escribir, esta issue está cerrada como 'not planned', lo que significa que el equipo de Codex no tiene previsto añadir un aviso. Revisa el estado de la issue antes de citarla; los trackers cambian.
El arreglo práctico: no metas todas las convenciones en un único AGENTS.md raíz gigante. Divide por directorio: deja el archivo global para las convenciones amplias y haz que cada subdirectorio lleve solo lo que le concierne. Así te mantienes por debajo del límite de 32 KiB y coincides con lo que la investigación sobre AGENTS.md/CLAUDE.md ya encontró: los archivos largos no ayudan, solo cuestan más.
project_doc_fallback_filenames y CODEX_HOME
Dos ajustes más pequeños que conviene conocer si personalizas a fondo:
project_doc_fallback_filenames: un array de nombres de archivo alternativos que Codex acepta en un nivel de directorio cuando allí no existe ningún AGENTS.md, útil si tu equipo ya tiene unTEAM_GUIDE.mdy no está listo para renombrarlo. Configúralo en~/.codex/config.toml:project_doc_fallback_filenames = ["TEAM_GUIDE.md"].CODEX_HOME: la variable de entorno que apunta al directorio de configuración de Codex, por defecto~/.codex. Contieneconfig.toml,auth.jsonehistory.jsonl; cámbiala si quieres separar la configuración de Codex por perfil o máquina (por ejemplo, unCODEX_HOMEdistinto por runner de CI, para que las sesiones automatizadas nunca toquen tuauth.jsonpersonal).
Un AGENTS.md real y escueto que puedes usar
Este es el AGENTS.md raíz que yo misma uso en un repositorio Node/TypeScript: corto a propósito, porque un archivo más largo no hace que Codex rinda mejor (mira la trampa de arriba y la investigación sobre archivos de contexto):
# Build & test
- Install: `pnpm install`
- Unit tests: `pnpm test` - e2e: `pnpm test:e2e` (Playwright, slow, run only when needed)
- Build: `pnpm build`
- Before committing: `pnpm lint && pnpm typecheck`
# Must not break
- Don't change the public API in `src/sdk/` without a major version bump.
- Never commit `.env*` files.
- Don't touch `infra/` (Terraform) outside a reviewed PR.
# Key paths
- API routes: `src/api/`
- Shared types: `src/types/`
- DB migrations: `db/migrations/` (never edit an applied migration, always add a new one)15 líneas. Ningún 'resumen del proyecto', ninguna prosa explicativa. Cada línea es o bien un comando ejecutable, o bien una regla concreta de 'no romper': exactamente la parte que la investigación sobre AGENTS.md vs CLAUDE.md descubrió que los agentes de verdad siguen.
El AGENTS.md pone las reglas — AgentKit añade las skills
El AGENTS.md es configuración gratuita que Codex lee de forma nativa, sin nada que instalar. Responde a 'qué hacer / qué no hacer'. Lo que no aporta son skills o flujos de trabajo empaquetados: eso es lo que añade AgentKit (agentkit.best, la CLI ak), corriendo por encima de Codex, sin reemplazar el AGENTS.md.
Instalar el kit para Codex: ak kit init engineer --target codex --global (añade --global para usarlo en todos los repositorios); luego, dentro de una nueva sesión de Codex, ejecuta $ak:cook ... (fíjate en la sintaxis $ak: en Codex, frente a /ak: en Claude Code: la entrega en Codex es, por ahora, solo nativa: skills, reglas, dispatch de agentes y hooks parciales; los comandos del kit todavía no están activos ahí, y no hay status line).
Para ser franca con la línea gratis/pago: el AGENTS.md no cuesta nada. AgentKit es un complemento de pago (el Engineer Kit ronda los $99, y la tienda suele aplicar un -20% que lo baja a unos $79.20 al momento de escribir: verifica el precio actual). ¿Nuevo en Codex? Mira primero qué es OpenAI Codex; si quieres saber qué es en realidad SKILL.md (distinto del AGENTS.md: una capacidad bajo demanda, no un contexto siempre cargado), mira Codex Skills explicado; si quieres el recorrido de ejecutar AgentKit dentro de Codex, mira AgentKit en Codex.
¿Quieres skills empaquetadas corriendo por encima de un AGENTS.md escueto? El AgentKit Engineer Kit añade flujos de trabajo/skills prediseñados para Codex y Claude Code; tu AGENTS.md sigue haciendo el trabajo básico de poner las reglas.
Descubre el AgentKit Engineer Kit — 20% de descuento, ahora $79.20 →
Preguntas frecuentes (FAQ)
¿Codex lee el CLAUDE.md?
No. Según la documentación oficial, Codex solo busca y carga archivos AGENTS.md (y AGENTS.override.md); no hay ningún mecanismo que lea el CLAUDE.md. Si usas Claude Code y Codex en el mismo repositorio, conserva ambos archivos (o crea un symlink de uno al otro).
¿Cuál es el límite de tamaño del AGENTS.md en Codex?
32 KiB por defecto, aplicado al total combinado de todos los archivos AGENTS.md encontrados (no a cada archivo por separado), vía project_doc_max_bytes. Todo lo que pase del límite se descarta en silencio, sin error ni aviso. Puedes subir el límite en ~/.codex/config.toml.
¿Qué archivo gana si tengo AGENTS.md global, en la raíz del repo y en un subdirectorio?
Ninguno 'gana' de forma absoluta: Codex los combina todos, en orden desde el global hasta la raíz de git y bajando hasta tu directorio actual. Como el archivo más cercano a tu directorio actual se añade el último, sus instrucciones suelen ser las que se siguen cuando algo entra en conflicto.
¿Para qué sirve el AGENTS.override.md?
Cuando está presente en un nivel (global o un directorio), el AGENTS.override.md se usa en lugar del AGENTS.md en ese mismo nivel. Es útil para mantener un AGENTS.md compartido por el equipo en git mientras añades overrides personales sin tocar el archivo compartido.
¿Codex me avisa si mi archivo es demasiado largo?
No, al menos al momento de escribir. La GitHub Issue #7138 documenta un archivo de 40 KB recortado en silencio a 32 KB sin aviso en el TUI, y está cerrada como not planned. Claude Code, en cambio, sí avisa cuando un archivo de contexto se pasa del presupuesto: una diferencia que vale la pena recordar.
¿Dónde guarda Codex su configuración?
Dentro del directorio CODEX_HOME, por defecto ~/.codex, que contiene config.toml, auth.json e history.jsonl. Puedes apuntar CODEX_HOME a otro directorio mediante la variable de entorno.
Conclusión
La mecánica del AGENTS.md en Codex se reduce a tres cosas: un orden de búsqueda fijo (global y, luego, de la raíz de git hasta el cwd), una concatenación de la raíz hacia abajo en la que el archivo más cercano a ti gana en el conflicto, y un límite de 32 KiB que descarta en silencio lo que sobra; y nada de esto toca jamás el CLAUDE.md. Escríbelo escueto, divídelo por directorio en vez de amontonar un único archivo raíz gigante, y esquivarás tanto la trampa como el coste desperdiciado. Para entender por qué los archivos largos no ayudan, para empezar, mira AGENTS.md vs CLAUDE.md — y si los archivos largos sirven de algo.