Un archivo que Codex lee antes que nada
¿Cansado de escribir las mismas instrucciones en Codex en cada prompt — "usa vistas basadas en funciones", "corre las pruebas antes de decir que terminaste"? Un solo archivo resuelve eso, de forma permanente. AGENTS.md vive en la raíz de tu proyecto, y Codex lo lee antes de hacer cualquier trabajo, en cada ejecución. Piénsalo como las notas de onboarding para un nuevo compañero de equipo que nunca las olvida.
Por qué existe
Un agente de codificación con IA no tiene memoria persistente de tu proyecto entre sesiones. Cada conversación arranca desde el mismo estado en blanco, lo que significa que cada convención que no hayas escrito se vuelve a explicar, se vuelve a corregir o se viola en silencio porque el agente adivinó mal. AGENTS.md es la respuesta de Codex: un archivo que lee deliberadamente al inicio de una ejecución, antes de tocar tu código, para que las convenciones ya estén cargadas antes de su primer paso. Es markdown plano, sin sintaxis especial, sin esquema: escríbelo a mano o genera un punto de partida con el flujo de init de Codex.
Qué va dentro
Tres secciones cubren la mayor parte de lo que importa:
AGENTS.md
Goal: <what this project is, one or two sentences>
Rules: <non-negotiable conventions the agent keeps getting wrong>
Commands: <the one command to run tests / lint / build>- Goal (Objetivo) — qué es el proyecto y para qué sirve, suficiente para que un nuevo contribuyente entienda su forma.
- Rules (Reglas) — convenciones que Codex no puede inferir con solo leer el código. "Solo vistas basadas en funciones" es un buen ejemplo: una base de código llena de ellas no le dice al agente por qué debería seguir escribiéndolas así en vez de "modernizar", ni que la alternativa ya fue rechazada.
- Commands (Comandos) — el comando exacto para correr las pruebas, el lint o el build. La línea de mayor apalancamiento: un agente que puede verificar su propio trabajo detecta sus propios errores antes de enviártelos.
Cómo lo usa Codex
Codex lee AGENTS.md antes de hacer cualquier trabajo en cada ejecución: se carga como contexto de forma automática, sin recordatorio. También se combina con archivos de directorios superiores: un archivo en la raíz del repo más uno más específico en una subcarpeta (digamos, un paquete de un monorepo con sus propias convenciones) aplican ambos, con el archivo de la subcarpeta sobrepuesto. Mantén las reglas de nivel raíz amplias, y empuja las excepciones específicas de un paquete hacia las carpetas donde de verdad son relevantes.
Cómo crear uno
- Crea
AGENTS.mden la raíz de tu proyecto (o deja que el flujo de init de Codex arme uno). - Escribe Goal, Rules, Commands en markdown plano.
- Haz commit como cualquier otro archivo del proyecto.
Empieza mínimo, agrega cuando algo se rompa
El consejo más útil aquí es también el más fácil de ignorar: no anticipes cada regla de entrada. Empieza con Goal y Commands, y una sección Rules casi vacía. La primera vez que Codex haga algo que no querías —recurre a una librería prohibida, escribe una prueba en el estilo equivocado— agrega exactamente esa regla y sigue adelante. Esto mantiene el archivo corto, lo cual importa porque cada línea cuesta presupuesto de contexto en cada ejecución, y lo mantiene anclado en cosas que de verdad han salido mal en lugar de una lista de deseos especulativa.
Dónde rinde más
- Al incorporar un repo legado y desordenado — escribe las rarezas una vez en lugar de re-explicarlas en cada prompt.
- Una convención de equipo recurrente que Codex sigue omitiendo — corregir lo mismo dos veces es la señal para agregar una línea a Rules, no para seguir corrigiéndolo en el chat.
- Monorepos — archivo raíz para las convenciones compartidas, archivos en subcarpetas para las excepciones específicas de cada paquete, ambos aplicados gracias al comportamiento de combinación.
Errores comunes
- Escribirlo una vez y no actualizarlo nunca. Actualiza el archivo en el mismo commit que el cambio de convención.
- Dejar que crezca sin límite. Cada línea cuesta contexto en cada ejecución: poda las reglas obsoletas como código muerto.
- Tratarlo como documentación en lugar de instrucciones. Escribe directivas ("usa X, nunca Y, corre Z para verificar"), no prosa de arquitectura: para eso está tu README.
Recursos
¿Construyendo una función con IA? Yeda AI diseña, audita y despliega sistemas LLM en producción.