Échecs avec Codex : pourquoi l'IA casse le code et comment valider ses changements

git diff --stat affiche soudain 18 fichiers, alors que la tâche donnée à Codex était simplement « corriger l’état d’un bouton ». La CI est verte. Mais en ouvrant le diff, on voit que coverageThreshold a été abaissé, qu’un flaky test est passé en skip, et qu’un helper validateEmail() a été ajouté alors que le dépôt avait déjà emailSchema.

Codex n’a pas cassé le code volontairement. Le périmètre de la tâche était trop large, et le workflow de validation trop lâche. Ici, on ne débat pas de la fiabilité abstraite de l’IA. On construit une table de motifs d’échec, des gates de validation, un flux de rollback et une checklist de review pour traiter l’échec comme un trou de processus, pas comme une surprise.

Table des motifs d’échec : comment l’IA casse du code

Une étude arXiv sur 33k agent-authored PRs GitHub observe que les PR non mergées sont souvent plus grandes, touchent plus de fichiers et échouent plus fréquemment aux validations CI/CD du projet. Cela ne veut pas dire que les agents IA manquent simplement d’intelligence. La décomposition des tâches, les critères d’acceptation et l’engagement des reviewers comptent aussi.

Voici 9 motifs fréquents, avec le signal à surveiller et la première réaction :

Motif	Manifestation	Signal	Première réaction
Diff trop grand	Le périmètre dépasse largement la demande	git diff --stat montre beaucoup plus de fichiers que la tâche, par exemple 10+ fichiers pour un « fix bouton »	Lire d’abord la file list. Séparer les changements attendus des changements hors scope ; découper ou revert le surplus
Tests faussement verts	Les tests passent mais la logique reste fausse	Le diff abaisse coverageThreshold, met un flaky test en skip ou assouplit les assertions	Vérifier si la configuration de test a changé ; demander un test de régression qui échoue avant le changement
Mauvais répertoire	La CI ou des fichiers sans rapport sont modifiés	.github/workflows/, Makefile ou package.json scripts changent alors que la tâche ne le demandait pas	Vérifier si AGENTS.md interdit les changements CI/config ; revert puis écrire la règle
Code dupliqué	Un helper ou utilitaire existe déjà	Le diff ajoute un helper alors que le dépôt a déjà une fonction ou un schema équivalent	Chercher l’implémentation existante ; si elle existe, revert le doublon et demander à Codex de l’utiliser
PR trop grosse	Une grosse PR sans plan	Le PR body dit seulement « fix issue », sans implementation plan, commandes de vérification ni rollback	Demander des PR plus petites, chacune vérifiable, reviewable et annulable
CI affaiblie	La config CI est changée pour faire passer les checks	La CI échoue, mais le patch ne touche que test/CI config et pas le code métier	Traiter comme blocker ; revert la CI et demander une correction du code métier
Bug métier caché	La logique semble correcte mais viole une règle métier	Le diff supprime un contrôle de permission ou une validation non couverte par les tests	Suivre un critical path, vérifier les effets de bord et demander un approval explicite
Untrusted input	Une entrée externe est utilisée sans validation	Codex utilise directement des données ou paths fournis par l’utilisateur, sans sanitization ni validation	Vérifier l’input validation ; si elle manque, demander des tests de validation
Grand changement sans plan	L’implémentation démarre avant le plan	Codex modifie du code avant d’énumérer les fichiers à modifier, les fichiers interdits et les commandes de vérification	Demander /plan ou des goal/context/constraints/done criteria explicites avant l’implémentation

Ces motifs se combinent souvent. Une PR au diff trop grand peut aussi toucher le mauvais répertoire, dupliquer du code et produire des tests faussement verts. La checklist de review GitHub pour les agent PRs cite aussi le CI gaming, l’oubli de réutilisation de code, les erreurs de correctness cachées et les grosses PR sans plan comme signaux d’alerte.

La première réaction : ne commencez pas par demander si la CI est verte. Commencez par le périmètre du diff et la granularité de rollback.

Workflow de découpage : les grosses tâches ne sont pas interdites à Codex

Les best practices OpenAI recommandent de planifier avant d’implémenter quand une tâche est complexe ou ambiguë. Codex travaille mieux quand il peut vérifier ce qu’il fait, et les petites tâches ciblées sont plus faciles à tester et à review.

Mais « découper plus petit » n’est pas une formule vague. La bonne granularité est atteinte lorsque chaque étape peut être vérifiée et rollback séparément.

La boucle en sept étapes : de scope à update rules

Utilisez cette boucle pour les changements Codex :

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

Chaque étape a ses questions et sa condition de retour.

1. scope

Questions :

• La tâche est-elle assez précise pour être écrite comme goal + context + constraints + done criteria ?
• Traverse-t-elle plusieurs sous-systèmes, comme auth, payment et notification ?
• Peut-elle toucher la configuration CI, le schema de base de données ou des dépendances externes ?

Retour : si plusieurs sous-systèmes ou CI/config sont concernés, découpez en tâches séparées.

2. plan

Questions :

• Codex a-t-il d’abord listé les fichiers prévus, les fichiers ou répertoires interdits et les commandes de vérification ?
• Le plan explicite-t-il les risques et les conditions de sortie ?
• Le plan décrit-il le rollback ?

Retour : s’il n’y a pas de plan, ou s’il manque ces éléments, demandez un nouveau /plan.

3. patch

Questions :

• git diff --stat correspond-il au scope du plan ?
• Codex a-t-il changé des fichiers hors scope, comme CI/config ou des fichiers sans rapport ?
• A-t-il généré du code dupliqué, par exemple un helper déjà présent ?

Retour : si le diff ne correspond pas au plan ou touche une alerte, revenez à l’étape 2.

4. verify

Questions :

• Des tests ont-ils été ajoutés pour le core path ?
• Le test échouerait-il avant le changement ?
• Les CI status checks sont-ils required et non skipped ?
• Lint ou pre-commit sont-ils passés ?

Retour : si aucun test pertinent n’a été ajouté ou si le changement fait seulement passer les tests en affaiblissant la configuration, revenez à l’étape 3.

5. review

Questions :

• Le périmètre du diff correspond-il à la tâche ?
• Quelqu’un a-t-il suivi un critical path ?
• Un reviewer humain a-t-il explicitement approved, au lieu de se fier au rapport de l’IA ?
• La branch protection impose-t-elle required reviews, required status checks et conversation resolution ?

Retour : si le reviewer demande des changements ou trouve une alerte, revenez à l’étape 3.

6. merge/rollback

Questions :

• Le changement satisfait-il la checklist de preuves de la section suivante ?
• Peut-il être rollback indépendamment au niveau hunk ou fichier ?
• Le travail était-il isolé dans un worktree, pour jeter un essai raté et pousser un succès en PR ?

Retour : si les preuves manquent ou si le changement n’est pas revertible indépendamment, rollback puis retour à l’étape 1.

7. update rules

Questions :

• L’échec vient-il d’une règle AGENTS.md manquante, par exemple « ne pas modifier la CI » ou « découper au-delà de cinq fichiers » ?
• Faut-il écrire le périmètre interdit, les critères d’acceptation ou le rollback dans AGENTS.md ?

Action : si l’échec vient d’une règle manquante, écrivez-la dans AGENTS.md.

Les grosses tâches restent possibles avec Codex

Les gros refactorings ne sont pas interdits. Ils doivent seulement être découpés jusqu’à ce que chaque étape soit rollbackable seule. L’expérience de refactoring IA de 10 000 lignes le montre aussi : petits pas et filet de sécurité par les tests sont essentiels.

Vérifiez la granularité avec ces questions :

• Chaque patch peut-il être revert au niveau hunk ou fichier ?
• Chaque vérification peut-elle prouver que le comportement avant changement échoue ?
• Chaque merge a-t-il un reviewer approve explicite et des status checks ?

Si la réponse est non, la tâche est encore trop grosse.

Codex review pane en pratique : la validation ne se limite pas aux tests

Lorsqu’on relit un changement Codex, le premier signal n’est pas le résultat des tests. C’est le périmètre du diff et la granularité de rollback. Le review pane de l’app Codex propose trois vues et des opérations au niveau hunk/fichier.

Trois vues de diff

Le review pane reflète l’état Git du dépôt, pas seulement les modifications Codex. Il peut afficher les changements Codex, les changements utilisateur et d’autres modifications non commitées.

Vue	Contenu	Usage
uncommitted changes	Toutes les modifications non commitées, par défaut	Vérifier le scope de la tâche Codex courante
all branch changes	Tous les changements de la branche courante par rapport à la base	Vérifier toute la chaîne de tâches, sur plusieurs turns ou tasks
last turn changes	Les changements du dernier turn Codex	Isoler ce que Codex vient de faire et repérer vite les modifications hors scope

Commencez par uncommitted changes pour confirmer le scope. Passez ensuite à all branch changes pour repérer les restes de travaux précédents. Utilisez enfin last turn changes pour vérifier que Codex a suivi le plan.

Inline comments et opérations hunk/fichier

Le review pane permet d’ajouter des inline comments sur des lignes précises du diff. Ces commentaires peuvent servir de contexte pour une correction Codex ultérieure.

Niveaux d’opération :

• entire diff : stage/unstage/revert tout le diff
• file : stage/unstage/revert un fichier
• hunk : stage/unstage/revert un bloc de code, la plus petite unité utile

Si vous trouvez un changement hors scope, comme une suppression de config CI, revertez d’abord ce hunk ou ce fichier au lieu de jeter tout le diff.

Chargement du contexte PR

Sur une PR branch, si l’accès GitHub ou gh auth login est disponible, le review pane peut charger le PR context, les review comments et les changed files. On passe alors de « lire le diff local » à « lire le diff PR plus les commentaires reviewer ».

Rappel sur les faits volatils : les détails d’UI et de slash command peuvent changer. Rouvrez la page officielle avant publication si ce comportement exact compte.

Le principe de base de la review

La validation ne se limite pas aux tests :

1. Vérifiez d’abord si le scope du diff correspond au plan
2. Vérifiez ensuite si la granularité de rollback est assez petite, par exemple hunk ou fichier
3. Vérifiez enfin si des tests ont été ajoutés et couvrent le critical path

Si les deux premiers points échouent, les tests qui passent ne prouvent pas que le code est correct.

Checklist de preuves : les tests qui passent ne suffisent pas

GitHub Docs explique que les required status checks doivent être successful, skipped ou neutral avant merge dans une protected branch. Dans GitHub Actions, un check skipped peut être traité comme success et ne pas bloquer le merge.

Donc « CI verte » ne veut pas dire « code de qualité ». Il faut un ensemble de preuves, pas un seul signal.

Utilisez cette checklist.

Preuves côté code

• Le scope du diff correspond à la tâche, sans changement hors scope
• Aucun code dupliqué n’a été ajouté ; le projet a été recherché pour trouver l’équivalent existant
• La CI/config n’a pas été modifiée, sauf si la tâche l’autorisait explicitement

Preuves côté tests

• Des tests ont été ajoutés pour le core path
• Les tests échoueraient avant le changement, pas seulement après
• La configuration de test n’a pas été affaiblie : pas de coverage threshold abaissé, pas de skip, pas d’assertion adoucie

Preuves côté CI

• lint et pre-commit sont passés
• Les CI status checks sont required et non skipped
• La configuration CI n’a pas été modifiée seulement pour faire passer le check

Preuves côté PR

• Le PR body contient un implementation plan, des commandes de vérification et des notes de rollback
• Un reviewer humain a explicitement approved, au lieu de se fier au rapport de l’IA
• La branch protection couvre required reviews, required status checks et conversation resolution

Preuves côté rollback

• Chaque patch peut être revert indépendamment au niveau hunk ou fichier
• La tâche a été isolée dans un worktree, pour jeter un essai raté et transférer un succès vers une PR

Branch protection et status checks

Les protected branches GitHub peuvent exiger :

• required reviews : un nombre défini de approvals avant merge
• required status checks : les checks doivent passer, être skipped ou neutral avant d’entrer dans la protected branch
• conversation resolution : toutes les conversations doivent être resolved avant merge

Ce sont des gates de merge hors de l’IA. Ils ne sont pas remplacés par un simple « c’est terminé » de l’IA.

Ordre de review

Utilisez cet ordre :

1. Vérifier d’abord le scope du diff, dont la file list et la taille du diff
2. Vérifier ensuite si la config CI ou test a changé
3. Vérifier ensuite si des tests ont été ajoutés et couvrent le core path
4. Vérifier enfin si un reviewer a explicitement approved

N’inversez pas l’ordre. Commencer par les tests fait facilement rater les changements hors scope et la CI affaiblie.

Rollback et rétrospective : que faire après un mauvais changement

Quand la review trouve un changement hors scope ou un test faussement vert, le premier réflexe est rollback, pas demander à Codex de continuer à corriger le même diff confus.

Granularité de rollback : du hunk à la branche

Choisissez le niveau de rollback selon l’ampleur et la cause de l’échec :

Granularité	Quand l’utiliser	Opération
Revert au niveau hunk	Un bloc de code contient un changement hors scope, comme une suppression CI	Sélectionner ce hunk dans le review pane -> revert
Revert au niveau fichier	Un fichier entier contient du code dupliqué ou des changements hors scope	Sélectionner ce file dans le review pane -> revert
Abandon de branche	La direction de la tâche est mauvaise et plusieurs fichiers doivent être jetés	git checkout main -> supprimer la branche

Préférez la plus petite granularité utile. N’abandonnez une branche que lorsque plusieurs hunks ou fichiers sont mauvais.

Isolation par worktree : les essais ratés peuvent être jetés

L’article Codex Worktree de cette série utilise les worktrees pour isoler les tâches parallèles. Un essai raté peut être jeté ; un essai réussi peut partir en PR.

Si une tâche casse le code dans son worktree, supprimez ce worktree et gardez l’espace principal propre. C’est plus sûr que d’enchaîner les revert sur la même branche.

Après le rollback : écrire dans AGENTS.md

Après le rollback, décidez si l’échec vient d’une règle manquante. Si oui, écrivez-la dans AGENTS.md.

Posez ces questions :

• L’échec vient-il d’une convention projet manquante, comme « ne pas modifier la config CI » ou « découper au-delà de cinq fichiers » ?
• Vient-il de critères d’acceptation manquants, comme « les tests doivent prouver l’échec avant changement » ?
• Vient-il d’une règle de rollback manquante, comme « chaque patch doit être revertible indépendamment » ?

Si oui, écrivez la règle au bon endroit dans AGENTS.md, comme décrit dans la section suivante.

Après la rétrospective : transformer les workflows répétés en skills

Décidez si un échec mérite un skill avec ces questions :

• L’échec vient-il d’une limite de Codex, par exemple une contrainte métier mal comprise ?
• Vient-il d’un workflow complexe en plusieurs étapes, comme une coordination multi-agent ?
• Vient-il d’un flux de review que vous répétez souvent, comme vérifier le scope du diff, la config CI et les tests ajoutés à chaque fois ?

Si oui, transformez-le en skill, comme dans l’article Codex Skills/plugins de cette série.

Où placer les règles dans AGENTS.md

Avant chaque run ou session, Codex construit une instruction chain et lit les fichiers AGENTS.md globaux et projet. Au niveau projet, il lit depuis le Git root jusqu’au répertoire courant. Le fichier le plus proche est le plus spécifique.

AGENTS.md peut donc vivre à la racine du dépôt, dans un sous-module ou dans un répertoire de fonctionnalité. Codex doit préférer la règle la plus spécifique quand les périmètres se chevauchent.

Emplacements et contenus courants d’AGENTS.md

Le guide de démarrage Codex de cette série couvre un modèle AGENTS.md typique :

Emplacement	Contenu typique	Exemple
repo root	repo layout, build/test/lint commands, engineering conventions	Project structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontend	frontend-specific conventions et PR expectations	frontend utilise seulement React hooks, pas class components ; les PR doivent inclure des Storybook stories
src/backend	backend-specific conventions et do-not rules	backend ne doit pas accéder directement à la base ; passer par l’ORM ; pas de SQL dans les controllers
src/shared	shared utility conventions	shared contient uniquement des pure functions, pas d’effets de bord

Où écrire les leçons d’échec

Après un échec, placez la règle selon la cause :

Cause d’échec	Où l’écrire	Exemple
Config CI supprimée par erreur	repo root -> PR expectations -> do-not rules	Ne pas modifier .github/workflows/, Makefile ou package.json scripts sans autorisation explicite
Plus de cinq fichiers modifiés	repo root -> PR expectations -> do-not rules	Les changements touchant plus de cinq fichiers doivent être découpés ; chaque tâche devrait toucher au plus trois fichiers
Tests faussement verts	repo root -> what done means	Les tests doivent couvrir le core path et prouver que le comportement avant changement échoue, pas seulement que le nouveau comportement passe
Code dupliqué	repo root -> engineering conventions	Chercher un équivalent existant avant d’ajouter un helper sous src/lib ; s’il existe, l’utiliser
Grand changement sans plan	repo root -> PR expectations	Les changements touchant plus de trois fichiers nécessitent d’abord /plan, avec fichiers à modifier, fichiers interdits et commandes de vérification
Untrusted input	src/backend -> engineering conventions	Toutes les entrées utilisateur doivent être validées ; ne pas utiliser directement les données ou paths fournis par l’utilisateur
Bug métier caché	src/backend -> engineering conventions	Après un changement de permission checks ou de validation, suivre un critical path et inspecter les effets de bord

Découverte des règles : le fichier le plus proche gagne

La documentation OpenAI AGENTS.md décrit les instructions projet comme une chaîne du Git root au répertoire courant, où les fichiers plus proches sont plus spécifiques.

En pratique :

• AGENTS.md à la racine contient les règles générales, comme build/test/lint commands et « ne pas modifier la CI »
• AGENTS.md dans un sous-module contient les règles spécifiques, comme hooks seulement côté frontend ou SQL interdit côté backend
• AGENTS.md dans un répertoire de fonctionnalité contient les règles les plus spécifiques, comme les contraintes métier d’une API

Quand vous écrivez une leçon :

• Les conventions globales comme « ne pas modifier la CI » vont à la racine
• Les conventions de sous-module comme les règles frontend vont sous src/frontend
• Les contraintes propres à une fonctionnalité vont sous src/backend/api/xxx

Les limites d’AGENTS.md

AGENTS.md réduit les changements hors scope et les erreurs de manipulation. Il ne prouve pas la correction du code. Codex peut suivre AGENTS.md et produire une logique fausse.

Le dernier gate reste l’approbation explicite d’un reviewer humain, pas la simple existence d’un fichier de règles.

Checklist de review humaine pour les PR IA

Les recommandations GitHub pour relire les agent-generated PRs commencent par la file list et la taille du diff, puis vérifient si la config CI/test a changé, cherchent les helpers dupliqués, suivent un critical path et demandent un test qui prouve l’échec avant changement.

Utilisez cette checklist de signaux rouges.

Signaux rouges côté code

• La file list et la taille du diff dépassent largement la description de la tâche
• La config CI/test a changé, comme .github/workflows/, Makefile ou package.json scripts
• Un nouveau helper duplique un helper existant
• Le PR body dit seulement « fix issue », sans implementation plan, commandes de vérification ni rollback
• La PR est trop grosse, par exemple plus de 10 fichiers

Signaux rouges côté tests

• Aucun nouveau test n’a été ajouté
• Le test vérifie seulement le comportement post-change et ne prouve pas que l’ancien comportement échouait
• La configuration de test a été affaiblie : coverage threshold abaissé, flaky test skipped ou assertion adoucie

Signaux rouges côté CI

• La CI échouait, mais le patch ne change que tests ou CI config au lieu du code métier
• Les CI status checks sont skipped ou neutral, pas passing
• La config CI a été changée pour faire passer le check

Signaux rouges côté PR

• PR body vide
• Aucun implementation plan
• Aucun reviewer approval, seulement le rapport de l’IA
• Conversations unresolved

Blockers et signaux de découpage

Type	Signal rouge	Réponse
Blocker	La CI échoue, mais seule la config test/CI change	Request changes, revert la CI et demander une correction du code métier
Blocker	Tests faussement verts, comme coverageThreshold abaissé ou skip	Request changes, revert la config de test et demander un nouveau test
Blocker	Untrusted input sans validation	Request changes et demander des validation tests
Signal de découpage	Grosse PR, par exemple plus de 10 fichiers	Request changes et découper en PR plus petites
Signal de découpage	PR body vide sans implementation plan	Request changes et ajouter plan, commandes de vérification et rollback

Le principe du reviewer

Le reviewer ne juge pas abstraitement si l’IA est fiable. Il vérifie :

1. si le scope du diff correspond à la description de la tâche
2. si la config CI/test a changé
3. si des tests ont été ajoutés et couvrent le core path
4. si les effets de bord cachés ont été vérifiés en suivant un critical path

N’inversez pas l’ordre. Commencer par les tests fait facilement rater la CI affaiblie et les changements hors scope.

Conclusion

Quand Codex casse du code, ce n’est généralement pas parce qu’il serait abstraitement « non fiable ». Le périmètre de la tâche était trop large, et le processus d’acceptation trop souple. La checklist pratique est la suivante :

• Table des motifs d’échec : reconnaître les formes fréquentes de problèmes Codex
• Boucle en sept étapes : de scope à update rules comme flux complet d’acceptation
• Review pane en pratique : ne pas s’arrêter aux tests ; vérifier d’abord le scope du diff et la granularité de rollback
• Checklist de preuves : les tests qui passent ne suffisent pas ; vérifier aussi diff scope, tests ajoutés, statut CI, review humaine et branch protection
• Rollback et rétrospective : revert hunk/fichier, isolation worktree et écriture dans AGENTS.md ou dans un skill
• Emplacements AGENTS.md : placer les règles à la racine, dans un sous-module ou dans un répertoire de fonctionnalité selon le scope
• Signaux rouges de review humaine : commencer par file list et diff size, puis CI/test config, tests ajoutés, reviewer approval

Transformez cette liste en outil de review réel. À chaque changement Codex, parcourez-la. Si le même flux de review revient souvent, envisagez d’en faire un skill, comme dans l’article Codex Skills/plugins.

L’échec n’est pas une surprise. C’est une faille de processus.

Étapes suivantes et lectures complémentaires

Articles publiés

• Refactoring IA de 10 000 lignes : retour d’expérience réel et filet de sécurité par les tests — leçons pratiques sur les petits pas et les tests
• Guide de refactoring Cursor — principes de review applicables aux autres outils de coding IA
• GitHub Actions CI workflow — bases des status checks
• GitHub Actions workflow — bases du PR workflow
• Workflow agent Codex Cloud — exécution distante, validation de PR et boucle pour tâches longues

Même série : guide pratique Codex

• Guide complet pour débuter avec Codex — CLI, IDE, Cloud et desktop
• Sécurité et permissions Codex — sandbox et approval réduisent le risque
• Revue de code Codex — review comme gate d’acceptation
• Tâches d’automatisation Codex — les patches générés par exec exigent encore une review humaine
• Codex Worktree en pratique — isoler les tâches parallèles
• Codex Skills/plugins — transformer les workflows de review en skills
• Développement piloté par les tests avec Codex — TDD + Codex
• Optimisation des coûts Codex
• Codex en entreprise