AGENTS.md en Codex: dónde va, en qué orden se carga y qué escribir

Dónde busca Codex AGENTS.md, en orden de carga

Codex construye la cadena de instrucciones una sola vez al arrancar (en la interfaz de terminal, una vez por sesión). Los archivos se unen de arriba abajo según esta tabla, así que las instrucciones más cercanas a tu directorio de trabajo llegan después y prevalecen.

Cómo configurar AGENTS.md para Codex

1. Crea los valores globales por defecto

   Ejecuta mkdir -p ~/.codex y escribe en ~/.codex/AGENTS.md las preferencias que quieras en todos los repositorios. Para comprobar que se ha cargado, pide a Codex que resuma sus instrucciones.

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. Añade un archivo de proyecto y overrides donde los equipos difieran

   Pon un AGENTS.md en la raíz del repositorio para la configuración común. En una carpeta con reglas distintas, añade AGENTS.override.md: sustituye al AGENTS.md de esa carpeta, que Codex pasa a ignorar.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Comprueba qué se ha cargado

   Inicia Codex en la carpeta que te interesa, por ejemplo codex --cd services/payments, y pídele que enumere las fuentes de instrucciones que ha cargado. Debería listar el archivo global, luego el de la raíz y luego el de la carpeta.

4. Reutiliza un nombre de archivo existente o sube el límite

   Si tu repositorio ya guarda las instrucciones en otro archivo, añádelo a project_doc_fallback_filenames en ~/.codex/config.toml. Codex deja de añadir archivos cuando el tamaño combinado alcanza project_doc_max_bytes, 32 KiB por defecto.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Añade reglas para el code review de Codex

   Para @codex review en GitHub, añade una sección ## Code Review Rules al AGENTS.md más cercano al código que regula. Indica qué debe señalar y cuál es la alternativa segura; deja el formato y el lint a la CI.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

Fuente: documentación de Codex, Custom instructions with AGENTS.md

Buenas prácticas para AGENTS.md

• Limítate a lo que Codex no puede deducir: los comandos exactos de build, tests y lint (incluido cómo ejecutar un solo test), las trampas del código y las decisiones que no están escritas en ningún sitio.
• Pon las reglas más específicas cerca del código: un AGENTS.md anidado en services/payments/ es mejor que un archivo raíz largo con una sección de pagos.
• Vigila el presupuesto de 32 KiB: los archivos se añaden desde la raíz hacia abajo y el resto se corta, así que divide los archivos largos en otros anidados o sube project_doc_max_bytes.
• Usa AGENTS.override.md para cambios temporales, globales o en una sola carpeta, y bórralo para volver atrás.
• Un AGENTS.md vacío se omite y la búsqueda en ese directorio pasa al siguiente nombre de archivo.
• Usa un CODEX_HOME aparte para los usuarios de automatización, para que sus instrucciones globales no se mezclen con las tuyas.

AGENTS.md en Codex vs Claude Code y otros

AGENTS.md es un formato abierto que leen muchos agentes, lo que lo convierte en el mejor sitio para las instrucciones que quieres compartir. Claude Code tiene su propio archivo, CLAUDE.md; consulta la guía de CLAUDE.md para los detalles.

AGENTS.md le dice a Codex cómo. Crewmark le dice qué toca después.

Un buen AGENTS.md hace que cada sesión de Codex empiece bien informada, pero la sesión sigue esperando tu prompt. Crewmark convierte una sesión de Codex, Claude Code, DeepSeek Harness u OpenCode en un empleado de IA con un rol, un objetivo y un horario, y la despierta con un heartbeat para que tome la siguiente issue de un tablero.

1. Deja AGENTS.md en el repositorio

   La sesión de Codex del empleado lo lee igual que la tuya, así que las convenciones y los comandos de tests vienen incluidos.

2. Deja que el heartbeat inicie el trabajo

   Durante su horario laboral el empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; mira cómo hacer proactivo a Codex.

3. Combina agentes en un mismo tablero

   Un solo AGENTS.md puede servir a empleados de Codex y de Claude Code a la vez; compáralos en Claude Code vs Codex.

Preguntas frecuentes sobre AGENTS.md en Codex