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

Lors des revues de code avec Codex, certains commentaires reviennent régulièrement. Il peut s’agir de préserver un ancien contrat d’API, d’éviter que des données clients se retrouvent dans les journaux ou d’empêcher un renommage qui casserait un autre service. Ces vérifications sont importantes, mais il est facile de les oublier lorsque seules quelques personnes chargées des revues connaissent le contexte.

La revue de code Codex peut désormais s’appuyer sur des règles personnalisées du dépôt dans AGENTS.md pour détecter ces problèmes et orienter les auteurs vers les consignes qui justifient un signalement. Si vous utilisez déjà AGENTS.md pour guider les tâches de programmation, le même fichier peut aussi guider les revues. C’est particulièrement utile lorsque des contributeurs ou des agents de programmation interviennent dans une partie du dépôt qu’ils connaissent mal et dont ils ignorent peut-être encore l’historique. Dans cet article, nous verrons où les règles du dépôt trouvent leur place et comment bien les rédiger, en nous appuyant notamment sur les enseignements de nos tests.

Livrer davantage de code

Les agents de programmation peuvent prendre en charge des modifications plus importantes et travailler sur des périodes plus longues, ce qui aide les équipes à concrétiser davantage d’idées dans le code. Chez OpenAI, le nombre hebdomadaire de PRs a plus que doublé depuis le quatrième trimestre, et nous observons des tendances similaires chez nombre de nos clients. Produire davantage de code est une bonne chose : cela permet aux équipes de livrer de nouvelles fonctionnalités et de résoudre davantage de problèmes. Mais cela signifie aussi que davantage de pull requests attendent une personne qui sait quoi vérifier, et la revue de code peut vite devenir un goulot d’étranglement.

La revue devient plus difficile lorsque plusieurs modifications arrivent en même temps. Un diff peut sembler tout à fait raisonnable et pourtant casser un ancien client ou franchir une limite que son auteur ignorait. Quelqu’un doit se souvenir de ce contexte et le partager tant que l’auteur peut encore en tenir compte.

La revue comme goulot d’étranglement

Lorsque les pull requests se multiplient, les personnes chargées des revues ont moins de temps pour comprendre l’objectif de chaque modification et réunir le contexte pertinent avant de donner leur avis. Une fois que l’auteur est passé à autre chose, même une petite correction peut prendre plus de temps. Des retours rapides aident les équipes à tirer parti de l’accélération du développement sans que les personnes chargées des revues deviennent le goulot d’étranglement.

Certains problèmes sont également difficiles à repérer à partir du seul diff. Renommer un champ de réponse peut sembler être un simple nettoyage, mais cela peut casser des clients qui dépendent encore du contrat existant. Une personne expérimentée dans les revues se souviendra peut-être de la raison pour laquelle ce champ doit être conservé ; un nouveau contributeur ou un agent qui intervient pour la première fois sur le service ne la connaîtra probablement pas.

Les règles comme interface

Comment transmettre à un agent de programmation le contexte que votre équipe acquiert habituellement au fil du temps ? La nouvelle interface de règles du dépôt permet de placer dans AGENTS.md des consignes de revue concises, dont le périmètre est bien défini. La revue de code Codex peut appliquer les règles pertinentes pour une modification et les citer dans un signalement. Au lieu de répéter la même explication dans chaque pull request, vous pouvez la conserver à proximité du code concerné.

Les modèles de programmation suivent de mieux en mieux les consignes : une instruction courte et bien ciblée peut donc aider à concentrer une longue revue sur ce qui compte vraiment pour votre équipe. Le dépôt Codex lui-même contient des règles de revue de code dans AGENTS.md, qui couvrent notamment le contexte visible par le modèle et les modifications qui rompent la compatibilité.

Voici 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 de revue du dépôt relative aux ruptures de compatibilité mentionne explicitement rawResponseItem/* comme une interface d’intégration à préserver lors des revues, même tant qu’elle reste expérimentale.

Le nom actuellement utilisé dans les échanges est défini dans le protocole de l’app-server. Imaginez qu’un nettoyage modifie une ligne :

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

Le code modifié compile, mais les clients à l’écoute de la notification existante cesseraient de la recevoir. L’extrait pertinent des règles du dépôt est concis :

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

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

Pour ce diff donné à titre d’exemple, un signalement de la revue de code pourrait être formulé ainsi :

Conservez la notification existante rawResponseItem/completed. Les composants de Codex Cloud qui la consomment attendent ce nom dans les échanges ; le renommer les empêchera donc de fonctionner, même si l’événement est expérimental. Conservez le nom existant ou ajoutez un événement rétrocompatible, comme décrit dans AGENTS.md.

L’équipe Codex a ajouté cette règle précisément pour protéger les composants consommateurs de Codex Cloud. Placez les règles qui s’appliquent à l’ensemble du dépôt à la racine, et celles propres à un service dans le répertoire concerné. Lors de la revue, Codex peut appliquer les consignes qui couvrent les fichiers modifiés et orienter les auteurs vers la règle pertinente ; une modification sans rapport n’a pas besoin du contexte de l’app-server.

Les règles complètent les outils sur lesquels les équipes s’appuient déjà. Les tests et les linters conviennent bien aux vérifications que l’on peut exprimer de façon déterministe ; les règles du dépôt permettent de consigner les critères de jugement plus difficiles à traduire en code. Les exigences de compatibilité et les limites à respecter dans l’utilisation des données sont de bons points de départ. Les auteurs n’ont pas besoin de connaître tous les incidents passés ni toutes les conventions locales avant de modifier le code : les consignes pertinentes sont déjà là.

Rédiger des règles qui tiennent la route

Nous avons testé la capacité de la revue de code à utiliser les consignes du dépôt à l’aide d’une suite d’évaluations comprenant des violations de règles connues et des contre-exemples sans risque. Dans la suite principale, les variantes guidées par des règles ont produit 98 % des signalements personnalisés attendus, contre 58,3 % pour la configuration témoin de référence.

Détecter une violation de règle n’est qu’une partie du travail. Nous voulions aussi savoir ce qui se passe lorsque plusieurs règles sollicitent l’attention ou qu’une pull request contient déjà de nombreuses modifications. Nous avons testé à la fois des violations aux conséquences importantes et des modifications qui ne devaient susciter aucun signalement, puis organisé les résultats autour de quatre questions :

Nous avons également essayé des formats courants pour rédiger les consignes, des courtes listes à puces aux sections placées sous la responsabilité d’une équipe précise.

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 qu’une revue par défaut risquait de manquer, mais des instructions trop générales pouvaient facilement générer des signalements superflus. Des ensembles de règles restreints, bien ciblés et indiquant explicitement une marche à suivre sûre aidaient Codex à se concentrer sur ce qui était le plus utile, sans appliquer une règle à chaque modification voisine.

Commencez par un invariant important, mais peu évident. Formalisez une vérification que les personnes chargées des revues expliquent régulièrement, comme une exigence de compatibilité ou une limite à respecter dans l’utilisation des données. Si retirer une règle ne change rien à la revue, ne la conservez pas.

Limitez la portée des règles au code qu’elles concernent. Placez les consignes communes à tout le dépôt à la racine, et celles propres à un service dans un fichier AGENTS.md situé dans un sous-répertoire. Un périmètre restreint évite que des instructions sans rapport se disputent l’attention et permet de savoir clairement qui en est responsable.

Énoncez l’invariant et la marche à suivre sûre. La règle rawResponseItem/* indique le risque de rupture de compatibilité. « Conservez le nom existant ou ajoutez un événement rétrocompatible » donne aux auteurs une solution de rechange claire.

Veillez à ce que les règles restent pérennes et à jour. Décrivez les résultats attendus plutôt que des noms de fonctions susceptibles de changer. Examinez les mises à jour des règles et restreignez ou supprimez les consignes qui génèrent régulièrement des signalements superflus.

Laissez les vérifications de mise en forme et les autres contrôles mécaniques à la CI. Réservez les règles du dépôt aux questions qu’il faudrait sinon poser à nouveau lors d’une revue.

Bien démarrer

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

Commencez par une explication qui revient sans cesse dans les revues ou par une erreur propre au dépôt dont la non-détection aurait des conséquences importantes. Essayez une modification qui devrait déclencher la règle, un contre-exemple sans risque et une modification sans rapport. Vérifiez que la première produit un signalement utile et que les autres ne génèrent pas de signalements superflus, puis affinez les consignes en fonction de vos observations.

La revue de code Codex apporte un regard supplémentaire ; les tests, les protections de branches et les approbations obligatoires continuent d’imposer des contrôles stricts.

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