Règles de revue de code personnalisées pour Codex

Lors des revues de code avec Codex, certaines remarques reviennent souvent. Il faut parfois préserver un ancien contrat d’API, éviter que des données clients se retrouvent dans les journaux ou conserver un nom dont dépend un autre service. Ces vérifications sont importantes, mais on peut facilement les oublier si seules quelques personnes savent pourquoi elles sont nécessaires.

Lors d’une revue de code, Codex peut désormais s’appuyer sur des règles propres au dépôt, consignées dans AGENTS.md, pour repérer ces problèmes et indiquer aux auteurs la règle qui justifie chaque signalement. Si vous utilisez déjà AGENTS.md pour guider Codex dans ses tâches de programmation, le même fichier peut aussi servir aux revues. C’est particulièrement utile lorsqu’un contributeur ou un agent de programmation intervient dans une partie du dépôt dont il connaît encore mal l’historique. Dans cet article, nous expliquons où placer ces règles et comment les rédiger, à partir notamment de ce que nous avons appris en les testant.

Livrer davantage de code

Les agents de programmation peuvent prendre en charge des changements plus importants et des tâches de longue durée. Les équipes peuvent ainsi concrétiser davantage de leurs idées. Chez OpenAI, le nombre de pull requests par semaine a plus que doublé depuis le quatrième trimestre, et nous observons une tendance similaire chez bon nombre de nos clients. Produire davantage de code permet aux équipes de livrer de nouvelles fonctionnalités et de résoudre plus de problèmes. Mais davantage de pull requests attendent aussi d’être relues par quelqu’un qui sait quoi vérifier, et la revue de code peut vite devenir un goulot d’étranglement.

La revue se complique lorsque plusieurs changements arrivent en même temps. À la lecture du diff, une modification peut sembler tout à fait justifiée et pourtant rendre un ancien client incompatible ou franchir une limite que l’auteur ignorait. Encore faut-il que quelqu’un se souvienne de ce contexte et le communique à l’auteur pendant qu’il peut encore en tenir compte.

Quand la revue de code ralentit l’équipe

À mesure que les pull requests s’accumulent, les personnes qui les relisent ont moins de temps pour comprendre l’objectif de chaque changement et réunir les informations nécessaires avant de commenter. Une fois que l’auteur est passé à autre chose, même une petite correction peut prendre plus de temps. Des retours rapides permettent aux équipes de tirer parti de l’accélération du développement sans que tout le travail s’accumule chez les personnes chargées des revues.

Certains problèmes sont aussi difficiles à repérer à la seule lecture du diff. Renommer un champ de réponse peut sembler anodin lors d’un nettoyage du code, mais risque de rendre incompatibles les clients qui dépendent toujours du contrat existant. Une personne expérimentée se souviendra peut-être de la raison pour laquelle ce champ doit garder son nom. Un nouveau contributeur ou un agent qui intervient pour la première fois sur ce service l’ignorera probablement.

Les règles comme interface

Comment transmettre à un agent de programmation le contexte que votre équipe acquiert au fil du temps ? La nouvelle interface de gestion des règles du dépôt vous permet de consigner dans AGENTS.md des consignes de revue brèves, dont le champ d’application est bien défini. Lors d’une revue de code, Codex peut appliquer les règles pertinentes pour un changement et les citer lorsqu’il signale un problème. Vous pouvez ainsi conserver l’explication à proximité du code concerné et vous épargner de la répéter dans chaque pull request.

À mesure que les modèles de programmation suivent plus finement les consignes, une instruction courte et ciblée peut orienter une revue de longue haleine vers les points qui comptent pour votre équipe. Le dépôt de Codex lui-même contient des règles de revue de code dans AGENTS.md. Elles portent notamment sur le contexte visible par le modèle et les ruptures de compatibilité.

Prenons un exemple réel.

L’App Server de Codex émet une notification interne nommée rawResponseItem/completed. Elle est marquée comme expérimentale, mais Codex Cloud l’utilise déjà. La règle du dépôt sur les ruptures de compatibilité mentionne explicitement rawResponseItem/* parmi les interfaces d’intégration à préserver lors des revues, même au stade expérimental.

Le protocole de l’App Server définit le nom transmis aux clients. Imaginons que l’on modifie une ligne en nettoyant le code.

-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"

Le code compile, mais les clients à l’écoute de la notification existante cesseraient de la recevoir. L’extrait pertinent de la règle du dépôt tient en quelques lignes.

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

Pour le diff de cet exemple, Codex pourrait formuler la remarque suivante lors de la revue de code.

Conservez la notification rawResponseItem/completed sous son nom actuel. Les clients de Codex Cloud écoutent les notifications portant ce nom dans le protocole. Si vous le modifiez, ils ne les recevront plus, même si l’événement est expérimental. Conservez le nom actuel ou ajoutez un événement rétrocompatible, comme le précise AGENTS.md.

L’équipe Codex a ajouté cette règle précisément pour protéger les clients de Codex Cloud. Placez les règles communes à tout le dépôt à la racine et celles qui sont propres à un service dans le répertoire correspondant. Lors d’une revue, Codex peut appliquer les consignes qui couvrent les fichiers modifiés et indiquer la règle pertinente aux auteurs. Un changement sans rapport avec l’App Server ne nécessite aucune connaissance de ce service.

Ces règles complètent les outils que les équipes utilisent déjà. Les tests et les linters conviennent bien aux vérifications dont le résultat peut être déterminé de façon mécanique. Les règles du dépôt permettent de consigner les critères d’appréciation plus difficiles à traduire en code. Les exigences de compatibilité et les limites à respecter dans la circulation des données sont de bons points de départ. Les auteurs peuvent ainsi modifier le code sans connaître tous les incidents passés ni toutes les conventions locales, puisque les consignes pertinentes sont déjà en place.

Rédiger des règles qui restent utiles

Pour évaluer dans quelle mesure Codex pouvait exploiter les consignes du dépôt lors d’une revue de code, nous avons utilisé une suite de tests comprenant des violations connues et des contre-exemples conformes aux règles. Dans la suite principale, les variantes guidées par les règles ont produit 98 % des signalements attendus au titre des règles personnalisées, contre 58,3 % pour la configuration témoin.

Repérer une infraction à une règle n’est qu’une partie du travail. Nous voulions aussi savoir ce qui se passe lorsque plusieurs règles sollicitent l’attention de Codex ou qu’une pull request comporte déjà de nombreuses modifications. Nous avons testé aussi bien des infractions lourdes de conséquences que des changements qui ne justifiaient aucune remarque, puis nous avons organisé les résultats autour de quatre questions.

Nous avons également essayé plusieurs formats courants pour rédiger les consignes, depuis les courtes listes à puces jusqu’aux sections dont une équipe précise assure la maintenance.

Nous avons fait le même constat en utilisant des règles dans nos dépôts internes. Codex pouvait trouver et citer des consignes locales qui auraient pu lui échapper lors d’une revue par défaut, mais les instructions trop générales entraînaient facilement des remarques superflues. Quelques règles ciblées, indiquant explicitement comment procéder sans risque, aidaient Codex à se concentrer sur les points les plus utiles sans appliquer une règle à chaque modification voisine.

Commencez par un invariant important qui ne va pas de soi. Consignez une vérification que les personnes chargées des revues doivent souvent expliquer, par exemple une exigence de compatibilité ou une limite à respecter dans la circulation des données. Si le retrait d’une règle ne change rien à la revue, laissez-la de côté.

Limitez chaque règle au code qu’elle concerne. Placez les consignes communes à tout le dépôt à la racine et celles qui sont propres à un service dans un fichier AGENTS.md de son sous-répertoire. Un périmètre précis évite de disperser l’attention entre des consignes sans rapport et permet de savoir qui en est responsable.

Précisez ce qui doit rester vrai et comment le garantir. La règle concernant rawResponseItem/* indique le risque d’incompatibilité. La consigne « Conservez le nom actuel ou ajoutez un événement rétrocompatible » donne aux auteurs une alternative claire.

Rédigez des règles durables et tenez-les à jour. Décrivez le résultat attendu sans vous appuyer sur des noms de fonctions susceptibles de changer. Relisez les modifications apportées aux règles et, lorsqu’une consigne génère régulièrement des remarques superflues, restreignez son champ d’application ou supprimez-la.

Confiez les vérifications de formatage et les autres contrôles mécaniques à l’intégration continue. Réservez les règles du dépôt aux questions que les personnes chargées de la revue devraient sinon poser à chaque fois.

Premiers pas

Si la revue de code avec Codex est déjà activée dans votre dépôt, ajoutez deux ou trois règles au fichier AGENTS.md approprié et ouvrez une pull request représentative. Si vous découvrez la fonctionnalité, le guide de démarrage de la revue de code explique comment l’activer pour un dépôt GitHub. Vous pouvez aussi demander directement une revue avec @codex review.

Partez d’une explication qui revient souvent dans les revues ou d’une erreur propre au dépôt qui aurait de lourdes conséquences si elle passait inaperçue. Essayez une modification qui devrait déclencher la règle, un contre-exemple qui la respecte et une modification sans rapport. Vérifiez que la première donne lieu à un signalement utile et que les deux autres ne suscitent aucune remarque superflue. Affinez ensuite la consigne en fonction de vos observations.

Codex apporte un regard supplémentaire lors de la revue de code. Les tests, les protections de branches et les approbations obligatoires restent les mécanismes qui imposent le respect des exigences.

Si vous passez plus de temps à relire des modifications qu’à les écrire, commencez par une vérification que votre équipe répète souvent. Ajoutez-la à AGENTS.md et essayez la revue de code avec Codex sur votre prochaine pull request.