# Era Demasiado Flojo Para Escribir CLAUDE.md — Y Resulta Que Fue la Decisión Correcta > Author: Tony Lee > Published: 2026-02-25 > URL: https://tonylee.im/es-LA/blog/agents-md-context-files-hurt-coding-agent-performance/ > Reading time: 4 minutes > Language: es-LA > Tags: ai, claude-code, agents-md, context-engineering, benchmark, coding-agents ## Canonical https://tonylee.im/es-LA/blog/agents-md-context-files-hurt-coding-agent-performance/ ## Rollout Alternates en: https://tonylee.im/en/blog/agents-md-context-files-hurt-coding-agent-performance/ ko: https://tonylee.im/ko/blog/agents-md-context-files-hurt-coding-agent-performance/ ja: https://tonylee.im/ja/blog/agents-md-context-files-hurt-coding-agent-performance/ zh-CN: https://tonylee.im/zh-CN/blog/agents-md-context-files-hurt-coding-agent-performance/ zh-TW: https://tonylee.im/zh-TW/blog/agents-md-context-files-hurt-coding-agent-performance/ ## Description Datos recientes de benchmarks muestran que los archivos de contexto AGENTS.md y CLAUDE.md en realidad perjudican el rendimiento de los agentes de código. A veces la flojera es la mejor decisión de ingeniería. ## Summary Era Demasiado Flojo Para Escribir CLAUDE.md — Y Resulta Que Fue la Decisión Correcta is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Los archivos de contexto generados por LLMs empeoran las cosas - Los agentes siguen instrucciones demasiado bien — y ese es el problema - "No hagas X" hace que los agentes piensen más en X - Si igual vas a escribir uno, que sea mínimo ## Content 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"](https://arxiv.org/abs/2602.11988) 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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/es-LA/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/es-LA/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/es-LA/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/es-LA/blog/agents-md-context-files-hurt-coding-agent-performance/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/es-LA/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.