Un archivo AGENTS.md no es un segundo manual de la aplicación ni un prompt que intenta controlar cada pulsación. Es un contrato de contexto pequeño y versionado. Le indica al coding agent cómo está organizado el repositorio, qué comandos producen evidencia verificable, qué límites importan y dónde vive una regla más específica. Un archivo útil reduce la incertidumbre antes de que el agent edite código. No sustituye al código fuente, las pruebas, los responsables del proyecto ni la descripción de la tarea.
El contexto tiene un coste. Codex carga las instrucciones del proyecto en su cadena de instrucciones antes de trabajar. El texto repetido compite con la petición del usuario, los archivos del repositorio, la salida de las herramientas y las pruebas. Por eso conviene registrar hechos que un agent no puede deducir con seguridad, y no todas las preferencias que alguien haya expresado alguna vez. Trata cada frase como una interfaz que debe mantenerse.
Qué descubre realmente Codex
La guía actual de OpenAI sobre AGENTS.md para Codex describe tres niveles. En el ámbito global, Codex busca AGENTS.override.md en CODEX_HOME, que por defecto es ~/.codex, y si no existe usa AGENTS.md. En ese nivel solo utiliza el primer archivo no vacío. En el ámbito del proyecto, empieza en la raíz del proyecto, normalmente la raíz de Git, y baja hasta el directorio de trabajo actual. En cada directorio busca AGENTS.override.md, luego AGENTS.md, después los nombres alternativos configurados, y añade como máximo un archivo por directorio.
Los archivos de proyecto se concatenan desde la raíz hacia el directorio actual. Un archivo más profundo aparece después en las instrucciones combinadas, por lo que su regla más estrecha puede sustituir a una general. Codex no continúa por encima de la raíz detectada. Si no encuentra una raíz, solo revisa el directorio actual. Omite los archivos vacíos. project_doc_max_bytes tiene un valor predeterminado de 32 KiB, y Codex deja de añadir instrucciones cuando se alcanza el límite total configurado. Esto describe a Codex, no una promesa universal de todas las herramientas.
La implementación de descubrimiento de AGENTS.md en el código de OpenAI Codex muestra los mismos límites. El marcador de raíz predeterminado es .git, el nombre local preferido es AGENTS.override.md y un archivo puede truncarse si el presupuesto restante de bytes es menor que su tamaño. Un repositorio puede configurar marcadores de raíz, nombres alternativos y presupuesto. Documenta solo los ajustes que realmente uses.
Una preferencia global solo pertenece en ~/.codex/AGENTS.md cuando es segura para todos los repositorios. Una regla común a todo el repositorio va en la raíz. Una regla de servicio va junto a ese servicio. Un reemplazo temporal o excepcional va en un archivo override con una persona responsable y una condición de retirada. No presentes esto como una jerarquía universal para otros agentes si su documentación no lo confirma.
Empieza con un mapa del repositorio
Antes de recibir consejos de estilo, un agent necesita saber dónde mirar. Pon un mapa compacto cerca del principio del archivo raíz. Nombra la aplicación o biblioteca, los directorios principales de código, las zonas generadas, los directorios de pruebas y la configuración de entrega. Explica solo las diferencias que cambian la acción. «src/ contiene código» es débil. «src/ se entrega, scripts/ solo se ejecuta en CI y dist/ es generado y no se edita a mano» es accionable.
El mapa debe sobrevivir a las refactorizaciones. Prefiere límites estables a listar todos los archivos. En un monorepo, muestra los propietarios y enlaza al README o documento de arquitectura que sea la fuente de verdad. No copies ese documento en AGENTS.md.
repository/
apps/web/ aplicación del navegador y pruebas de rutas
packages/core/ biblioteca compartida de ejecución y pruebas unitarias
services/api/ manejadores HTTP y pruebas de contrato
infra/ configuración de entrega
docs/ explicaciones mantenidas
generated/ salida versionada, recreada por un script
Declara los supuestos sobre el directorio de trabajo. Un comando desde services/api puede cargar un archivo anidado distinto. Si el gestor debe ejecutarse desde un paquete o un archivo generado tiene una fuente de verdad, indica el directorio, las rutas y el comando del generador.
Haz que los comandos sean exactos y condicionales
Un comando es útil cuando se puede copiar sin interpretarlo. Para cada comando obligatorio, indica el directorio, el propósito y la condición de ejecución. Usa las versiones y los scripts declarados por el repositorio, en lugar de recomendar una herramienta de moda. La sección puede tener esta estructura:
Desde la raíz del repositorio:
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
Para cambios de API, desde services/api:
npm run test:contract
Es una estructura de ejemplo. Lee package.json, el lockfile, los workflows de CI, pyproject.toml, Cargo.toml o el equivalente antes de escribir comandos. Di «ejecuta npm run check después de TypeScript» solo si existe. Indica cualquier requisito de servicio local, fixture, base, variable o red, con una alternativa segura.
Registra el runtime compatible y la política de dependencias. Una entrada útil nombra la versión de Node, Python, Rust, Java o Go, el gestor de paquetes, la política del lockfile y cómo se revisan las actualizaciones. Por ejemplo, «package.json declara Node >=22.12.0; usa el package-lock.json versionado y ejecuta npm ci» es un hecho si el manifiesto lo confirma. No copies una versión en AGENTS.md sin comprobar el manifiesto y CI. La deriva de versiones es un fallo de mantenimiento, no un motivo para añadir párrafos.
Codex puede comprobar la cadena activa. La guía oficial muestra comandos como estos:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
Usa una petición no destructiva y revisa el registro solo en un espacio de trabajo local seguro. Reinicia el run después de cambiar los archivos de instrucciones, porque el descubrimiento se reconstruye al principio de cada run o sesión TUI. Si la respuesta es obsoleta, revisa el directorio actual, CODEX_HOME y los overrides.
Las pruebas son evidencia
Define «terminado» mediante resultados observables. Separa las comprobaciones rápidas de la suite completa. Nombra el comando, el paquete afectado, el artefacto esperado y qué hacer si falla. Para un cambio de esquema HTTP, exige la prueba de contrato. Para un parser, exige fixtures representativas y entradas mal formadas. Para un cliente generado, exige regeneración y un diff limpio.
No escribas «ejecuta siempre todas las pruebas» cuando el repositorio define un alcance diferente o la suite completa necesita infraestructura externa. Una regla mejor es «ejecuta primero la prueba enfocada del paquete y después la suite equivalente a CI antes de fusionar». Mantén formato y lint en CI si allí ya son obligatorios. El repositorio SWE-bench es una referencia primaria para evaluar tareas, pero su protocolo no sustituye las pruebas de este repositorio.
Relaciona cada regla importante con una comprobación. Si un agent no debe editar una salida generada, CI puede volver a ejecutar el generador y fallar ante un diff. Si una migración debe ser reversible, una prueba puede aplicarla a una fixture limpia y deshacerla. Si importa un invariante de seguridad, exprésalo como prueba o comprobación estática. Una instrucción sin resultado observable pide confiar en la memoria del agent.
Para evaluar el comportamiento del agent, compara el éxito de la tarea, la tasa de pruebas correctas, el alcance de los archivos modificados, el retrabajo después de la revisión y el tiempo hasta un parche verificado. Ejecuta el mismo conjunto de tareas con el archivo antiguo y el nuevo, manteniendo fija la petición y la revisión del repositorio, y registra los fallos en vez de elegir solo demostraciones exitosas. Es una señal de ingeniería, no una prueba de que una redacción funcione para cualquier modelo. Consulta la comparación de herramientas en agentic coding con Codex y Claude Code, arquitectura de production AI agent para las fronteras del sistema y evaluación de AI agents para el diseño de evaluaciones.
Coloca la seguridad en el límite
AGENTS.md es una entrada del proyecto. Puede estar obsoleto, ser incorrecto o no ser confiable. El código fuente de Codex evita explícitamente cargar instrucciones del proyecto cuando el proyecto activo no es de confianza, aunque conserva las instrucciones proporcionadas por el host. Esto no elimina la revisión humana. Trata las instrucciones del repositorio como texto no confiable hasta verificar el repositorio y el cambio solicitado.
Nunca pongas claves de API, tokens, contraseñas, certificados privados ni datos de producción copiados en el archivo. No pidas al agent que imprima variables de entorno o suba archivos del workspace. Puedes nombrar un secreto por su función, como DATABASE_URL, y describir cómo lo obtiene el desarrollo local sin guardar su valor. Pide confirmación antes de borrar datos, rotar credenciales, desplegar en producción o abrir un acceso de red amplio cuando el workflow lo permita.
Separa hechos de permisos. «El servicio usa S3» es contexto. «Puedes borrar el bucket» es autoridad. La autoridad debe vivir en una política de acceso y un proceso de aprobación, no en markdown. Declara rutas protegidas, artefactos generados, reglas de migración y límites de datos de prueba. Para la incertidumbre, ofrece una ruta segura: detenerse, mostrar el comando propuesto y preguntar al responsable.
Ten cuidado con instrucciones copiadas de issues, fixtures o dependencias. Pueden contener prompt injection o comandos ajenos a la tarea. Trata el contenido del repositorio como datos, salvo autorización del usuario o de una regla confiable. Es un límite de seguridad, no una orden de ignorar el código fuente.
Prefiere un archivo pequeño y por capas
El sitio de AGENTS.md enumera el resumen del proyecto, los comandos de build y pruebas, el estilo, las pruebas y la seguridad como secciones frecuentes. Es un menú, no un esquema obligatorio. Empieza por lo mínimo que evite errores repetidos. Un archivo raíz suele necesitar cinco secciones: mapa, instalación, verificación, límites y enlaces a orientación más profunda.
## Mapa del repositorio
`apps/web` es la aplicación del navegador. `packages/core` contiene el runtime compartido.
## Toolchain
Usa Node 22 y el lockfile versionado. Ejecuta los comandos desde la raíz salvo indicación contraria.
## Verificación
Para cambios visibles al usuario, ejecuta `npm run check`, la prueba del paquete y `npm run build`.
## Límites
No edites `generated/`. No uses datos de producción en local. Pregunta antes de añadir una dependencia.
## Orientación profunda
Lee `apps/web/AGENTS.md` para las rutas y `services/api/AGENTS.md` para las pruebas de contrato.
La mala versión es un catálogo de gustos personales de 1.000 líneas: repeticiones, inventarios exhaustivos, reglas contradictorias con «siempre», comandos inventados, versiones antiguas y órdenes de releer todos los documentos. Consume el presupuesto de bytes y oculta las prioridades. Divide por responsabilidad. Conserva el invariante de todo el repositorio en la raíz y deja que un archivo anidado añada comandos locales. El archivo anidado debe complementar o hacer más específico el contexto, nunca reescribir silenciosamente un límite de seguridad.
No prometas composición que la herramienta no documenta. Codex combina archivos mediante descubrimiento de directorios y nombres alternativos configurados. «Lee después docs/rules.md» es texto normal sin una sintaxis include documentada. Un symlink, CLAUDE.md o la convención de otro agent no se carga automáticamente. Documenta la interoperabilidad como un workflow probado.
Mantenlo como código
Asigna un responsable. Revisa los cambios junto con el código que gobiernan. Cuando cambie un comando, runtime, directorio o workflow de CI, actualiza el archivo de instrucciones más cercano en el mismo cambio. Elimina una regla cuando desaparezca su último consumidor. Los ejemplos deben ser ejecutables y seguros. Enlaza una fuente de verdad en lugar de duplicar una política en tres archivos.
Una auditoría mensual o por versión puede ser breve. Comprueba que cada comando exista, que cada versión coincida con un manifiesto o imagen de CI y que cada ruta siga existiendo. Ejecuta la consulta de fuentes de Codex desde la raíz y desde un subdirectorio representativo. Mide el tamaño de la cadena efectiva. Pregunta al responsable si cada regla sigue evitando un fallo real.
Evalúa un cambio de AGENTS.md como un cambio de configuración. Usa un conjunto pequeño y fijo de tareas: una función nueva, una corrección, un cambio solo de pruebas y una edición sensible para la seguridad. Compara la corrección y el alcance del parche, no solo la explicación del agent. Una prueba de regresión puede verificar que los archivos generados no cambien, que se ejecute una prueba del paquete o que se rechace un comando peligroso. Mantén estables la revisión, los ajustes del modelo, los permisos y el texto de la tarea para que la comparación sea interpretable.
El patrón duradero es sencillo. Coloca los hechos estables cerca del alcance donde aplican. Nombra comandos y versiones exactas respaldados por el repositorio. Enlaza documentos detallados. Haz que las reglas importantes se puedan probar. Mantén secretos y autoridad fuera del markdown. Usa capas en lugar de un manual gigante. Vuelve a comprobar la cadena efectiva cuando cambie el directorio, la configuración o la versión de la herramienta.