Por qué falla el archivo de instrucciones gigante

La maleta sobrecargada

Creas un AGENTS.md y metes todas las reglas que se te ocurren. Al mes tiene 300 líneas, a los dos meses 450, a los tres 600. Y el agente va peor: para arreglar un bug sencillo procesa instrucciones de despliegue, una regla de seguridad en la línea 300 se ignora, y tres reglas de estilo se contradicen.

Es como llenar una maleta «por si acaso»: para encontrar un calcetín tienes que vaciarla entera.

El ciclo vicioso

1. El agente comete un error.
2. Tú añades una regla a AGENTS.md.
3. Funciona un tiempo.
4. Aparece otro error. Vuelta al paso 2.

Cada paso parece razonable. El efecto acumulado no lo es.

Qué se rompe

• Se gasta el presupuesto de contexto. Un archivo hinchado puede ocupar 10.000-20.000 tokens antes de empezar a trabajar. Luego hay que leer código y salidas de herramientas, y el espacio escasea (ver context rot).
• Perdido en el medio. El estudio «Lost in the Middle» muestra que los modelos usan peor lo que está en el centro de un texto largo. Una regla crítica en la línea 300 de 600 tiene muchas probabilidades de diluirse.
• Prioridades confusas. Una restricción innegociable, una preferencia de estilo y una anécdota de la semana pasada se ven iguales. El agente no sabe cuál pesa más.
• Deterioro del mantenimiento. Borrar da miedo («¿y si algo depende de esto?») y añadir parece gratis. El archivo solo crece y la señal se ahoga en ruido.
• Contradicciones. Reglas añadidas en momentos distintos acaban diciendo cosas opuestas, y el agente elige al azar.

Antipatrones típicos

El curso resume estos errores comunes:

• Meter todo el conocimiento del repo en un solo archivo.
• Repetir la misma regla en varios sitios.
• Mantener reglas obsoletas que nadie revisa.
• Escribir instrucciones condicionales tan específicas que casi nunca se aplican.
• Pegar manuales largos de herramientas en el contexto inicial.

Qué dice la evidencia

Conviene ser honestos: el beneficio de acortar depende del contenido y de la tarea. OpenAI cuenta que sustituyó un AGENTS.md grande por una entrada de unas 100 líneas que apunta a un directorio docs/, pero no publica porcentajes de mejora. Un estudio de ETH Zurich no encontró una mejora general de éxito con archivos de contexto en sus escenarios, y sí un coste de inferencia más de un 20% mayor. Otro estudio con 124 tareas midió ahorros de tiempo y tokens con un AGENTS.md, pero medía eficiencia, no corrección.

Ejemplo: cada regla con su ficha

Para evitar que el archivo se pudra, el curso sugiere que cada instrucción tenga tres cosas:

- Regla: las consultas SQL usan parámetros, nunca texto concatenado.
  Por qué: se corrigió una inyección en el módulo de pagos.
  Cuándo aplica: al tocar src/db/.
  Caduca: si migramos a un ORM que ya lo garantiza.