# Era demasiado vago para escribir el CLAUDE.md — y resulta que acerté > Author: Tony Lee > Published: 2026-02-25 > URL: https://tonylee.im/es/blog/agents-md-context-files-hurt-coding-agent-performance/ > Reading time: 4 minutes > Language: es > Tags: ai, claude-code, agents-md, context-engineering, benchmark, coding-agents ## Canonical https://tonylee.im/es/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 Nuevos datos de benchmarks demuestran que los ficheros de contexto AGENTS.md y CLAUDE.md perjudican el rendimiento de los agentes de código. A veces la pereza es la mejor decisión de ingeniería. ## Summary Era demasiado vago para escribir el CLAUDE.md — y resulta que acerté is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Los ficheros de contexto generados por LLMs empeoran las cosas - Los agentes siguen las instrucciones demasiado bien — y ése es el problema - "No hagas X" hace que los agentes piensen más en X - Si tienes que escribirlo, que sea mínimo ## Content 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"](https://arxiv.org/abs/2602.11988) 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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/es/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/es/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/es/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/es/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/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.