PulseFlow Tecnologia
← Insights
·5 min de lectura·guia-tecnica·agents-md·harness-engineering·buenas-practicas
PulseFlow Tecnologia

Cómo estructurar un AGENTS.md para un repositorio corporativo

AGENTS.md nació de una premisa simple: "a simple, open format for guiding coding agents" - un lugar único y predecible donde un agente de código busca instrucciones antes de tocar un repositorio. La pregunta real que enfrenta cualquier equipo de ingeniería no es si vale la pena tener uno, sino qué poner dentro para que funcione.

Lo que enseñan más de 2.500 repositorios

Un análisis de GitHub sobre más de 2.500 repositorios con agents.md llegó a una conclusión clara: "the successful agents aren't just vague helpers; they are specialists." Descripciones genéricas como "helpful coding assistant" no producen mejores resultados - lo que funciona es una instrucción específica, con límites claros. El estudio identificó seis bloques que aparecen consistentemente en los AGENTS.md más efectivos:

  1. Comandos ejecutables - npm test, npm run build, y equivalentes, listos para copiar y pegar
  2. Estructura del proyecto - dónde vive cada cosa, sin obligar al agente a explorar
  3. Stack técnico con versiones - no "React", sino "React 18", "TypeScript 5", etc.
  4. Ejemplos de código real - mostrar el patrón esperado, no solo describirlo
  5. Patrones de estilo - convenciones de nomenclatura y formato
  6. Límites claros - qué puede hacer el agente solo, qué necesita aprobación, qué nunca debe hacer

Entre las restricciones identificadas, la más común y más útil fue simplemente "never commit secrets" - una frase corta que evita uno de los errores más costosos que puede cometer un agente.

Por qué la estructura importa a escala: el caso Codex

Cuánto importa esto queda claro en un experimento que la propia OpenAI documentó: un repositorio que nació vacío en agosto de 2025, con el scaffold inicial generado por Codex CLI (GPT-5) - incluso el AGENTS.md inicial fue escrito por un agente. Cinco meses después, el repositorio tenía cerca de un millón de líneas de código, con más de 1.500 pull requests fusionados, producidos por solo tres ingenieros conduciendo agentes - un promedio de 3,5 PRs por ingeniero por día. Ninguna línea fue escrita manualmente por un humano.

El aprendizaje central de ese experimento es lo que OpenAI llama "legibilidad": el repositorio necesita estar optimizado para que un agente pueda entender todo el dominio de negocio a partir del propio código y la documentación - sin depender de contexto tácito. Cuando las decisiones de arquitectura vivían solo en conversaciones de Slack, eran tan invisibles para el agente como lo serían para un empleado nuevo el primer día. La solución fue traer ese contexto al repositorio, al lugar donde el agente realmente busca.

Una estructura de referencia

Combinando la investigación de los 2.500 repositorios con el formato abierto de agents.md, un AGENTS.md corporativo consistente cubre, en la práctica:

  1. Objetivo del proyecto y dominio de negocio
  2. Arquitectura y patrones adoptados
  3. Configuración local (paso a paso, sin asumir conocimiento previo)
  4. Comandos permitidos (build, test, lint, deploy)
  5. Pruebas obligatorias antes de cualquier PR
  6. Estilo de código y convenciones de nomenclatura
  7. Reglas de seguridad (empezando por "never commit secrets")
  8. Restricciones explícitas - lo que el agente nunca debe hacer solo
  9. Flujo de pull request esperado
  10. Criterios de aceptación para considerar una tarea terminada

El punto práctico

Un AGENTS.md no es documentación que se escribe una vez y se olvida - es un artefacto vivo, versionado con el mismo rigor que el código que gobierna. Los equipos que tratan este archivo como parte de la arquitectura, no como una nota al pie, son los mismos que logran escalar de "un agente ayudando en una tarea" a "agentes conduciendo entrega real", como en el caso documentado por OpenAI.

Fuentes