El agente de código lee su archivo de instrucciones, el CLAUDE.md o el AGENTS.md, al empezar cada tarea. Si ese archivo lo escribió un modelo, cada tarea cuesta de media más de un 20 % más y el agente resuelve prácticamente las mismas.
El archivo del agente se escribe con lo que el agente no puede deducir del código. Todo lo demás le hace dar más pasos y gastar más tokens sin ayudarle a resolver la tarea. Un buen archivo sale más de lo que el equipo quita que de lo que añade.
Qué midió el estudio de ETH Zúrich
Thibaud Gloaguen, Niels Mündler-Sasahara y Martin Vechev, de ETH Zúrich, con Mark Niklas Müller y Veselin Raychev, de LogicStar.ai, midieron qué pasa cuando un agente trabaja con y sin archivo de instrucciones. Probaron Claude Code con Sonnet 4.5, Codex con GPT-5.2 y con GPT-5.1 mini, y Qwen Code. Usaron 300 tareas de SWE-bench Lite, de 11 repositorios sin archivo de instrucciones, y 138 de un banco propio, sacadas de 12 repositorios que ya tenían su archivo escrito por desarrolladores.
Con un archivo generado por un modelo, las tareas resueltas bajaron de media un 0,5 % en SWE-bench Lite y un 2 % en el banco propio, y el coste subió un 20 % y un 23 %. Con el archivo escrito por desarrolladores, en el banco propio, las tareas resueltas subieron un 2,4 % de media y el coste, hasta un 19 %. Ninguna de esas diferencias de acierto es estadísticamente significativa. La que sí lo es: los archivos escritos por personas resolvieron de media un 7 % más que los generados.
El agente obedece lo que lee. Cuando el archivo mencionaba la herramienta uv, el agente la usaba 1,6 veces por tarea; cuando no, casi nunca. Con el archivo, además, lanzaba más tests y buscaba y leía más archivos. Y el resumen del repositorio, que tenían ocho de los doce archivos de los desarrolladores, no le hacía llegar antes al archivo que había que cambiar. Al quitar del repositorio toda la documentación, los archivos generados sí ayudaron: lo que aportaban era una copia de lo que ya estaba escrito.
Límite Son tareas de un banco de pruebas, todas en Python, y el estudio solo mide si la tarea se resuelve: deja fuera la seguridad y la eficiencia del código. Las diferencias de acierto son pequeñas. Lo más sólido es el coste y que el agente hace caso de cada línea.
Qué se queda en el archivo
Los autores lo concretan: el archivo escrito por personas debe llevar solo las instrucciones que el agente necesita y que no están ya en el README, como convenciones propias o requisitos no funcionales. Con eso, lo que se queda cabe en tres grupos:
- Comandos propios del repositorio, sobre todo los que no son los habituales: con qué se instalan las dependencias, qué tests se lanzan antes de cada cambio.
- Convenciones que el código no deja ver: en qué zona horaria se guardan las fechas, qué versión de la API está congelada.
- Requisitos que no se ven en el código: un límite de rendimiento, una tabla que no admite consultas sin índice.
Sale el mapa de carpetas, la descripción del producto, lo que ya dice el README y las reglas de estilo que ya aplica el linter. Salen también las instrucciones de una sola tarea: GitHub, en el ejemplo de su documentación, pide que las instrucciones del repositorio «must not be task specific» y que no pasen de dos páginas. Ese mismo ejemplo pide un resumen del repositorio y de su estructura, justo lo que el estudio no ve útil. Los autores lo dicen sin rodeos: su recomendación va en contra de lo que aconsejan los fabricantes de agentes.
Queda fuera una tercera cosa: las reglas que no se pueden saltar nunca. Si una regla tiene riesgo, va en permisos o en una comprobación automática, por lo que cuento en dónde va cada regla en Claude Code.
Cómo podar el archivo, línea a línea
Una forma de hacerlo con el archivo que ya tiene tu equipo:
- Para cada línea, pregúntate si el agente podría deducirla del código, del README o de la configuración del linter. Si puede, se borra.
- Si la línea solo sirve para una tarea, pásala a la especificación de esa tarea.
- Si es una regla que nunca se puede saltar, como no tocar las migraciones o no leer secretos, llévala a un permiso o a una comprobación automática.
- Revisa lo que queda en una pull request, la propuesta de cambio que el equipo revisa antes de incorporarla, como cualquier otro cambio del repositorio.
- Lanza el mismo puñado de tareas antes y después, y compara los pasos y el coste. Los autores piden evaluar cualquier cambio en el archivo antes de darlo por bueno.
Así podría quedar un archivo después de la poda. Es un ejemplo inventado, de ningún equipo real:
# Comandos
- Dependencias con uv: `uv sync`. No usar pip.
- Antes de cada commit: `make test-fast`. La suite completa solo corre en CI.
# Convenciones que no son las habituales
- Las fechas se guardan en UTC y se muestran en Europe/Madrid.
- Los endpoints nuevos van en /v2. /v1 está congelado.
# Requisitos que no se ven en el código
- Ninguna consulta nueva sobre orders sin índice: la tabla tiene 40 millones de filas.Lo que salió de ese archivo: tres párrafos sobre el producto, el árbol de carpetas y doce reglas de estilo que el linter ya comprobaba.
Por dónde empezar esta semana
Abre el archivo de instrucciones de tu equipo y cuenta cuántas líneas pasan el primer paso. Si pasan pocas, el archivo está trabajando contra el agente. Si estáis ordenando dónde va cada cosa en vuestra forma de trabajar con agentes, las plantillas gratuitas de SDD (Spec-Driven Development, el desarrollo guiado por especificaciones) son un punto de partida.
Si quieres revisarlo con alguien de fuera, el diagnóstico es gratuito. Antes, puedes ver cómo trabajamos con equipos de desarrollo en AI-Accelerated Development.
Preguntas frecuentes
¿Qué es AGENTS.md y en qué se diferencia de CLAUDE.md?
Los dos son archivos de instrucciones que el agente de código lee al empezar a trabajar en un repositorio. CLAUDE.md es el que lee Claude Code. AGENTS.md es un nombre que aceptan varios agentes: GitHub Copilot, por ejemplo, lee AGENTS.md y acepta CLAUDE.md o GEMINI.md en la raíz como alternativa. Lo que conviene poner dentro es lo mismo en todos.
¿Conviene que el propio agente genere el archivo?
No. En el estudio de ETH Zúrich, los archivos generados por un modelo no mejoraron las tareas resueltas y subieron el coste más de un 20 % de media. Sus autores recomiendan no usarlos de momento y escribir el archivo a mano, solo con lo que no esté ya en el README.
¿Qué debe incluir un CLAUDE.md o un AGENTS.md?
Lo que el agente no puede deducir leyendo el código o el README: por ejemplo, que las dependencias se instalan con uv o un límite de rendimiento que no se ve en el código.
¿Ayuda poner un resumen del repositorio en el archivo?
En el estudio, no. Ocho de los doce archivos escritos por desarrolladores tenían un resumen del código, y con ellos el agente no llegaba antes al archivo que había que cambiar. Ese resumen se puede quitar.
¿Cuánto debe ocupar el archivo de instrucciones?
El estudio no da un número. GitHub, en el ejemplo de su documentación, pide que las instrucciones no pasen de dos páginas y que no sean de una tarea concreta. Un criterio práctico: cada línea tiene que responder a algo que el agente no puede averiguar por su cuenta.
¿El agente hace caso de lo que pone el archivo?
Sí. En el estudio, cuando el archivo mencionaba la herramienta uv, el agente la usaba 1,6 veces por tarea de media; cuando no la mencionaba, casi nunca. Por eso cada línea cuenta, también las que sobran. Lo que tiene que cumplirse siempre conviene llevarlo a permisos o comprobaciones automáticas.
Fuentes
- Thibaud Gloaguen, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev y Martin Vechev, «Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?», arXiv:2602.11988, v3 del 29 de septiembre de 2026 (v1 del 12 de febrero de 2026).
- GitHub Docs, «Adding repository custom instructions for GitHub Copilot» (sin fecha; consultada el 4 de noviembre de 2026).
Bernat López es fundador y CEO de onext, boutique de IA. Acompaña a equipos de desarrollo y de producto a trabajar con IA con método —especificación antes de programar, una persona que decide donde hay riesgo y Spec-Driven Development— y aplica a su propia empresa lo que propone: onext funciona con su propio sistema agéntico.
LinkedIn →