Un playbook para implementar AGENTS.md en repositorios enterprise

Escribir un buen AGENTS.md para un repositorio es un problema resuelto - GitHub ya documentó el patrón de seis bloques que funciona, basado en más de 2.500 repositorios analizados. El problema que la mayoría de las empresas todavía no resolvió es otro: cómo implementar esto de forma consistente en decenas o cientos de repositorios, sin que cada equipo reinvente su propio formato.

Inventario de repositorios antes de cualquier plantilla

Antes de escribir un solo AGENTS.md, mapea qué repositorios ya tienen uno (aunque sea informal), qué stacks técnicos están representados, y cuál es el nivel de actividad de cada uno. Los repositorios abandonados no necesitan AGENTS.md; los repositorios con PRs diarios y múltiples equipos lo necesitan con urgencia.

Plantilla base con los seis bloques ya validados

En vez de que cada equipo invente su propia estructura, el análisis de GitHub sobre más de 2.500 repositorios ya identificó lo que funciona: comandos ejecutables listos para copiar y pegar, estructura del proyecto, stack técnico con versiones específicas, ejemplos de código real, patrones de estilo, y límites claros. Una plantilla organizacional con estos seis bloques, más una sección fija de seguridad que empiece con "never commit secrets" - la restricción más común y más útil identificada —, da a cada equipo un punto de partida en vez de una hoja en blanco.

Personalización por stack, no reinvención por equipo

La plantilla base necesita variaciones por lenguaje y stack (Node, Python, Go, etc.), pero la estructura de seis bloques debe permanecer idéntica entre repositorios. Eso permite que un agente que ya operó en un repositorio de la empresa reconozca el formato instantáneamente al entrar a un segundo.

Ownership, revisión técnica y revisión de seguridad

Cada AGENTS.md necesita un dueño - normalmente el tech lead o arquitecto responsable del repositorio - y pasa por dos tipos de revisión antes de entrar en vigor: revisión técnica (¿los comandos y el stack son correctos?) y revisión de seguridad (¿los límites y restricciones cubren los riesgos reales de ese sistema, no solo el boilerplate genérico de la plantilla?).

Versionamiento como parte del propio repositorio

El AGENTS.md se revisa en el mismo pull request que cambia la arquitectura que describe - no como documentación externa que se actualiza después, o nunca. Eso es lo que garantiza que el archivo se mantenga correcto con el tiempo, en vez de desactualizarse silenciosamente como pasa con las wikis y herramientas de conocimiento separadas del código.

Métricas de uso y auditoría

Hacer seguimiento de cuántos repositorios tienen AGENTS.md, con qué frecuencia se actualizan, y - cuando la plataforma de agentes lo permita - cuántas veces un agente consultó efectivamente el archivo antes de actuar, da visibilidad sobre dónde la implementación todavía está incompleta.

Evolución continua, no implementación única

Un AGENTS.md implementado una vez y nunca revisado tiende a desactualizarse exactamente igual que cualquier otra documentación. El playbook necesita incluir revisión periódica - trimestral, por ejemplo - para capturar cambios de stack, nuevas herramientas, y restricciones que solo quedaron claras después de un incidente.

Las diez etapas del rollout

1. Inventario de repositorios - mapear dónde se necesita AGENTS.md
2. Plantilla base - los seis bloques validados por GitHub
3. Personalización por stack - variaciones de lenguaje, misma estructura
4. Definición de ownership - un dueño por archivo
5. Revisión técnica - comandos y stack correctos
6. Revisión de seguridad - restricciones específicas del sistema
7. Versionamiento - en el mismo PR que cambia la arquitectura
8. Métricas de uso - cobertura y frecuencia de actualización
9. Auditoría - consulta efectiva por el agente, cuando sea medible
10. Evolución continua - revisión periódica, no implementación única

Fuentes

• GitHub - How to write a great AGENTS.md - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
• AGENTS.md - https://github.com/agentsmd/agents.md