Era Demasiado Flojo Para Escribir CLAUDE.md — Y Resulta Que Fue la Decisión Correcta

Cada vez que aparecía en mi feed un post sobre CLAUDE.md (o AGENTS.md), me decía “ya lo configuro después” y seguía scrolleando. Ver cómo otros armaban configuraciones elaboradísimas de AGENTS.md me generaba cierta angustia. ¿Me estaba quedando atrás?

Entonces salieron los datos recientes de los benchmarks, y esa angustia desapareció de golpe. Resulta que mi flojera era una decisión de ingeniería bastante racional.

Los archivos de contexto generados por LLMs empeoran las cosas

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

Cuando los investigadores probaron contexto auto-generado por LLMs en SWE-bench Lite, la tasa de éxito bajó un 0.5%. En AgentBench, cayó otro 2%. Incluso los archivos escritos cuidadosamente a mano lograron apenas un 4% de mejora. A esto le llamo “sobreajuste de contexto.”

• 0.5% de disminución en la tasa de éxito con contexto generado por LLM en SWE-bench Lite
• 2% adicional de caída en AgentBench
• Aumento del 20–23% en costos de inferencia
• Efecto positivo (2.7%) observado únicamente en repositorios sin ninguna documentación

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

Los agentes siguen instrucciones demasiado bien — y ese es el problema

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

Escribe una sola línea en tu archivo de contexto diciéndole al agente que use uv, y lo va a instalar y ejecutar incluso en situaciones donde es completamente innecesario, agregando pasos de más en cada oportunidad.

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

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

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

Ya había mencionado cómo el contenido de SKILL.md se lee en momentos específicos en un post anterior, y AGENTS.md tiene un problema similar.

Vive en la capa de “mensaje del desarrollador”, entre el system prompt y el user prompt. Esta posición condiciona fuertemente el razonamiento del agente.

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

• Orden de prioridad: instrucciones del proveedor → system prompt → AGENTS.md → user prompt
• Los archivos mantenidos manualmente no pueden seguirle el ritmo a los cambios del código, así que la información se vuelve obsoleta rapidísimo

Si igual vas a escribir uno, que sea mínimo

Si tu repositorio no tiene absolutamente ninguna documentación, los archivos de contexto pueden ayudar — los datos mostraron un efecto positivo del 2.7% en esos casos. Pero si vas a escribir uno, mantén el volumen al mínimo.

Una línea para indicar qué herramienta de build usa el repo. Una línea para corregir un patrón que el agente sigue repitiendo mal.

Agrega algo como “si encontrás algo estructuralmente raro, avisá de inmediato” y el agente se convierte en una herramienta que te reporta vulnerabilidades en el codebase. 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.

• Fortalecer los unit tests y los type checks le gana a los archivos de contexto
• Si la ubicación de los archivos es confusa, muévelos en vez de escribir direcciones

Escribir buenos archivos de contexto no es necesariamente señal de habilidad. Entender la estructura de los archivos de contexto y diseñar meta-sistemas alrededor de ellos — eso sí es habilidad. Y a veces, “ser flojo” es la mejor decisión de ingeniería que podés tomar.