Configurer votre environnement et AGENTS.md

Préparer votre projet pour Codex

Avant de lancer votre première tâche, vous devez configurer deux choses : votre accès à Codex (compte et connexion GitHub) et votre projet (le fichier AGENTS.md qui guide Codex).

Étape 1 : Configurer votre compte

Pour utiliser Codex, vous avez besoin d’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

Important : Codex n’a besoin que d’un accès en lecture à vos repositories pour cloner le code. L’accès en écriture n’est nécessaire que si vous souhaitez que Codex crée des pull requests automatiquement.

É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 commande palette (Ctrl+Shift+P → “Codex: Sign In”).

É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 de manière sécurisée dans votre keychain système.

Le fichier AGENTS.md — le guide de votre projet

Le fichier AGENTS.md est au cœur de l’utilisation efficace de Codex. C’est un fichier Markdown placé à la racine de votre repository qui contient les instructions, conventions et commandes spécifiques à votre projet.

Quand Codex clone votre repo pour exécuter une tâche, il lit AGENTS.md en premier. C’est comme un onboarding automatique pour l’agent.

Structure d’un AGENTS.md basique

# 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

Vous pouvez placer des fichiers AGENTS.md dans les sous-dossiers pour des instructions spécifiques à une partie du projet :

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 les instructions : les fichiers AGENTS.md des sous-dossiers complètent (et peuvent surcharger) le fichier racine.

Bonnes pratiques pour AGENTS.md

• Soyez explicite : « Utilise Vitest, pas Jest » plutôt que « Utilise notre framework de test »
• Incluez les commandes : Codex a besoin de savoir comment lancer les tests, le linting, le build
• Documentez la structure : un arbre de dossiers aide Codex à naviguer le projet
• Listez les interdits : les règles « NE JAMAIS » évitent les erreurs courantes
• Mettez à jour régulièrement : AGENTS.md doit refléter l’état actuel du projet

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