784 formas de decir «no»: qué escriben los repos más grandes en su AGENTS.md (2026)
By Surya Pratap
22 de agosto de 2026
12 min de lectura
IA y tecnología
22 de agosto de 2026
12 min de lectura
El archivo que se cobra en cada sesiónHover to exploreAlguien en r/AI_Agents hizo el trabajo que nadie más había hecho: leyó el AGENTS.md de los 100 repositorios de GitHub con más estrellas que tienen uno —alrededor del 27 % de los 1.000 primeros, según su recuento— y contabilizó qué había dentro.
El hallazgo estructural no sorprendió. Arquitectura y disposición del repositorio, cómo ejecutar las pruebas, comandos de compilación, lo que se debe y no se debe hacer, etiqueta de los PR, estilo de código. Los encabezados más frecuentes eran pruebas, comandos, descripción del proyecto y arquitectura. Previsible.
Lo interesante fue el tono. Alrededor del 90 % de esos archivos está escrito en clave de «debe», «siempre» y «nunca». En todo el corpus hay 784 viñetas explícitas de «no hagas», y la mayoría son extrañamente, casi forensemente, específicas.
La mejor que encontró:
«No afirmes que una prueba interrumpida o agotada por tiempo ha pasado.»
Nadie escribe esa frase en abstracto. Alguien escribe esa frase porque un agente lo hizo.
Este es el cambio de encuadre que conviene llevarse, y modifica la forma de escribir el archivo.
Un README se escribe hacia fuera: le explica un proyecto a alguien que no lo ha visto nunca. Un AGENTS.md escrito igual produce una descripción pulida del proyecto que no ayuda a nadie, porque el agente ya puede leer su package.json, su árbol de directorios y los nombres de sus archivos de prueba.
Lo que el agente no puede deducir es el conjunto de cosas en las que ya se ha equivocado aquí. Eso son esas 784 viñetas. Lea con atención un buen AGENTS.md y podrá reconstruir el parte de incidencias: el agente de alguien dio por buena una prueba colgada, el agente de alguien hizo un force-push, el agente de alguien se inventó un script que no existe, el agente de alguien reescribió sin avisar una migración.
Why the prohibitive voice actually works
La formulación «debe / siempre / nunca» no es autoritarismo, es compresión. «Conviene ejecutar la suite completa» es una preferencia que un agente puede sopesar frente a otras y descartar. «Nunca marques una prueba como superada si no has visto que termina con código 0» es un predicado verificable y sin margen de negociación. Cuando el lector es un modelo que optimiza por parecer que ha terminado, la ambigüedad no es cortesía: es una vulnerabilidad.
El archivo más corto de la muestra es el de neovim, con 35 palabras. Es una sola regla, y merece la pena reproducirlo entero porque expone la idea mejor que cualquier argumento:
# AGENTS.md
## AI Disclosure
If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.
Ese es el archivo completo. Codifica exactamente una cosa que le importa al proyecto y que un agente no podría deducir por su cuenta —una convención de procedencia— y no dice nada más.
Compare ahora Next.js. Veintiuna secciones: estructura del código, comandos de compilación, elección de empaquetador, pruebas, cómo escribir pruebas, linting y tipos, «trabaje en un worktree desechable», estado de los PR y fallos de CI, seguridad de secretos y variables de entorno, flujos de trabajo eficientes en contexto, descomposición y verificación de tareas, recompilar antes de ejecutar pruebas, antipatrones de desarrollo. Incluida esta, que le sonará a cualquiera que haya revisado el PR de un agente:
«NO añadas pies de "Generated with Claude Code" ni de coautoría a los commits ni a los PR»
Ambos archivos son correctos. La variable no es la diligencia, sino cuánto tráfico de agentes ha absorbido el repositorio y lo caros que salen sus fallos. Next.js tiene agentes atravesando un monorepo con un empaquetador en Rust y una matriz de CI que cuesta dinero real repetir. Neovim tiene una convención con la que no piensa transigir.
La extensión correcta de su AGENTS.md es el número de errores que sus agentes han cometido de verdad, más el puñado de convenciones que jamás habrían podido adivinar. Cada línea que pase de ahí es algo que se paga en cada sesión, para siempre.
Aquí está la parte que los fundadores pasan por alto una y otra vez, y es la razón por la que «escríbelo a fondo» es un mal consejo.
AGENTS.md se lee al principio de cada sesión. Cada frase que contiene es gasto recurrente, en cada tarea, sea o no relevante para lo que el agente está haciendo en ese momento. Un archivo de 400 líneas explicando su arquitectura no es contexto gratis: es un impuesto fijo que grava cada corrección de errores, cada actualización de dependencias, cada errata.
Esa es toda la restricción de diseño del archivo, y explica la respuesta de neovim.
También explica por qué el ecosistema desarrolló un segundo mecanismo. Una skill —un SKILL.md dentro de una carpeta— se carga de forma perezosa: al empezar la sesión el agente solo lee el frontmatter YAML, un nombre y una descripción. El cuerpo se carga únicamente cuando una tarea encaja de verdad. Diez skills sin usar no le cuestan casi nada.
Dónde trazar la línea entre ambos
AGENTS.md. «Nunca subas secretos.» «Ejecuta npm run test:unit -- --coverage, no la suite completa.» «Las migraciones solo se añaden, nunca se modifican.»Esa tercera viñeta es de donde salen casi todos los archivos hinchados. Si su AGENTS.md abre con tres párrafos describiendo una estructura de directorios que el agente va a listar en su primera llamada a una herramienta, está pagando tokens por contarle algo que estaba a punto de aprender gratis.
GitHub hizo una versión más amplia de este estudio sobre más de 2.500 archivos agents.md, y los resultados convergen con la muestra de Reddit de una forma útil.
pytest -v tests/unit sirve. «Ejecuta las pruebas como corresponda» se ignora, porque no es una instrucción: es un deseo.never commit secrets. Si no escribe nada más esta semana, escriba esa y el comando exacto de las pruebas.Sale en todos los hilos sobre el tema, y la razón mecánica convence más que las anécdotas.
Pídale a un agente que genere su AGENTS.md y producirá un resumen competente, bien formateado y de trescientas líneas de su repositorio, porque es lo que alcanza a ver. Describirá la estructura de carpetas, listará las dependencias y caracterizará la configuración de pruebas. Todo ello lo podría haber deducido en el momento.
Lo que no puede escribir es la parte que importa: las 784 prohibiciones. Esas salen de verlo fallar. Un archivo generado es, casi por construcción, el impuesto fijo por sesión sin ninguno de los beneficios.
No conozco ningún benchmark público riguroso sobre esto —quienes lo practican informan de que los archivos generados rinden peor, y algunas investigaciones cercanas a los fabricantes apuntan en la misma dirección—, pero conviene tomarlo como una intuición sólida y no como un dato asentado. El argumento estructural se sostiene solo: un archivo que únicamente contiene datos deducibles cuesta tokens y no aporta nada.
Una vía intermedia práctica: deje que el agente redacte la sección de comandos, porque puede leer sus scripts con precisión y esa parte es tediosa. Escriba usted mismo los límites, línea a línea, según vayan surgiendo los problemas. Nunca acepte una descripción de arquitectura generada.
AGENTS.md lo usan más de 60.000 proyectos de código abierto y lo custodia la Agentic AI Foundation, bajo la Linux Foundation, el mismo organismo que ya alberga MCP y, desde esta semana, Agent2Agent. Lo leen Codex, Cursor, Gemini CLI, Jules, el agente de programación de Copilot, Aider, goose, opencode, Zed, Devin, Windsurf, JetBrains Junie y una larga cola de herramientas más.
Hace dos días escribimos sobre cómo todos los protocolos de agentes acabaron bajo el mismo techo. Esta es la misma consolidación aflorando a nivel de archivo, y tiene una ventaja concreta: un archivo, no cinco.
El fallo que evita es real y caro. Usted endurece un límite en CLAUDE.md, se olvida de .cursorrules, cambia de herramienta a mitad de semana y el agente que no recibió la actualización ejecuta el comando destructivo. La deriva de reglas entre CLAUDE.md, .cursorrules, .windsurfrules y copilot-instructions.md es la queja operativa más repetida por los equipos que usan más de un agente; hay quien está publicando arneses de sincronización solo para resolverla.
Si empieza ahora, la jugada correcta es aburrida: haga de AGENTS.md la fuente de verdad y genere desde ahí los archivos específicos de cada herramienta. Un script de diez líneas gana a acordarse.
Dos límites honestos, porque en algunos sitios se está vendiendo el archivo por encima de lo que da.
No es memoria. AGENTS.md es estático. No sabe que el PR #184 zanjó hace tres meses la discusión entre Postgres y Mongo, así que su agente volverá a proponer Mongo tan tranquilo en una sesión nueva, y una línea caduca del tipo «usamos X» se servirá con absoluta seguridad mucho después de que X haya desaparecido. Es una carencia realmente sin resolver —hay quien está construyendo herramientas de memoria de decisiones justo para eso— y no se cierra escribiendo con más cuidado.
No restringe nada. Cada línea es una sugerencia a un sistema probabilístico. «Nunca hagas force-push» en un archivo Markdown es una petición; un hook que bloquea git push --force es un control. Confundir ambas cosas es un patrón que ya tratamos en Los agentes de IA necesitan sistemas de permisos, no mejores prompts, y los últimos doce meses no han cambiado la conclusión. AGENTS.md reduce la frecuencia del error. No elimina la posibilidad.
Si no tiene AGENTS.md, no arranque de una plantilla. Arranque de esto y deje que crezca solo cuando algo salga mal.
# AGENTS.md
## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.
## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.
## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.
Son unas 150 palabras de instrucción real. No contiene ninguna descripción de la arquitectura, ninguna explicación de qué hace el producto y nada que el agente pudiera haber leído del repositorio; y cubre los cuatro límites que explican la mayor parte del daño que un agente causa en una base de código pequeña.
A partir de ahí, trátelo como un registro de incidencias. Cada vez que un agente haga algo que usted tenga que deshacer, añada una línea, en imperativo, tan específica como lo fue el error. En seis meses tendrá su propia versión de esas 784 prohibiciones, y todas se habrán pagado antes.
Los repositorios con más estrellas del código abierto convergieron en un formato que no se parece en nada a la documentación, porque el lector no es una persona. Es prohibitivo, específico, cargado de comandos y —en los mejores casos— muy breve.
Para un fundador que saca adelante un MVP con agentes escribiendo la mayor parte del código, ese archivo es probablemente las 150 líneas de mayor apalancamiento del repositorio. Es también el único archivo del proyecto que se paga en cada tarea, y justo por eso el impulso de hacerlo exhaustivo es el impulso que hay que resistir.
Escriba los errores. Sáltese la visita guiada. Deje que crezca una cicatriz cada vez.
Fuentes: r/AI_Agents, «What the 100 biggest GitHub repos put in their AGENTS.md files» · Blog de GitHub, «How to write a great agents.md: lessons from over 2,500 repositories» · agents.md, sobre el formato, su adopción y la custodia de la Agentic AI Foundation · AGENTS.md de neovim/neovim · AGENTS.md de vercel/next.js
IdeaToMVP Academy
4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.
