AGENTS.md vs CLAUDE.md vs rules: the context your agent actually reads
Casi todo lo que escribes en tu AGENTS.md se ignora. Y no es culpa del agente: es que cada token de ese archivo se carga en cada petición, compita o no con la tarea del momento. Si tu archivo tiene 400 líneas, estás pagando 400 líneas de contexto para pedir un console.log.
Esta pieza es lo que aprendí ordenando el mío, con la fuente de cada regla: la guía completa de AGENTS.md de AI Hero. - Source: A Complete Guide To AGENTS.md - AI Hero
Los tres nombres de lo mismo
AGENTS.md: el estándar abierto. Es un markdown que commiteas y que personaliza cómo se comportan los agentes en tu repo. Se coloca al inicio del historial, justo debajo del system prompt. Lo soportan muchas herramientas, aunque no todas. - Source: A Complete Guide To AGENTS.md - AI HeroCLAUDE.md: el que usa Claude Code. Si no quieres mantener dos, se enlazan:ln -s AGENTS.md CLAUDE.md. - Source: A Complete Guide To AGENTS.md - AI Hero- rules (carpetas de reglas por herramienta/dominio): la misma idea, aplicada por dominio en lugar de por archivo raíz.
No es "cuál es mejor": es decidir qué merece cargarse siempre y qué debería esperar a que haga falta.
El presupuesto de instrucciones
Un concepto que me ordenó todo: los LLM de frontera siguen ~150-200 instrucciones con consistencia razonable (menos si son modelos pequeños o sin razonamiento). - Source: Writing a good CLAUDE.md - Humanlayer, citado en A Complete Guide To AGENTS.md - AI Hero
Ahora míralo como presupuesto:
| Escenario | Impacto |
|---|---|
AGENTS.md chico y enfocado | Más presupuesto para la tarea del momento |
AGENTS.md inflado | Menos espacio para lo importante y agente más confundido |
| Instrucciones irrelevantes | Tokens gastados + distracción = peor resultado |
La conclusión incómoda: el ideal es que sea lo más chico posible.
Por qué crece (y por qué crece mal)
Hay un bucle perfecto: al agente le sale algo que no te gusta → añades una regla → repites cien veces en seis meses → el archivo se convierte en un "ball of mud" con opiniones contradictorias y sin nadie que haga una pasada completa. - Source: A Complete Guide To AGENTS.md - AI Hero
Y el atajo tentador lo empeora: nunca generes el AGENTS.md con un script de inicialización. Los archivos generados priorizan exhaustividad sobre contención: meten "lo útil para la mayoría" en lugar de lo que tu proyecto necesita. - Source: A Complete Guide To AGENTS.md - AI Hero
El veneno silencioso: información vieja
La documentación caduca. Para un humano, un doc viejo es molesto pero se detecta. Para un agente que lo lee en cada petición, la información vieja contamina el contexto: si tu AGENTS.md dice "la lógica de auth está en src/auth/handlers.ts" y ese archivo se movió, el agente buscará con total seguridad en el lugar equivocado. - Source: A Complete Guide To AGENTS.md - AI Hero
Por eso: describe capacidades, no estructura de archivos. Los conceptos de dominio ("organización", "grupo", "espacio de trabajo") envejecen mejor que las rutas.
Qué SÍ va en el root
El mínimo absoluto:
- Una frase que describa el proyecto (funciona como un prompt de rol).
- El package manager, si no es el estándar.
- Los comandos de build/typecheck, si no son los típicos.
Eso es todo. El resto, a otro lado. - Source: A Complete Guide To AGENTS.md - AI Hero
Progressive disclosure: el resto vive afuera
En vez de pegar las convenciones de TypeScript en el root, se referencian:
Para convenciones de TypeScript, ver docs/TYPESCRIPT.mdAsí las reglas de TypeScript solo se cargan cuando el agente escribe TypeScript, y no gastan presupuesto en una sesión de CSS. Y se puede anidar: docs/TYPESCRIPT.md referencia docs/TESTING.md, y así se construye un árbol de documentación que el agente navega solo. - Source: A Complete Guide To AGENTS.md - AI Hero
Esa es la misma idea que usan los skills: conocimiento que se carga cuando se necesita, no siempre. → Skills que sobrevivieron
Monorepos
No estás limitado a un solo archivo. Puedes poner AGENTS.md en subdirectorios y se mezclan con el del root. La regla para no arruinarlo: root = propósito del monorepo y cómo navegarlo; paquete = propósito y convenciones de ese paquete. Sin sobrecargar ningún nivel. - Source: A Complete Guide To AGENTS.md - AI Hero
Arréglalo hoy
Un prompt que sirve para refactorizar el tuyo (idea tomada de la guía de AI Hero):
Refactoriza mi AGENTS.md con progressive disclosure:
1. Encuentra contradicciones entre instrucciones y pregúntame cuál conservar.
2. Extrae solo lo esencial para el root: una frase del proyecto,
package manager y comandos no estándar.
3. Agrupa el resto por dominio (TypeScript, testing, API, git)
en archivos separados dentro de docs/.
4. Deja el root con enlaces a esos archivos.
5. Marca para eliminar: redundante, vago o demasiado obvio.Mi regla
Si una instrucción no aplica a cada tarea posible del repo, no va en el root. Va en un archivo que se descubre cuando hace falta. El AGENTS.md ideal es chico, concreto y con migas de pan.
Esto forma parte del flujo completo; el marco está en Mi flujo completo de AI en desarrollo web y en Diseña tu repo para que los agentes trabajen mejor.
¿Cuántas líneas tiene tu AGENTS.md hoy? Si son más de 50, este fin de semana tienes tarea. Cuéntame en los comentarios cuál fue la regla que sí sobrevivió.