Bien démarrer avec Codex : bonnes pratiques pour de meilleurs résultats

Si vous débutez avec @OpenAI Codex ou les agents de codage en général, ce guide vous aidera à obtenir de meilleurs résultats plus rapidement. Il couvre les habitudes essentielles qui rendent Codex plus efficace dans l’interface en ligne de commande (CLI), les extensions IDE et l’application Codex, que ce soit pour le prompting, la planification, la validation, le MCP, les compétences et les automatisations.

Codex fonctionne mieux lorsque vous le traitez moins comme un assistant ponctuel et plus comme un coéquipier que vous configurez et améliorez au fil du temps.

Un modèle mental utile est le suivant : commencez avec le bon contexte de tâche, utilisez AGENTS.md pour des directives durables, configurez Codex en fonction de votre flux de travail, connectez des systèmes externes avec MCP, transformez les tâches répétées en compétences, et automatisez les workflows stables.

1. Configurez Codex pour une première utilisation optimale avec un contexte et un prompting clairs

Codex est déjà suffisamment performant pour être utile même lorsque votre prompt n’est pas parfait. Vous pouvez souvent lui confier un problème difficile avec une configuration minimale et obtenir un résultat solide. Un prompting clair n’est pas nécessaire pour en tirer de la valeur, mais il rend les résultats plus fiables, en particulier dans les bases de code volumineuses ou les tâches à enjeux élevés.

Si vous travaillez dans un dépôt volumineux ou complexe, le principal levier est généralement de fournir à Codex le bon contexte de tâche et une structure claire de ce que vous souhaitez faire.

Une bonne approche par défaut consiste à inclure quatre éléments dans votre prompt :

• Objectif : Que cherchez-vous à changer ou à construire ?
• Contexte : Quels fichiers, dossiers, documents, exemples ou erreurs sont pertinents pour cette tâche ? Vous pouvez @mentionner certains fichiers comme contexte.
• Contraintes : Quelles normes, architecture, exigences de sécurité ou conventions Codex doit-il suivre ?
• Terminé quand : Qu’est-ce qui doit être vérifié avant que la tâche soit terminée, comme des tests qui passent, un changement de comportement, ou un bug corrigé ?

Cela aide Codex à rester dans le cadre, à faire moins d’hypothèses et à produire un travail plus facile à réviser et à valider.

Choisissez un niveau de raisonnement en fonction de la difficulté de la tâche et testez ce qui fonctionne le mieux pour votre flux de travail. Différents utilisateurs et tâches bénéficient de réglages différents.

• Faible pour des tâches rapides et bien cadrées
• Moyen ou Élevé pour des modifications ou du débogage plus complexes
• Très élevé pour des tâches longues, agentiques et nécessitant beaucoup de raisonnement

Conseil pour les nouveaux utilisateurs

La plupart des gens montent en compétence le plus rapidement en commençant par quelques petites victoires, comme poser des questions à Codex sur la base de code ou l’utiliser pour effectuer une petite correction ciblée. Je recommande vivement d’utiliser la dictée vocale dans l’application Codex pour accélérer les itérations.

Efforts de raisonnement de Codex

2. Réduisez les erreurs sur les tâches difficiles en demandant d’abord à Codex de planifier

Si la tâche est complexe, ambiguë ou difficile à décrire clairement, demandez à Codex de planifier avant de commencer à coder.

Il existe plusieurs bonnes façons de procéder :

Utiliser 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 rassembler le contexte, de poser des questions de clarification et d’élaborer un plan plus solide avant la mise en œuvre. Activez-le avec /plan ou Maj+Tab.

Demander à Codex de vous interviewer : Si vous avez une idée vague de ce que vous voulez mais que vous n’êtes pas sûr de bien la décrire, demandez à Codex de vous questionner d’abord. Dites-lui de remettre en question vos hypothèses et de transformer l’idée floue en quelque chose de concret avant d’écrire du code.

Utiliser un modèle PLANS.md : Pour des workflows plus avancés, vous pouvez configurer Codex pour suivre un modèle PLANS.md ou un plan d’exécution pour des travaux longs ou en plusieurs étapes. Pour plus de détails, consultez notre guide des plans d’exécution.

Mode Plan

3. Rendez les bonnes pratiques réutilisables avec AGENTS.md

Une fois qu’un modèle de prompting fonctionne, l’étape suivante est d’arrêter de le répéter manuellement. C’est là qu’intervient AGENTS.md.

Considérez AGENTS.md comme un README pour les agents. C’est un format simple et ouvert qui est chargé automatiquement dans le contexte et le meilleur endroit pour encoder comment vous et votre équipe souhaitez que Codex fonctionne dans un dépôt.

Un bon AGENTS.md couvre généralement :

• La disposition du dépôt et les répertoires importants
• Comment exécuter le projet
• Les commandes de build, de test et de lint
• Les conventions d’ingénierie et les attentes pour les PR
• Les contraintes et les règles à ne pas faire
• Ce que signifie « terminé » et comment vérifier le travail

La commande slash /init dans la CLI est la commande de démarrage rapide pour générer un AGENTS.md de base dans le répertoire courant. C’est un excellent point de départ, mais vous devez modifier le résultat pour qu’il corresponde à la façon dont votre équipe construit, teste, révise et livre le code.

Vous pouvez créer des fichiers AGENTS.md à plusieurs niveaux : un AGENTS.md global pour les paramètres personnels situé dans ~/.codex, un fichier au niveau du dépôt pour les normes partagées, et des fichiers plus spécifiques dans les sous-répertoires pour les règles locales. S’il existe un fichier plus spécifique plus proche de votre répertoire courant, ces directives l’emportent.

Restez pratique. Un AGENTS.md court et précis est plus utile qu’un long fichier rempli de règles vagues. Commencez par l’essentiel, puis ajoutez de nouvelles règles uniquement après avoir remarqué des erreurs répétées.

Si AGENTS.md commence à devenir trop volumineux, gardez le fichier principal concis et référencez des fichiers markdown spécifiques à la tâche pour des choses comme la planification, la revue de code ou l’architecture.

Conseil

Lorsque Codex fait la même erreur deux fois, demandez-lui une rétrospective et mettez à jour AGENTS.md. Les directives restent ainsi pratiques et basées sur des frictions réelles.

Site web AGENTS.md

4. Obtenez un comportement plus cohérent en configurant Codex selon votre flux de travail

La configuration est l’un des principaux moyens de rendre le comportement de Codex plus cohérent entre les sessions et les surfaces. Par exemple, vous pouvez définir des valeurs par défaut pour le choix du modèle, l’effort de raisonnement, le mode sandbox, la politique d’approbation, les profils et la configuration MCP.

Un bon modèle de départ est le suivant :

• Conservez les paramètres personnels par défaut dans ~/.codex/config.toml (Paramètres → Configuration → Ouvrir config.toml depuis l’application Codex)
• Conservez le comportement spécifique au dépôt dans .codex/config.toml
• Utilisez les surcharges en ligne de commande uniquement pour des situations ponctuelles (si vous utilisez la CLI)

Config.toml est l’endroit où vous définissez des préférences durables telles que les serveurs MCP, les profils, la configuration multi-agent et les fonctionnalités expérimentales. Vous pouvez le modifier directement ou demander à Codex de le mettre à jour pour vous.

Codex est livré avec un sandboxing au niveau du système d’exploitation et dispose de deux leviers clés que vous pouvez contrôler. Le mode d’approbation détermine quand Codex demande votre autorisation pour exécuter une commande, et le mode sandbox détermine si Codex peut lire ou écrire dans le répertoire et quels fichiers l’agent peut consulter.

Si vous êtes complètement novice en matière d’agents de codage, il est recommandé de commencer de manière conservatrice avec des autorisations par défaut. Gardez l’approbation et le sandboxing serrés par défaut, puis assouplissez les autorisations uniquement pour les dépôts de confiance ou les workflows spécifiques une fois que le besoin est clair.

Notez que la CLI, l’IDE et l’application Codex partagent toutes les mêmes couches de configuration. Apprenez-en plus sur notre page de configuration d’exemple.

Conseil

Configurez Codex pour votre environnement réel dès le début. De nombreux problèmes de qualité sont en réalité des problèmes de configuration, comme un mauvais répertoire de travail, un accès en écriture manquant, de mauvais paramètres de modèle par défaut, ou des outils et connecteurs manquants.

5. Améliorez la fiabilité en demandant à Codex de tester, valider et réviser le travail

Ne vous arrêtez pas à demander à Codex d’apporter une modification. Demandez-lui de créer des tests si nécessaire, d’exécuter les vérifications appropriées, de valider le résultat et de réviser le travail avant que vous l’acceptiez.

Codex peut effectuer cette boucle pour vous, mais seulement s’il sait ce qu’est un « bon » résultat. Ces directives peuvent provenir du prompt ou d’AGENTS.md.

Cela peut inclure :

• Écrire ou mettre à jour des tests pour la modification
• Exécuter les suites de tests appropriées
• Vérifier le lint, le formatage ou les vérifications de type
• Confirmer que le comportement final correspond à la demande
• Réviser le diff pour détecter des bugs, des régressions ou des motifs risqués

Conseil :

Activez le panneau de diff dans l’application Codex pour

réviser les modifications localement. Cliquez sur une ligne spécifique pour fournir un retour qui sera utilisé comme contexte pour le prochain tour de Codex.

Une option utile ici est la commande slash /review, qui vous offre plusieurs façons de réviser le code :

• Réviser par rapport à une branche de base pour une révision de type PR
• Réviser les modifications non commitées
• Réviser un commit
• Utiliser des instructions de révision personnalisées

Si vous et votre équipe avez un fichier code_review.md référencé dans AGENTS.md, Codex peut également suivre ces directives lors de la révision. C’est un modèle puissant pour les équipes qui souhaitent que le comportement de révision reste cohérent entre les dépôts et les contributeurs.

Codex ne devrait pas seulement générer du code. Avec les bonnes instructions, il peut aussi le tester, le valider et le réviser.

Si vous utilisez GitHub Cloud, vous pouvez facilement configurer Codex pour effectuer des révisions de code pour vos PR. Chez OpenAI, Codex révisé 100% des PR. Vous avez la possibilité d’activer les révisions automatiques ou de demander à Codex de réviser de manière réactive lorsque vous @Codex.

/review dans Codex CLI

6. Apportez des outils externes et du contexte en direct à Codex avec les MCP

Utilisez les MCP lorsque le contexte dont Codex a besoin se trouve en dehors du dépôt. Cela permet à Codex de se connecter aux outils et systèmes que vous utilisez déjà, afin que vous n’ayez pas à copier-coller manuellement des informations en direct dans les prompts.

Model Context Protocol, ou MCP, est un standard ouvert pour connecter Codex à des outils et 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 se fier à des instructions copiées-collées
• Vous avez besoin d’une intégration reproductible entre utilisateurs ou projets

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

Dans l’application Codex, allez dans Paramètres → Serveurs MCP pour voir les serveurs personnalisés et recommandés. Souvent, Codex peut vous aider à installer les serveurs nécessaires. Il vous suffit de le demander. Vous pouvez également utiliser la commande codex mcp add dans la CLI pour ajouter vos serveurs personnalisés avec un nom, une URL et toute information supplémentaire.

Conseil

N’ajoutez des outils que lorsqu’ils débloquent un workflow réel. Ne commencez pas par connecter tous les outils que vous utilisez. Commencez par un ou deux outils qui suppriment clairement une boucle manuelle que vous effectuez souvent, puis développez à partir de là.

Gestion des serveurs MCP

7. Transformez les workflows répétés en compétences réutilisables

Une fois qu’un workflow devient répétable, arrêtez de vous appuyer sur de longs prompts ou des allers-retours répétés. Utilisez une Compétence pour empaqueter les instructions dans un fichier SKILL.md, le contexte et la logique de support que Codex doit appliquer de manière cohérente. Les compétences fonctionnent dans la CLI, l’extension IDE et l’application Codex.

Gardez chaque compétence strictement limitée à une seule tâche. Commencez avec 2 à 3 cas d’utilisation concrets, définissez des entrées et sorties claires, et rédigez la description de manière à ce qu’elle indique clairement ce que fait la compétence et quand l’utiliser. Incluez les types de phrases déclencheuses qu’un utilisateur pourrait réellement prononcer.

N’essayez pas de couvrir tous les cas particuliers dès le début. Commencez par une tâche représentative, faites-la fonctionner correctement, puis transformez ce workflow en compétence et améliorez-le à partir de là. N’incluez des scripts ou des ressources supplémentaires que s’ils améliorent significativement la fiabilité.

Une bonne règle de base : si vous réutilisez le même prompt ou corrigez le même workflow à plusieurs reprises, il devrait probablement devenir une compétence.

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

• Le tri des logs
• La rédaction de notes de version
• La révision de PR par rapport à une checklist
• La planification de migration
• Les résumés de télémétrie ou d’incidents
• Les flux de débogage standard

La compétence $skill-creator est le meilleur point de départ pour structurer une première version d’une compétence, et utilisez la compétence $skill-installer pour l’installer localement. L’une des parties les plus importantes d’une compétence est la description. Elle doit clairement indiquer ce que fait la compétence et quand l’utiliser.

Conseil

Les compétences personnelles sont stockées dans

$HOME /.agents/skills, et les compétences d’équipe partagées peuvent être intégrées dans .agents/skills à l’intérieur d’un dépôt. C’est particulièrement utile pour l’intégration des nouveaux membres de l’équipe.

Création et installation de compétences

Interface utilisateur des compétences de l’application Codex

8. Gagnez du temps sur les tâches récurrentes avec les automatisations

Une fois qu’un workflow est stable, vous pouvez planifier l’exécution de Codex en arrière-plan pour vous. Dans l’application Codex, les automatisations vous permettent de choisir le projet, le prompt, la cadence et l’environnement d’exécution pour une tâche récurrente.

Lorsqu’une tâche devient répétitive pour vous, vous pouvez facilement créer une automatisation dans l’onglet Automatisations de l’application Codex. Vous pouvez choisir le projet dans lequel elle s’exécute, le prompt qu’elle exécute (vous pouvez invoquer des compétences) et la cadence à laquelle elle s’exécutera. Vous pouvez également choisir si l’automatisation s’exécute dans un worktree git dédié ou dans votre environnement local. Apprenez-en plus sur les worktrees git.

Les bons candidats incluent :

• Résumer les commits récents
• Scanner les bugs probables
• Rédiger des notes de version
• Vérifier les échecs CI
• Produire des résumés de stand-up
• Exécuter des workflows d’analyse répétables selon un calendrier

Une règle utile est que les compétences définissent la méthode, les automatisations définissent le calendrier. Si un workflow nécessite encore beaucoup de pilotage, transformez-le d’abord en compétence. Une fois qu’il est prévisible, l’automatisation devient un multiplicateur de force.

Conseil

Utilisez les automatisations pour la réflexion et la maintenance, pas seulement pour l’exécution. Révisez les sessions récentes, résumez les frictions répétées et améliorez les prompts, les instructions ou la configuration du workflow au fil du temps.

Création d’automatisation dans l’application Codex

9. Restez organisé dans les travaux de longue durée avec les contrôles de session

Les sessions Codex ne sont pas seulement un historique de chat. Ce sont des fils de travail qui accumulent du contexte, des décisions et des actions au fil du temps, donc bien les gérer a un impact important sur la qualité.

La gestion de plusieurs fils est plus facile dans l’interface utilisateur de l’application Codex, avec la possibilité d’épingler des fils et de créer des worktrees. Mais si vous utilisez la CLI, ces commandes slash sont particulièrement utiles :

• /experimental pour activer/désactiver les fonctionnalités expérimentales et les ajouter à votre config.toml
• /resume pour reprendre une conversation sauvegardée
• /fork pour créer un nouveau fil tout en conservant la transcription originale
• /compact lorsque le fil devient long et que vous souhaitez une version résumée du contexte précédent. Notez que Codex compacte automatiquement les conversations pour vous
• /agent lorsque vous exécutez plusieurs agents et que vous souhaitez basculer entre le fil de l’agent actif
• /theme pour choisir un thème de coloration syntaxique
• /apps pour utiliser les applications ChatGPT directement dans Codex
• /status pour inspecter l’état de la session actuelle

Gardez un fil par unité de travail cohérente. Si le travail fait toujours partie du même problème, rester dans le même fil est souvent mieux car cela préserve la trace de raisonnement. Ne bifurquez (fork) que lorsque le travail diverge vraiment.

Conseil :

Utilisez les workflows

multi-agents de Codex pour décharger du travail limité du fil principal. Gardez l’agent principal concentré sur le problème central, et utilisez des sous-agents pour des tâches comme l’exploration, les tests ou le tri.

10. Erreurs courantes à éviter

Quelques erreurs courantes à éviter lors de la première utilisation de Codex :

• Surcharger le prompt avec des règles durables au lieu de les déplacer dans AGENTS.md ou une compétence
• Ne pas laisser l’agent voir son travail en ne donnant pas de détails sur la meilleure façon d’exécuter les commandes de build et de test
• Sauter la planification pour les tâches multi-étapes et complexes
• Donner à Codex une autorisation totale sur votre ordinateur avant de comprendre le workflow
• Exécuter plusieurs fils actifs sur les mêmes fichiers sans utiliser de worktrees git
• Transformer une tâche récurrente en automatisation avant qu’elle ne soit fiable manuellement
• Utiliser Codex en parallèle avec votre propre travail au lieu de le traiter comme quelque chose que vous devez surveiller étape par étape

Liste de contrôle pour démarrer

1. Donnez à Codex le bon objectif, contexte, contraintes et condition de fin
2. Pour les tâches difficiles, demandez d’abord à Codex de planifier
3. Créez un AGENTS.md de base
4. Dites à Codex comment builder, tester, valider et réviser
5. Définissez des valeurs de configuration par défaut qui correspondent à votre flux de travail
6. Ajoutez MCP pour les outils externes à forte valeur ajoutée
7. Transformez les workflows répétés en compétences
8. Utilisez les automatisations une fois qu’un workflow est stable

Plus vous transformez votre flux de travail, vos normes et votre contexte en quelque chose que Codex peut utiliser, plus vous verrez ce que l’agent peut vraiment faire. Commencez dès aujourd’hui !