AGENTS.md : configurer les instructions de votre repo — Codex — Développement Assisté par IA

Maîtriser le fichier de configuration de Codex

Vous avez découvert AGENTS.md dans la leçon 3. Nous approfondissons ici les patterns avancés, ceux qui séparent un fichier décoratif — trois lignes écrites au démarrage puis oubliées — d’un fichier qui pilote réellement le comportement de l’agent sur un projet vivant.

La hiérarchie des AGENTS.md

Codex lit ces fichiers de manière hiérarchique, du plus général au plus spécifique. Sur un projet structuré, l’arborescence prend cette forme :

mon-projet/
  AGENTS.md                    → Règles globales (priorité basse)
  src/
    AGENTS.md                  → Règles pour tout le code source
    api/
      AGENTS.md                → Règles spécifiques aux API
      routes/
        AGENTS.md              → Règles pour les routes
    components/
      AGENTS.md                → Règles pour les composants React
  tests/
    AGENTS.md                  → Règles pour les tests

Les règles se cumulent : un fichier situé dans un sous-dossier hérite des règles parentes, puis les complète ou les surcharge. Imaginons que votre fichier racine interdise any tandis que tests/AGENTS.md autorise des assertions plus souples dans les mocks. Codex appliquera la tolérance dans les tests et la rigueur ailleurs, sans que vous ayez à arbitrer à chaque tâche. C’est ce mécanisme qui vous évite un fichier racine truffé d’exceptions du type « sauf dans les tests, sauf dans les scripts, sauf dans le dossier legacy ».

Les sections qui portent le fichier

Le contexte vient en premier, parce qu’il oriente toutes les décisions suivantes. Un SaaS soumis au RGPD ne se code pas comme un outil interne réservé à cinq personnes :

## Contexte
Application SaaS de gestion de factures pour les TPE/PME françaises.
Conformité RGPD obligatoire. Données hébergées en France (OVH).
Stack : Astro 6, React, TypeScript strict, Prisma, PostgreSQL.
Authentification : Better Auth avec sessions serveur.

Sachant qu’il manipule des données soumises au RGPD, Codex ajoutera les protections attendues sans que vous ayez à le préciser dans chacune de vos demandes. Viennent ensuite les conventions, qui répondent à une seule question : à quoi ressemble du code correct ici ?

## Conventions
- TypeScript strict (no any, no implicit any)
- Composants React fonctionnels uniquement
- Nommage : fichiers kebab-case, composants PascalCase, 
  variables camelCase
- Imports : @/ pour les alias de chemin
- Validation : Zod pour toutes les entrées utilisateur
- Erreurs : classes d'erreur custom dans src/lib/errors.ts
- Logging : utiliser src/lib/logger.ts (pas console.log)

La section des commandes est la plus souvent omise, et son absence coûte cher : privé de ces commandes, Codex ne peut pas vérifier son propre travail et vous rend du code qu’il n’a jamais exécuté ni testé.

## Commandes
- `npm run dev` — Serveur de développement (port 4321)
- `npm run build` — Build de production
- `npm run test` — Tests Vitest
- `npm run test:e2e` — Tests Playwright
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Migrations Prisma
- `npm run db:seed` — Seed de la base de données

Les règles strictes forment le garde-fou. Formulées en « NE JAMAIS » et « TOUJOURS », elles écartent les erreurs qui coûtent une soirée entière à réparer : une migration Prisma supprimée que vous devrez reconstituer à partir de la base de production, un secret committé qu’il faudra révoquer, un innerHTML glissé dans un composant qui ouvre une faille XSS.

## Règles strictes (NE JAMAIS enfreindre)
- NE JAMAIS modifier le schéma Prisma sans créer une migration
- NE JAMAIS stocker de secrets dans le code (utiliser .env)
- NE JAMAIS utiliser innerHTML (risque XSS)
- NE JAMAIS supprimer de migration Prisma existante
- NE JAMAIS exposer les IDs internes dans les URLs publiques
- TOUJOURS valider les entrées utilisateur avec Zod
- TOUJOURS utiliser les transactions Prisma pour les opérations multi-tables

L’architecture décrit enfin la circulation autorisée entre les couches. Sans elle, Codex produit du code qui fonctionne mais qui court-circuite votre découpage — une route qui interroge Prisma directement, par exemple, parce que c’était le chemin le plus court.

## Architecture
Couches :
1. Routes (src/pages/) → reçoivent les requêtes
2. Services (src/services/) → logique métier
3. Repositories (src/repositories/) → accès aux données

Règle : les routes NE DOIVENT PAS accéder directement à Prisma.
Tout passe par un service, qui passe par un repository.

S’ajoutent à cela, projet par projet, les instructions propres à chaque technologie employée :

## React
- Préférer les Server Components par défaut
- Client Components uniquement quand nécessaire (interactivité)
- Pas de useEffect pour le data fetching (utiliser les Server Actions)
- État local avec useState, état global avec Zustand

## Prisma
- Relations : toujours inclure les champs requis explicitement
- Pagination : utiliser cursor-based, pas offset-based
- Soft delete : utiliser deletedAt au lieu de DELETE

Deux patterns qui évitent des surprises

Déclarer les variables d’environnement attendues empêche Codex d’inventer des noms de clés au moment d’écrire un script, ou de logger par mégarde une valeur sensible dans une trace de débogage :

## Variables d'environnement requises
- DATABASE_URL — URL de connexion PostgreSQL
- AUTH_SECRET — Secret pour Better Auth (min 32 chars)
- SMTP_HOST — Serveur SMTP pour les emails
- STRIPE_SECRET_KEY — Clé API Stripe (ne jamais logger)

Nommer vos bibliothèques préférées, et surtout celles que vous refusez, règle un agacement récurrent : l’agent installe une dépendance parfaitement valable en soi, mais que votre équipe a écartée il y a deux ans après une mauvaise expérience.

## Dépendances
Si tu as besoin de :
- Validation → Zod (PAS Joi, PAS Yup)
- Dates → date-fns (PAS moment, PAS dayjs)
- HTTP client → ofetch (PAS axios)
- Tests → Vitest (PAS Jest)
- E2E → Playwright (PAS Cypress)

Faire vivre le fichier

AGENTS.md évolue avec votre code, au même titre qu’un test ou qu’un README. Mettez-le à jour dès que vous adoptez une nouvelle convention, dès que vous changez de bibliothèque ou de framework, et surtout dès que vous identifiez une erreur récurrente de Codex : ce dernier cas signale toujours une instruction manquante plutôt qu’une défaillance du modèle. Un quatrième déclencheur, plus discret, mérite d’être guetté — quand un nouveau développeur pose une question à laquelle AGENTS.md aurait dû répondre, la réponse a sa place dans le fichier.

Points clés à retenir

La hiérarchie des AGENTS.md permet des instructions de plus en plus spécifiques
Les commandes sont critiques pour que Codex puisse vérifier son travail
Les règles NE JAMAIS sont les plus importantes pour éviter les erreurs
Documentez les dépendances préférées pour éviter les mauvais choix
Maintenez AGENTS.md à jour comme du code vivant