CursorDÉBUGGER UNE ERREUR
Prérequis
- Erreur reproductible en local via `pnpm run build` (ou `npm run build`)
- AGENTS.md à la racine rappelant les breaking changes Next.js du dépôt
- Scripts `typecheck` et `lint` fonctionnels pour valider le patch
- Variables d’environnement documentées (`.env.example` à jour)
Les erreurs de build en CI s’affichent souvent tronquées dans l’interface, alors que la cause réelle se trouve dans la première ligne du log local. L’agent Cursor accélère le diagnostic si vous lui fournissez le log intégral, le fichier suspect en @mention, et une consigne stricte : patch minimal, pas de refactor hors sujet.
Cadrer la session debug
Reproduisez l’échec localement : `pnpm run build 2>&1 | tee build.log`. Copiez la première erreur avec fichier, ligne et message — pas une capture tronquée.
Ouvrez le fichier incriminé dans l’éditeur. Rappelez AGENTS.md : votre version Next peut différer des docs publiques ; renvoyez vers `node_modules/next/dist/docs/` si l’agent cite une API dépréciée.
Diagnostiquer les cas Next.js fréquents
Client Component important un module serveur : ajoutez `'use client'` au bon fichier ou scindez en `actions.ts` serveur + composant client léger.
Export `metadata` dans un fichier client : déplacez vers un `layout.tsx` ou `page.tsx` Server Component.
Variable d’env absente au build : distinguez `NEXT_PUBLIC_*` des secrets serveur. Vérifiez `.env.example` et la config Vercel preview.
Valider le patch avant PR
Après le diff : `pnpm run build`, puis `pnpm run typecheck` et `pnpm run lint`. Documentez dans la PR la cause racine en une phrase.
Erreurs fréquentes
Coller uniquement « Module not found » sans le chemin d’import : l’agent devine.
Accepter un refactor massif « pour éviter que ça revienne » : hors scope du hotfix.
Corriger la dernière erreur du log alors que la première est la cause.
Ajouter `@ts-ignore` pour faire passer le build : dette immédiate.
Oublier de tester une preview Vercel après fix env.
Ce qu’il faut retenir
Log complet + premier fichier en erreur + consigne patch minimal.
Rebuild local après chaque fix ; une erreur à la fois.
AGENTS.md et docs Next locales pour les APIs instables.
L’agent peut lancer le build en mode Agent ; vous validez le succès avant commit.
FAQ
Oui en mode Agent avec terminal. Vérifiez vous-même le code de sortie et relisez le diff avant commit. Ne poussez pas un fix non reproduit localement.
Comparez Node version, env vars et cache. Collez le log CI complet dans Cursor avec la mention « échec uniquement en pipeline » pour orienter le diagnostic.
Rarement. Préférez @fichier + @folder parent. @codebase utile seulement si l’erreur mentionne un type partagé dispersé dans le repo.
ChatGPT