Configurer votre environnement et AGENTS.md — Codex — Développement Assisté par IA

Leçon corrigée le 3 novembre 2026 d’après la documentation de Codex (Codex CLI, Authentication, Codex IDE extension, Custom instructions with AGENTS.md) : le paquet @openai/codex-cli et la commande codex auth login n’existent pas (npm install -g @openai/codex, codex login), l’extension a pour identifiant openai.chatgpt, l’adresse codex.openai.com et l’offre « Team, Enterprise ou API » sont remplacées par les accès actuels, et l’ordre de lecture d’AGENTS.md est précisé (racine du projet → dossier courant). Sources : Codex CLI · Authentication · AGENTS.md · Pricing.

Préparer votre projet pour Codex

Deux choses doivent être en place avant votre première tâche : votre accès à Codex — le compte et la connexion GitHub — et votre projet lui-même, à travers le fichier AGENTS.md qui guidera l’agent. La première partie prend un quart d’heure et ne se refait jamais. La seconde conditionne la qualité de tout ce que vous obtiendrez ensuite, et sépare les équipes satisfaites de Codex de celles qui le trouvent décevant.

Étape 1 : Votre accès à Codex

Codex s’utilise avec un compte ChatGPT ou avec une clé d’API. Les offres gratuite et Go donnent accès, selon le déploiement en cours, à GPT-6 Luna dans l’application de bureau ; à partir de Plus, Codex est disponible sur le web, dans le CLI, dans l’extension d’éditeur et sur iOS, avec les intégrations cloud comme la revue de code automatique. Une clé d’API convient à l’automatisation dans des environnements partagés comme la CI, avec le CLI, le SDK ou l’extension — certaines fonctions ne sont alors pas disponibles. Les détails et les limites d’usage figurent sur la page de tarification de Codex.

Pour travailler dans le cloud sur vos dépôts, connectez GitHub au moment de créer votre premier environnement Codex Cloud (leçon 2). Au moment d’accorder les droits, gardez la main légère : limitez l’accès aux dépôts dont vous avez réellement besoin.

Étape 2 : Installer l’extension d’éditeur

Dans VS Code et ses dérivés (Cursor, Windsurf), installez l’extension Codex depuis la place de marché — son identifiant est openai.chatgpt :

code --install-extension openai.chatgpt

Ouvrez ensuite Codex par son icône, ou par la palette de commandes avec Codex: Open Codex Sidebar, puis connectez-vous. Xcode et les IDE JetBrains ont leurs propres intégrations : dans JetBrains, ouvrez AI Chat et choisissez Codex.

Étape 3 : Installer le CLI

# Installation (macOS et Linux), ou npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Vérifier l'installation
codex --version

# Se connecter (navigateur), ou consulter l'état de la connexion
codex login
codex login status

codex login ouvre le parcours de connexion dans le navigateur ; pour une clé d’API, passez-la par l’entrée standard (printenv OPENAI_API_KEY | codex login --with-api-key). Codex met les identifiants en cache, soit dans un fichier en clair, ~/.codex/auth.json, soit dans le gestionnaire d’identifiants du système, selon le réglage cli_auth_credentials_store (file, keyring, auto ou ephemeral). Si le fichier est utilisé, traitez-le comme un mot de passe : il contient des jetons d’accès, ne le commitez jamais. Le CLI et l’extension partagent ce cache.

Le fichier AGENTS.md — le guide de votre projet

AGENTS.md est au cœur d’une utilisation efficace de Codex. C’est un simple fichier Markdown placé à la racine de votre repository, qui rassemble les instructions, conventions et commandes propres à votre projet. Quand Codex clone le dépôt, il le lit en premier : voyez-le comme l’onboarding automatique de l’agent, ce que vous expliqueriez oralement à un nouvel arrivant.

L’effet se mesure immédiatement. Sans AGENTS.md, demandez un test unitaire sur un projet qui utilise Vitest : il y a de bonnes chances que Codex vous rende du Jest, parce que c’est le choix le plus répandu dans l’écosystème. Une seule ligne de convention suffit à obtenir du Vitest du premier coup, et vous épargne la même correction cent fois. Voici la structure d’un fichier de base, sur un projet SaaS de gestion de factures.

# AGENTS.md

## Contexte du projet
Application SaaS de gestion de factures.
Stack : Next.js 15, TypeScript, Prisma, PostgreSQL.

## Conventions de code
- Utiliser des composants fonctionnels React (pas de classes)
- Nommer les fichiers en kebab-case
- Types TypeScript dans des fichiers .types.ts séparés
- Tests avec Vitest, fichiers .test.ts à côté du code

## Commandes utiles
- `npm run dev` — serveur de développement
- `npm run test` — lancer les tests
- `npm run lint` — vérifier le linting
- `npm run build` — build de production

## Structure du projet
    src/
      app/          → Pages Next.js (App Router)
      components/   → Composants React réutilisables
      lib/          → Logique métier et utilitaires
      prisma/       → Schéma et migrations DB

## Règles strictes
- NE JAMAIS modifier le schéma Prisma sans migration
- NE JAMAIS commit de fichiers .env
- Toujours utiliser les Server Actions pour les mutations

Comment Codex trouve les fichiers AGENTS.md

Un fichier racine unique devient vite trop générique. Codex permet d’empiler les instructions, selon un ordre précis qu’il faut connaître :

Le niveau global : dans votre dossier Codex (~/.codex, sauf si CODEX_HOME le redéfinit), Codex lit AGENTS.override.md s’il existe, sinon AGENTS.md.
Le niveau du projet : en partant de la racine du projet (en général la racine Git), Codex descend jusqu’au dossier courant et lit, dans chaque dossier traversé, AGENTS.override.md ou à défaut AGENTS.md.
La fusion : les fichiers sont concaténés de la racine vers le dossier courant ; les plus proches du dossier courant arrivent en dernier et l’emportent donc sur les consignes plus générales.

mon-projet/
  AGENTS.md              → Instructions du projet
  src/
    api/
      AGENTS.md          → "Les routes API utilisent Zod pour la validation"

Conséquence pratique : src/api/AGENTS.md n’est lu que si Codex travaille depuis src/api ou un de ses sous-dossiers, pas lorsqu’il est lancé à la racine. Les fichiers vides sont ignorés, et la concaténation s’arrête à 32 Kio par défaut (project_doc_max_bytes). Si votre dépôt utilise déjà un autre nom, comme TEAM_GUIDE.md, ajoutez-le à project_doc_fallback_filenames dans ~/.codex/config.toml.

Pour vérifier ce que Codex a réellement chargé, demandez-le-lui : codex --ask-for-approval never "Résume les instructions actuelles.". Codex reconstruit la chaîne d’instructions à chaque lancement : en cas de doute, relancez-le dans le bon dossier.

Bonnes pratiques pour AGENTS.md

Le principe directeur est l’explicite. « Utilise Vitest, pas Jest » vaut mieux que « Utilise notre framework de test », qui suppose une connaissance que l’agent n’a pas. Incluez systématiquement les commandes : sans elles, Codex ne sait lancer ni vos tests, ni votre linter, ni votre build, et il vous livrera du code qu’il n’a pas pu vérifier. Documentez la structure sous forme d’arbre de dossiers, ce qui lui évite d’explorer à l’aveugle et de créer un fichier au mauvais endroit.

Listez enfin les interdits. Les règles écrites en « NE JAMAIS » sont les plus rentables du fichier, parce qu’elles bloquent des erreurs qui coûtent cher et se rattrapent mal : un .env committé, une modification de schéma sans migration. Reste la discipline la plus difficile, maintenir le fichier à jour. Un AGENTS.md qui décrit le projet d’il y a un an oriente activement Codex vers des conventions abandonnées — nettement pire que l’absence de fichier, puisque l’erreur devient alors systématique.

Points clés à retenir

La configuration initiale nécessite un compte OpenAI et une connexion GitHub
L’extension IDE et le CLI s’installent en quelques minutes
AGENTS.md est le fichier le plus important pour une utilisation efficace de Codex
Il contient les conventions, commandes et règles spécifiques à votre projet
Des AGENTS.md dans les sous-dossiers permettent des instructions contextuelles