Codex /goal : le guide expert pour utiliser l’agent autonome d’OpenAI

Jusqu’ici, la plupart des agents de coding IA fonctionnaient encore sur un modèle très interactif : vous donnez une instruction, l’agent répond, vous relisez, vous corrigez, puis vous relancez. Même quand l’outil est puissant, la boucle reste dépendante de votre présence.

/goal change cette logique. Au lieu de demander à Codex de faire « la prochaine action », vous lui donnez un résultat à atteindre. L’agent peut alors travailler en autonomie sur plusieurs itérations : lire le projet, planifier, modifier les fichiers, exécuter les tests, analyser les erreurs, ajuster son approche et poursuivre jusqu’à ce que le résultat soit vérifiable.

Ce que /goal change dans Codex CLI

La commande /goal est apparue dans Codex CLI 0.128.0, publié le 30 avril 2026. Dans le changelog officiel, OpenAI décrit la fonctionnalité comme des workflows /goal persistants, avec API côté app-server, outils modèle, continuation runtime et contrôles TUI pour créer, mettre en pause, reprendre et effacer un objectif.

Cette phrase technique cache un changement important : l’objectif n’est plus seulement une ligne de texte dans le terminal. Il devient un état suivi par Codex. L’agent sait quel résultat il poursuit, peut reprendre une boucle, afficher son statut et s’arrêter lorsque la condition prévue est remplie.

Ainsi, /goal transforme Codex CLI en agent de long horizon. Ce n’est pas une fonction magique qui rend toutes les tâches fiables. C’est plutôt un mécanisme pour donner à Codex un cadre de travail durable : une cible, des contraintes, des commandes de validation et une règle d’arrêt.

Comment fonctionne une boucle /goal

Un bon /goal suit toujours la même mécanique. Codex commence par comprendre le projet, identifie les fichiers concernés, propose ou applique un plan, puis vérifie son travail avec les commandes disponibles dans le dépôt. Ensuite, les erreurs de test deviennent un signal de correction plutôt qu’un simple échec. Ainsi, la boucle continue tant que le résultat reste mesurable et non atteint. Enfin, toute ambiguïté forte, tout risque excessif ou toute décision produit non tranchée doit provoquer un arrêt clair avec un signalement explicite.

La qualité de la boucle dépend surtout de la qualité de vos garde-fous. Codex ne peut pas deviner vos critères de succès métier. Il peut très bien « améliorer » un projet dans une direction qui ne vous convient pas si vous ne lui donnez ni périmètre, ni test, ni contrainte.

Installer Codex CLI et vérifier que /goal est disponible

Codex CLI s’installe globalement avec npm ou Homebrew. Le dépôt officiel OpenAI recommande les commandes suivantes :

Installer Codex CLI
npm install -g @openai/codex

# ou, sur macOS avec Homebrew
brew install --cask codex

Puis lancez Codex :

Démarrer Codex
codex

OpenAI recommande de se connecter avec un compte ChatGPT pour utiliser Codex avec les plans compatibles. L’usage par clé API existe aussi, mais il demande une configuration séparée et toutes les fonctions produit ne sont pas forcément disponibles de la même manière.

Pour utiliser /goal, vérifiez d’abord votre version :

Vérifier la version
codex --version

Si vous êtes sous Codex CLI 0.128.0 ou une version supérieure, la fonctionnalité peut être disponible dans votre environnement. Comme /goal a été introduit récemment et a connu des ajustements, gardez Codex à jour avant de diagnostiquer un problème de commande non reconnue.

Les commandes /goal à connaître

La logique de base tient en quelques commandes. Elles permettent de lancer un objectif, de consulter l’état, de suspendre le travail ou de repartir proprement.

Comment rédiger un bon objectif /goal

La règle est simple : si vous ne savez pas comment prouver que le travail est terminé, /goal n’est pas prêt. Un objectif utile doit contenir quatre blocs : le résultat attendu, le périmètre, les commandes de vérification et les conditions d’arrêt.

Alors, évitez les objectifs génériques du type :

Mauvais objectif
/goal Améliore ce projet.

Ce prompt donne trop de liberté à l’agent. Il ne précise ni les fichiers concernés, ni les critères de succès, ni le moment où Codex doit s’arrêter. Le résultat peut être long, coûteux et impossible à valider.

Préférez une formulation structurée :

Bon objectif
/goal Migre ce projet de Pydantic v1 vers Pydantic v2.

Conditions de succès :
- tous les tests passent avec pytest ;
- le typage ne régresse pas avec mypy ;
- les endpoints publics restent compatibles ;
- les changements importants sont documentés dans MIGRATION.md.

Contraintes :
- ne modifie pas la configuration CI ;
- ne renomme pas les dossiers publics ;
- si une décision produit est nécessaire, arrête-toi et explique le blocage.

Enfin, demandez à Codex des rapports de progression compacts. Un bon statut doit dire ce qui vient d’être vérifié, ce qui reste à faire et ce qui bloque. Si le statut devient vague, ne rajoutez pas dix instructions improvisées : resserrez plutôt l’objectif.

Templates /goal prêts à adapter

Voici des modèles directement réutilisables. Le principe n’est pas de les copier tels quels, mais de remplacer les variables par vos vrais fichiers, vos vraies commandes et vos vraies contraintes.

1. Migration technique

Migration de framework
/goal Migre ce projet de [ancienne stack] vers [nouvelle stack].

Procédure :
- inspecte d’abord l’architecture actuelle ;
- propose un plan court ;
- migre par petits lots ;
- lance les tests après chaque étape importante ;
- documente les incompatibilités restantes.

Conditions de succès :
- [commande de test] passe ;
- [commande de build] passe ;
- aucune régression visible sur [pages ou fonctionnalités critiques].

Arrêt :
- arrête-toi si une décision produit ou design est nécessaire ;
- ne supprime pas de fonctionnalité sans justification explicite.

2. Génération de tests

Ajout de tests
/goal Ajoute une couverture de tests fiable pour [module ou dossier].

Objectif :
- couvrir les comportements principaux ;
- couvrir les erreurs attendues ;
- éviter les tests fragiles qui dépendent de détails internes.

Vérification :
- lance [commande de test] ;
- vérifie que les nouveaux tests échouent si le comportement attendu est cassé ;
- documente les zones non testées et pourquoi.

3. Correction d’un bug complexe

Debug autonome
/goal Corrige le bug décrit dans BUG.md.

Méthode :
- reproduis le bug avec un test ou un script minimal ;
- identifie la cause racine ;
- applique le correctif le plus local possible ;
- ajoute un test de non-régression.

Conditions de succès :
- le test de reproduction échoue avant correction et passe après ;
- la suite existante reste verte ;
- le correctif ne change pas l’API publique.

4. Prototype à partir d’un plan

Prototype guidé par PLAN.md
/goal Implémente PLAN.md jusqu’à obtenir une première version utilisable.

Règles :
- crée un jalon par section du plan ;
- ajoute des tests ou vérifications pour chaque jalon ;
- garde l’interface simple ;
- signale les compromis techniques à la fin.

Conditions de succès :
- l’application démarre avec [commande] ;
- le parcours principal fonctionne ;
- les erreurs bloquantes sont documentées.

5. Optimisation de prompts avec evals

Prompt optimization
/goal Optimise les prompts dans [fichier ou dossier] jusqu’à atteindre [score cible].

Procédure :
- lance [commande d’évaluation] après chaque changement ;
- inspecte les cas échoués ;
- modifie les prompts de manière minimale et ciblée ;
- conserve un journal des changements utiles.

Arrêt :
- arrête-toi quand le score cible est atteint ;
- arrête-toi si les prochaines améliorations demandent une décision produit, juridique ou éditoriale.

Les meilleurs cas d’usage pour /goal

/goal n’est pas utile pour tout. Il devient intéressant quand la tâche est longue, répétitive, mesurable et vérifiable par des commandes. OpenAI met notamment en avant les migrations, la création de prototypes et l’optimisation de prompts avec une suite d’évaluation.

Migrations de stack ou de framework

Les migrations sont le terrain idéal. Elles exigent beaucoup de petites modifications, mais le succès peut souvent être vérifié avec des tests, un build, un lint ou une vérification visuelle. Codex peut avancer fichier par fichier, corriger les erreurs et continuer sans que vous relanciez chaque étape.

Création d’un prototype à partir d’un plan

Si vous avez un PLAN.md précis, Codex peut l’utiliser comme feuille de route. Le bon réflexe consiste à découper le plan en jalons : structure du projet, première interface, logique métier, tests, documentation minimale. Plus le plan est concret, plus /goal est exploitable.

Optimisation de prompts avec une suite d’évaluation

OpenAI documente explicitement ce cas : Codex peut modifier des prompts, lancer une suite d’évaluation, inspecter les échecs, ajuster les formulations et recommencer jusqu’à atteindre un score cible ou une condition d’arrêt. C’est l’un des usages les plus solides, car la boucle repose sur un signal mesurable.

Ajout de tests sur une zone existante

Une autre utilisation très rentable consiste à demander à Codex de renforcer une suite de tests. Le périmètre est clair, le résultat est vérifiable et les erreurs sont faciles à détecter. En revanche, évitez de lui demander de « tester tout le projet » : c’est trop large.

Quand éviter /goal

En pratique, /goal doit être évité quand le succès dépend surtout du goût, de la stratégie ou d’une décision humaine. Un agent peut aider à explorer, mais il ne peut pas deviner une priorité produit non écrite.

Le signal d’alerte est simple : si vous êtes incapable d’écrire la commande, le test ou le critère qui prouve la réussite, commencez par clarifier la tâche avant de lancer /goal.

Les limites à connaître avant de lancer /goal

Le coût en tokens peut monter vite. Une boucle autonome lit, écrit, teste, analyse et recommence. Plus la tâche est large, plus la consommation augmente. Définissez donc un périmètre strict, une condition d’arrêt et une règle de pause.

La vérification doit exister. /goal est beaucoup plus fiable quand le projet contient déjà des tests, un build, un typecheck ou une suite d’évaluation. Sans vérification automatisée, Codex peut produire un résultat plausible mais difficile à valider.

Le contexte du projet compte énormément. Un dépôt avec README, scripts npm, tests, conventions et documentation interne donnera de meilleurs résultats qu’un dossier désorganisé. Avant de lancer un objectif long, ajoutez les informations que vous donneriez à un développeur humain.

La supervision reste nécessaire. /goal peut travailler seul, mais il ne doit pas fusionner aveuglément du code sensible. Utilisez Git, relisez les diffs, vérifiez les dépendances ajoutées et gardez les opérations dangereuses derrière validation humaine.

La fonctionnalité évolue vite. Comme /goal est récent dans Codex CLI, les commandes, comportements et intégrations peuvent changer. Vérifiez le changelog OpenAI avant de publier une procédure figée ou de diagnostiquer un comportement étrange.

Checklist avant de lancer un /goal long

Checklist rapide
git status
[commande de test]
[commande de build]
[commande de lint ou typecheck]

# Puis seulement :
/goal [objectif structuré]

La méthode expert : préparer le goal dans un fichier

Pour les tâches sérieuses, ne tapez pas votre objectif directement dans le terminal. Rédigez plutôt un fichier GOAL.md. Cela vous oblige à clarifier la demande et permet à Codex de s’appuyer sur un document stable.

GOAL.md
# Objectif
Migrer le module billing vers la nouvelle API interne.

# Périmètre
- src/billing/**
- tests/billing/**
- docs/billing.md

# Hors périmètre
- configuration CI
- schéma de base de données
- endpoints publics non liés au billing

# Conditions de succès
- npm test -- billing passe
- npm run typecheck passe
- npm run build passe
- docs/billing.md explique les changements

# Règles d’arrêt
- s’arrêter si une migration de base de données semble nécessaire
- s’arrêter si une décision produit est requise
- ne pas supprimer de test existant sans justification

Puis lancez :

Lancer depuis un fichier
/goal Lis GOAL.md et exécute l’objectif décrit. Respecte strictement le périmètre, les conditions de succès et les règles d’arrêt.

Cette approche est plus propre, plus auditable et plus facile à réutiliser. Elle permet aussi de versionner vos objectifs, comme vous versionnez vos tickets techniques ou vos plans de migration.

Ce que /goal annonce pour Codex

/goal montre la direction prise par les agents de coding : moins de micro-prompts, plus d’objectifs vérifiables. L’enjeu n’est plus seulement de générer du code, mais de tenir une boucle de travail jusqu’à un résultat mesurable.

Pour un développeur, la compétence clé devient donc la formulation d’objectifs. Il faut savoir cadrer le périmètre, définir les tests, imposer les contraintes et prévoir les conditions d’arrêt. Ce n’est pas moins de méthode : c’est plus de méthode, appliquée à un agent autonome.

La bonne manière de commencer est simple : choisissez une tâche utile mais limitée, avec des tests existants, un dépôt Git propre et une commande de validation claire. Lancez /goal, inspectez le diff, puis ajustez votre manière d’écrire les objectifs. C’est là que Codex devient réellement intéressant : pas comme un assistant qui répond, mais comme un agent qui poursuit un résultat.