Manual del proyecto AGENTS.md: Sella las reglas en el flujo de trabajo de Codex

📚 Navegación de la serie: El artículo anterior 10 · Codex Cloud en la nube explicó a fondo cómo "dejar que Codex se ejecute en la nube y recoger el PR más tarde". Este artículo vuelve a local para hablar de un archivo que todo proyecto debería tener, pero que el noventa por ciento de los novatos escribe mal: AGENTS.md, el manual del proyecto que Codex debe leer siempre antes de comenzar a trabajar.

Permítanme contarles una tontería que hice cuando recién empecé a usar Codex.

El año pasado le entregué un proyecto Node a Codex y, para empezar bien, escribí un archivo AGENTS.md en el directorio raíz. En la primera línea puse claramente: "Este proyecto usa pnpm, prohíbase npm". El resultado fue que de inmediato me soltó un npm install. En el acto pensé que no lo había leído, así que, enfadado, copié esa regla tres veces, la puse en negrita y le añadí signos de exclamación. Seguía sin hacerme caso.

Después de dar muchas vueltas, descubrí el problema: sí lo había leído, pero esa regla estaba enterrada en la línea 140. Antes de eso, yo había metido la presentación de la empresa, la hoja de ruta del producto y todo el historial de las decisiones tecnológicas, llenando más de cien líneas de texto. Cuando Codex llegó a la frase de "prohibir npm", su atención ya se había diluido por completo con el montón de palabrería anterior. El problema nunca fue que no obedeciera, sino que yo había metido la única regla útil dentro de una montaña de información inútil.

AGENTS.md para Codex es lo mismo que CLAUDE.md para Claude Code, el mismo concepto pero con un nombre de archivo diferente. Sin embargo, en Codex el mecanismo de descubrimiento, las reglas de sobrescritura y el límite de bytes tienen sus propias particularidades, con algunas trampas fáciles de evitar. En este artículo explicaremos todo esto detalladamente, junto con "qué escribir y qué no escribir".

Al terminar este artículo, obtendrás:

• La cadena completa de descubrimiento de AGENTS.md por parte de Codex (nivel global → nivel de proyecto → orden de combinación) y cuál tiene prioridad en caso de conflicto.
• El mecanismo de "sello temporal" AGENTS.override.md, que no existe en Claude Code, y cuándo utilizarlo.
• Una lista de "qué escribir vs qué no escribir" para evitar caer en el error de la "línea 140 que nadie escucha" que cometí en su día.
• El uso oficial de dos configuraciones: cambiar el nombre del archivo (project_doc_fallback_filenames) y ajustar el límite de bytes (project_doc_max_bytes).
• Un flujo práctico que puedes seguir paso a paso para verificar si Codex ha leído realmente el archivo.

Nota: Este artículo se enfoca únicamente en cómo escribir bien y cómo se carga el archivo AGENTS.md. El mecanismo de "Memoria (Memories)", con el que es fácil confundirse (que es una capa de recuperación automática local y viene desactivada por defecto), ya se mencionó en [02 Conceptos clave]. Recuerda una frase: las reglas del equipo que realmente deben aplicarse en cada ocasión se escriben en AGENTS.md, no confíes en la memoria.

---

01 Entender primero: AGENTS.md es la "lista de entrega" de Codex antes de empezar a trabajar

Primero la conclusión: AGENTS.md es una instrucción persistente que le escribes a Codex, la cual lee antes de iniciar y ponerse a trabajar cada vez, cargándola en su mente como el contexto del proyecto.

¿Por qué es necesario? Porque Codex comienza desde cero en cada ejecución (cada ejecución (per run): término oficial, que en la TUI suele corresponder a cada sesión iniciada). Lo que le indicaste pacientemente la vez anterior como "usa pnpm, no toques legacy/, ejecuta las pruebas así", esta vez no lo recordará en absoluto. Sin un archivo AGENTS.md, tendrías que volver a explicárselo cada vez.

Analogía: La lista de tareas para el cambio de turno. En una fábrica con tres turnos, el turno saliente escribe claramente en una pizarra antes de retirarse: esta máquina tiene un fallo, no la enciendas a la fuerza; este lote de material debe pasar primero por control de calidad; quién es el contacto de emergencia. El siguiente turno toma el relevo y trabaja siguiendo la pizarra, sin necesidad de llamar al turno anterior para que se lo explique de viva voz. AGENTS.md es esa pizarra de entrega para Codex, y además es la que lee de reojo cada vez antes de tomar el relevo.

(Nota que aquí no he usado "manual de inducción": esa analogía ya se utilizó en [02]. La lista de entrega es más precisa porque enfatiza que "se vuelve a leer en cada ejecución", y no "se lee una vez el día de ingreso".)

¿Cuándo deberías añadir contenido en él? Aquí tienes algunas señales muy claras:

• Cuando Codex comete el mismo error por segunda vez: esto debe consolidarse allí, no lo corrijas de forma verbal por tercera vez.
• 当你这轮又敲了一遍上轮敲过的那句更正
• Cuando vuelves a escribir en esta sesión la misma corrección que escribiste en la anterior.
• 代码审查时发现，它本该早就知道这个代码库的某个约定
• Cuando descubres en la revisión de código que debería haber conocido cierta convención de este repositorio desde el principio.
• 新队友（或者三个月后的你自己）需要同样的背景才能快速上手
• Cuando un nuevo compañero (o tú mismo dentro de tres meses) necesite el mismo contexto para ponerse al día rápidamente.

Mi uso favorito, ya mencionado en [02] y que vuelvo a destacar aquí: úsalo como un bucle de retroalimentación. Si Codex hace una suposición incorrecta sobre tu código, no te limites a corregirlo en la conversación (eso es de una sola vez y lo olvidará en la siguiente sesión); ordénale directamente que escriba esa corrección en AGENTS.md. Estuve ajustando un proyecto Python durante dos semanas, y ese archivo AGENTS.md creció de la nada hasta tener unas veinte líneas, llenas de fallos que cometió, que detecté y que él mismo registró; ahora las nuevas sesiones casi no repiten los mismos errores.

💡 Resumen en una frase: AGENTS.md es la lista de entrega obligatoria que Codex lee en cada ejecución: registra una regla cada vez que cometa un error y funcionará cada vez mejor; es el mismo concepto que CLAUDE.md de Claude Code, solo cambia el nombre.

---

02 Cadena de descubrimiento: cómo encuentra Codex estos archivos

No hay un solo archivo AGENTS.md, sino que puede colocarse en varios lugares, con un alcance que va de mayor a menor. Cuando Codex se inicia, los encadena en una "cadena de instrucciones". En esta sección desglosaremos esta cadena; esta es la mayor diferencia con Claude Code, así que presta atención.

Según la documentación oficial, Codex construye la cadena de instrucciones en dos pasos (se construye una vez por ejecución, lo que en la TUI suele ser cada vez que se inicia una sesión):

Primer paso: Nivel global (Global scope). En el directorio principal de tu Codex (por defecto ~/.codex, a menos que configures la variable de entorno CODEX_HOME), Codex busca primero si existe AGENTS.override.md, y si es así lo usa; si no, lee AGENTS.md. En este nivel solo se toma el primer archivo que no esté vacío, no leerá ambos.

Segundo paso: Nivel de proyecto (Project scope). Comenzando desde el directorio raíz del proyecto (normalmente la raíz de Git), avanza hacia abajo hasta llegar al directorio en el que te encuentras actualmente. En cada directorio del camino, Codex elige en este orden: primero busca AGENTS.override.md, luego AGENTS.md y finalmente los nombres de archivo alternativos que hayas definido en project_doc_fallback_filenames. Cada directorio acepta como máximo un archivo.

Tercer paso: Combinación (Merge order). Codex concatena en orden los archivos encontrados desde la raíz hasta la hoja, separados por líneas en blanco. Los archivos que estén más cerca de tu directorio actual se colocan al final de la concatenación, por lo que tienen mayor prioridad y sobrescriben a los anteriores.

Para que no sea confuso, aquí tienes un diagrama:

Este diagrama recorre toda la cadena: primero elige uno de dos en el nivel global, luego elige uno en cada nivel del proyecto y finalmente los concatena desde la raíz hasta la hoja: cuanto más cerca esté de ti, más tarde se aplica y mayor es su efecto.

Aquí hay dos puntos clave, ambos de la documentación oficial, que debes recordar:

Primero: Es "concatenación" y no "sobrescritura completa". El archivo global y el del proyecto tienen efecto al mismo tiempo, no ocurre que al escribir uno a nivel de proyecto el de nivel global deje de funcionar. Todos entran al contexto, el posterior no eliminará por completo al anterior, sino que los elementos en conflicto se regirán por el que aparezca más adelante (el más cercano).

Segundo: El más cercano gana. Por ejemplo, si el AGENTS.md global dice "usar comillas simples para cadenas" y el AGENTS.md en la raíz del proyecto dice "usar comillas dobles", la raíz del proyecto está más cerca del directorio actual y se coloca más adelante, por lo que ganan las comillas dobles. En pocas palabras: las reglas del proyecto pueden sobrescribir tus preferencias personales, lo cual es justo lo que se busca en el trabajo en equipo.

Analogía: Los tres niveles de zoom en un mapa de navegación. El mapa nacional te da la dirección general (nivel global), el mapa de la ciudad te da las calles urbanas (raíz del proyecto) y el letrero en la entrada del vecindario te indica cómo dar los últimos pasos (subdirectorio). Los tres niveles son válidos simultáneamente y la información no se borra mutuamente; pero si el letrero de la entrada no coincide con el mapa grande, se toma como referencia el letrero más cercano en el sitio, ya que es el más preciso para tu paso actual. La cadena de AGENTS.md sigue exactamente esta lógica de "cuanto más cerca de la ubicación actual, más específico y mayor prioridad en caso de conflicto".

Esta imagen apila los tres niveles de arriba a abajo: el nivel global (~/.codex/), la raíz del repositorio y el subdirectorio se concatenan en orden, teniendo efecto simultáneamente; el eje de "prioridad" a la derecha te recuerda: cuanto más cerca esté ese nivel de tu directorio actual, más al final aparecerá en la concatenación y más prioritario será en caso de conflicto, lo que se conoce como "sobrescritura por cercanía".

💡 Resumen en una frase: Cadena de descubrimiento de Codex = nivel global (~/.codex, override prioritario, toma un solo archivo no vacío) → nivel de proyecto (desde la raíz de Git hasta el directorio actual paso a paso, eligiendo uno por directorio) → concatenación de la raíz a la hoja, donde el más cercano tiene mayor prioridad; es concatenación, no sobrescritura.

---

03 AGENTS.override.md: el "sello temporal" que no existe en Claude Code

En la sección anterior apareció repetidamente un nombre: AGENTS.override.md. Esta herramienta no tiene equivalente en Claude Code; es un diseño exclusivo de Codex y lo explicaremos por separado.

Veamos qué problema resuelve. Imagina que en tu ~/.codex/AGENTS.md escribiste un conjunto de convenciones globales compartidas por el equipo, lo cual funciona bien en el día a día. Pero hoy tienes una tarea temporal y necesitas reemplazar por completo estas directrices globales, pero sin borrar el archivo original (si lo borras, tendrías que volver a escribirlo después). ¿Qué haces?

Analogía: Colocar una nota adhesiva de "válido con esto" sobre un documento. El contrato original sigue en el cajón, no lo has roto; simplemente pegaste temporalmente una nota adhesiva que dice "este mes se aplica este nuevo término". Cuando termine el asunto, retiras la nota y el contrato original vuelve a tener efecto automáticamente. AGENTS.override.md es esa nota adhesiva: mientras exista, se omitirá por completo el AGENTS.md del mismo nivel; si lo eliminas, el archivo original regresará de inmediato.

Dos escenarios típicos descritos oficialmente:

• Sobrescritura temporal global: escribes directrices globales temporales en ~/.codex/AGENTS.override.md, dejando intacto el ~/.codex/AGENTS.md original. Al terminar la tarea eliminas el override y se restaura el archivo compartido.
• Reglas especiales en subdirectorios: un equipo en un subdirectorio específico necesita reglas totalmente diferentes a las del exterior. Por ejemplo, en el directorio del servicio de pagos services/payments/, se coloca un archivo AGENTS.override.md:

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`

Al colocar este override, se omitirá el archivo AGENTS.md del mismo nivel en este directorio (si lo hubiera), y Codex reconocerá el contenido del override al trabajar en este directorio.

Aquí hay que tener muy claro un punto con el que los principiantes suelen confundirse: el override no es lo mismo que "sobrescribir toda la cadena":

Alcance	Función de AGENTS.override.md
Dentro del mismo directorio	Si existe → se omite el AGENTS.md (y nombres alternativos) del mismo nivel, este nivel solo reconoce el override
Entre directorios (toda la cadena)	No elimina las instrucciones de otros directorios; las instrucciones superiores se concatenan con normalidad, pero en caso de conflicto se sobrescriben por la más cercana

En pocas palabras: el override significa "usa mi contenido en este nivel, no el AGENTS.md de al lado", no significa "todo el sistema solo me escucha a mí". La concatenación de toda la cadena y las reglas de prioridad por cercanía siguen funcionando igual. La primera vez que lo usé lo entendí mal, pensando que colocar un override en un subdirectorio bloquearía el archivo global, pero la convención global se aplicó de igual manera; más tarde revisé la documentación oficial y comprendí que solo elige uno de dos dentro de su propia casilla.

También hay un uso excelente para depurar problemas: si Codex te muestra una instrucción extraña que no has escrito en absoluto, lo primero que debes hacer es buscar si hay algún AGENTS.override.md oculto subiendo por el árbol de directorios, incluido ~/.codex. Cámbiale el nombre o bórralo, y volverás al AGENTS.md convencional. La lista de depuración oficial incluye específicamente este paso.

💡 Resumen en una frase: AGENTS.override.md es el "sello temporal" exclusivo de Codex: en el nivel donde se encuentra, se omite el AGENTS.md del mismo nivel; no afecta a la concatenación de instrucciones de otros directorios; es la forma más fácil de cambiar temporalmente las directrices sin borrar el archivo original; si ves instrucciones extrañas, ve primero a buscar si hay un override oculto.

---

04 Qué escribir vs qué no escribir

Esta sección es el núcleo de todo el artículo y también la cura para mi error de la "línea 140 que nadie escucha" mencionado al principio. Si AGENTS.md está mal escrito, el noventa por ciento de las veces se debe a que "lo que se debe escribir no se aclara, y lo que no se debe escribir se llena a montones".

Primero, lo que se debe escribir: en una frase, escribe "los hechos que Codex debe mantener presentes en cada ejecución". Convertido en una lista, se reduce a estas cinco categorías:

Categoría	Qué escribir concretamente	Ejemplo
Descripción del proyecto	Explicar en una frase qué es exactamente	"Backend de gestión de pedidos basado en FastAPI"
Stack tecnológico	Lenguajes, frameworks, bases de datos, herramientas clave	"Python 3.11 / PostgreSQL / pytest"
Comandos comunes	Cómo ejecutar pruebas, compilación, comprobación / lint	npm run lint , make test-payments
Convenciones de código	Estilo, nomenclatura, patrones de escritura obligatorios	"Las funciones deben tener anotaciones de tipo", "Usar comillas dobles para cadenas"
Cosas explícitas a "no hacer"	Zonas de peligro, archivos prohibidos de modificar, operaciones que requieren confirmación previa	"Prohibido modificar archivos existentes en migrations/", "Confirmar antes de añadir nuevas dependencias de producción"

Entre ellos, los comandos comunes son los que más se consultan: Codex acudirá aquí a buscar los comandos antes de ejecutar pruebas o crear un PR, para evitar adivinar o equivocarse. La primera regla en el archivo AGENTS.md de ejemplo oficial es un comando: "Ejecutar npm run lint antes de crear un PR". La lista de prohibiciones actúa como una barrera para evitar que "sea inteligente pero cause problemas": qué directorios contienen código antiguo que solo se lee pero no se modifica, o qué operaciones requieren preguntarte antes de realizar el cambio.

再说不该写的，这才是新手翻车重灾区，也是我亲身踩过的坑： Por otro lado, lo que no se debe escribir, que es donde los novatos suelen fallar y la trampa en la que caí personalmente:

• ❌ Contexto demasiado extenso: presentación de la empresa, visión del producto, origen histórico de las decisiones tecnológicas; Codex no lo necesita para escribir código, consume contexto y diluye las reglas útiles (ver mis 140 líneas del inicio).
• ❌ Información obsoleta: cambiar de gestor de paquetes pero no actualizar AGENTS.md, dejando la indicación de npm y terminando por confundirlo.
• ❌ Cosas que se pueden deducir leyendo el código: no repitas qué hace cada archivo en la estructura de directorios, ni vuelvas a copiar las convenciones de estilo de código ya definidas en ESLint o Prettier. Codex lee el código por sí mismo, repetirlo solo ocupa espacio inútilmente.

La documentación oficial establece un límite estricto para "no escribir demasiado", pero su línea roja es diferente a la convencional: Claude Code se rige por "número de líneas" (se sugieren menos de 200), mientras que Codex se rige por "bytes":

Codex omite archivos vacíos y, una vez que el tamaño total combinado alcanza el límite project_doc_max_bytes (por defecto 32 KiB), deja de añadir archivos.

Presta atención a que esto tiene dos implicaciones: primero, el límite por defecto es de 32 KiB, y si lo supera se truncará (o incluso se excluirá el archivo completo); segundo, este límite calcula la suma combinada, sumando el nivel global, el del proyecto y los subdirectorios. Por lo tanto, si escribes un archivo demasiado pesado, podrías dejar fuera de la ventana a otro archivo posterior más importante. La recomendación oficial: si chocas con el límite, aumenta project_doc_max_bytes o divide las instrucciones colocándolas de manera dispersa en varios subdirectorios (lo cual coincide con lo explicado en [04] sobre "reducir el tamaño de AGENTS.md + estructurar por subdirectorios" para ahorrar tokens).

Existe un truco práctico muy útil: antes de escribir cualquier regla, me pregunto a mí mismo: "¿Codex puede deducir esto por sí mismo leyendo el código? Si es así, lo elimino". Gracias a este filtro, he logrado reducir el archivo AGENTS.md de un proyecto heredado de más de cien líneas a unas pocas decenas, conservando únicamente las restricciones estrictas que no puede deducir; tras este recorte, la cantidad de veces que usó un gestor de paquetes equivocado disminuyó notablemente.

💡 Resumen en una frase: Escribe "los hechos que se deben recordar en cada ejecución" (descripción, stack tecnológico, comandos, convenciones, prohibiciones), elimina todo lo que Codex pueda deducir por sí mismo leyendo el código; la línea roja son los bytes (por defecto 32 KiB combinados en project_doc_max_bytes), y si se supera, divide las reglas o aumenta el límite.

---

05 Dos configuraciones: cambiar el nombre de archivo y ajustar el límite de bytes

Para la mayoría de los usuarios, el archivo AGENTS.md por defecto es suficiente. Pero hay dos casos en los que debes modificar la configuración: en esta sección explicaremos dos opciones que se configuran en ~/.codex/config.toml (el archivo de configuración a nivel de usuario de Codex).

Configuración uno: Hacer que Codex reconozca tus nombres de archivo existentes

Imagina que en tu repositorio ya tienes un archivo TEAM_GUIDE.md que todo el equipo ha usado siempre como documento de referencia. No quieres crear otro archivo AGENTS.md para repetir lo mismo, y deseas que Codex lea directamente TEAM_GUIDE.md como archivo de instrucciones. En este caso, utiliza project_doc_fallback_filenames (nombres de archivo alternativos):

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

Cualquier nombre de archivo que no esté en esta lista será ignorado por completo por Codex en la fase de descubrimiento. Si quieres que un archivo personalizado se trate como el manual del proyecto, debes añadir obligatoriamente su nombre en project_doc_fallback_filenames; no esperes que Codex lo "adivine".

Configuración dos: Si el contenido combinado se trunca, aumenta el límite

En la sección anterior mencionamos que el límite por defecto es de 32 KiB. Si tus instrucciones realmente superan este límite y por el momento no quieres dividir los archivos, puedes aumentar project_doc_max_bytes:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Esto eleva el límite a 64 KiB, permitiendo albergar más directrices combinadas antes de tocar techo. Sin embargo, debo advertirte: esto es una solución temporal. Si el contenido realmente es útil, aumenta el límite; pero en la mayoría de los casos, chocar con los 32 KiB es una señal que te avisa que "debes simplificar" o "debes dividir por subdirectorios", y no de que "debes elevar el límite". Mi preferencia personal es priorizar la división, luego la eliminación y, solo en casos extremos, aumentar el límite.

Tabla comparativa de escenarios de uso para ambas configuraciones:

Tu situación	Qué configuración modificar
Ya tienes TEAM_GUIDE.md en el repositorio y quieres usarlo directamente como manual	Añadir su nombre en project_doc_fallback_filenames
Las directrices combinadas superan los 32 KiB y se truncan	Intenta primero dividir por subdirectorios o simplificar; si es estrictamente necesario, aumenta project_doc_max_bytes
Quieres usar un perfil de configuración independiente (como un usuario automatizado)	Configurar CODEX_HOME apuntando a otro directorio (ver el flujo práctico en la siguiente sección)

⚠️ Recuerda reiniciar Codex tras modificar config.toml; estas dos configuraciones se leen al iniciar y no tendrán efecto sin reiniciar. La lista oficial de depuración destaca este punto ("¿No funciona el nombre de archivo alternativo? Confirma la ortografía y reinicia Codex").

💡 Resumen en una frase: project_doc_fallback_filenames permite que Codex reconozca tus nombres de archivos personalizados (los que no estén en la lista serán ignorados); project_doc_max_bytes eleva el límite de combinación (por defecto 32 KiB), pero si chocas con el límite, prioriza dividir o eliminar en lugar de forzar el aumento; debes reiniciar tras modificar la configuración.

---

06 Manos a la obra: configurar un AGENTS.md correcto en un proyecto de prueba y verificar su carga

Hablar sin practicar no sirve de nada. A continuación, utilizaremos un proyecto mínimo para recorrer el flujo completo de "crear archivo → escribir reglas → verificar si Codex lo ha leído realmente". Sigue los pasos y lo tendrás en pocos minutos.

Nota sobre diferencias de plataforma: los comandos de creación de proyectos mkdir / git init que se muestran a continuación se usan directamente en Mac / Linux; en Windows se recomienda ejecutarlos en Git Bash o WSL, o crear las carpetas manualmente desde el Explorador de archivos. El símbolo ~ en las rutas hace referencia al directorio principal del usuario, que en Windows equivale a C:\Users\tu_nombre_de_usuario\.

Primer paso: Crear un proyecto de prueba e inicializar git

mkdir agents-md-demo
cd agents-md-demo
git init

Resultado esperado: aparece un directorio .git dentro de la carpeta agents-md-demo. La inicialización de git sirve para que Codex identifique este lugar como la "raíz del proyecto" (por lo general escanea a partir de la raíz de Git) y también para que este archivo AGENTS.md entre al control de versiones y se comparta con el equipo.

Segundo paso: Escribir un AGENTS.md simplificado a nivel de proyecto

Utiliza tu editor favorito para crear un nuevo archivo AGENTS.md en la raíz del proyecto y pega el siguiente bloque (nota que solo tiene unas pocas líneas; así es como debe ser un buen AGENTS.md):

# agents-md-demo — 一个演示用的最小项目

只有用来演示 AGENTS.md 怎么写，没有真实业务逻辑。

## 常用命令

- `npm test` —— 运行测试

## 编程约定

- 所有函数必须有类型注解
- 字符串一律用双引号

## 注意事项

- 不要新增任何生产依赖，需要时先问我

Resultado esperado: aparece AGENTS.md en la raíz del proyecto con las secciones anteriores. Un total de unas quince líneas; recuerda esta noción de tamaño, y evita que se expanda sin control en proyectos reales.

Tercer paso: Hacer que Codex repita las instrucciones que ha leído

La documentación oficial ofrece un método de verificación muy directo: hacer que Codex resuma las instrucciones vigentes en ese momento. Ejecuta en el directorio del proyecto:

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

Resultado esperado: antes de proponer cambios, Codex mostrará las reglas que acabas de escribir (comandos, anotaciones de tipo, comillas dobles, no añadir dependencias). Si las repite, significa que este archivo AGENTS.md se ha cargado realmente en su contexto para esta ejecución.

ℹ️ El uso de --ask-for-approval never aquí es solo para evitar que se detenga a pedir aprobaciones durante la demostración y obtener una salida limpia; no significa que se recomiende usarlo así en el trabajo diario. El modo de aprobación a usar en el día a día se detalla en [02 Conceptos clave] y en las secciones relacionadas con permisos más adelante; no desactives las aprobaciones a la ligera en proyectos que no conozcas.

Cuarto paso (Avanzado): Verificar que el override en subdirectorios realmente tiene "prioridad por cercanía"

Si quieres ver con tus propios ojos cómo "el más cercano tiene mayor efecto", da un paso más. Crea un subdirectorio en el proyecto y coloca un override que modifique solo un comando:

mkdir -p services/payments

Escribe en services/payments/AGENTS.override.md:

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`

Luego, desde la perspectiva de este subdirectorio, inicia Codex y pídele que informe qué fuentes de instrucciones ha cargado:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Resultado esperado: de acuerdo con la descripción oficial, Codex los enumerará en orden: primero el archivo global (si existe en ~/.codex), luego el AGENTS.md en la raíz del repositorio y finalmente este override del servicio de pagos; además, el comando de prueba en este nivel se regirá por make test-payments del override, sobrescribiendo el comando npm test de la raíz en este subdirectorio. Este es un ejemplo en vivo de la "prioridad por cercanía".

⚠️ En caso de que descubras que Codex no sigue las directrices de AGENTS.md: ① Usa el comando anterior "Summarize the current instructions" para confirmar si las leyó; ② Ejecuta codex status para comprobar si reconoce la raíz del espacio de trabajo que tú crees; ③ Busca en el árbol de directorios hacia arriba si hay algún AGENTS.override.md oculto que sobrescriba tus reglas; ④ Asegúrate de que el archivo no esté vacío (Codex omite archivos vacíos). Estos pasos siguen el orden de la lista de depuración oficial y permiten localizar la mayoría de los problemas.

💡 Resumen en una frase: Sigue el flujo "crear archivo → escribir reglas sencillas → usar 'Summarize the current instructions' para que Codex las repita" una vez, confirmando con tus propios ojos que ha leído tu AGENTS.md; al añadir un override en un subdirectorio, podrás ver claramente cómo se sobrescribir el comando de la raíz.

---

07 Resumen

En este artículo has conocido a fondo desde el mecanismo de descubrimiento hasta la forma de redactar el manual del proyecto de Codex, AGENTS.md:

Dimensión	Conclusiones clave
Qué es	Lista de entrega obligatoria en cada ejecución, es simplemente CLAUDE.md con otro nombre
Cadena de descubrimiento	Nivel global (override prioritario, toma uno no vacío) → Nivel de proyecto (de la raíz de Git al directorio actual paso a paso, uno por directorio) → Concatenación de raíz a hoja
Quién manda	Concatenación sin sobrescritura completa, el más cercano al directorio actual se concatena más al final y tiene prioridad en caso de conflicto
override	Sello temporal exclusivo de Codex: en ese nivel se omite el AGENTS.md del mismo nivel, pero no limpia las instrucciones de otros lugares
Qué escribir	Descripción / Stack / Comandos / Convenciones / Prohibiciones, elimina todo lo que el código demuestre por sí mismo
Línea roja de tamaño	Se calcula por bytes, 32 KiB combinados por defecto (project_doc_max_bytes), prioriza dividir o eliminar si se supera
Configuraciones	project_doc_fallback_filenames para cambiar nombres, project_doc_max_bytes para ajustar límites, debes reiniciar tras modificar

Ahora deberías ser capaz de: decidir si una información debe incluirse en AGENTS.md y en qué nivel colocarla; comprender quién gana en caso de conflicto entre múltiples niveles; usar AGENTS.override.md para cambiar temporalmente las directrices sin borrar el archivo original; saber si dividir o aumentar el límite al chocar con el límite de bytes; y verificar en una sola frase con "Summarize the current instructions" si Codex lo ha leído. En resumen: puedes escribir un archivo AGENTS.md que Codex realmente escuche, en lugar de redactar 140 líneas que nadie atienda como me ocurrió a mí.

---

El siguiente artículo 12 · Comandos de barra diagonal y atajos de teclado: en este artículo ya has escrito codex ... varias veces en la terminal, pero ¿qué pasa una vez que entras a la sesión? Los comandos de barra diagonal que empiezan con / te permiten cambiar de modo al instante, limpiar el contexto y ver el estado, lo cual, combinado con algunos atajos de teclado cómodos, duplicará tu eficiencia operativa. En el próximo artículo desglosaremos esta "paleta de operaciones rápidas". Un pequeño pensamiento: en este artículo, lograr que Codex "recuerde las reglas" dependía de escribir archivos, pero si quisieras cambiar su comportamiento en el acto durante una sesión y sin tocar AGENTS.md, ¿qué crees que deberías usar?

---

Lecturas recomendadas

• Mejores prácticas: aquellas reglas realmente aplicables más allá de la "palabrería correcta"
• Técnicas avanzadas y aceleración: lo que te ralentiza no es el modelo, sino el mal contexto que le proporcionas
• Introducción a la CLI de línea de comandos