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

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 : Configurer votre compte

Utiliser Codex suppose un compte OpenAI avec un abonnement compatible — Team, Enterprise ou API. Connectez-vous sur codex.openai.com et liez votre compte GitHub.

1. Allez sur codex.openai.com
2. Connectez-vous avec votre compte OpenAI
3. Cliquez sur "Connect GitHub"
4. Autorisez l'accès aux repositories souhaités
5. Sélectionnez votre organisation GitHub

Au moment d’accorder les droits, gardez la main légère. Codex n’a besoin que d’un accès en lecture à vos repositories pour cloner le code ; l’écriture ne devient nécessaire que si vous souhaitez qu’il crée des pull requests automatiquement. Beaucoup d’équipes restent volontairement en lecture seule quelques semaines, le temps de calibrer la qualité des résultats, puis élargissent dépôt par dépôt.

Étape 2 : Installer l’extension IDE

Pour VS Code :

# Via le marketplace
code --install-extension openai.codex

# Ou depuis l'interface VS Code
# Extensions (Ctrl+Shift+X) → Rechercher "OpenAI Codex" → Installer

Pour JetBrains (IntelliJ, WebStorm, PyCharm) :

Settings → Plugins → Marketplace → "OpenAI Codex" → Install

Après installation, connectez l’extension à votre compte OpenAI via la palette de commandes (Ctrl+Shift+P → « Codex: Sign In »). Tant que cette étape n’est pas faite, l’extension s’affiche mais reste muette, et l’on cherche volontiers dix minutes une panne qui n’existe pas.

Étape 3 : Installer le CLI

# Via npm
npm install -g @openai/codex-cli

# Vérifier l'installation
codex --version

# Configurer l'authentification
codex auth login

Le CLI stocke votre token d’authentification dans le keychain de votre système. Vous n’avez donc aucune variable d’environnement à poser dans votre shell, et rien qui risque de se retrouver dans un fichier versionné.

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

AGENTS.md dans les sous-dossiers

Un fichier racine unique devient vite trop générique : à force d’y ajouter des exceptions, il cesse d’être lisible. Placez donc des AGENTS.md dans les sous-dossiers pour porter les instructions locales.

mon-projet/
  AGENTS.md              → Instructions globales
  src/
    api/
      AGENTS.md          → "Les routes API utilisent Zod pour la validation"
    components/
      AGENTS.md          → "Tous les composants exportent un type Props"

Codex fusionne automatiquement ces instructions : les fichiers des sous-dossiers complètent le fichier racine et peuvent le surcharger. Vous posez ainsi une règle générale de projet tout en assumant une exception sur un module précis, sans que la racine ait à connaître cette exception.

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