El problema oculto de los agentes de código: cuando las descripciones de PR son demasiado buenas

El problema oculto de los agentes de código: cuando las descripciones de PR son demasiado buenas
Foto de Zulfugar Karimov en Unsplash

Los agentes de IA ya escriben mejor que la mayoría de los desarrolladores... y eso se ha convertido en un problema real. Cuando Claude Code o Codex abren un Pull Request por ti, generan descripciones tan exhaustivas y precisas que, paradójicamente, nadie las lee.

El nuevo flujo de trabajo con agentes de codificación

Cada vez más equipos de desarrollo están adoptando un modelo donde el agente es el que abre los Pull Requests. No es una curiosidad técnica, es una transformación silenciosa del flujo de trabajo profesional. El desarrollador define el objetivo, el agente itera sobre los commits, documenta las decisiones tomadas y presenta el resultado listo para revisar y mergear.

En este esquema, el PR deja de ser un trámite burocrático y se convierte en la unidad real de trabajo, el contenedor donde vive tanto el código como la narrativa de por qué ese código existe. Hasta aquí, todo suena ideal.

Cuando la exhaustividad se vuelve ruido

El problema es que los agentes actuales son demasiado buenos describiendo el trabajo. Una descripción generada por un agente es precisa, completa y bien estructurada. Cubre cada cambio, explica cada decisión, anticipa preguntas de revisión. En teoría, perfecto. En la práctica, genera un muro de texto que el revisor humano ignora por completo.

Aquí emerge una tensión que vale la pena nombrar con claridad: la completitud no equivale a utilidad. Un documento que lo explica todo no comunica nada prioritario. El cerebro humano no procesa bloques densos de texto técnico generado automáticamente del mismo modo en que procesa un resumen escrito por un compañero que sabe qué es lo importante.

El resultado práctico es que los revisores saltan directamente al diff, ignorando la descripción. Con ello se pierde precisamente lo más valioso que aporta el agente, el contexto y el razonamiento detrás de los cambios.

Una solución elegante: ocultar sin eliminar

La propuesta que está ganando tracción en algunos flujos de trabajo avanzados es usar el elemento HTML <details> y <summary> de Markdown en GitHub para colapsar la descripción detallada del agente detrás de un bloque expandible. Así, el PR muestra en primera línea un resumen humano breve y accionable, mientras que el texto exhaustivo del agente queda disponible para quien quiera profundizar, sin invadir la pantalla de nadie.

La estructura es simple pero efectiva. El revisor ve de entrada lo esencial, lo que necesita saber para aprobar o pedir cambios. Si necesita el detalle completo, lo expande. Si no, no pierde tiempo procesando información que no pedía.

Esto refleja un principio más amplio que conviene interiorizar en la era de los agentes: el output del agente no es el producto final, es la materia prima. Igual que no publicarías el borrador bruto de un LLM como artículo de blog sin edición, no deberías presentar la descripción del agente sin una capa mínima de curaduría humana que priorice y contextualice.

Lecciones para equipos que trabajan con IA

Este caso aparentemente pequeño, cómo estructurar una descripción de PR, revela algo más profundo sobre cómo integrar agentes en flujos de trabajo profesionales:

  • La voz del agente y la voz del humano tienen funciones distintas. El agente documenta; el humano comunica.
  • Más información no es mejor comunicación. Diseña el output pensando en quién lo consume y cuánta atención tiene disponible.
  • Los estándares de equipo deben evolucionar. Si tus plantillas de PR no contemplan que el 80% de las descripciones serán generadas por agentes, ya están desactualizadas.
  • El contexto colapsado sigue siendo contexto. No hay que elegir entre transparencia y legibilidad, se pueden tener ambas con la estructura adecuada.

Conclusión

La irrupción de los agentes de codificación en el día a día del desarrollo profesional no es solo una cuestión de productividad, es una cuestión de diseño de comunicación. El código que genera un agente puede ser excelente; la forma en que ese trabajo se presenta al equipo humano es responsabilidad nuestra.

¿Tu equipo ya tiene un protocolo para gestionar el output de los agentes en las revisiones de código? Si no, quizás este es el momento de definirlo antes de que el ruido supere a la señal.