Codex et Next.js : guide pratique pour l’agent de code

Lancer Codex dans un projet Next.js permet de déléguer l’implémentation de routes, de composants et de tests, à condition de le cadrer. Le point clé est de décrire le projet dans un fichier AGENTS.md et de ne jamais accepter un diff sans l’avoir relu et testé. Ce guide couvre le setup, une boucle de travail fiable, les pièges propres à Next.js et la vérification.

Pourquoi Codex convient bien au travail sur Next.js

Next.js impose des conventions fortes : dossiers app/, fichiers page.tsx, layout.tsx, route.ts, directive ‘use client’. Codex lit tout le dépôt et peut appliquer ces conventions de façon cohérente, là où un snippet ignore le contexte. Il est utile pour les transformations répétitives (ajouter loading.tsx et error.tsx, typer les props, convertir un composant client en Server Component) et pour générer des route handlers avec validation Zod. Il ne remplace pas la compréhension du modèle de rendu, mais accélère le travail mécanique.

Mise en place du projet pour l’agent

Le premier levier est un AGENTS.md versionné à la racine. Il doit contenir les commandes exactes, les conventions de dossiers et les règles Next.js que l’agent ne doit pas deviner. Voici un exemple court :

# AGENTS.md

## Commandes
- `pnpm dev` : serveur de développement
- `pnpm build` : build de production
- `pnpm lint` : ESLint
- `pnpm test:run` : exécution unique des tests Vitest
- `pnpm exec playwright test` : tests end-to-end

## Conventions du projet
- App Router dans `src/app/`, composants partagés dans `src/components/`.
- Tout composant est un Server Component par défaut. N'ajoute `'use client'` que si l'état, les effets ou les événements navigateur l'exigent.
- Les route handlers sont dans `src/app/api/.../route.ts` et renvoient des réponses JSON typées.
- Valide les données entrantes avec Zod dans les route handlers.
- Utilise TypeScript strict, pas de `any` sauf exception explicitement validée.

## Règles pour l'agent
- Ne modifie pas `next.config.*` sans demande explicite.
- Ne change pas les versions dans `package.json` sans validation.
- Ajoute un test unitaire pour toute nouvelle fonction de transformation.
- Vérifie `pnpm lint` et `pnpm test:run` avant de terminer.

Ce fichier transforme les demandes vagues en exécutions cohérentes. Si vous découvrez la CLI, le guide pas à pas détaille la configuration initiale.

Une boucle de travail fiable

Ne demandez jamais un gros refactor d’un coup. La boucle qui fonctionne est : définir un objectif précis, laisser Codex proposer un premier diff, relire git diff, lancer les tests et le lint, puis demander des corrections ciblées. Exemples de prompts adaptés :

• « Ajoute une route POST /api/contact dans src/app/api/contact/route.ts. Valide le corps avec Zod, renvoie 400 sur erreur et 201 avec l’objet créé. Ajoute un test Vitest pour le handler. »
• « Le composant src/components/DatePicker.tsx provoque un mismatch d’hydratation. Analyse la cause, corrige sans désactiver l’hydratation, puis lance pnpm lint et les tests liés. »
• « src/app/dashboard/page.tsx utilise useEffect seulement pour charger des données. Transforme-le en Server Component asynchrone, ajoute un loading.tsx, et vérifie que les props restent typées. »
• « Écris un test Playwright pour le flux connexion → tableau de bord avec un utilisateur de test. Utilise les rôles accessibles déjà présents et ajoute le test dans tests/e2e/login.spec.ts. »
• « Le formulaire ContactForm gère les erreurs avec plusieurs useState. Refactore-le avec useActionState si pertinent, conserve l’accessibilité et ajoute un test du comportement de soumission. »

Après chaque étape, relisez le diff avec git diff --stat puis git diff. Exécutez vous-même pnpm test:run et pnpm build avant de valider. Codex peut exécuter les commandes, mais valider le résultat reste votre responsabilité.

Tâches typiques et points de vigilance

Codex s’en sort bien pour créer ou modifier des route handlers, générer des pages serveur avec fetch, ajouter des pages de chargement et d’erreur, et produire des tests unitaires ou E2E. En revanche, surveillez les points suivants, propres à Next.js :

Autres pièges fréquents : importer un module server-only dans un composant client, utiliser cookies() ou headers() sans await, ou modifier le comportement de cache sans comprendre les conséquences sur le build. Demandez toujours un petit diff et vérifiez les imports.

Test et vérification pour Next.js avec l’agent

Pour valider le travail de Codex, combinez trois niveaux : tests unitaires Vitest pour les fonctions et handlers, tests de composants avec React Testing Library si besoin, et Playwright pour les parcours critiques. Demandez à l’agent d’écrire les tests en même temps que le code, mais vérifiez que les assertions sont significatives. Un test qui vérifie seulement que le rendu ne lève pas d’erreur est insuffisant pour un formulaire.

Les commandes à exiger avant de terminer : pnpm lint, pnpm test:run, pnpm exec playwright test et surtout pnpm build. Le build Next.js révèle les erreurs de frontière serveur/client, les usages de Suspense manquants et les problèmes de génération statique. Si vous travaillez à plusieurs agents, la revue de code IA aide à repérer ces erreurs structurelles avant qu’elles n’arrivent en CI.

Exécuter plusieurs agents sur un projet Next.js avec AgentVera

Pour les gros refactors Next.js, plusieurs agents peuvent travailler en parallèle via AgentVera, chacun dans son propre worktree Git pour éviter les écrasements de fichiers. La revue de code automatique est précieuse sur Next.js, car elle repère les imports de code serveur dans un composant client ou un usage de searchParams sans Suspense. Les checkpoints permettent d’annuler une mauvaise passe en un clic, et les budgets de tokens empêchent un agent de dériver sur tout le projet. Voir aussi workflow d’agents IA pour composer des équipes.

En résumé

Codex devient un bon exécutant sur Next.js quand le projet est décrit dans AGENTS.md, que les tâches sont petites et que chaque diff passe par les tests, le lint et le build. Méfiez-vous surtout de la frontière client/serveur et du rendu dynamique. Une revue systématique transforme l’agent en accélérateur plutôt qu’en générateur de dette.