AGENTS.md y copilot-instructions.md: cómo dar contexto a la IA en proyectos de desarrollo de software

Descubre qué son AGENTS.md y copilot-instructions.md, cómo funcionan los archivos de contexto para agentes de IA y por qué son clave para generar código coherente, seguro y alineado con los estándares del proyecto.

La inteligencia artificial se ha integrado de forma acelerada en el desarrollo de software. Hemos pasado de ciclos de desarrollo de varios meses a crear MVPs en cuestión de días gracias a la IA generativa.

Hoy, cualquier IDE competitivo incorpora chats o agentes capaces de generar funcionalidades completas con pocas instrucciones, permitiendo elegir entre múltiples modelos especializados según la tarea.

Sin embargo, sin el contexto adecuado, estos “compañeros de programación” pueden:

• Romper convenciones del proyecto.
• Generar código inconsistente.
• Introducir errores críticos o comportamientos no deseados.

AGENTS.md, el README.md de las máquinas

Todos los desarrolladores conocen el README.md, un archivo que explica cómo instalar un proyecto, qué tecnologías utiliza y cómo contribuir.
Los agentes de IA también necesitan su propio manual: aquí es donde entran AGENTS.md y copilot-instructions.md.

Qué información aportan los archivos de contexto

Un archivo AGENTS.md puede incluir:

• Estructura de carpetas.
• Convenciones de programación.
• Estándares para commits.
• Cómo ejecutar tests.
• Patrones y anti-patrones del proyecto.
• Reglas que no deben romperse.

El objetivo es claro: evitar que la IA “improvise” y asegurar que trabaje alineada con las decisiones del equipo.

AGENTS.md vs copilot-instructions.md

Aunque AGENTS.md es un estándar emergente consensuado entre varias compañías, algunos proveedores utilizan configuraciones propias, como copilot-instructions.md en GitHub Copilot.

Ventaja clave de AGENTS.md

AGENTS.md es agnóstico a la herramienta, lo que permite reutilizar el mismo contexto con distintos agentes y modelos de IA, reduciendo dependencias de proveedor.

Cómo se estructura un archivo AGENTS.md

En la documentación oficial de AGENTS.md se muestran ejemplos claros de su uso. En ellos se observa cómo, mediante lenguaje natural, se puede describir el funcionamiento interno del proyecto.

Contenido habitual de un AGENTS.md

• Comandos importantes del proyecto.
• Guidelines para commits.
• Estructura de directorios.
• Estilo de programación.
• Proceso de instalación y despliegue.

Este archivo debe guardarse en la raíz del proyecto y puede referenciar otros documentos para mantener una estructura limpia y escalable.

Un documento vivo

Al igual que el repositorio, estos archivos evolucionan con el tiempo. Su función es optimizar el contexto que reciben los modelos de IA y mejorar el uso de tokens, logrando resultados más precisos y personalizados.

Ejemplo real de uso en un proyecto

En el proyecto NewClientsOnlineOnboarding (Banksy) se implementó copilot-instructions.md tras un refactor, con el objetivo de garantizar que las nuevas funcionalidades respetaran:

• La estructura existente.
• Las buenas prácticas.
• Las convenciones arquitectónicas definidas.
  BLOG AGENTS – Versión SEO Jirad…

Instrucciones especializadas por área

Las reglas se dividieron en varios archivos, cada uno enfocado en una parte concreta del sistema. Esto facilita que un nuevo desarrollador entienda rápidamente cómo trabajar en el proyecto.

Control sobre lo que la IA debe y no debe hacer

Este enfoque permite definir, por ejemplo, cómo estructurar un componente React:

• Qué carpetas usar.
• Qué archivos generar.
• Qué convenciones seguir.

Además, impide acciones no deseadas como generar ficheros innecesarios o romper patrones arquitectónicos.

¿Estándar emergente o moda pasajera?

Como ocurre con toda nueva tecnología, la adopción de archivos de contexto será progresiva.
Según un estudio de la Universidad de Heidelberg (Context Engineering for AI Agents in Open-Source Software), solo el 5% de los 10.000 repositorios más populares de GitHub utilizan actualmente este tipo de archivos.

BLOG AGENTS – Versión SEO Jirad…

Esto indica que estamos ante una tendencia emergente, pero con un potencial de crecimiento significativo.

Retos y limitaciones de los archivos de contexto

A pesar de su utilidad, AGENTS.md y copilot-instructions.md no están exentos de riesgos.

Principales desafíos

• No existe un estándar formal universal.
• Interpretación distinta según proveedor.
• Riesgos de seguridad si se conceden permisos excesivos.
• Falta de control de versiones nativo.
• Posible ignorancia parcial del archivo por parte del modelo.

Estos factores hacen imprescindible la supervisión humana.

Conclusión: una nueva capa en el desarrollo asistido por IA

Los archivos de contexto como AGENTS.md y copilot-instructions.md representan un paso natural en la evolución del desarrollo de software asistido por IA.
Permiten alinear a los agentes con la arquitectura del proyecto, reducir errores y mejorar la coherencia del código generado.

No son una solución mágica ni un estándar definitivo, pero sí una herramienta poderosa que veremos adoptarse de forma creciente en proyectos profesionales.