Codex: darle las normas del proyecto una vez (AGENTS.md)

AGENTS.md es un fichero de texto que pones en la carpeta de tu proyecto y donde escribes cómo tiene que trabajar Codex ahí dentro: cómo se compila, cómo se prueban las cosas, qué estilo seguir y qué no tocar. Codex lo lee solo al abrir el proyecto, así que no tienes que repetírselo en cada mensaje.

Un repositorio es la carpeta de tu proyecto; AGENTS.md se queda dentro y viaja con él. El comando /init te lo crea: Codex mira el proyecto, te propone un borrador y tú lo editas a tu gusto.

Si quieres normas que valgan en todos tus proyectos, esas van en ~/.codex/AGENTS.md (tu carpeta personal, la misma para todo).

Para que no tengas que explicarle lo de siempre cada vez:

• Deja de preguntarte cómo se compila o se prueban las cosas: se lo has escrito una vez y ya lo sabe.
• Mantienes un estilo: nombres, formato, idioma, todo lo que quieras que respete.
• Evitas sustos: si le dices qué carpetas no debe tocar, se lo piensa.
• Ahorras tiempo y cupo: menos idas y venidas para ponerle en contexto.

Sirve para el proyecto concreto (el AGENTS.md de la carpeta) y, si quieres, para todos a la vez (el de tu carpeta personal).

• Abre Codex en la carpeta de tu proyecto (el repositorio).
• Dentro de la sesión, escribe el comando y pulsa Intro:

/init

Codex mira el proyecto y crea un borrador de AGENTS.md.

• Edítalo sin miedo. Deja solo lo que de verdad hace falta: cómo se compila, cómo se prueba y el estilo. Por ejemplo:

Compilar: npm run build
Probar: npm test
Estilo: variables en inglés, comentarios en español
No tocar: la carpeta /datos

• (Opcional) Tus normas de siempre: crea ~/.codex/AGENTS.md con lo que quieras que se aplique en todos tus proyectos (por ejemplo, que siempre te conteste en español de España).
• Vuelve a abrir Codex en el proyecto para que lo lea ya con lo que has escrito y comprueba que lo tiene en cuenta.

Antes de tocar nada, ten claro esto:

• Un fichero largo y vago empeora el resultado. Corto y concreto: mejor tres líneas útiles que treinta de relleno. El límite por defecto es 32 KiB.
• Hace falta Codex. Sí entra en el plan gratuito de ChatGPT, con un cupo reducido (un tope de uso): si te quedas sin él, tendrás que esperar o cambiar de plan.
• Se lee, no se ejecuta: son instrucciones para él, no un programa que corra solo. Si escribes algo falso o confuso, trabajará confundido.
• Comprobado el 05/10/2026.

1. El comando /init no crea el fichero. Asegúrate de estar dentro de la carpeta del proyecto y de que Codex la ve. Si aun así no lo crea, hazlo a mano: abre un editor, escribe tus normas, guárdalo como AGENTS.md en la raíz del proyecto y ya está.

2. No le hace caso a lo que he escrito. Suele ser el sitio o el tamaño. Revisa que el fichero se llama AGENTS.md (todo en mayúsculas) y que está en la carpeta correcta; y quítale paja: un texto corto con órdenes claras se obedece mucho mejor que un párrafo largo.

3. Me sale un error de que el fichero es demasiado grande. Has pasado el límite de 32 KiB. Borra lo que ya no uses y deja solo lo imprescindible. Si necesitas mucho detalle, en vez de un solo fichero enorme pon varios AGENTS.md por subcarpeta, cada uno con lo de esa parte.