Accueil › Codex › AGENTS.md

AGENTS.md pour OpenAI Codex : le guide complet des instructions projet

AGENTS.md est un fichier Markdown qui indique à Codex comment travailler sur votre codebase : conventions de code, commandes de test, structure du projet, règles de PR. C’est l’équivalent d’un README, mais destiné à l’agent IA plutôt qu’aux développeurs humains. Codex est entraîné pour suivre scrupuleusement ces instructions.

Qu’est-ce qu’AGENTS.md ?

Quand Codex ouvre une session, la première chose qu’il fait est de chercher des fichiers AGENTS.md dans votre environnement. Il les lit, les intègre dans son contexte, et s’en sert comme guide pour toutes les actions qu’il entreprend sur votre code.

Le concept est simple : vous écrivez en Markdown ce que vous attendez de l’agent, exactement comme vous brieferiez un nouveau développeur qui rejoint l’équipe. Conventions de nommage, commandes pour builder et tester, structure des dossiers, format des messages de commit et de PR, dépendances à éviter, pièges connus du codebase.

AGENTS.md est un format ouvert. Il a émergé d’une collaboration entre OpenAI (Codex), Google (Jules), Cursor, Amp, et Factory, et est désormais géré par l’Agentic AI Foundation sous l’égide de la Linux Foundation. Vous pouvez utiliser le même fichier AGENTS.md avec plusieurs outils de coding IA, dont Claude Code (qui utilise un format similaire nommé CLAUDE.md) et GitHub Copilot.

La hiérarchie de découverte

Ordre de chargement

Codex construit une chaîne d’instructions au démarrage de chaque session. La découverte suit cet ordre de priorité :

Niveau global (~/.codex/ ou $CODEX_HOME) : Codex cherche d’abord AGENTS.override.md. S’il n’existe pas, il lit AGENTS.md. Seul le premier fichier non vide à ce niveau est utilisé. Ces instructions s’appliquent à tous vos projets.

Niveau projet : à partir de la racine du projet (généralement le répertoire contenant .git), Codex descend répertoire par répertoire jusqu’à votre répertoire de travail actuel. Dans chaque répertoire, il cherche dans l’ordre : AGENTS.override.md, puis AGENTS.md, puis les noms de fallback configurés dans project_doc_fallback_filenames.

Chaque fichier découvert est injecté comme un message utilisateur séparé dans la conversation, dans l’ordre racine vers feuille. Le message est formaté ainsi :

# AGENTS.md instructions for <directory>
<INSTRUCTIONS>
...contenu du fichier...
</INSTRUCTIONS>

Les fichiers les plus proches de votre répertoire de travail remplacent les fichiers plus éloignés quand il y a conflit. Les instructions explicites dans votre prompt de chat ont toujours la priorité sur tout le reste.

Exemple concret de hiérarchie

Imaginons cette structure de projet :

~/.codex/
  AGENTS.md                    # Conventions personnelles globales

mon-projet/
  AGENTS.md                    # Règles du projet (build, test, lint)
  src/
    api/
      AGENTS.md                # Spécificités de l'API REST
    services/
      payments/
        AGENTS.override.md     # Override pour le service paiement

Si vous lancez Codex depuis mon-projet/src/services/payments/, il chargera dans cet ordre : le fichier global ~/.codex/AGENTS.md, puis mon-projet/AGENTS.md, puis l’override payments/AGENTS.override.md. Il ne chargera pas le fichier de src/api/ car ce répertoire n’est pas dans le chemin entre la racine et votre CWD.

Le mécanisme d’override

Les fichiers AGENTS.override.md remplacent le AGENTS.md du même répertoire. C’est utile dans deux cas :

Au niveau global, pour tester temporairement des instructions différentes sans modifier votre fichier de base. Supprimez l’override pour revenir aux instructions par défaut.

Au niveau sous-répertoire, pour spécialiser les règles d’une équipe ou d’un service sans toucher au AGENTS.md du projet. Par exemple, l’équipe paiement a des règles de sécurité et de tests plus strictes que le reste du projet.

Écrire un bon AGENTS.md

Structure recommandée

Un AGENTS.md efficace est court, spécifique et actionnable. Voici la structure que nous recommandons :

# AGENTS.md

## Build et tests
- Build : `pnpm build`
- Tests : `pnpm test`
- Lint : `pnpm lint`
- Tout changement doit passer tests ET lint avant commit

## Conventions de code
- TypeScript strict, pas de `any` sauf type guard documenté
- Nommage : camelCase (variables), PascalCase (types/interfaces)
- Pas de `console.log` en production, utiliser `logger` (src/utils/logger.ts)
- Imports absolus via alias `@/` (configuré dans tsconfig.json)

## Structure du projet
- /src/api/ : endpoints REST (Express, un fichier par route)
- /src/services/ : logique métier (un service par domaine)
- /src/models/ : schémas Prisma et types dérivés
- /src/utils/ : fonctions utilitaires partagées
- /src/middleware/ : middlewares Express (auth, validation, logging)

## Règles de PR
- Titre en Conventional Commits (feat:, fix:, refactor:, docs:, test:)
- Description : contexte + motivation + ce qui a changé
- Max 400 lignes de diff par PR
- Toujours inclure des tests pour le nouveau code

## Dépendances
- Demander confirmation avant d'ajouter une dépendance de production
- Préférer pnpm à npm
- Vérifier les licences (pas de GPL dans les dépendances directes)

## Pièges connus
- Le module auth utilise un cache Redis qui expire après 15min
- Les migrations Prisma doivent être exécutées manuellement (`pnpm db:migrate`)
- Le port 3000 est souvent occupé en dev, utiliser PORT=3001 si erreur EADDRINUSE

Principes de rédaction

Placez les règles les plus importantes en haut. Codex lit le fichier séquentiellement et le contexte est limité. Si votre fichier est tronqué (dépassement de project_doc_max_bytes), ce sont les dernières lignes qui disparaissent.

Soyez spécifique et actionnable. « Utiliser de bonnes pratiques de test » ne sert à rien. « Lancer pnpm test après chaque modification de fichier TypeScript » est exploitable. Codex a besoin de commandes exactes, pas de principes vagues.

Utilisez des directives conditionnelles. Le format « Si X, alors Y » est très efficace avec Codex. Par exemple : « Si le changement touche src/api/, exécuter $api-validation avant de committer. » OpenAI utilise ce pattern dans ses propres repos.

Gardez le fichier court. Un AGENTS.md de 200 lignes consomme du contexte à chaque tour de conversation. Si vous avez beaucoup de règles, répartissez-les dans des fichiers AGENTS.md de sous-répertoires et des skills dédiées. La skill porte ses instructions uniquement quand elle est activée, contrairement au AGENTS.md qui est toujours chargé.

Documentez les commandes exactes. Ne supposez pas que Codex sait comment builder votre projet. Indiquez explicitement pnpm build, cargo test --workspace, python -m pytest tests/. Si la commande nécessite des variables d’environnement, précisez-le.

AGENTS.md pour les équipes

OpenAI documente l’utilisation d’AGENTS.md dans ses propres repos du SDK Agents. L’approche qu’ils utilisent combine des règles conditionnelles avec des invocations de skills obligatoires :

# AGENTS.md (repo OpenAI Agents SDK)

## Règles obligatoires
- Avant de modifier du code runtime ou API, appeler `$implementation-strategy`
- Si le changement touche le code SDK, les tests ou le build, appeler `$code-change-verification`
- Si le changement touche les métadonnées de package, appeler `$changeset-validation`
- Quand le travail est terminé, appeler `$pr-draft-summary`

Ce pattern transforme AGENTS.md en un système de workflow enforçable : chaque type de changement déclenche une skill spécifique qui valide le travail. OpenAI rapporte que cette approche a contribué à augmenter le nombre de PRs mergées sur ces repos de 316 à 457 en trois mois.

Fichiers de fallback

Si votre repo utilise déjà un nom de fichier différent pour les instructions d’agent (par exemple TEAM_GUIDE.md, .agents.md, ou CLAUDE.md), vous pouvez configurer Codex pour le reconnaître via le paramètre project_doc_fallback_filenames :

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CLAUDE.md"]
project_doc_max_bytes = 65536

Avec cette configuration, Codex vérifie dans chaque répertoire : AGENTS.override.md d’abord, puis AGENTS.md, puis TEAM_GUIDE.md, puis .agents.md, puis CLAUDE.md. Le premier fichier non vide trouvé est utilisé pour ce répertoire.

Redémarrez Codex après avoir modifié cette configuration pour qu’elle prenne effet.

Configuration avancée

Limite de taille

Le paramètre project_doc_max_bytes contrôle la quantité de données lue par fichier AGENTS.md. La valeur par défaut est d’environ 64 Ko, ce qui est généreux pour la plupart des projets. Si votre fichier est tronqué, deux options : augmenter la limite, ou mieux, scinder les instructions dans des fichiers de sous-répertoires.

Racine de projet

Par défaut, Codex considère le répertoire contenant .git comme racine du projet. Pour les monorepos ou les projets sans Git, vous pouvez personnaliser les marqueurs :

# Traiter un répertoire comme racine s'il contient l'un de ces fichiers/dossiers
project_root_markers = [".git", ".hg", "package.json"]

# Désactiver la recherche de racine (traiter le CWD comme racine)
# project_root_markers = []

CODEX_HOME personnalisé

La variable d’environnement CODEX_HOME permet de pointer Codex vers un répertoire de configuration différent. Utile pour maintenir des profils séparés (personnel vs travail) ou pour les utilisateurs d’automatisation :

# Utiliser un profil de configuration spécifique au projet
CODEX_HOME=$(pwd)/.codex codex exec "Lister les sources d'instructions actives"

Feature flag : child_agents_md

Quand le flag child_agents_md est activé dans la config ([features]), Codex ajoute des instructions supplémentaires sur le scope et la priorité des fichiers AGENTS.md. Il émet ces instructions même quand aucun AGENTS.md n’est présent, ce qui aide le modèle à mieux comprendre la hiérarchie s’il rencontre des fichiers AGENTS.md dans les sous-répertoires pendant son travail.

Vérifier vos instructions

Avant de compter sur vos AGENTS.md en production, testez qu’ils sont bien chargés et interprétés correctement.

# Demander à Codex de résumer ses instructions actuelles
codex --ask-for-approval never "Résume les instructions actuelles."

# Vérifier depuis un sous-répertoire spécifique
codex --cd src/services/payments --ask-for-approval never 
  "Quels fichiers d'instructions sont actifs ?"

# Vérifier les logs après une session
cat ~/.codex/log/codex-tui.log | grep "AGENTS"

Codex devrait lister les fichiers d’instructions dans l’ordre de priorité, du global au plus spécifique. Si un fichier manque, vérifiez qu’il n’est pas vide, que le nom est correct, et que le répertoire est bien dans le chemin entre la racine du projet et votre CWD.

AGENTS.md vs les alternatives

Le format AGENTS.md a l’avantage d’être un standard ouvert reconnu par plusieurs outils. Si vous travaillez avec plusieurs agents de coding, un seul fichier AGENTS.md peut servir à tous. Configurez les noms de fallback dans Codex pour reconnaître aussi les fichiers d’autres outils (CLAUDE.md, etc.) et inversement.

Exemples par type de projet

Projet fullstack TypeScript

# AGENTS.md

## Stack
- Frontend : Next.js 15 + React 19 + Tailwind CSS
- Backend : tRPC + Prisma + PostgreSQL
- Tests : Vitest (unit), Playwright (E2E)
- CI : GitHub Actions

## Commandes
- `pnpm dev` : serveur de dev (port 3000)
- `pnpm build` : build production
- `pnpm test` : tests unitaires Vitest
- `pnpm test:e2e` : tests E2E Playwright (nécessite `pnpm dev` en parallèle)
- `pnpm lint` : ESLint + Prettier check
- `pnpm db:push` : appliquer les changements de schéma Prisma

## Conventions
- Composants React : function components + hooks, pas de classes
- API : procédures tRPC dans /src/server/routers/
- Styles : Tailwind uniquement, pas de CSS modules
- Pas de barrel exports (index.ts) sauf dans /src/components/ui/

Projet Python / Data Science

# AGENTS.md

## Environnement
- Python 3.12, venv dans .venv/
- Activer : `source .venv/bin/activate`
- Installer les dépendances : `pip install -e ".[dev]"`

## Tests
- `pytest tests/ -v` : tous les tests
- `pytest tests/unit/ -v` : tests unitaires seuls
- `mypy src/` : vérification de types

## Conventions
- Type hints obligatoires sur toutes les fonctions publiques
- Docstrings Google style
- Black pour le formatage (max line length 88)
- isort pour l'ordre des imports

## Données
- Les données brutes sont dans /data/raw/ (gitignored)
- Les données traitées dans /data/processed/
- Ne jamais committer de fichiers > 1 Mo dans le repo

Projet Rust

# AGENTS.md

## Build
- `cargo build` : build debug
- `cargo build --release` : build release
- `cargo test --workspace` : tous les tests
- `cargo clippy --workspace -- -D warnings` : lint strict

## Conventions
- Noms de crates préfixés par le nom du projet (ex: myapp-core, myapp-api)
- Utiliser `format!` avec variables inline quand possible
- `pretty_assertions::assert_eq` dans les tests pour des diffs lisibles
- Si snapshot tests (insta), inclure les snapshots mises à jour dans la PR

## Sécurité
- Pas de `unwrap()` en code de production, utiliser `?` ou `anyhow::Result`
- Pas de `unsafe` sans revue explicite et commentaire justifiant

Dépannage

Rien ne se charge : vérifiez que vous êtes dans le bon répertoire (codex status montre la racine du workspace). Vérifiez que les fichiers ne sont pas vides : Codex ignore les fichiers vides.

Les mauvaises instructions apparaissent : cherchez un AGENTS.override.md plus haut dans l’arborescence ou dans votre ~/.codex/. Renommez ou supprimez l’override pour revenir au fichier de base.

Codex ignore les noms de fallback : vérifiez l’orthographe dans project_doc_fallback_filenames de votre config.toml, puis redémarrez Codex.

Instructions tronquées : augmentez project_doc_max_bytes ou scindez les fichiers volumineux dans des sous-répertoires pour garder les instructions critiques intactes.

Confusion de profil : exécutez echo $CODEX_HOME avant de lancer Codex. Une valeur non standard pointe vers un répertoire home différent de celui que vous avez édité.