Codex y AGENTS.md: cómo leer los archivos que usa Codex

Codex lee instrucciones de archivos Markdown llamados AGENTS.md. Cuando se lo pides, también puede escribir planes, especificaciones y notas como archivos .md en tu proyecto. Esta página explica dónde busca Codex los AGENTS.md y cómo leer todos estos archivos con comodidad.

Dónde busca Codex el AGENTS.md

Al iniciarse, Codex construye una única cadena de instrucciones: un archivo global y luego los archivos del proyecto a lo largo de la ruta hasta tu carpeta de trabajo.

1. Tu archivo global. En la carpeta personal de Codex, ~/.codex (o la carpeta definida por CODEX_HOME). Codex usa AGENTS.override.md si existe y, si no, AGENTS.md. Aquí solo se usa un archivo.

2. Tu proyecto. Codex empieza en la raíz del proyecto (la raíz de Git por defecto; project_root_markers puede cambiarlo) y baja hasta la carpeta en la que estás trabajando. En cada carpeta toma como máximo un archivo, comprobando en este orden:

  1. AGENTS.override.md
  2. AGENTS.md
  3. Cualquier nombre que hayas indicado en project_doc_fallback_filenames

Si no hay raíz del proyecto, Codex solo comprueba la carpeta actual.

Cómo se combinan los archivos

Codex une los archivos desde la raíz hacia abajo, con líneas en blanco entre ellos. Un archivo más cercano a tu carpeta de trabajo va después, así que sus instrucciones prevalecen sobre las anteriores. Los archivos vacíos se omiten.

Hay un límite de tamaño: Codex deja de añadir archivos cuando su tamaño combinado alcanza project_doc_max_bytes, que por defecto es 32 KiB (32,768 bytes). Si tus instrucciones son largas, sube el límite o divídelas en archivos AGENTS.md en subcarpetas.

Los dos ajustes están en config.toml, en la carpeta personal de Codex (por defecto ~/.codex/config.toml):

project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

Inicia una nueva ejecución de Codex después de cambiarlos.

Un AGENTS.md sencillo

# AGENTS.md

## Commands
- Build: `npm run build`
- Test: `npm test`

## Rules
- Write plans to `docs/plans/<task>.md` before changing code.
- Keep each change small; explain it in the pull request.

Codex no guarda los planes en archivos por su cuenta. Para obtener planes que puedas leer más tarde, pídele que escriba uno en un archivo, en AGENTS.md (como la segunda regla) o en tu instrucción.

Cómo leer lo que escribe Codex

Con pocos archivos, sirve cualquier editor. Con muchos (un plan por tarea, notas, informes), ayuda leerlos como páginas y ver qué ha cambiado.

En un Mac, PilcrowMD (gratis, beta):

PilcrowMD para Mac (beta) · Más sobre cómo leer archivos de agentes

Preguntas frecuentes

¿AGENTS.md es solo para Codex? No. Es una convención abierta que leen varios agentes de programación, no un formato exclusivo de Codex. Claude Code, por ejemplo, puede leer AGENTS.md cuando un proyecto no tiene CLAUDE.md (página de Claude Code).

¿Por qué Codex ignora parte de mis instrucciones? Comprueba el límite de tamaño (32 KiB por defecto) y si un AGENTS.override.md de la misma carpeta ocupa el lugar de tu AGENTS.md.

¿Puedo leer estos archivos en mi teléfono? Si la carpeta del proyecto se sincroniza con Google Drive, añádela en Mis carpetas en PilcrowMD para Android. Abre una nota para ver su última versión; en Android no hay recarga en directo.

También en Mac: PilcrowMD para Mac (beta)