CLAUDE.md pour un projet Next.js (App Router, TypeScript)

# CLAUDE.md — projet Next.js (App Router, TypeScript)
 
<!-- Fichier lu par Claude Code au démarrage de chaque session.
     Gardez-le court : ce qui est ici occupe du contexte à chaque échange. -->
 
## Aperçu
 
Application Next.js (App Router) écrite en TypeScript strict.
Composants serveur par défaut, rendu côté client uniquement si nécessaire.
 
## Commandes
 
- `npm run dev` : serveur de développement (http://localhost:3000)
- `npm run build` : build de production
- `npm run lint` : ESLint
- `npm run typecheck` : `tsc --noEmit`
- `npm test` : tests unitaires ; `npm test -- chemin/du/fichier` pour un seul fichier
 
Avant de déclarer une tâche terminée : lint + typecheck + tests du périmètre modifié.
 
## Arborescence
 
- `app/` : routes, layouts, `page.tsx`, `route.ts`
- `components/` : composants réutilisables (`components/ui/` = primitives)
- `lib/` : logique métier et utilitaires sans React
- `hooks/` : hooks clients partagés
 
## Conventions
 
- Composants serveur par défaut ; ajouter `"use client"` seulement pour
  l'interactivité (état, effets, événements navigateur).
- Données récupérées dans les composants serveur, pas dans des `useEffect`.
- Pas de `any` : préférer `unknown` puis un rétrécissement de type.
- Imports absolus via l'alias `@/`.
- Un composant par fichier, nommé en PascalCase.
 
Conventions de style détaillées (importées au démarrage) :
@docs/conventions.md
 
## À ne pas faire
 
- Ne pas modifier `next.config.*`, les workflows CI ni les fichiers de
  verrouillage (`package-lock.json`) sans le demander.
- Ne pas ajouter de dépendance sans justifier le besoin.
- Ne jamais committer de secrets : les variables sont dans `.env.local`
  (non versionné) ; seules les variables `NEXT_PUBLIC_*` vont au navigateur.
- Ne pas désactiver une règle ESLint pour faire passer le lint.
 
## Git
 
- Branches : `feat/…`, `fix/…`, `chore/…`
- Messages de commit courts, à l'impératif.

Le fichier CLAUDE.md placé à la racine d'un dépôt est chargé par Claude Code au lancement de chaque session. C'est l'endroit où l'on consigne ce qu'un nouveau venu devrait savoir avant de toucher au code : comment lancer le projet, comment vérifier qu'une modification ne casse rien, et quelles habitudes l'équipe a prises. Ce modèle vise une application Next.js utilisant l'App Router et TypeScript en mode strict.

Ce que contient le modèle

• Commandes : développement, build, lint, vérification des types et tests. Claude s'en sert pour valider son propre travail ; une commande absente ou fausse l'amène à deviner.
• Arborescence : le rôle de app/, components/, lib/ et hooks/, pour que les nouveaux fichiers atterrissent au bon endroit.
• Conventions : composants serveur par défaut, "use client" seulement quand c'est justifié, pas de any, alias d'import @/.
• Interdits : fichiers de configuration sensibles, dépendances ajoutées sans justification, secrets.
• Import : la ligne @docs/conventions.md injecte un second fichier au démarrage. Le chemin est résolu par rapport au fichier qui contient l'import, et les imports peuvent s'enchaîner sur quelques niveaux au maximum.

Comment l'adapter

1. Remplacez les commandes par celles de votre package.json (pnpm, yarn, bun…).
2. Réécrivez la section « Arborescence » : si votre projet utilise src/app/, dites-le.
3. Créez docs/conventions.md ou supprimez la ligne d'import. Un import vers un fichier situé hors du dépôt déclenche une demande d'approbation.
4. Ajoutez vos propres interdits, surtout ceux qui ont déjà causé des incidents.

Pour des préférences personnelles propres à ce projet (URL de votre environnement de test, par exemple), la documentation prévoit un fichier CLAUDE.local.md à ajouter au .gitignore.

Pièges fréquents

• Trop long : tout le fichier est chargé à chaque session et consomme du contexte. Visez des consignes courtes et vérifiables plutôt qu'un manuel.
• Consignes contradictoires : si deux règles se contredisent, Claude peut suivre l'une ou l'autre. Relisez le fichier quand le projet évolue.
• Confondre consigne et garde-fou : CLAUDE.md est du contexte, pas une contrainte technique. Pour interdire réellement une action, utilisez des règles de permission ou un hook PreToolUse.
• Écrire un chemin sans vouloir l'importer : un @chemin hors bloc de code est interprété comme un import ; entourez-le d'accents graves pour le laisser littéral.

La commande /memory liste les fichiers d'instructions chargés et permet de les ouvrir, et /context indique ce qui occupe réellement le contexte.

Pour aller plus loin, la leçon Le fichier CLAUDE.md du cours Claude Code en action détaille la hiérarchie des fichiers de mémoire.