De bout en bout : de l'issue à la pull request mergée

Vous avez une issue dans votre repo GitHub et, au terme de cette boucle, vous voulez une pull request mergée qui la clôt, avec un humain qui relit le diff comme dernier verrou. C'est tout le travail, et Codex est conçu pour en exécuter l'essentiel pendant que vous gardez le contrôle.

Cette leçon parcourt la boucle concrètement : prendre l'issue, laisser Codex crcrLe pourcentage de visiteurs ou de prospects qui réalisent une action attendue (achat, inscription, formulaire de contact), calculé en divisant les conversions par le nombre total d'opportunités.Voir la définition complète →éererLe rapport entre les interactions (likes, commentaires, partages) et le reach d'un contenu, utilisé pour mesurer la réaction de l'audience au regard du nombre de personnes touchées.Voir la définition complète → la branche et implémenter, lancer les tests, ouvrir la PR, relire, merger. La discipline qui fait fonctionner tout ça n'a rien de sophistiqué : hygiène de branche, petits diffs, et une review traitée comme un vrai point de contrôle, pas comme une formalité.

Où Codex intervient dans ce workflow

Codex est l'agent d'ingénierie logicielle d'OpenAI. Il tourne dans une sandbox cloud isolée, lit votre repo, édite des fichiers, exécute des commandes et pousse des branches. Vous y accédez depuis la sidebar Codex dans ChatGPT et depuis le Codex CLI dans votre terminal, et il se connecte à GitHub via l'intégration GitHub de Codex, ce qui lui permet d'ouvrir et de mettre à jour des PR directement.

Le modèle mental : Codex est un coéquipier capable d'abattre vite le travail mécanique d'un changement, mais qui ne merge jamais son propre code. Vous cadrez le périmètre, il produit un diff, vous relisez et mergez. C'est la branch protection de GitHub qui fait respecter cette frontière, donc mettez-la en place en premier.

Posez les garde-fousgarde-fousRègles et contrôles qui maintiennent un système d'IA dans des limites sûres, légales et conformes à la marque, en bloquant les sorties et actions hors cadre.Voir la définition complète → avant de commencer

Sur le repo, activez la branch protection sur votre branche par défaut :

• Exiger une pull request avant de merger.
• Exiger au moins une review approuvée.
• Exiger que les status checks (votre CI) passent.

Désormais, même un agent qui pousse du code ne peut pas le faire atterrir sans un build vert et une approbation humaine. C'est le réglage le plus important pour laisser un agent travailler dans un vrai repo.

Étape 1 : prendre l'issue

Partez d'une issue réelle et bien cadrée. Codex donne le meilleur quand l'issue se lit comme une spec, pas comme une impression. Comparez :

Faible : « Le login est instable. »

Fort : « Les utilisateurs dont l'email contient un alias + (ex. sam+test@x.com) sont rejetés à l'inscription. Attendu : les adresses conformes à la RFC avec + sont acceptées. Voir validateEmail dans src/auth/validate.ts. Ajouter d'abord un test qui échoue. »

La version forte nomme le fichier, le comportement attendu, et demande un test. Cette seule contrainte tend à réduire le diff de moitié.

Dans la sidebar Codex, pointez-le vers le repo et collez la tâche. Si votre repo contient un fichier codex.md ou AGENTS.md à la racine, Codex le lit comme des instructions permanentes : comment lancer les tests, le style de code, ce qu'il ne faut pas toucher. Considérez ce fichier comme la version durable de vos instructions personnalisées pour cette codebase.

# AGENTS.md
## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- TypeScript strict mode. No `any`.
- One logical change per PR. Keep diffs under ~150 lines.
- Never edit files under `src/generated/`.

Étape 2 : laissez Codex créer la branche

Ne laissez pas Codex travailler sur main. Demandez-lui de créer une branche avec un nom clair rattaché à l'issue :

codex "Fix issue #214: accept + aliases in validateEmail.
Branch: fix/214-email-plus-alias.
Write a failing test first, then make it pass."

Les bons noms de branche sont ennuyeux et traçables : fix/214-email-plus-alias, feat/187-csv-export. Le numéro d'issue dans le nom de branche permet à n'importe qui de remonter du code à la conversation qui l'a produit. C'est ça, l'hygiène de branche : une branche, une intention, facile à supprimer après le merge.

Codex démarre sa sandbox, clone la branche et se met au travail. Vous le verrez lire des fichiers, formuler un plan et exécuter des commandes. Laissez-le tourner, mais lisez le plan proposé avant qu'il n'écrive beaucoup. Si le plan sent déjà trop large (il veut refactorer trois modules pour un bug d'une ligne), arrêtez-le et resserrez le périmètre maintenant, pas au moment de la review.

Étape 3 : implémenter et tester le changement

L'ordre compte, et il vaut la peine d'être explicite avec Codex : d'abord le test qui échoue, ensuite le correctif. C'est la version agent du test-driven development, et ça fait deux choses. Ça prouve que le bug existe, et ça prouve que votre correctif traite bien ce bug et pas quelque chose d'à côté.

Une boucle propre, sur notre exemple, ressemble à ça :

# tests/test_validate.py
import pytest
from src.auth.validate import validate_email

@pytest.mark.parametrize("email", [
    "sam+test@example.com",
    "sam+news+promo@example.com",
])
def test_plus_alias_is_accepted(email):
    assert validate_email(email) is True

def test_bare_plus_still_rejected():
    assert validate_email("+@example.com") is False

Codex ajoute le test, l'exécute, le voit échouer, puis édite validate_email jusqu'à ce que la suite soit verte. Comme il exécute les commandes dans sa sandbox, vous obtenez la vraie sortie, pas une supposition sur le fait que le code fonctionne. Si un test échoue d'une manière inattendue, il itère. Surveillez qu'il ne « corrige » pas le test pour l'aligner sur un comportement cassé. C'est un mode de défaillance classique des agents, et c'est pour ça que vous avez demandé le test qui échoue en amont : vous pouvez lire le test et confirmer qu'il encode le comportement que vous voulez vraiment.

Quand il a fini, Codex rapporte ce qui a changé et pourquoi. Lisez ce résumé, mais ne lui faites pas confiance à la place du diff.

Étape 4 : ouvrir la pull request

Demandez à Codex d'ouvrir la PR depuis sa branche vers main. Un bon corps de PR rédigé par un agent est structuré pour qu'un relecteur puisse approuver en quelques minutes :

## What
Accept email addresses with `+` aliases in `validateEmail`.

## Why
Closes #214. Aliased addresses are RFC 5321 valid; we were rejecting them.

## Changes
- `src/auth/validate.ts`: widened local-part regex to allow `+`.
- `tests/test_validate.py`: added alias-accept and bare-plus-reject cases.

## Testing
- `pnpm test` passes (2 new cases).

Notez Closes #214. Ce mot-clé relie automatiquement la PR à l'issue et clôt l'issue au merge de la PR. Votre board reste à jour sans un clic de plus.

La PR déclenche votre CI. Comme vous avez exigé les status checks, le bouton de merge reste désactivé jusqu'à ce que le build passe. C'est votre premier verrou automatique qui fait son travail avant même qu'un humain regarde.

Étape 5 : relire le diff (le vrai verrou)

C'est l'étape que vous ne déléguez jamais. Ouvrez l'onglet Files changed et lisez chaque ligne comme si un ingénieur junior l'avait écrite, parce que fonctionnellement c'est le cas.

Ce qu'il faut chercher spécifiquement dans les diffs générés par un agent :

• La dérive de périmètre. N'a-t-il touché que ce que l'issue exigeait ? Fichiers reformatés, variables sans rapport renommées, retouches « tant que j'y étais » gonflent le diff et masquent le vrai changement. Demandez à Codex de revenir sur tout ce qui est hors sujet.
• La regex ou la logique qui « corrige ». Une regex élargie peut accepter + et aussi accepter n'importe quoi. Lisez le pattern réel. C'est là que se logent les bugs subtils de sécurité et de correction.
• La qualité des tests. Le test échoue-t-il sans le correctif ? Assert-il la bonne chose ? Un test qui passe même avec le bug présent est pire que pas de test.
• Secrets et config. Vérifiez que rien n'a hardcodé une clé ni changé une valeur d'env par défaut.

Les petits diffs rendent tout ça possible. Une PR de 40 lignes obtient une vraie review ; une PR de 600 lignes est survolée puis validée d'un geste, ce qui annule tout l'intérêt du verrou humain. Si Codex a produit quelque chose de gros, découpez : demandez-lui d'ouvrir le changement en deux ou trois PR successives, chacune relisible indépendamment.

Vous pouvez aussi laisser des commentaires de review directement sur la PR et demander à Codex de les traiter. Il pousse de nouveaux commits sur la même branche, la CI se relance, et vous relisez le delta. C'est dans cette boucle par commentaires que se joue l'essentiel de la collaboration réelle.

Étape 6 : merger et nettoyer

Une fois la CI verte et votre approbation donnée, mergez. Préférez Squash and merge pour le travail d'agent : la branche peut contenir une douzaine de micro-commits d'itération (« fix test », « oops », « lint »), et le squash les rassemble en un commit propre sur main avec le titre de votre PR comme message. L'historique reste lisible.

Après le merge, supprimez la branche. GitHub le propose comme un bouton juste après le merge, et vous pouvez activer la suppression automatique dans les réglages du repo pour que les branches d'agent obsolètes ne s'accumulent jamais. L'issue se clôt automatiquement grâce à votre ligne Closes #214. La boucle est complète : une issue en entrée, un changement relu et testé en sortie, un historique propre.

Une note sur les deux façons d'utiliser Codex

Vous alternerez entre deux surfaces, adaptées à des tâches différentes :

• Cloud (sidebar ChatGPT / intégration GitHub) : idéal pour les tâches asynchrones et autonomes que vous lancez et consultez plus tard. Assignez, partez, relisez la PR quand il vous notifie.
• Codex CLI (local) : idéal quand vous voulez observer et piloter en temps réel, l'exécuter sur un état local non commité, ou travailler dans un repo avec un outillage uniquement local.

Les deux ouvrent des PR ; les deux respectent votre AGENTS.md. La lecture sur platform.openai.com/docs et la doc développeur seront toujours plus à jour que n'importe quel tutoriel, alors mettez-les en favori.

Pourquoi cette boucle passe à l'échelle

Si ça fonctionne à l'échelle d'une équipe, c'est parce que Codex s'insère dans un process qui existe déjà. Vous n'inventez pas une nouvelle politique de merge pour l'IA. Vous pointez un agent vers les mêmes branch protection, CI et culture de review que vos humains utilisent, et l'agent hérite de ces garde-fous. L'habitude du test-qui-échoue-d'abord, les petits diffs et l'approbation humaine obligatoire sont exactement les pratiques qui rendent les PR humaines sûres. Elles rendent les PR d'agent sûres pour les mêmes raisons.

Le mode de défaillance à éviter, c'est la pression de vitesse : Codex produit des diffs vite, et il est tentant d'approuver vite pour suivre le rythme. Résistez. Votre goulot d'étranglement doit être la qualité de la review, pas la vitesse de l'agent, parce que la review est la seule étape qui attrape le changement plausible mais faux.

Points clés

• Configurez la branch protection avant de laisser Codex toucher au repo. Exigez une PR, une review et des checks qui passent, pour qu'un agent soit physiquement incapable de merger du code non relu.
• Rédigez vos issues comme des specs. Nommez le fichier, le comportement attendu, et demandez d'abord un test qui échoue. Un input serré produit des diffs serrés et relisibles.
• Une branche par intention, et squash au merge. Des noms de branche traçables avec le numéro d'issue, plus Closes #NNN dans la PR, gardent l'historique et votre board propres automatiquement.
• Ne déléguez jamais la review du diff. Lisez chaque ligne en traquant la dérive de périmètre, la logique douteuse et les tests faibles. Ce sont les petits diffs qui rendent une review honnête possible.
• Adaptez la surface à la tâche : Codex cloud pour les PR à lancer et oublier, le Codex CLI quand vous voulez observer et piloter en direct.