Simon Willison pliega las descripciones de PR generadas por IA: los cambios en 1 párrafo

Abres un pull request y te encuentras varias pantallas de texto: el planteamiento del problema, el diseño de la solución, la lista de archivos, las comprobaciones y algunas explicaciones más. El agente lo ha documentado todo con esmero. Pero antes de leer ese informe, quieres entender una cosa: qué ha cambiado y por qué merece tu atención.

Simon Willison ha descrito una técnica que utiliza en sus PR preparados con Claude Code y Codex. Deja al principio una breve introducción de cuyo contenido se responsabiliza personalmente. La descripción completa del agente va en una sección desplegable. GitHub permite hacerlo directamente en Markdown con las etiquetas HTML <details> y <summary>.

Para un equipo que recibe habitualmente cambios de agentes de programación, es una forma lista para usar de poner orden en las descripciones. Se puede incorporar mediante una plantilla de PR y una instrucción para el agente. Eso sí, una persona tendrá que leer la breve introducción de todos modos.

Qué debe quedar a la vista

Willison utiliza el PR como unidad de trabajo: agrupa en él los commits, perfecciona una funcionalidad, documenta las decisiones y finalmente integra el resultado terminado. Aquí resulta útil contar con una descripción detallada. El problema surge cuando el lector tiene que recorrer todo el material para averiguar el propósito del cambio.

Según su experiencia, los textos de los agentes pueden ser precisos e informativos, pero su propia extensión desanima a leerlos. Por eso, el primer párrafo debe situar rápidamente al lector: qué problema tenía el usuario o el desarrollador y qué funciona ahora de otra manera.

En uno de los ejemplos que presenta, la página de un registro individual mostraba los datos en una tabla de una sola fila. Cuando había muchos campos, la tabla se extendía mucho hacia la derecha y el resto de la página quedaba vacío. Esa explicación proporciona de inmediato el contexto necesario para evaluar la nueva vista. Una captura de pantalla permite ver el resultado incluso antes de estudiar el código.

No es necesario escribir la introducción desde cero. A veces, Willison toma un fragmento adecuado del texto del agente. Lo importante es que una persona lo haya seleccionado y considere que merece la atención del lector.

Cómo preparar la sección desplegable

La etiqueta <details> envuelve la parte oculta de la descripción. En su interior, <summary> define el encabezado visible: al pulsarlo, se despliega el resto del contenido. GitHub admite esta estructura en las descripciones de PR y en los comentarios de las incidencias.

Willison incluye el nombre del modelo en el encabezado de la sección y, en ocasiones, añade el nivel de esfuerzo. Así identifica la procedencia del informe detallado. El informe se conserva íntegro: el lector puede abrirlo cuando necesite explicaciones sobre la implementación o información sobre las comprobaciones.

Pensemos en un PR que aplaza la carga de un script de edición. Al principio basta con explicar que antes el script se cargaba en todas las páginas y que ahora se carga cuando un usuario con los permisos necesarios interactúa por primera vez con la función de edición. Es una paráfrasis de uno de los ejemplos del autor.

Debajo se puede colocar el informe del agente: qué manejadores han cambiado, cómo se activa la carga y qué comprobaciones se han realizado. Quien revisa ya entiende el propósito del trabajo y decide qué detalles necesita. A un responsable de producto puede bastarle el párrafo introductorio para evaluar el impacto en los usuarios; un desarrollador continuará examinando el código y la descripción técnica.

Los límites del formato

Una sección desplegable no demuestra que los cambios sean correctos ni convierte en fiables las comprobaciones enumeradas. Si el agente afirma que las pruebas han pasado, sigue siendo necesario contrastarlo con los resultados de la ejecución. Willison describe su método de trabajo; el artículo no aporta mediciones del ahorro de tiempo ni de la calidad de las revisiones.

También hay un límite editorial: las condiciones importantes no deben quedar ocultas de tal forma que el lector solo las descubra por casualidad. Si un cambio requiere una migración, afecta a la compatibilidad o modifica un flujo de trabajo habitual, conviene indicarlo junto a la introducción. Esta es una aplicación práctica del enfoque propuesto al trabajo en equipo.

Puedes probar la técnica en tu próximo PR: deja al principio una explicación del problema y del resultado, añade una captura de pantalla útil y después pliega el informe técnico del agente. Antes de enviarlo a revisión, lee el primer párrafo por separado. Si permite entender qué habrá que evaluar, la descripción habrá cumplido su primera función.