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:
AGENTS.override.mdAGENTS.md- 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):
- Añade la carpeta de tu proyecto en Mis carpetas. Los archivos que escribe Codex aparecen marcados con N (nuevo) o U (actualizado). Una nota abierta se recarga cuando Codex u otra app la modifica.
- Resaltar cambios muestra lo que Codex ha cambiado en un plan que ya leíste: azul para lo añadido, naranja para lo eliminado o editado.
- Comparar en paralelo muestra dos versiones, como la página o como el código fuente.
- Con el historial de archivos activado, Archivo › Mostrar historial… te permite volver a una versión anterior.
- Las tablas, los bloques de código, las listas de tareas y los diagramas de Mermaid se dibujan como una página. Sin conexión a internet.
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)