¿Cuántas veces ha escrito hoy alguien de tu equipo algo como «te dije que no tocaras ese archivo» o «eso no es lo que te pedí»? Cada una de esas frases explica qué le faltaba al agente para hacerlo bien. En la mayoría de los equipos se queda en el historial de una sesión que nadie vuelve a abrir.
Lo que tu equipo corrige cada día al agente es la lista de lo que le falta a vuestra forma de trabajar con él, y casi nadie la guarda.
Qué analizaron en 20.574 sesiones reales
Ningzhi Tang, Toby Jia-Jun Li y otros seis investigadores publicaron en mayo de 2026, con una revisión en agosto, un análisis de 20.574 sesiones reales con agentes de código, de 1.639 repositorios, tanto en el editor como en la terminal. Salen de dos fuentes públicas: 14.789 historiales de chat que los desarrolladores subieron a sus repositorios de GitHub y 5.785 sesiones de terminal de personas que aceptaron registrarlas en abierto.
Los autores llaman desalineamiento a cada momento en que el desarrollador frena o corrige al agente. Validaron 16.118 episodios y anotaron de cada uno qué forma tuvo, por qué pasó, qué costó y cómo se resolvió.
Qué corrigen las personas
El código que no funciona es solo la cuarta forma de fallo. Estas son las más frecuentes; un mismo episodio puede tener varias:
- Saltarse una restricción que el desarrollador había dicho: 38,33 % de los episodios.
- Entender mal la petición: 26,95 %.
- Informar mal de su propio trabajo: 22,58 %.
- Escribir código erróneo: 17,82 %.
En las causas, la primera es que el agente no siguió una instrucción que sí tenía (36,49 %). Le siguen una instrucción poco concreta (15,36 %) y actuar antes de conocer el proyecto (11,11 %). En un 26,85 % de los episodios, los autores no pudieron saber la causa.
Por qué la misma corrección vuelve
La corrección vive en el chat. Cuando la sesión termina, la siguiente empieza sin ella, salvo que alguien la haya llevado a un sitio que el agente lea o a una comprobación que se ejecute sola. El estudio mide que los fallos se repiten de una sesión a la siguiente en el mismo repositorio, y es razonable pensar que buena parte de esa repetición viene de que nadie lleva la corrección a un sitio fijo; esa lectura es nuestra y el estudio no la prueba.
Además, los fallos cambian con el tiempo. La tasa general de desalineamiento por turno baja, pero dentro de los que quedan pesan cada vez más las restricciones ignoradas y los informes inexactos. Los dos se arreglan mejor fuera del chat: una restricción que hay que repetir en cada sesión necesita un sitio fijo, y un informe del que no te puedes fiar necesita algo que lo compruebe.
Cómo guardar lo que corrige tu equipo
Una forma de hacerlo en una semana, sin herramientas nuevas:
- Cada vez que alguien frena al agente, lo apunta en una línea: qué pasó y de qué tipo fue, con las formas del estudio como lista (restricción saltada, petición mal entendida, informe inexacto, código erróneo).
- Al final de la semana, el equipo mira qué líneas se repiten. Una corrección que sale una sola vez se queda donde está.
- Lo que se repite se lleva a su sitio: al archivo de instrucciones si es algo del repositorio que el agente no puede deducir del código, a la especificación si es de un tipo de tarea, y a un permiso o una comprobación automática si no se puede saltar nunca.
- Se revisa en un rato corto y sin buscar culpables, como en un postmortem sin culpa: el análisis que los equipos de SRE (la ingeniería de fiabilidad de sistemas de Google) hacen tras un incidente para encontrar sus causas sin acusar a ninguna persona ni a ningún equipo.
- A la semana siguiente se mira si esa corrección ha vuelto. Si vuelve, el sitio elegido no era el bueno.
Así podría quedar el registro de una semana (ejemplo inventado):
lun · restricción saltada · tocó las migraciones; se le había dicho que no
lun · informe inexacto · dijo que los tests pasaban; no se habían lanzado
mar · restricción saltada · volvió a tocar las migraciones
mié · petición mal entendida · rehízo el módulo entero; se pedía un método
jue · restricción saltada · migraciones, otra vezLas migraciones salen tres veces en cuatro días. Una regla que el agente se salta tantas veces va a un permiso que le impida tocarlas (dónde va cada regla en Claude Code). El informe inexacto pide que los tests se lancen solos antes de dar nada por terminado. Y si la petición mal entendida se repitiera, quizá falta una convención en el archivo del agente (qué dejar en ese archivo).
Límite Las sesiones son de desarrolladores que publicaron sus historiales; los equipos de empresa, con sus propias reglas, pueden fallar de otra forma. Solo el 9,33 % de los episodios deja ver cómo se resolvió, y el 91,49 % se calcula sobre esa parte. Los propios autores avisan de que la revisión continua del desarrollador, de la que hoy depende casi toda resolución visible, difícilmente escalará cuando los agentes trabajen más tiempo solos.
Una semana de prueba
Pide a tu equipo que esta semana apunte cada corrección al agente en una línea, en un documento compartido. El viernes tendréis la primera lista de lo que le falta a vuestra forma de trabajar con agentes, que es justo la parte que no viene con la herramienta.
Como dice Manel Marcos, nuestro CTO: “La mejora continua de los agentes y de las skills forma parte de nuestro día a día y así construimos un flujo que cada vez funciona mejor. Auditamos de forma habitual la deriva de la documentación y del proceso de Spec-Driven Development (SDD, desarrollo guiado por especificaciones), y para ello usamos el agente orquestador SDD. Esos archivos no los tocamos a mano: le pedimos que nos ayude a mejorarlos.”
Si quieres revisar esa lista con alguien de fuera, el diagnóstico es gratuito. Cómo trabajamos con equipos de desarrollo: AI-Accelerated Development.
Preguntas frecuentes
¿Por qué fallan los agentes de código?
En un análisis de 20.574 sesiones reales, el fallo más frecuente fue saltarse una restricción que el desarrollador había dicho (38,33 % de los episodios), por delante de entender mal la petición (26,95 %), informar mal de su propio trabajo (22,58 %) y escribir código erróneo (17,82 %).
¿Por qué el agente de código no sigue las instrucciones?
En el estudio, la causa más frecuente fue que el agente no siguió una instrucción que sí tenía (36,49 % de los episodios). Una instrucción poco concreta explica otro 15,36 %. Lo que no se puede saltar nunca conviene llevarlo a permisos o comprobaciones automáticas.
¿El agente de código se corrige solo?
Pocas veces. De los episodios en los que se ve cómo se resolvieron, el 91,49 % se arregló después de que la persona corrigiera al agente, y solo el 2,99 % lo corrigió el agente por su cuenta.
¿Los fallos del agente se repiten de una sesión a otra?
En el mismo repositorio, cuando una sesión tuvo un desalineamiento, la siguiente también lo tuvo en el 51,9 % de los casos, frente al 33,6 % cuando la anterior no lo tuvo.
¿Cómo mejora un equipo el trabajo con su agente de código?
Apuntando cada corrección con su tipo y revisando cada semana cuáles se repiten para llevarlas a su sitio: el archivo de instrucciones, la especificación de la tarea o un permiso o comprobación automática.
¿Qué es un postmortem sin culpa?
Es el análisis que hace un equipo después de un fallo para encontrar las causas que lo provocaron sin acusar a ninguna persona ni a ningún equipo. Lo describe el libro de SRE de Google, y sirve también para revisar las correcciones al agente.
Fuentes
- Ningzhi Tang, Chaoran Chen, Gelei Xu, Yiyu Shi, Yu Huang, Collin McMillan, Tao Dong y Toby Jia-Jun Li, «How Coding Agents Fail Their Users: A Large-Scale Analysis of Developer-Agent Misalignment in 20,574 Real-World Sessions», arXiv:2605.29442, v2 del 31 de agosto de 2026 (v1 del 28 de mayo de 2026).
- John Lunney y Sue Lueder, «Postmortem Culture: Learning from Failure», capítulo 15 de Site Reliability Engineering, Google y O'Reilly, 2017.
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 →