Pour utiliser Codex sur un projet React, ouvrez un terminal dans le dossier du projet et lancez codex. L’agent lit le fichier AGENTS.md présent à la racine pour comprendre les commandes, la structure et les règles du projet. Ce guide explique comment préparer ce fichier, organiser une boucle de travail efficace et éviter les erreurs spécifiques à React.
Pourquoi Codex convient au travail React
Un projet React moderne, notamment avec Vite, Vitest et React Testing Library, fournit un feedback très rapide : les modifications sont visibles immédiatement et les tests s’exécutent en quelques secondes. Codex peut exploiter cette boucle parce qu’il ne se contente pas de générer du code : il lance les commandes du projet, lit les erreurs de compilation ou de test, puis ajuste. Cette approche est pertinente pour les composants, les hooks et les corrections ciblées, où la frontière entre le code et son exécution est courte. Plutôt que de décrire une solution à l’aveugle, il peut vérifier qu’une props est bien passée, qu’un hook ne déclenche pas de rendu infini ou qu’un test échoue pour une raison précise.
Configurer le projet pour l’agent
Le point de départ est un fichier AGENTS.md lisible par Codex. Décrivez-y les commandes réellement utilisées par le projet, avec le gestionnaire de paquets employé (npm, pnpm ou yarn). Précisez la structure des dossiers : composants, hooks, pages, utilitaires de test. Ajoutez les conventions de nommage et les règles spécifiques à React : hooks, typage, accessibilité, formulaires contrôlés, tests. Un fichier court mais précis évite à l’agent de deviner ou de suivre des pratiques génériques.
# AGENTS.md
## Commandes
- Installer : pnpm install
- Dev : pnpm dev
- Build : pnpm build
- Tests : pnpm test -- --run
- Lint : pnpm lint
## Structure
- `src/components/` : composants réutilisables, PascalCase, un dossier par composant avec son test et son story.
- `src/hooks/` : hooks custom, camelCase, un hook par fichier.
- `src/pages/` : pages routées.
- `src/test/` : utilitaires de test et setup Vitest.
## Règles React
- Ne jamais appeler un hook dans une condition ou une boucle ; utiliser le plugin `eslint-plugin-react-hooks`.
- Privilégier les composants fonctionnels et les hooks.
- Un composant ne doit pas modifier le DOM directement, sauf via refs quand nécessaire.
- Les formulaires sont contrôlés : state React, pas de lecture directe des inputs sauf cas précis.
- Pas de `any` ; typer les props avec TypeScript.
- Les tests utilisent React Testing Library ; préférer `getByRole` à `getByTestId`.Ce fichier doit rester factuel : si vous utilisez pnpm, écrivez pnpm, pas npm. Si le projet a un alias d’import @/, précisez-le pour que Codex ne génère pas de chemins relatifs profonds. Si le projet est en TypeScript strict, Codex doit le savoir pour ne pas introduire de any. Pour les bases de l’outil, le guide Utiliser Codex CLI : le guide pas à pas détaille le lancement et le contexte.
Une boucle de travail efficace
Commencez par une demande précise, pas par une grande refonte. Pour une tâche un peu large, demandez à Codex de proposer un plan en trois étapes sans écrire de code, validez ce plan, puis demandez l’étape 1 seulement. Ensuite, demandez une modification unique et petite, lancez les tests, relisez le diff avec git diff, puis commitez. Cette boucle évite les changements diffus et rend les erreurs plus faciles à attribuer.
Exemples de prompts typiques pour un projet React :
- « Ajoute un hook
useLocalStoragedanssrc/hooks/useLocalStorage.ts, typé génériquement, avec un testrenderHooket une story optionnelle. » - « Refactore
ProductListpour extraire uneProductCardsans changer le comportement, puis lancepnpm test -- --runet corrige uniquement les tests cassés. » - « Corrige l’avertissement
react-hooks/exhaustive-depsdanssrc/pages/Dashboard.tsxsans provoquer de boucle infinie, puis lancepnpm lint. » - « Ajoute un état de chargement dans
UserProfile: affiche un squelette pendant le fetch, gère l’erreur avec un message accessible, mets à jour les tests. » - « Passe
ThemeSwitcherà une API contrôlée avecvalueetonChange, mets à jour le story et les tests associés. »
Après chaque prompt, exécutez git diff --stat puis git diff pour voir ce qui a changé. Si un test échoue, donnez le message d’erreur à Codex plutôt que de lui demander de tout corriger d’un coup.
Tâches React bien gérées et pièges à surveiller
Codex gère bien les tâches qui ont une spécification locale : créer un composant, extraire un hook, corriger un test, ajouter un état. Il est moins fiable quand la modification touche plusieurs niveaux d’abstraction ou quand les effets et les closures jouent un rôle important.
| Tâche React | Demande type | Point de vigilance |
|---|---|---|
| Créer un composant | « Ajoute un composant Badge avec les props variant et label. » | Props, accessibilité, style cohérent |
| Créer un hook | « Crée useDebounce avec timer nettoyé. » | Dépendances, cleanup, closures |
| Corriger un test | « Répare le test de Login qui échoue. » | Ne pas modifier le comportement pour faire passer le test |
| Refactorer un composant | « Extrais usePagination depuis Table. » | Préserver le rendu et les cas limites |
Les pièges spécifiques à React : appels de hooks conditionnels, tableaux de dépendances incomplets, closures périmées dans les effets, absence de cleanup pour les abonnements, état dérivé inutile. Sur les tableaux de dépendances, Codex propose parfois d’ajouter des variables qui provoquent des boucles infinies. Vérifiez que la modification ne tourne pas en rond dans le dev server. Pour les effets, exigez un cleanup explicite pour tout timer, abonnement ou fetch annulable.
Tests et vérification pour React
Sur un projet React avec Vitest et React Testing Library, demandez à Codex d’exécuter pnpm test -- --run après chaque modification. Les tests doivent vérifier le comportement observable, pas l’implémentation interne : privilégiez getByRole, getByLabelText et les interactions userEvent. Si le projet utilise Storybook, vérifiez aussi l’aspect visuel d’un composant avant de valider. Codex peut mettre à jour les stories, mais ne le laissez pas remplacer un test par une capture d’écran. Ne laissez pas Codex désactiver un test ou ajouter test.skip pour faire passer la suite.
Exécutez aussi pnpm lint et pnpm build pour détecter les problèmes de typage ou de bundling. Une revue de code IA peut ensuite passer sur les changements pour repérer les problèmes de hooks ou d’accessibilité avant le merge.
Plusieurs agents sur un projet React avec AgentVera
Avec AgentVera, plusieurs agents Codex peuvent travailler en parallèle sur un même projet React, chacun dans son propre worktree git pour éviter les conflits de fichiers. À la fin d’un tour, un second modèle revoit le code et les remarques renvoient à file:line, ce qui aide à valider les règles de hooks et les tests. Les checkpoints conservent un instantané de chaque tour : on peut annuler une modification en un clic et rejouer la session. Les budgets de tokens par agent, tour et jour évitent qu’une exploration parte en boucle. Pour orchestrer ces sessions, le guide Workflow d’agents IA : équipes, parties parallèles, flows montre comment enchaîner les agents.
En résumé
Codex devient utile sur un projet React quand le contexte est clair : un AGENTS.md qui décrit les commandes et les règles, des demandes petites et précises, des tests rapides exécutés à chaque étape et une relecture attentive des hooks et des effets. En gardant cette discipline, vous pouvez déléguer la mécanique du code React tout en gardant le contrôle sur l’architecture et le comportement.