AGENTS.md: instrucciones de proyecto que ayudan al agente
Neaptide · 6 de septiembre de 2026 · 7 min de lectura
Qué escribir en AGENTS.md, dónde lo busca Codex y cómo comprobar que aplica las reglas. Incluye ejemplo breve, archivo editable y esquema.
En este artículo
Si el agente edita una y otra vez la carpeta equivocada o propone una prueba inexistente, conviene guardar la regla. AGENTS.md es un archivo Markdown con acuerdos de trabajo del proyecto. Resulta útil cuando aporta contexto que el código no permite deducir con facilidad.
Qué información va en cada sitio
| Lugar | Contenido |
|---|---|
| README | Instalación y orientación para personas |
| AGENTS.md | Acuerdos permanentes del proyecto |
| Skill (procedimiento reutilizable) | Procedimiento de investigación o revisión |
| Mensaje de la tarea | Encargo actual y excepciones concretas |
Sustituye «escribe buen código» por una indicación verificable: dónde cambiar el contenido y qué comprobación ejecutar. Enlaza la documentación existente en vez de duplicarla.
Un ejemplo para un sitio de contenidos
Estos directorios y la orden de compilación existen en nuestro sitio. Revísalos antes de adaptarlos a otro proyecto. La descarga es un .txt; guarda tu versión como AGENTS.md en la carpeta adecuada.
# Trabajar en este proyecto
- Leer package.json y los archivos cercanos antes de editar.
- Los artículos están en content/blog/articles, no en los diccionarios de interfaz.
- Mantener el slug publicado salvo que la tarea exija cambiar la URL.
- Ejecutar npm run build tras modificar contenido.
- Para nueva lógica, ejecutar las comprobaciones pertinentes de scripts.
- Informar de las comprobaciones realizadas y las limitaciones pendientes.No añadas npm test por costumbre si el proyecto no define ese script. Ajusta la verificación al cambio: corregir una leyenda no exige automáticamente una auditoría completa.
Cómo encuentra Codex las instrucciones
Al iniciarse, Codex lee las instrucciones globales y después los archivos situados en la ruta desde la raíz del proyecto hasta el directorio de trabajo actual. En cada carpeta, busca AGENTS.override.md antes que AGENTS.md y selecciona como máximo uno de los dos. Las instrucciones más cercanas al directorio de trabajo concretan las anteriores. Otros agentes pueden cargar los archivos de otra forma; consulta su documentación.
Añade un AGENTS.md en una subcarpeta cuando esa parte del proyecto tenga comandos o convenciones propios. Mantén las reglas comunes en la raíz, sin copiarlas en cada carpeta.
Comprobar el comportamiento
- Revisa el nombre del archivo y el directorio de trabajo.
- Tras modificar instrucciones, inicia una ejecución nueva y pide que enumere los archivos aplicables.
- Encarga un cambio pequeño y comprueba rutas, comandos y resultado.
- Si una regla se incumple, busca conflictos y archivos override antes de añadir más texto.
Recitar correctamente las reglas no demuestra que se cumplan. Inspecciona el trabajo real. Codex también limita el tamaño total de las instrucciones de proyecto; no supongas que un archivo enorme se carga completo.
Lo que un Markdown no puede garantizar
Escribir «no leas las claves secretas» no restringe los permisos de acceso. Pedir al agente que ejecute pruebas no configura comprobaciones automáticas. Ajusta por separado los permisos, la protección de ramas y la integración continua (CI). No incluyas credenciales reales en los ejemplos.
Actualiza AGENTS.md cuando cambie el proyecto. Añade reglas para problemas concretos y recurrentes, comprueba su efecto y elimina lo que ya no sirve. Debe reducir las suposiciones, no registrar todas las equivocaciones del pasado.