Revue par IA

La forme d’une revue

Une revue par IA est une exécution du pipeline pr_review fourni d’origine face à une pull request ouverte. Le pipeline ouvre l’espace de revue de la PR, déploie des agents relecteurs pour lire le diff dans la copie de travail isolée de cet espace, chacun consigne ses remarques sous forme de nœuds de revue structurés, un agent chef de file les consolide en un parcours, et un finaliseur calcule un verdict unique : Ship, Hold ou Block. Ce que le pipeline ne fait jamais, en revanche, c’est publier — la publication sur GitHub est une étape distincte et délibérée qu’un humain déclenche.

Le reste de cette page explique les rouages et pourquoi ils sont conçus ainsi.

Un espace de revue par PR

Le contexte de revue d’une PR est un espace de messagerie — mode review, kind pr — relié à la pull request par une association d’espace de revue. Il est créé de façon idempotente : la page de la PR, le pipeline de revue et les surfaces de chat résolvent tous l’unique espace de la PR par le même chemin de code, de sorte qu’un modèle qui relit une PR et un humain qui l’ouvre ne peuvent jamais se retrouver dans deux salles différentes devant deux copies de travail différentes.

L’arbre de travail isolé de l’espace contient la PR extraite à sa référence de tête. Une seule salle, c’est aussi une seule copie de travail : chaque relecteur travaille dans le même espace au lieu d’obtenir son propre clone de l’espace de travail.

Chaque relecteur publie dans son propre flux nommé au sein de cet espace unique, et les remarques prennent la forme de messages review_node plutôt que de simple prose. La collecte à l’échelle de l’espace en fin de parcours est délibérée : un verdict calculé à partir des remarques d’un seul fil serait silencieusement un verdict sur un seul relecteur.

L’association porte une échelle de statuts — requested → in progress → awaiting approval → completed — qui conditionne le bouton Publier sur GitHub dans l’onglet Revue de la PR.

Niveaux de revue

La profondeur d’une revue relève d’une règle de l’espace de travail à trois niveaux, définie dans Paramètres → Espace de travail → Général, sur la carte Règles de l’espace de travail :

Niveau	Relecteurs déployés	Restitution
light	Ingénieur uniquement	Uniquement ce qui compte vraiment
balanced	Ingénieur, QA, architecte (par défaut)	La passe standard
thorough	Les cinq, y compris sécurité et performance	Rien n’est rétrogradé

Le niveau agit sur deux leviers à la fois : quels relecteurs sont déployés, ce qu’imposent les verrous d’état runWhen du modèle de pipeline plutôt que la formulation du prompt — une formulation de prompt peut être ignorée, pas un verrou —, et où sont restituées les remarques sous le seuil. Aucun des deux leviers ne supprime jamais une remarque : un niveau qui restitue moins en consigne exactement autant et regroupe le reste.

Les passes de sécurité et de performance réutilisent les agents architecte et ingénieur fournis d’origine au lieu d’en introduire de nouveaux. La spécialité tient au brief avec lequel le relecteur est lancé, pas à un agent distinct par axe — un agent par axe, ce serait cinq lignes de plus dans chaque espace de travail pour aucune capacité supplémentaire. La sélection des relecteurs n’inspecte jamais le diff pour en déduire un langage ou un domaine.

Les nœuds de revue : des remarques en données, pas en prose

Une remarque consignée avec add_review_node devient un nœud de revue sur la PR — c’est ce que restitue l’onglet Revue, ce à partir de quoi le verdict est calculé, et ce que « Publier sur GitHub » transforme en commentaire en ligne. Un relecteur qui ne renvoie que de la prose produit une exécution de pipeline qui semble réussie et une surface de revue vide ; c’est la consignation qui fait tout tenir.

Chaque nœud porte :

Champ	Valeurs
Type	bug, suggestion, recommendation, question, ticket
Priorité	P0 (critique) → P3 (détail)
Triplet de triage	catégorie (security, stability, …), gravité, effort
Ancre	Chemin de fichier, début et fin de ligne
Correctif embarqué	Lignes de remplacement suggérées, un diff facultatif, une invite de correction facultative
Confiance	Un score dans [0, 1]
Raisonnement	L’analyse, rédigée avant la remarque

Deux détails sont délibérés. Une suggestion GitHub en un clic n’est proposée que si le relecteur a fourni des lignes de remplacement exactes — les déduire d’un diff unifié se trompe sans bruit, et valider en un clic une déduction erronée est pire que pas de bouton du tout. Et le schéma d’add_review_node présente reasoning avant la remarque, si bien qu’un modèle qui remplit l’objet dans l’ordre du schéma rédige l’analyse en premier. Le champ est facultatif : l’omettre ne fait pas rejeter le nœud. Un nœud dont la charge utile est malformée disparaît plutôt que de polluer la revue.

Consensus entre pairs

Un nœud passe par open → consensus-ready → resolved ou dismissed. L’étape intermédiaire est le cœur du modèle : une remarque n’est validée que lorsqu’un relecteur pair la confirme, et un agent ne peut jamais confirmer sa propre remarque. L’outil MCP publish_review_to_github et la valeur par défaut du RPC ne publient toujours que les remarques confirmées par un pair. Le bouton Publier sur GitHub de l’onglet Revue envoie, lui, toutes les remarques encore ouvertes.

La règle est appliquée à trois endroits indépendants — l’outil de confirmation, le finaliseur et le composant de publication — si bien qu’elle survit à un appelant défectueux dans l’un d’eux. Tous les changements de statut passent par un seul service, et c’est ce qui donne du sens à un statut : avant cela, deux demi-chemins pouvaient diverger sur le fait qu’une même remarque était résolue.

Quand des relecteurs ne sont pas d’accord — même fichier et même ligne, priorités séparées de deux niveaux ou plus, ou l’un qui parle de bug là où l’autre parle de suggestion —, le désaccord est mis en évidence au-dessus de la liste des remarques. C’est là que les avis des relecteurs divergent et que le jugement d’un humain compte le plus.

Rejeter une remarque écrit aussi un fait de suppression douce dans le domaine de la mémoire, à faible confiance : un rejet est une préférence, pas une règle.

Les cohortes : ce autour de quoi la revue se regroupe

La passe de calcul de la revue regroupe les fichiers modifiés d’une PR en cohortes dérivées du graphe de code : les fichiers modifiés correspondent aux symboles qu’ils touchent, les symboles aux composants connexes, et les cohortes sont classées par rayon d’impact. Une cohorte porte un ordre de lecture guidé, des diagrammes et des éclairages, au lieu d’être une simple liste de fichiers.

Deux règles d’honnêteté façonnent cela. Les clés de cohorte sont dérivées du contenu et stables d’un push à l’autre, si bien que les remarques et la progression de la revue survivent à un rebase ou à un force-push au lieu d’être orphelinées. Et quand le dépôt n’a pas d’index de code, le regroupement se replie sur les chemins bruts et le dit — ce repli ne simule jamais une confiance sémantique.

Axes de revue et verrous

Parallèlement aux remarques des relecteurs, une revue accumule des résultats d’axe : six axes, de deux sortes.

Axe	Sorte	Calculé à partir de
correctness, security	Piloté par les tokens	Les remarques des relecteurs elles-mêmes
testGap	Piloté par les tokens	Les remarques des relecteurs
visual, apiContract	Déterministe	Calculé sans dépenser de tokens
performance	Déterministe	Énumération seule — rien dans le produit ne calcule de résultat

Un verdict d’axe vaut pass, warn, fail, partial ou unavailable — et seuls pass et warn franchissent un verrou. La distinction entre fail, partial et unavailable est structurante : un axe soumis à verrou qui n’a pas pu aboutir ou qui n’a pas pu s’exécuter du tout retient le verdict global au lieu de le valider. L’absence de preuve ne se transforme jamais en verrou vert.

Certains axes sont volontairement indicatifs. L’axe des lacunes de tests dérivé des cohortes ne voit pas la couverture des injections de dépendances ni celle des fabriques — un dépôt sans index avec une suite exhaustive et un dépôt sans aucun test sont identiques de ce point de vue, donc affirmer l’un ou l’autre serait un mensonge ; il apparaît dans le tableau de bord sans bloquer. Les axes pilotés par les tokens sont indicatifs parce que les priorités des remarques déterminent déjà le verdict, et les remettre sous verrou reviendrait à compter double.

Le verdict

Le finaliseur calcule le verdict sur les remarques dont le statut est open ou consensus-ready :

• toute remarque P0 avec une confiance ≥ 0,7 → Block
• sinon, toute remarque P0 (à faible confiance) ou toute P1 → Hold
• sinon → Ship

Le verdict porte une confiance agrégée dérivée de la dispersion des confiances contributrices : l’accord la fait monter, la divergence la fait baisser.

La consolidation de l’agent chef de file (le CEO) est une passe éditoriale, pas une re-liste : une deuxième copie des remarques écrite à la main est précisément ce qui finit par diverger de la vraie. Les remarques en double sont rétrogradées plutôt que répétées — plusieurs relecteurs sont pointés sur un même diff avec des périmètres délibérément chevauchants, si bien que le même défaut arrivant trois fois au finaliseur est le système qui fonctionne ; le publier trois fois, c’est le système qui laisse fuiter sa propre architecture dans la boîte de réception du lecteur. Lors d’une nouvelle revue, les remarques reçoivent une empreinte et sont comparées à la passe précédente, de sorte que seul le delta ressort.

Enfin, les axes s’y ajoutent, et ils ne peuvent que rendre le verdict plus sévère : un axe en échec soumis à verrou force Block — il ne peut pas être mis en minorité par les remarques — et un axe soumis à verrou qui n’a pas pu aboutir force au moins Hold.

La publication vous revient

Le pipeline ne publie délibérément pas sur GitHub ; la publication est conditionnée par l’utilisateur, de sorte qu’une revue ne peut jamais publier deux fois. Quand vous appuyez sur Publier sur GitHub :

• Une seule revue GitHub est envoyée. Les remarques déjà résolues ou rejetées sont ignorées. Le bouton publie toutes les remarques encore ouvertes (selection: all_open). L’outil MCP publish_review_to_github reste par défaut limité aux remarques confirmées par un pair (consensus).
• Les remarques ancrées à un fichier et à une ligne deviennent des commentaires en ligne ; tout le reste est replié dans le corps du résumé, chacune portant un pied de page « — Control Center AI review » pour que la source soit sans ambiguïté.
• Les ancres sont revérifiées par rapport au diff actuel de la PR au moment de la publication. Un commentaire sur du code déjà réécrit est ce qui détruit le plus la confiance qu’un relecteur peut laisser ; si GitHub rejette malgré tout une ancre en ligne, toute la revue est renvoyée avec chaque remarque repliée dans le corps, pour que rien ne soit abandonné en silence.
• Un verdict Block est envoyé comme REQUEST_CHANGES ; Hold comme COMMENT ; Ship comme APPROVE depuis le bouton (approve_on_ship: true). L’outil MCP laisse Ship en COMMENT tant que vous ne passez pas approve_on_ship.
• La revue est publiée sous l’identité applicative du serveur. La personne qui a appuyé sur Publier est enregistrée pour le contrôle de rôle et le journal d’audit ; ce n’est pas l’auteur GitHub.

La publication déclare la classe d’action prPublish, de sorte que le point de passage des garde-fous la soumet au même verrou que toute action mutante : elle demande une approbation par défaut et refuse l’action si aucun approbateur n’est connecté. Voir Garde-fous.

Ce qu’un relecteur peut faire

Les agents relecteurs s’exécutent en mode review : un bac à sable en lecture seule et une liste d’autorisation d’outils sélectionnés couvrant les remarques, les commentaires, les tickets et la relecture par les pairs — mais aucune mutation. Un relecteur ne peut pas corriger le code qu’il critique ; il peut joindre un correctif suggéré qu’un humain applique. Le message de refus du mode invite un agent qui tente malgré tout d’agir à finaliser la revue et à laisser l’utilisateur agir sur le résumé publié.

Concepts liés

• Garde-fous — le moteur de règles qui conditionne la publication
• Modes — ce que le mode review change pour un agent
• Pipelines et automatisation — le moteur sur lequel tourne la revue
• Cycle de vie du lancement d’un agent — d’où vient l’arbre de travail isolé

Guides pratiques

• Utiliser la revue assistée par IA — lancer une revue et la publier
• Lancer des agents relecteurs — choisir vous-même les relecteurs
• Calcul de revue — cohortes, axes et diffs