AGENTS.md
AGENTS.md es un fichero de instrucciones para agentes situado en la raíz del repositorio, que se ha convertido en el formato más parecido a un estándar universal para decirle a un agente cómo trabajar en un proyecto. Es el soporte habitual de la constitución del proyecto y de los boundaries de proyecto en desarrollo guiado por especificaciones.
El soporte de las instrucciones para agentes ha dejado de ser cosa de cada herramienta. AGENTS.md lo leen de forma nativa una veintena de herramientas de codificación, lo han adoptado más de sesenta mil proyectos y su especificación está tutelada desde diciembre de 2025 por la Agentic AI Foundation, dentro de la Linux Foundation. Para el equipo, la consecuencia práctica es que la constitución y los boundaries de proyecto tienen un lugar donde vivir que cualquier agente entiende, con independencia del proveedor: escribirlos una vez en ese formato evita mantener versiones distintas para cada herramienta.
El sistema de boundaries: Always / Ask First / Never
El contenido más característico de un AGENTS.md es el sistema de boundaries, un marco de delegación de tres niveles que supera a la lista plana de prohibiciones:
| Nivel | Significado | Ejemplos |
|---|---|---|
| Always (siempre hacer) | Acciones que el agente ejecuta sin preguntar. | Ejecutar las pruebas antes de un commit, seguir las convenciones de nomenclatura, registrar los errores. |
| Ask First (preguntar primero) | Acciones que podrían ser correctas pero requieren aprobación por su impacto. | Modificar el esquema de la base de datos, añadir dependencias nuevas, cambiar la API pública. |
| Never (nunca hacer) | Líneas rojas absolutas. | Hacer commit de secretos, editar directorios de dependencias, modificar la configuración de producción. |
El sistema da autonomía donde es segura (Always), crea puntos de control donde hacen falta (Ask First) y establece líneas rojas inequívocas (Never). No es estático: a medida que el equipo gana confianza, algo que hoy es Ask First puede pasar a Always, y algo que se creía inocuo puede subir a Ask First tras un incidente. Es autonomía gradual, análoga a cómo se delega cada vez más en un profesional que demuestra criterio.
Dos ámbitos: proyecto y tarea
Los boundaries operan en dos niveles. En la constitución, fijan las reglas generales que valen para todo lo que se construya. En cada tarea, añaden las restricciones concretas de esa implementación (el tercer campo del prompt de cuatro campos, véase Tareas atómicas y commits atómicos). La combinación da consistencia global y precisión local. «Nunca hacer commit de secretos» es de proyecto; «no tocar los puntos de entrada existentes» es de la tarea concreta.
Error frecuente
Una lista plana de prohibiciones. Sin niveles, el agente no sabe qué puede hacer solo, qué consultar y qué evitar. Tampoco conviene mantener todo en Ask First de forma indefinida —desaprovecha la confianza ganada y satura de consultas— ni confundir el ámbito de proyecto con el de tarea. Y que el fichero exista y lo lean todas las herramientas no dice nada de si sus reglas son las correctas: el contenido lo decide el equipo y se revisa con la misma deliberación que la constitución.
Recursos
📊 Guía didáctica SDDRecursos · Scrum Manager
🏦 SDD en equipos ágilesSkill Arena · Scrum Manager
Referencias
- AGENTS.md (especificación del formato).
- Agentic AI Foundation / Linux Foundation. (2025). Tutela de la especificación AGENTS.md.
- Osmani, Addy. (2025). «How to write a good spec for AI agents».
Véase también
¿Quieres avanzar en agilidad? Puedes buscar convocatorias de cursos y exámenes o ir a tu ritmo haciéndote miembro del Club Agile. Esta membresía incluye recursos exclusivos, aulas e-learning y acceso a Skill Arena: un espacio para practicar y medir tus habilidades ágiles a tu ritmo.