Bonnes pratiques

Si vous découvrez Codex ou les agents de programmation en général, ce guide vous aidera à obtenir plus rapidement de meilleurs résultats. Il présente les habitudes qui rendent Codex plus efficace dans la CLI, l’extension IDE et l’application de bureau ChatGPT. Vous y apprendrez à rédiger des prompts, à planifier et à vérifier le travail, ainsi qu’à utiliser MCP, les skills et les tâches planifiées.

Vous tirerez davantage parti de Codex en le considérant comme un membre de votre équipe dont vous ajustez la configuration et les méthodes au fil du temps, plutôt que comme un assistant que vous sollicitez ponctuellement.

Commencez par fournir le contexte pertinent pour la tâche. Consignez les instructions durables dans AGENTS.md, configurez Codex en fonction de votre façon de travailler, connectez vos systèmes externes avec MCP, transformez les tâches répétitives en skills et automatisez les workflows qui ont fait leurs preuves.

Bien démarrer avec le contexte et les prompts

Codex peut déjà vous aider même si votre prompt est imparfait. Souvent, vous pouvez lui confier un problème difficile avec peu de préparation et obtenir un bon résultat. Vous pouvez donc commencer sans maîtriser la rédaction de prompts. Des consignes claires rendent toutefois les résultats plus fiables, surtout lorsque la base de code est volumineuse ou que les enjeux sont importants.

Si vous travaillez dans un dépôt volumineux ou complexe, le plus important est de fournir à Codex le contexte pertinent pour la tâche et de structurer clairement votre demande.

En règle générale, incluez quatre éléments dans votre prompt :

• Objectif : que souhaitez-vous modifier ou créer ?
• Contexte : quels fichiers, dossiers, documents, exemples ou messages d’erreur sont pertinents pour cette tâche ? Vous pouvez mentionner certains fichiers avec @ pour les ajouter au contexte.
• Contraintes : quelles normes, règles d’architecture, exigences de sécurité ou conventions Codex doit-il respecter ?
• Critères de réussite : comment saurez-vous que la tâche est terminée ? Par exemple, les tests passent, le comportement a changé ou le bug ne se reproduit plus.

Ces quatre éléments aident Codex à respecter le périmètre de votre demande, à faire moins de suppositions et à produire un travail plus facile à relire.

Utilisez GPT-6.1 Sol s’il est disponible pour votre compte dans votre client, en commençant par le niveau d’effort de raisonnement proposé par défaut dans ce client. Pour GPT-6 Luna, commencez par Élevé. Pour GPT-6 Astra, commencez par Léger (low dans la configuration). Ajustez ensuite le niveau en fonction de la tâche et du résultat. Consultez la page Modèles pour connaître les niveaux de raisonnement disponibles.

• Faible pour les tâches rapides et bien délimitées
• Moyen ou Élevé pour les modifications plus complexes ou le débogage
• Très élevé pour les tâches de longue durée que l’agent mène de façon autonome et qui demandent un raisonnement approfondi

Planifiez les tâches difficiles avant de coder

Si la tâche est complexe, ambiguë ou difficile à décrire précisément, demandez à Codex de préparer un plan avant de commencer à coder.

Plusieurs approches fonctionnent bien :

Utilisez le mode Plan : pour la plupart des utilisateurs, c’est l’option la plus simple et la plus efficace. Le mode Plan permet à Codex de recueillir le contexte, de poser des questions pour clarifier votre demande et d’élaborer un plan plus solide avant de passer à la mise en œuvre. Activez ou désactivez ce mode avec /plan ou Maj+Tab.

Demandez à Codex de vous poser des questions : si vous avez une idée générale du résultat souhaité, mais que vous avez du mal à la formuler, demandez à Codex de vous interroger d’abord. Invitez-le à remettre vos hypothèses en question et à vous aider à concrétiser votre idée avant d’écrire du code.

Utilisez un modèle PLANS.md : pour les workflows plus avancés, vous pouvez configurer Codex pour qu’il suive un fichier PLANS.md ou un modèle de plan d’exécution lors de tâches de longue durée ou en plusieurs étapes. Pour en savoir plus, consultez le guide des plans d’exécution.

Rendez vos instructions réutilisables avec AGENTS.md

Lorsqu’une façon de formuler vos prompts donne de bons résultats, vous pouvez éviter de répéter les mêmes instructions à la main grâce à AGENTS.md.

Considérez AGENTS.md comme un README au format ouvert destiné aux agents. Son contenu est automatiquement chargé dans le contexte. C’est l’endroit idéal pour préciser comment votre équipe et vous-même souhaitez que Codex travaille dans un dépôt.

Un bon fichier AGENTS.md précise :

• L’organisation du dépôt et ses principaux répertoires
• La procédure pour lancer le projet
• Les commandes de build, de test et de lint
• Les conventions de développement et les attentes concernant les pull requests
• Les contraintes et les actions à proscrire
• Les critères de réussite et la façon de vérifier le travail

Dans la CLI, la commande slash /init génère un premier fichier AGENTS.md dans le répertoire courant. C’est un bon point de départ. Adaptez ensuite le fichier à la façon dont votre équipe compile, teste, relit et livre le code.

Vous pouvez créer des fichiers AGENTS.md à plusieurs niveaux : un fichier AGENTS.md global dans ~/.codex pour vos préférences personnelles, un fichier à la racine du dépôt pour les conventions communes et des fichiers dans les sous-répertoires pour les règles locales. Les instructions du fichier le plus spécifique et le plus proche de votre répertoire courant sont prioritaires.

Privilégiez les consignes concrètes. Un fichier AGENTS.md court et précis est plus utile qu’un long fichier rempli de règles vagues. Commencez par l’essentiel et n’ajoutez de règles que lorsque vous constatez des erreurs récurrentes.

Si AGENTS.md devient trop long, gardez le fichier principal concis et renvoyez à des fichiers Markdown consacrés à des sujets précis, comme la planification, la revue de code ou l’architecture.

Configurez Codex pour obtenir un comportement cohérent

La configuration est l’un des principaux moyens d’obtenir un comportement cohérent d’une session à l’autre et dans différentes interfaces. Vous pouvez notamment définir le modèle par défaut, l’effort de raisonnement, le mode de bac à sable, la politique d’approbation, les profils et les paramètres MCP.

Pour commencer :

• Enregistrez vos préférences personnelles dans ~/.codex/config.toml (Paramètres > Configuration > Ouvrir config.toml dans l’application de bureau ChatGPT)
• Définissez les paramètres propres au dépôt dans .codex/config.toml
• Si vous utilisez la CLI, réservez les options de ligne de commande qui remplacent ces paramètres aux besoins ponctuels

Le fichier config.toml vous permet de définir des préférences durables, comme les serveurs MCP, la configuration multi-agent et les options d’activation des fonctionnalités. Les paramètres propres à chaque profil se trouvent dans des fichiers $CODEX_HOME/profile-name.config.toml distincts.

Codex intègre un bac à sable au niveau du système d’exploitation. Vous disposez de deux réglages principaux. Le mode d’approbation détermine quand Codex vous demande la permission d’exécuter une commande. Le mode de bac à sable détermine si Codex peut lire ou écrire dans le répertoire et à quels fichiers l’agent peut accéder.

Si vous découvrez les agents de programmation, commencez par les autorisations par défaut. Conservez des règles d’approbation et de bac à sable strictes par défaut. N’élargissez les autorisations que pour des dépôts de confiance ou des workflows précis, une fois le besoin établi.

La CLI, l’extension IDE et l’application de bureau ChatGPT utilisent les mêmes niveaux de configuration. Pour en savoir plus, consultez l’exemple de configuration.

Améliorez la fiabilité grâce aux tests et à la revue de code

Lorsque vous demandez une modification à Codex, demandez-lui aussi de créer des tests si nécessaire, d’exécuter les vérifications pertinentes, de confirmer le résultat et de relire les modifications avant que vous les acceptiez.

Codex peut se charger de toutes ces étapes s’il connaît vos critères de réussite. Vous pouvez les préciser dans le prompt ou dans AGENTS.md.

Vous pouvez notamment lui demander de :

• Rédiger ou mettre à jour les tests correspondant à la modification
• Exécuter les suites de tests pertinentes
• Vérifier les résultats du lint, du contrôle du formatage ou de la vérification des types
• Confirmer que le comportement final correspond à la demande
• Examiner le diff pour repérer les bugs, les régressions ou les pratiques à risque

La commande slash /review propose plusieurs façons d’effectuer une revue de code :

• Comparer les modifications à une branche de base, comme pour la revue d’une pull request
• Examiner les modifications qui n’ont pas encore fait l’objet d’un commit
• Examiner un commit
• Utiliser des instructions de revue personnalisées

Si votre équipe dispose d’un fichier code_review.md et que vous y faites référence dans AGENTS.md, Codex peut également suivre ces instructions lors de la revue. Cette approche permet d’appliquer les mêmes pratiques de revue quels que soient le dépôt et les contributeurs.

Vous pouvez confier à Codex bien plus que la génération de code. Avec les bonnes instructions, il peut aussi vous aider à tester le code, à le vérifier et à en faire la revue.

Si vous utilisez GitHub Cloud, vous pouvez configurer Codex pour qu’il effectue des revues de code sur vos pull requests. Chez OpenAI, Codex examine 100 % des pull requests. Vous pouvez activer les revues automatiques ou demander une revue en mentionnant @Codex.

Utilisez MCP pour accéder au contexte externe

Utilisez des serveurs MCP lorsque le contexte dont Codex a besoin se trouve en dehors du dépôt. Codex peut ainsi se connecter aux outils et aux systèmes que vous utilisez déjà, sans que vous ayez à copier-coller les informations à jour dans chaque prompt.

Le Model Context Protocol, ou MCP, est un standard ouvert qui permet de connecter Codex à des outils et à des systèmes externes.

Utilisez MCP lorsque :

• Le contexte nécessaire se trouve en dehors du dépôt
• Les données changent fréquemment
• Vous souhaitez que Codex utilise un outil plutôt que de s’appuyer sur des instructions copiées-collées
• Vous avez besoin d’une intégration réutilisable par plusieurs utilisateurs ou dans plusieurs projets

Codex prend en charge les serveurs STDIO ainsi que les serveurs Streamable HTTP avec OAuth.

Dans l’application de bureau ChatGPT, ouvrez Paramètres > Serveurs MCP pour consulter les serveurs personnalisés et recommandés. Codex peut souvent vous aider à installer les serveurs nécessaires. Il suffit de le lui demander. Vous pouvez aussi utiliser la commande codex mcp add dans la CLI pour ajouter vos serveurs personnalisés en indiquant leur nom, leur URL et d’autres paramètres.

Transformez les tâches répétitives en skills

Lorsqu’un workflow devient reproductible, vous pouvez vous passer des longs prompts et des échanges à répétition. Utilisez un skill pour regrouper les instructions dans un fichier SKILL.md, avec le contexte et la logique que Codex doit appliquer systématiquement. Les skills fonctionnent dans la CLI, l’extension IDE et l’application de bureau ChatGPT.

Limitez chaque skill à une seule tâche. Commencez par deux ou trois cas d’usage concrets et définissez clairement les entrées et les sorties. Dans la description, précisez ce que fait le skill et quand l’utiliser. Incluez des formulations qu’un utilisateur emploierait naturellement pour le déclencher.

Évitez de vouloir traiter tous les cas particuliers dès le départ. Commencez par une tâche représentative. Une fois qu’elle s’exécute correctement, transformez le workflow en skill, puis affinez-le. N’ajoutez des scripts ou d’autres ressources que s’ils améliorent sa fiabilité.

Si vous réutilisez souvent le même prompt ou corrigez régulièrement le même workflow, il est probablement temps d’en faire un skill.

Les skills sont particulièrement utiles pour les tâches récurrentes comme :

• Le tri des journaux
• La rédaction de notes de version
• La revue de pull requests à partir d’une liste de vérification
• La planification de migrations
• La synthèse de données de télémétrie ou d’incidents
• Les procédures habituelles de débogage

Le skill $skill-creator est le meilleur point de départ pour créer une première version d’un skill. Gardez cette version en local le temps de l’affiner. Lorsqu’elle est prête à être diffusée plus largement, distribuez-la sous forme de plugin. La description est l’un des éléments les plus importants d’un skill : elle doit préciser ce qu’il fait et quand l’utiliser.

Utilisez les tâches planifiées pour le travail récurrent

Une fois qu’un workflow est stable, vous pouvez programmer son exécution par Codex en arrière-plan. Dans l’application de bureau ChatGPT, les tâches planifiées vous permettent de choisir le projet, le prompt, la fréquence et l’environnement d’exécution de vos tâches récurrentes.

Créez une tâche planifiée depuis la page Tâches planifiées. Choisissez le projet, le prompt et la fréquence, puis indiquez si la tâche doit s’exécuter dans un arbre de travail Git dédié ou dans votre environnement local. Le prompt peut faire appel à des skills. Pour en savoir plus, consultez la page sur les arbres de travail Git.

Voici quelques exemples de tâches qui se prêtent à la planification :

• Résumer les commits récents
• Rechercher des bugs potentiels
• Rédiger des notes de version
• Examiner les échecs de la CI
• Préparer des synthèses pour les points d’équipe quotidiens
• Exécuter des workflows d’analyse reproductibles à intervalles réguliers

Les skills définissent la méthode, les tâches planifiées fixent le calendrier. Si un workflow demande encore beaucoup d’interventions de votre part, commencez par en faire un skill. Une fois son comportement prévisible, vous pouvez gagner du temps en planifiant son exécution.

Organisez les discussions de longue durée

Au fil du temps, chaque discussion accumule du contexte, des décisions et des actions. La façon dont vous organisez vos discussions influe donc beaucoup sur la qualité des résultats.

L’application de bureau ChatGPT vous permet d’épingler des discussions et de créer des arbres de travail. Si vous utilisez la CLI, ces commandes slash sont particulièrement utiles :

• /experimental pour activer ou désactiver des fonctionnalités expérimentales et enregistrer vos choix dans config.toml
• /resume pour reprendre une discussion enregistrée
• /fork pour créer une discussion tout en conservant l’historique de la discussion d’origine
• /compact pour résumer le contexte précédent lorsqu’une discussion s’allonge. Codex effectue aussi cette opération automatiquement
• /subagents pour passer d’un fil de sous-agent à l’autre dans la discussion en cours
• /theme pour choisir un thème de coloration syntaxique
• /apps pour utiliser les applications ChatGPT directement dans Codex
• /status pour consulter l’état de la session en cours

Consacrez chaque discussion à un ensemble cohérent de tâches. Si vous travaillez toujours sur le même problème, il est souvent préférable de poursuivre la discussion pour conserver le fil du raisonnement. Ne forkez la discussion que lorsque le travail prend réellement des directions distinctes.

Erreurs courantes

Voici quelques erreurs à éviter lorsque vous débutez avec Codex :

• Surcharger le prompt de règles durables au lieu de les consigner dans AGENTS.md ou dans un skill
• Empêcher l’agent de vérifier son travail en omettant de préciser comment exécuter les commandes de build et de test
• Sauter l’étape de planification pour les tâches complexes ou en plusieurs étapes
• Accorder à Codex un accès complet à votre ordinateur avant de bien comprendre le workflow
• Exécuter des tâches en parallèle sur les mêmes fichiers sans utiliser d’arbres de travail Git
• Planifier une tâche récurrente avant que son exécution manuelle soit fiable
• Surveiller Codex à chaque étape au lieu de le laisser avancer en parallèle de votre propre travail
• Utiliser une seule discussion pour tout un projet au lieu d’en consacrer une à chaque résultat distinct. Le contexte devient alors trop volumineux et les résultats se dégradent au fil du temps