Simon Willison replie les descriptions de PR générées par l’IA : l’essentiel des changements en 1 paragraphe

Vous ouvrez une pull request et découvrez plusieurs écrans de texte : définition du problème, conception de la solution, liste des fichiers, vérifications et quelques explications supplémentaires. L’agent a tout décrit consciencieusement. Mais avant de lire ce rapport, vous voulez comprendre une chose : ce qui a changé et pourquoi cela mérite votre attention.

Simon Willison a décrit la méthode qu’il utilise pour ses PR préparées par Claude Code et Codex. En tête, il conserve une courte introduction dont il assume personnellement le contenu. Il place la description complète de l’agent dans un bloc dépliable. GitHub permet de le faire directement dans Markdown avec les balises HTML <details> et <summary>.

Pour une équipe qui reçoit régulièrement des modifications produites par des agents de programmation, cette méthode offre un moyen immédiatement applicable de structurer les descriptions. Elle peut être intégrée à un modèle de PR et aux instructions données à l’agent. Une personne devra toutefois toujours relire la courte introduction.

Ce qui doit rester visible

Willison utilise la PR comme unité de travail : il y rassemble les commits, affine une fonctionnalité, consigne les décisions, puis fusionne le résultat final. Une description détaillée est utile dans ce contexte. Le problème apparaît lorsque le lecteur doit parcourir tout le contenu pour comprendre l’objectif du changement.

Selon lui, les textes des agents peuvent être précis et riches en informations, mais leur longueur suffit à décourager la lecture. Le premier paragraphe doit donc donner rapidement le contexte : quel problème rencontrait l’utilisateur ou le développeur, et ce qui se passe désormais différemment.

Dans l’un des exemples présentés, la page d’un enregistrement affichait les données dans un tableau à une seule ligne. Lorsque les champs étaient nombreux, le tableau s’étendait très loin vers la droite, tandis que le reste de la page demeurait vide. Cette explication donne immédiatement à la personne chargée de la revue le contexte nécessaire pour évaluer la nouvelle présentation. Une capture d’écran permet de voir le résultat avant même d’examiner le code.

Il n’est pas indispensable de rédiger l’introduction de zéro. Willison reprend parfois un passage pertinent du texte de l’agent. L’essentiel est qu’un humain l’ait choisi et le juge digne de l’attention du lecteur.

Comment organiser le bloc dépliable

La balise <details> englobe la partie masquée de la description. À l’intérieur, <summary> définit le titre visible : un clic dessus déploie le reste du contenu. GitHub prend en charge cette structure dans les descriptions de PR et les commentaires des issues.

Willison indique le nom du modèle dans le titre du bloc, en ajoutant parfois son niveau d’effort. Cela précise l’origine du rapport détaillé. Le rapport lui-même est conservé intégralement : le lecteur peut l’ouvrir lorsqu’il a besoin d’explications sur l’implémentation ou d’informations sur les vérifications.

Imaginons une PR qui introduit le chargement différé d’un script d’édition. Au début, il suffit d’expliquer que le script était auparavant chargé sur chaque page et qu’il ne l’est désormais qu’à la première interaction avec la fonction d’édition, pour un utilisateur disposant des droits nécessaires. Il s’agit d’une reformulation de l’un des exemples de l’auteur.

Le rapport de l’agent peut figurer plus bas : quels gestionnaires ont changé, comment le chargement est déclenché et quelles vérifications ont été effectuées. La personne chargée de la revue comprend déjà l’objectif du travail et choisit les détails dont elle a besoin. Pour un responsable produit, le paragraphe d’introduction peut suffire à évaluer l’effet pour l’utilisateur ; un développeur poursuivra son examen dans le code et la description technique.

Les limites de la mise en forme

Un bloc dépliable ne garantit ni la validité des changements ni la fiabilité des vérifications énumérées. Si l’agent affirme que les tests ont réussi, il faut toujours confronter cette affirmation aux résultats de leur exécution. Willison décrit sa propre méthode de travail ; l’article ne présente aucune mesure du temps gagné ou de la qualité des revues.

Il existe aussi une limite éditoriale : les conditions importantes ne doivent pas être dissimulées au point que le lecteur les découvre par hasard. Si le changement exige une migration, modifie la compatibilité ou touche un parcours habituel, il est judicieux de le signaler à côté de l’introduction. Il s’agit ici d’une application pratique de l’approche proposée au travail en équipe.

Vous pouvez essayer cette méthode dès votre prochaine PR : conserver en tête une explication du problème et du résultat, ajouter une capture d’écran utile, puis replier le rapport technique de l’agent. Avant de soumettre la PR à la revue, relisez le premier paragraphe seul. S’il permet de comprendre ce qu’il faudra évaluer, la description a rempli sa première mission.