AGENTS.md importa porque actúa como el contrato entre tu base de código y el ecosistema de agentes IA; especifica qué puedes pedirle al agente, qué herramientas, convenciones y flujos de trabajo están dentro del alcance y qué no. Un conjunto bien mantenido de documentos de direccionamiento hace la inteligencia artificial más predecible y fiable: orienta al agente para que siga tus patrones, entienda tu arquitectura y genere código que encaje con tu base de código. No sustituye las buenas prácticas de IA, pero mejora mucho la experiencia out of the box. Recuerda que estos documentos se escriben para agentes, no para humanos, así que mantenerlos concisos y directos es clave.
Cómo probar tus steering docs: testear un AGENTS.md es parecido a evaluar una guía de onboarding. Recorre paso a paso tus instrucciones creando una colección de prompts de ejemplo, cubriendo todas las tareas que un ingeniero podría realizar en el monorepo, con uno o dos prompts por tarea. Guarda esos ejemplos en un lugar durable y accesible. Ejecuta los prompts con todos los agentes que soportes, por ejemplo Claude Code, Cursor o Codex CLI. Observa dónde se atascan los agentes, qué conocimiento les falta y qué instrucciones deberías afinar. Edita AGENTS.md y vuelve a probar hasta que el agente resuelva el caso en un solo intento. La simplicidad es una ventaja para descubrir huecos reales rápidamente; con el tiempo puedes agregar evaluaciones automáticas, pero no dejes que eso te impida empezar.
Estructura recomendada en monorepos: la mayoría de herramientas reconocen AGENTS.md como estándar, aunque algunas como Claude Code aceptan únicamente CLAUDE.md. Una opción práctica es crear CLAUDE.md que simplemente diga Read @AGENTS.md para evitar duplicación y mantener espacio para anexos específicos de Claude. La recomendación por defecto en monorepos es tener AGENTS.md anidados por carpeta, pero esto puede ser limitante si el agente solo lee el archivo más cercano. Por eso conviene combinar archivos locales con un AGENTS.md raíz que actúe como mapa y router, indicando documentos contextuales según la tarea. Ejemplo de mapa en el AGENTS.md raíz: para crear un email leer @emails/AGENTS.md; para crear un servicio Go leer @go/services/AGENTS.md; para añadir tests leer @.agents/unit-tests.md. Estructura de carpeta sugerida: repo-root con AGENTS.md, carpeta emails con su AGENTS.md, carpeta go/services con su AGENTS.md y una carpeta .agents con guías transversales como unit-tests.md. Así controlas mejor la ventana de contexto cuando las tareas son de larga duración.
Documentación externa y resúmenes: referenciar documentación externa está permitido, pero tiene el riesgo de llenar la ventana de contexto con material orientado a humanos. Una estrategia práctica es pedir al agente que resuma la documentación externa y guardar ese resumen en un AGENTS.md, indicando además la URL original para que el agente pueda consultar más si lo necesita. Mantener esos resúmenes actualizados será importante y es una tarea que pronto podremos delegar a agentes autónomos cuando el flujo de trabajo esté maduro.
Colaboración con equipos de plataforma y producto: el equipo central debe proveer el andamiaje y la navegación (AGENTS.md raíz, routing, configuraciones compartidas), mientras que los equipos de producto y plataforma mantienen las instrucciones de dominio específicas como por ejemplo cómo añadir observabilidad a un backend Python. Esto acerca la experticia al lugar donde se hace el trabajo y mantiene una estructura de navegación consistente para todos los agentes y desarrolladores.
Soporte para personalización de usuario: no todos los ingenieros trabajan igual, así que admite personalizaciones. Reserva ~/AGENTS.md para preferencias globales de usuario como tono o priorización de herramientas y permite overrides por repositorio con AGENTS.local.md ignorado por git. Indica en el AGENTS.md raíz que, si existe, se priorice @AGENTS.local.md. Esto permite que cada desarrollador ajuste el comportamiento de los agentes a su contexto sin fragmentar las reglas centrales.
En Q2BSTUDIO somos especialistas en desarrollo de aplicaciones a medida y software a medida, inteligencia artificial, ciberseguridad y servicios cloud aws y azure. Podemos ayudar a diseñar AGENTS.md efectivos, pipelines de integración para agentes IA, y prácticas seguras para desplegarlos en producción. También ofrecemos servicios de servicios inteligencia de negocio e implementaciones con power bi y soluciones de automatización de procesos. Conozca nuestras soluciones de inteligencia artificial y descubra cómo desarrollamos software a medida que integra agentes IA, ciberseguridad y operaciones en la nube para maximizar el valor de su monorepo y sus equipos.
Conclusión: los steering documents son un campo en rápida evolución y las mejores prácticas surgirán de la comunidad y de la experiencia operativa. Empiece por lo mínimo viable, pruebe con casos reales, itere rápido y distribuya la responsabilidad entre los equipos. Si quiere que le ayudemos a definir la estrategia de agentes IA, optimizar AGENTS.md y conectar todo con su plataforma cloud y herramientas de inteligencia de negocio, Q2BSTUDIO está listo para acompañarle.
