Conseils d'utilisation avancée de Codex
Après avoir terminé l’installation de base et la première conversation, la vraie valeur de Codex réside dans son intégration à votre flux de travail de développement quotidien.
Cet article couvre cinq orientations avancées : configuration de projet, gestion des sessions, intégration à l’éditeur, automatisation CI/CD et conseils sur les prompts, vous aidant à faire en sorte que Codex comprenne votre projet, mémorise vos conventions et travaille automatiquement dans le pipeline.
1. Rédiger un « document d’intégration » pour Codex avec AGENTS.md
AGENTS.md est un manuel de projet écrit pour Codex. Placé dans le répertoire racine du projet, il est automatiquement chargé à chaque démarrage et reste en vigueur tout au long de la session.
Pourquoi vous en avez besoin
Par défaut, Codex ne sait rien de votre projet.
Il ne sait pas si vous utilisez App Router ou Pages Router, ne sait pas par quel fichier les opérations de base de données doivent uniformément passer, et ne sait pas quels fichiers ne doivent pas être touchés.
Si vous devez réexpliquer le contexte à chaque conversation, l’efficacité sera très faible et des erreurs sont probables.
AGENTS.md permet d'écrire ces informations une fois et qu'elles restent en vigueur, ce qui évite d'avoir à vous répéter.
Ce qu'il faut écrire
Un AGENTS.md efficace contient généralement quatre types d'informations : présentation du projet, stack technique, conventions importantes et éléments interdits.
Voici un exemple complet :
# AGENTS.md ## 项目概述 这是一个基于 Next.js 14 + Prisma + PostgreSQL 的 SaaS 应用。 使用 App Router,不使用 Pages Router。 ## 技术栈 - 前端:Next.js 14, React 18, TailwindCSS, shadcn/ui - 后端:Next.js API Routes, Prisma ORM - 数据库:PostgreSQL 15 - 认证:NextAuth.js ## 重要约定 - 所有数据库操作必须通过 lib/db.ts 中的 prisma 实例 - API 路由错误统一用 lib/api-error.ts 处理 - 环境变量在 .env.local 中,参考 .env.example ## 禁止事项 - 不要修改 prisma/schema.prisma,除非我明确要求 - 不要删除任何现有测试 - 生产环境的 .env 文件不要碰
La section « Éléments interdits » est particulièrement importante. Lors de l'exécution de tâches, Codex déduit activement quels fichiers doivent être modifiés. Sans limites claires, il peut toucher des endroits que vous ne souhaitez pas. Écrire clairement les lignes rouges est bien plus facile que de corriger les problèmes après qu'ils se sont produits.
Structure hiérarchique de la configuration
AGENTS.md prend en charge trois niveaux d'imbrication, avec une priorité organisée de faible à élevée.
Plus un fichier est proche du répertoire courant, plus sa priorité est élevée. Dans le même répertoire, lorsque AGENTS.override.md existe, le fichier AGENTS.md situé au même niveau sera ignoré.
| Niveau | Chemin | Portée | Priorité |
|---|---|---|---|
| Niveau global | ~/.codex/AGENTS.md | Conventions générales inter-projets | Faible |
| Niveau projet | repo/AGENTS.md | Conventions au niveau du dépôt | Moyenne |
| Niveau de remplacement | repo/services/payments/AGENTS.override.md | Règles spéciales pour les sous-répertoires | Élevée |
Le niveau global convient aux conventions qui s'appliquent à tous les projets, par exemple :
# ~/.codex/AGENTS.md ## 全局约定 - 安装依赖时优先使用 pnpm - 修改 JavaScript 文件后始终运行 npm test - 新增生产依赖前先请求确认
Une fois la configuration terminée, vous pouvez utiliser la commande suivante pour vérifier que le chargement est correct :
codex --ask-for-approval never "Summarize the current instructions."
2. Gestion des sessions : poursuivre de grandes tâches sur plusieurs jours
La fonctionnalité de gestion de session vous permet d'exporter l'état actuel de la conversation vers un fichier et de le restaurer directement la prochaine fois, sans rétablir le contexte.
Arrière-plan
La fenêtre de contexte de Codex est limitée.
Lorsque vous traitez une grande tâche qui couvre plusieurs fichiers et doit être avancée par étapes, si vous fermez le terminal en cours de route ou passez à autre chose, le contexte sera perdu lorsque vous reviendrez — Codex ne se souviendra pas de ce qui a été discuté auparavant ni des décisions qui ont été prises.
L'exportation de la session peut résoudre ce problème, en vous permettant de restaurer l'état de la conversation précédente à tout moment.
Utilisation de base
Les commandes courantes liées à la gestion des sessions sont les suivantes :
Exemple
/export session-2024-01-15.json
# Restaurer lors de la reprise la prochaine fois
/load session-2024-01-15.json
# Reprendre directement la session la plus récente (la plus couramment utilisée)
codex resume --last
# Afficher toutes les sessions enregistrées
ls ~/.codex/sessions/
Quand exporter
Vous n'avez pas besoin d'exporter chaque conversation. Les situations suivantes méritent d'être enregistrées :
| Scénario | Description |
|---|---|
| Tâches à plusieurs étapes s'étalant sur plusieurs jours | La tâche s'étend sur plusieurs jours avec des phases clairement délimitées ; après sauvegarde, vous pouvez reprendre directement à partir du dernier point de contrôle la prochaine fois. |
| Décisions architecturales importantes | Une décision architecturale importante a été discutée avec Codex, et les tâches suivantes doivent se poursuivre sur la base de cette décision. |
| Processus de débogage complexes | Débogage d’un bug complexe, plusieurs pistes déjà écartées, ne pas vouloir repartir de zéro la prochaine fois. |
3. Intégration avec VS Code
Codex fournit officiellement une extension VS Code. Après installation, vous pouvez démarrer des conversations directement dans l’éditeur sans passer au terminal.
Installation et connexion
Les étapes d’installation sont les suivantes :
Étape 1 : Ouvrez la place de marché des extensions (Cmd/Ctrl + Shift + X).
-
Étape 2 : Recherchez « Codex » ou « OpenAI Codex » et installez le plugin officiel.

-
Étape 3 : Vous devez vous connecter à votre compte ChatGPT lors de la première utilisation.
-
Étape 4 : Une fois que l’icône Codex apparaît dans la barre latérale, il est prêt à l’emploi.
Après l'installation, vous pouvez utiliser les raccourcis clavier suivants pour des actions rapides :
| Raccourci | Fonction |
|---|---|
| Alt + G | Envoyer le code sélectionné à Codex, y compris le contexte du fichier actuel |
| Cmd + Shift + P | Ouvrez la palette de commandes, tapez "Codex" pour afficher toutes les commandes disponibles |
Mode BYO (pour les utilisateurs sans abonnement à ChatGPT)
Si vous avez déjà configuré votre propre clé API dans le CLI (Anthropic, OpenAI ou d'autres fournisseurs compatibles), vous pouvez utiliser un compte ChatGPT gratuit pour vous connecter au plugin VS Code.
Le plugin réutilise automatiquement la configuration de modèle du CLI et ne vous force pas à utiliser ChatGPT Plus.
| Scénarios applicables | Description |
|---|---|
| Vous avez déjà une clé API, mais vous ne voulez pas vous abonner à ChatGPT séparément | Utilisez directement votre propre clé API, aucun abonnement payant supplémentaire n'est requis |
| Vous voulez que VS Code et CLI utilisent le même modèle | Le plugin réutilise automatiquement la configuration du CLI, afin que les deux côtés aient une expérience identique. |
4. Intégration CI/CD
Codex CLI prend en charge l'exécution en mode headless, sans nécessiter d'interaction humaine, ce qui le rend adapté à une intégration dans des workflows automatisés.
Ce que Codex peut faire dans un pipeline
Voici les utilisations courantes de Codex dans CI/CD en mode headless :
| Cas d'utilisation | Description | Moment de déclenchement typique |
|---|---|---|
| Mettre à jour automatiquement CHANGELOG | Après chaque fusion vers la branche principale, mettre à jour automatiquement CHANGELOG.md en fonction de l'historique des commits. | Après fusion vers la branche principale |
| Générer la documentation API | Générer ou synchroniser automatiquement la documentation API en fonction des modifications de code | Après un push de code |
| Revue de code automatique | Exécuter automatiquement la revue de code dans le pipeline de PR et déposer des commentaires | Lorsqu'une PR est créée ou mise à jour |
Exemple GitHub Actions
Le workflow suivant permet automatiquement à Codex de mettre à jour CHANGELOG.md en fonction des derniers commits à chaque fois que du code est poussé vers la branche main :
Exemple
name: Mise à jour automatique du journal des modifications
sur:
push:
branches: [main]
jobs:
update-changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configurer Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Installer Codex CLI
run: npm install -g @openai/codex
- name: Exécuter la tâche Codex
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
CODEX_QUIET_MODE: 1
run: |
codex exec --full-auto "Mettre à jour CHANGELOG.md en fonction des derniers commits"
- name: Valider les modifications
run: |
git config --local user.email 'action@github.com'
git add CHANGELOG.md
git commit -m 'chore: update changelog [skip ci]'
git push
Il y a deux points clés dans la configuration qui nécessitent une attention particulière :
| Élément de configuration | Objectif | Description |
|---|---|---|
| CODEX_QUIET_MODE: 1 | Supprimer la sortie interactive | Éviter que le pipeline se bloque en attendant une entrée interactive |
| --full-auto | Exécuter en mode sans interface | Laisser Codex s'exécuter directement sans supervision, sans attendre de confirmation |
Lors d'une utilisation en CI, il est recommandé de définir explicitement dans le fichier AGENTS.md à la racine du projet le périmètre des fichiers que Codex est autorisé à modifier en mode automatique, afin d'éviter des modifications inattendues dues à une mauvaise interprétation des prompts.
5. Conseils pour les prompts
La qualité de la sortie de Codex dépend largement de la manière dont vous posez vos questions.
Les cinq conseils suivants traitent des problèmes les plus courants rencontrés par les nouveaux utilisateurs, chacun avec des exemples spécifiques.
Conseil 1 : Fournir suffisamment de contexte
Codex ne peut pas lire dans les esprits. Une instruction comme « corriger le bug » l'amènera à deviner à l'aveugle, et le résultat n'est souvent pas celui souhaité.
Voici un exemple de comparaison :
| Non recommandé | Recommandé |
|---|---|
| "Corriger le bug" | "Lorsqu'un utilisateur se connecte, une erreur est levée : TypeError: Cannot read properties of null. L'erreur se produit à la ligne 42 de src/auth/login.ts. Cette fonction est chargée de valider les jetons JWT. Veuillez trouver et corriger ce problème." |
Un contexte efficace comprend trois éléments :
| Élément | Description | Exemple |
|---|---|---|
| Symptôme précis | Message d'erreur ou comportement spécifique | TypeError: Cannot read properties of null |
| Emplacement concerné | Fichier et numéro de ligne | Ligne 42 de src/auth/login.ts |
| Responsabilité du code | L'objectif d'origine de ce code | Valider le jeton JWT |
Astuce 2 : Diviser les tâches complexes en deux étapes
Pour les tâches impliquant un large éventail de modifications, demandez d'abord à Codex d'analyser et de proposer un plan, puis exécutez après avoir confirmé que la direction est la bonne.
Tout faire en une seule étape peut sembler plus rapide, mais le coût est plus élevé si la direction est mauvaise.
Exemple
codex "Analysez la qualité du code du répertoire src/api/ et listez les principaux problèmes. Ne modifiez aucun fichier."
# Étape 2 : Exécuter après avoir confirmé le plan
codex "OK, suivez votre plan proposé. Commencez par les problèmes de gestion des erreurs ; je vais examiner le reste plus tard."
Astuce 3 : Utilisez le mode Ask pour comprendre d'abord la base de code
askLe mode Ask est un mode en lecture seule, adapté pour comprendre la structure et la logique du code existant avant d'apporter des modifications.
Comprendre avant de modifier fait gagner du temps par rapport au fait de revenir comprendre après avoir apporté des modifications.
Exemple
# ask 模式不会触发任何文件修改 codex -a ask "这个项目是如何处理用户认证的?梳理完整的认证流程"
Une fois que vous avez une compréhension claire, quittez la session actuelle et redémarrez en mode éditable :
# 可编辑模式(需要确认) codex -a auto # 全自动执行(谨慎使用) codex -a full-auto
Flux de travail recommandé :
ask ↓ 理解代码结构 ↓ 确定修改方案 ↓ 重新启动 Codex ↓ 进入可编辑模式 ↓ 执行修改
Remarque : La CLI ne prend plus en charge le changement de modes de permission pendant l'exécution ; cela doit être spécifié via un
/approvalsparamètre au démarrage. Le client de bureau prend toujours en charge le changement au sein d'une session.-aparamètre. Le client de bureau prend toujours en charge le changement au sein d'une session.
Astuce 4 : Utilisez des instructions négatives pour définir des limites
Dire à Codex ce qu'il ne faut pas toucher est tout aussi important que de lui dire quoi faire.
En particulier pour les tâches de refactoring impliquant plusieurs fichiers associés, des limites floues peuvent facilement entraîner des modifications collatérales inutiles.
Exemple
codex "Refactorisez les fonctions de formatage des dates dans utils/date.ts. Ne modifiez pas les signatures des fonctions et ne modifiez pas les fichiers de test."
Astuce 5 : demandez d'abord un plan, puis exécutez
Pour les tâches pour lesquelles vous avez des doutes, demandez d'abord à Codex de lister comment il compte s'y prendre.
Cette étape ne prend presque pas de temps, mais elle vous permet de détecter tôt les écarts de direction et d'éviter d'aller trop loin dans la mauvaise voie.
# 先要计划 codex "你打算怎么实现这个功能?先列出步骤,不要执行" # 确认计划合理后再推进 codex "计划没问题,开始执行第一步"
Résumé
Ces cinq axes couvrent tout le parcours, de la "configuration du projet" aux "opérations quotidiennes" jusqu'à l'"automatisation".
Vous n'avez pas besoin de les utiliser toutes au début. Il est recommandé de procéder dans l'ordre : écrivez d'abord AGENTS.md pour que Codex comprenne votre projet, puis intégrez-le progressivement dans votre flux de travail VS Code et votre pipeline CI/CD.
Les techniques de prompt s'accumulent mieux progressivement par l'usage quotidien que mémorisées d'un coup.
Autres extensions