Era demasiado vago para escribir el CLAUDE.md — y resulta que acerté

Cada vez que me salía en el timeline un artículo sobre CLAUDE.md (o AGENTS.md), me decía “ya lo configuro luego” y pasaba de largo. Ver a otros montarse configuraciones elaboradísimas de AGENTS.md me generaba cierta ansiedad. ¿Me estaba quedando atrás?

Entonces salieron los últimos datos de benchmarks, y esa ansiedad desapareció de golpe. Resulta que mi vagancia era una decisión de ingeniería bastante racional.

Los ficheros de contexto generados por LLMs empeoran las cosas

“Darle más contexto al agente siempre ayuda, ¿no?” Eso pensaba yo también.

Cuando los investigadores probaron contexto autogenerado por LLMs en SWE-bench Lite, la tasa de éxito bajó un 0,5 %. En AgentBench, cayó otro 2 % más. Incluso los ficheros escritos a mano con mucho cuidado solo conseguían una mejora del 4 %. A esto lo llamaría “sobreajuste de contexto”.

• Bajada del 0,5 % en la tasa de éxito con contexto generado por LLM en SWE-bench Lite
• Caída adicional del 2 % en AgentBench
• Incremento del 20–23 % en los costes de inferencia
• Efecto positivo (2,7 %) observado únicamente en repositorios sin ningún tipo de documentación

El paper “Evaluating AGENTS.md” de Gloaguen et al. lo confirma: los ficheros de contexto tienden a reducir las tasas de éxito en las tareas comparado con no proporcionar ningún contexto del repositorio.

Los agentes siguen las instrucciones demasiado bien — y ése es el problema

El problema no es que los agentes ignoren tus instrucciones. Es justo lo contrario.

Escribe una línea en tu fichero de contexto diciéndole al agente que use uv, y lo instalará y ejecutará incluso en situaciones donde es completamente innecesario, añadiendo pasos extra cada vez.

Con GPT-5.2, los tokens de inferencia aumentaron entre un 14 y un 22 % cuando había ficheros de contexto. El agente estaba tan ocupado siguiendo instrucciones que perdía el foco en resolver el problema de verdad.

• Aumentaron las ejecuciones innecesarias de pytest
• El uso de herramientas como grep y read se disparó bastante más de lo necesario

”No hagas X” hace que los agentes piensen más en X

En un artículo anterior hablé de cómo el contenido del SKILL.md se lee en momentos concretos, y AGENTS.md tiene un problema parecido.

Se sitúa en la capa del “mensaje de desarrollador”, entre el system prompt y el prompt del usuario. Esta posición condiciona enormemente el razonamiento del agente.

Escribe “no toques este fichero” y el agente pensará en ese fichero una vez más. Los investigadores lo llamaron el “efecto elefante rosa”. Dile a alguien que no piense en un elefante rosa, y es exactamente lo primero que se le viene a la cabeza.

• Orden de prioridad: instrucciones del proveedor → system prompt → AGENTS.md → prompt del usuario
• Los ficheros mantenidos a mano no pueden seguir el ritmo de los cambios del código, así que la información se queda rápidamente obsoleta

Si tienes que escribirlo, que sea mínimo

Si tu repositorio no tiene absolutamente ninguna documentación, los ficheros de contexto pueden ayudar — los datos mostraron un efecto positivo del 2,7 % en esos casos. Pero si decides escribirlo, que sea lo más escueto posible.

Una línea para indicar qué herramienta de build usa el repositorio. Una línea para corregir un patrón que el agente repite mal constantemente.

Añade algo como “si encuentras algo estructuralmente raro, avísame de inmediato” y el agente se convierte en una herramienta que va reportando vulnerabilidades del código. Más allá de eso, hacer que la estructura de tu código sea más intuitiva es mucho más efectivo que escribir instrucciones sobre ella.

• Reforzar los tests unitarios y las comprobaciones de tipos supera a cualquier fichero de contexto
• Si la ubicación de los ficheros resulta confusa, muévelos en lugar de escribir instrucciones para encontrarlos

Saber escribir buenos ficheros de contexto no es necesariamente una señal de habilidad. Entender la estructura de esos ficheros y diseñar metasistemas a su alrededor — eso sí es habilidad. Y a veces, “ser un vago” es la mejor decisión de ingeniería que puedes tomar.