Cómo evitar que Codex ignore silenciosamente tus reglas de AGENTS.md (2026)

Un archivo por directorio, y la invalidación siempre gana

Codex compila una cadena de instrucciones al inicio con una precedencia documentada. A nivel global, en tu directorio de inicio de Codex —"por defecto ~/.codex, a menos que configures CODEX_HOME"— "lee AGENTS.override.md si existe. De lo contrario, Codex lee AGENTS.md. Codex utiliza únicamente el primer archivo no vacío en este nivel".

Luego, el alcance del proyecto: comenzando en la raíz del proyecto, descendiendo hasta tu directorio de trabajo, "En cada directorio a lo largo de la ruta, busca AGENTS.override.md, luego AGENTS.md, y después cualquier nombre alternativo en project_doc_fallback_filenames. Codex incluye como máximo un archivo por directorio."

Esa última frase es la clave de todo el fallo. Un AGENTS.override.md no se fusiona con el AGENTS.md que tiene al lado: lo reemplaza. La documentación describe el uso previsto como temporal: "Usa ~/.codex/AGENTS.override.md cuando necesites una invalidación global temporal sin eliminar el archivo base. Elimina la invalidación para restaurar la guía compartida". Los archivos temporales tienen la costumbre de volverse permanentes, y seis meses después nadie recuerda que las reglas reales del repositorio están siendo suprimidas por una que alguien subió durante un incidente.

La búsqueda se detiene donde iniciaste, por lo que cualquier cosa más profunda es invisible

"Comenzando en la raíz del proyecto (normalmente la raíz de Git), Codex desciende hasta tu directorio de trabajo actual". Y: "Codex deja de buscar una vez que llega a tu directorio actual, así que coloca las invalidaciones lo más cerca posible del trabajo especializado".

Interpreta esto como una restricción en lugar de un consejo. Si ejecutas Codex desde la raíz del repositorio, el AGENTS.md cuidadosamente escrito dentro de services/payments/ no está en la cadena: estás por encima de él, no por debajo. Los directorios hermanos tampoco están nunca en la cadena. El conjunto de archivos que se cargan es una única ruta vertical, y qué ruta depende completamente de dónde te encontrabas cuando iniciaste.

Hay una brecha relacionada: "Si Codex no puede encontrar una raíz de proyecto, solo comprueba el directorio actual".

La cadena está limitada, y las dos páginas oficiales describen el límite de manera diferente

"Codex omite los archivos vacíos y deja de agregar archivos una vez que el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB por defecto)". El consejo que sigue es concreto: "Aumenta el límite o divide las instrucciones en directorios anidados cuando alcances el límite".

Vale la pena señalar una inconsistencia en lugar de ignorarla. La página de configuración avanzada describe el mismo ajuste como "cuánto leer de cada archivo AGENTS.md", mientras que la página de AGENTS.md lo describe como un punto de parada por tamaño combinado. Esas no son la misma regla. Trata los 32 KiB como un techo real que puedes alcanzar y verifica el resultado con el comando de volcado que se muestra a continuación en lugar de deducirlo de cualquiera de las dos frases; para eso existe la entrada de resolución de problemas "Instructions truncated".

De cualquier manera, el truncamiento es silencioso y afecta al final de la cadena: los archivos más cercanos a tu directorio de trabajo, que son precisamente los que más te interesaban.

Un nombre de archivo que no está en la lista no existe

Codex lee AGENTS.override.md, AGENTS.md y cualquier cosa que listes en project_doc_fallback_filenames. Puedes ampliar eso:

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

Con eso configurado, "Codex comprueba cada directorio en este orden: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md". Y luego la línea que importa: "Los nombres de archivo que no estén en esta lista se ignoran para el descubrimiento de instrucciones."

Lo que significa que CONTRIBUTING.md, CLAUDE.md, .cursorrules y .github/copilot-instructions.md son invisibles para Codex por defecto. En un repositorio donde se utilizan varios agentes, esta es la versión más común de este problema: las instrucciones existen, son buenas y están en un archivo que Codex nunca iba a abrir. La versión de esta cuestión sobre estándares de archivos entre diferentes herramientas se aborda en migrar tu CLAUDE.md a AGENTS.md.

La cadena se compila una vez, por lo que editar a mitad de la sesión no cambia nada

"Codex compila una cadena de instrucciones cuando se inicia (una vez por ejecución; en la TUI esto suele significar una vez por sesión iniciada)". Y, según la guía de verificación: "Si las instrucciones parecen desactualizadas, reinicia Codex en el directorio de destino. Codex vuelve a compilar la cadena de instrucciones en cada ejecución (y al inicio de cada sesión de TUI), por lo que no hay caché que borrar manualmente".

Así que el paso natural de depuración —notar que Codex ignora una regla, agregar la regla con más énfasis, volver a preguntar— no puede funcionar dentro de la misma sesión. Estás editando un archivo que ya fue leído. Reiniciar es la solución, y es sencillo una vez que lo sabes.

Archivos vacíos y un CODEX_HOME que olvidaste que habías configurado

Dos puntos rápidos de la lista de resolución de problemas. "Codex ignora los archivos vacíos": un marcador de posición AGENTS.md creado por herramientas y nunca completado sigue ocupando el único espacio de su directorio. Y: "Confusión de perfiles: Ejecuta echo $CODEX_HOME antes de iniciar Codex. Un valor que no sea el predeterminado apunta a Codex a un directorio de inicio diferente al que editaste". Si un script contenedor o un perfil de automatización específico del proyecto lo configuró, tu archivo global no está donde crees.

Reescribir la regla con un lenguaje más fuerte. Comprensible, pero no sirve de nada si el archivo no se cargó. Comprueba la carga antes de revisar la redacción.

Mover todo a un único AGENTS.md gigante en la raíz. Esto sí evita la regla de un archivo por directorio, pero te lleva directo al límite de 32 KiB. La documentación apunta en la dirección opuesta: dividir en directorios anidados.

Repetir la restricción en el prompt en cada ejecución. Funciona, permanentemente, con el mismo coste cada vez: el bucle descrito en cómo dejar de explicar el contexto a la IA una y otra vez.

Eliminar los archivos de invalidación a primera vista. A veces es lo correcto, a veces elimina una regla que era intencionada. Lee primero lo que contiene.

Asumir que las instrucciones son de obligado cumplimiento. Son guías que se incluyen en el primer turno. Para algo que deba cumplirse siempre, una comprobación de CI es la garantía; el punto general en por qué los agentes ignoran los archivos de instrucciones que escribiste.

Crear un enlace simbólico de CLAUDE.md a AGENTS.md y cruzar los dedos. Agregar el nombre del archivo a project_doc_fallback_filenames es la ruta documentada, y es solo una línea.

Dos comandos y una pasada de limpieza. Primero, deja de adivinar.

Vuelca la cadena desde la raíz del repositorio. La comprobación documentada:

codex --ask-for-approval never "Summarize the current instructions."

"Codex debería mostrar la guía de los archivos globales y del proyecto en orden de precedencia". Si una regla que escribiste no está en el resumen, el problema es de descubrimiento, no de cumplimiento, y te acabas de ahorrar una tarde de ingeniería de prompts.

Vuélcala de nuevo desde el directorio en el que trabajas realmente. Porque la cadena depende de dónde empieces:

codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

La documentación describe la salida esperada como "el archivo global primero, el AGENTS.md de la raíz del repositorio en segundo lugar y la invalidación de payments al final". Compara eso con lo que crees que debería cargarse. La diferencia es tu error.

Obtén un registro si quieres un historial en lugar de texto. "Para auditar qué archivos de instrucciones cargó Codex, opta por un registro TUI en texto plano con codex -c log_dir=./.codex-log y comprueba ./.codex-log/codex-tui.log, o inspecciona el archivo session-*.jsonl más reciente si habilitaste el registro de sesiones". Confirma también el espacio de trabajo: "Verifica que estás en el repositorio correcto y que codex status informa de la raíz del espacio de trabajo que esperas".

Luego limpia, en este orden. Busca cada AGENTS.override.md en el repositorio y en ~/.codex, decide si la supresión es intencionada y fusiona y elimina los que no lo sean. Agrega los nombres de archivo de instrucciones de cualquier otro agente a project_doc_fallback_filenames para que dejen de ser invisibles. Divide cualquier cosa cercana a 32 KiB en directorios anidados en lugar de aumentar el límite y olvidarlo. Elimina los archivos de instrucciones vacíos para que dejen de ocupar un espacio. Y comprueba echo $CODEX_HOME.

Eso hace que tus instrucciones se carguen. Lo que no puede solucionar es que la cadena está limitada a propósito. Una vez que el descubrimiento es correcto, estás racionando un presupuesto de 32 KiB en cada directorio en el que trabajas, y lo primero que queda fuera es siempre la misma categoría: por qué existe una restricción, qué se intentó antes, qué enfoque se rechazó y por qué razón. Las reglas sobreviven al recorte. El razonamiento no.

Eso es lo que MemoryLake almacena: el conocimiento duradero de tu proyecto en una capa de la que leen tus herramientas, para que los archivos de instrucciones sigan siendo pequeños y el razonamiento permanezca disponible. La configuración consta de tres pasos.

Paso 1: Crea una clave API

Inicia sesión en MemoryLake y crea una clave API. Una sola credencial para todas las herramientas que conectes.

Paso 2: Sube tus primeros recuerdos

Entradas cortas, una afirmación cada una. Lo que pertenece fuera de la cadena en lugar de dentro de ella:

Restricciones con el motivo adjunto. "Payments utiliza make test-payments porque el script de npm no inicia el stub del sandbox". Una línea de AGENTS.md indica el comando. Solo el motivo evita que alguien lo elimine por considerarlo redundante.

Enfoques ya rechazados en esta base de código. La categoría que no encaja en ningún lugar de un archivo de instrucciones y que se propone en cada nueva ejecución.

Hechos del entorno que nada anuncia. El límite de velocidad que no está documentado, la prueba que solo falla en CI, el requisito de orden entre dos migraciones.

Decisiones derivadas de incidentes. El motivo por el que existía la invalidación en primer lugar, para que la siguiente persona pueda distinguir una supresión intencionada de un residuo.

Paso 3: Conecta tu IA y agentes

Conecta las herramientas que utilizas. MemoryLake es accesible a través de MCP y de una API, por lo que los agentes nativos de MCP —entre ellos Claude Code, Codex y OpenClaw— se conectan apuntando al servidor MCP, mientras que otros asistentes leen la misma memoria a través de la API. El efecto práctico es que lo que recuperas no cuenta para el presupuesto de instrucciones, porque no se envía en el primer turno.

Tres límites honestos. MemoryLake no escribe tus archivos AGENTS.md y no cambia la forma en que Codex los descubre —los seis mecanismos anteriores son de Codex, y las soluciones están todas de tu lado. Solo contiene lo que tú o tus agentes introducen en él, por lo que el Paso 2 es manual. And las instrucciones son guías en lugar de una configuración forzada; una capa de memoria no cambia el cumplimiento, y para los requisitos estrictos, la CI sigue siendo la respuesta.

"Ignoró mi regla" se convierte en una pregunta de un solo comando. Pide a Codex que resuma sus instrucciones actuales. O bien tu regla está en la lista o no lo está, y los dos casos tienen soluciones completamente diferentes.

Los archivos de invalidación dejan de ser minas terrestres. Una vez unificados, no hay ningún archivo oculto que volver a descubrir en noviembre.

Los archivos de instrucciones se vuelven más pequeños. La cadena se estaba acercando a los 32 KiB porque estaba haciendo dos trabajos. Sepáralos y el límite dejará de ser una restricción.

Los archivos de otros agentes dejan de ser peso muerto. Una línea en config.toml y el CLAUDE.md o TEAM_GUIDE.md que tu equipo ya mantiene empieza a contar.

Reiniciar se convierte en un reflejo. La cadena se compila una vez por ejecución. Saber esto convierte una sesión confusa en una solución de cinco segundos.

Vuelca la cadena antes de editar cualquier cosa. Pide a Codex que resuma sus instrucciones actuales, desde la raíz y desde tu directorio de trabajo.

Nunca dejes un AGENTS.override.md permanente. Suprime el archivo que tiene al lado, y la documentación lo define como temporal.

Inicia desde el directorio para el que deseas las reglas. La cadena se detiene en tu directorio de trabajo; los archivos más profundos nunca se cargan.

Divide cerca del límite, no te limites a aumentarlo. Los directorios anidados son el remedio documentado para cuando se alcanza project_doc_max_bytes.

Lista el nombre de archivo de instrucciones de cualquier otro agente en project_doc_fallback_filenames. Los nombres de archivo que no estén en la lista se ignoran para el descubrimiento de instrucciones.

Elimina los archivos de instrucciones vacíos. Un archivo vacío se omite, y aun así ocupa el único espacio de su directorio.

Reinicia después de editar. La cadena de instrucciones se compila una vez por ejecución, por lo que las ediciones a mitad de sesión no se aplican.

Comprueba echo $CODEX_HOME cuando el archivo global parezca no tener efecto. Un valor que no sea el predeterminado apunta a un inicio diferente al que editaste.

Mantén el razonamiento fuera de la cadena. Las instrucciones están limitadas y siempre activas; el argumento detrás de una regla es lo que permite a un agente manejar el caso que no escribiste: el problema general en por qué RAG no es memoria.

Codex es inusualmente explícito sobre cómo encuentra las instrucciones, lo que hace que este sea un problema solucionable en lugar de uno misterioso. Lee como máximo un archivo por directorio, y AGENTS.override.md prevalece sobre AGENTS.md. Va desde la raíz del proyecto hasta tu directorio de trabajo y se detiene allí. Concatena empezando por la raíz y deja de agregar una vez que el tamaño combinado alcanza project_doc_max_bytes, 32 KiB por defecto. Ignora los nombres de archivo que no están en la lista de descubrimiento, ignora los archivos vacíos y compila toda la cadena una vez por ejecución.

Seis mecanismos, todos silenciosos, y cada uno de ellos visible en unos diez segundos pidiéndole a Codex que resuma las instrucciones que cargó. Hazlo desde la raíz y desde el directorio en el que trabajas realmente, unifica las invalidaciones que debían ser temporales, agrega los nombres de archivo de tus otros agentes a la lista de alternativas y divide en lugar de aumentar el tamaño cuando te acerques al límite.

Luego, coloca las restricciones, los incidentes y los enfoques rechazados en una capa que puedas consultar en lugar de una que envíes en el primer turno, de modo que la cadena de instrucciones se mantenga lo suficientemente pequeña como para cargarse por completo, y el razonamiento siga estando allí cuando sea necesario.