AGENTS.md : configurer les instructions de votre repo

Maîtriser le fichier de configuration de Codex

Vous avez découvert AGENTS.md dans la leçon 3. Cette leçon approfondit les patterns avancés pour tirer le maximum de ce fichier de configuration.

La hiérarchie des AGENTS.md

Codex lit les fichiers AGENTS.md de manière hiérarchique, du plus général au plus spécifique :

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 dans un sous-dossier hérite des règles parentes et peut les compléter ou les surcharger.

Sections essentielles d’un AGENTS.md complet

1. Contexte du projet

## 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.

Le contexte aide Codex à prendre des décisions adaptées. Si Codex sait que l’application gère des données RGPD, il ajoutera automatiquement les protections nécessaires.

2. Conventions de code

## 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)

3. Commandes

## 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

C’est critique : sans les commandes, Codex ne sait pas comment vérifier son travail.

4. Règles strictes

## 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

Les règles « NE JAMAIS » sont les plus importantes : elles empêchent Codex de faire des erreurs coûteuses.

5. Architecture et patterns

## 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.

6. Instructions par langage/framework

## 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

Patterns avancés

Variables d’environnement documentées

## 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)

Dépendances préférées

## 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)

Cela évite que Codex n’installe une bibliothèque que vous ne souhaitez pas utiliser.

Maintenance du fichier

AGENTS.md doit vivre avec votre code. Mettez-le à jour quand :

• Vous ajoutez une nouvelle convention
• Vous changez de bibliothèque ou de framework
• Vous identifiez une erreur récurrente de Codex
• Un nouveau développeur pose une question à laquelle AGENTS.md devrait répondre

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