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

# Exporter la session actuelle à tout moment pendant une conversation
/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

# Chemin du fichier : .github/workflows/codex-changelog.yml

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

# Étape 1 : Analyser uniquement, ne pas modifier
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

# Définissez clairement la portée qui ne doit pas être modifiée
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