Initialisation de projet : Générer CLAUDE.md en un clic avec /init

📚 Navigation de la série : Le précédent article 11 Version Web et Cloud vous a sorti du terminal pour utiliser Claude Code dans un navigateur et des environnements cloud. Ce chapitre nous ramène en local, à une des meilleures habitudes à prendre : la première chose à faire dans un nouveau projet, taper /init, et laisser Claude explorer le code pour rédiger lui-même son manuel d'instructions. Prochain chapitre : 13 Structure du projet.

Mes amis, parlons d'une erreur classique au début.

Quand j'ai commencé avec Claude Code, j'ai repris un vieux projet Node backend d'un collègue sans avoir lancé /init. À ma première question, « comment lancer les tests ? », il a passé du temps à chercher dans package.json pour me répondre. Vingt minutes plus tard, j'ouvre une nouvelle session, je pose la même question, il cherche de nouveau depuis le début. L'après-midi, pour une autre tâche, il me demande pour la troisième fois « ce projet utilise npm ou pnpm ? ».

C'est à ce moment-là que c'est devenu agaçant — ce n'est pas lui qui est stupide, c'est juste que sans « manuel de projet », il doit tout redécouvrir à chaque fois. Une fois qu'on a pris le réflexe de lancer /init en arrivant dans un projet, ces répétitions disparaissent : il analyse le projet une fois pour toutes, l'écrit dans un fichier CLAUDE.md, et ensuite, à chaque début de session, il s'en souvient instantanément sans qu'on ait à réexpliquer.

En bref, /init fait une chose : transformer « Claude découvre le projet à chaque fois » en « Claude le découvre une fois et s'en souvient toujours ». Ce chapitre va vous expliquer son utilisation, ce que génère cette commande, et le temps qu'elle vous fera gagner.

Après avoir lu cet article, vous obtiendrez :

• La compréhension de l'utilité principale de /init : palier l'« amnésie » entre les sessions pour créer une mémoire persistante.
• La démarche pour le lancer, très simple : démarrer claude à la racine, puis taper /init.
• Ce qu'il se passe en arrière-plan : scan de l'architecture, identification des technologies, brouillon de CLAUDE.md.
• Un aperçu de la structure d'un CLAUDE.md généré et l'utilité de chaque section.
• Une révélation cruciale : /init n'est qu'un point de départ, il faut retoucher le brouillon manuellement (nous verrons le "comment" en détail au chapitre 18).

---

01 Pourquoi /init est nécessaire : L'« amnésie » de Claude

Conclusion immédiate : Chaque nouvelle session de Claude Code commence dans un état d'« amnésie » — il n'a aucun souvenir des sessions précédentes.

Ce n'est pas un bug, c'est par design. La documentation officielle l'explique clairement :

Chaque session de Claude Code démarre avec une fenêtre de contexte entièrement vierge.

Analogie : C'est comme accueillir un nouveau stagiaire tous les jours. Ce stagiaire est compétent, mais il a un problème : ce que vous lui apprenez aujourd'hui est oublié demain, et vous devez recommencer de zéro avec son remplaçant. Vous lui dites « on utilise pnpm et non npm », « les tests sont dans tests/ », « il faut lancer le linter avant de commiter »... et le lendemain, il faut tout répéter au nouveau venu.

Voilà la réalité sans fichier CLAUDE.md. L'exemple du projet Node au début illustre bien cela — ce n'est pas que Claude a une mauvaise mémoire, c'est qu'il n'a pas de support de mémoire entre les sessions.

Que faire alors ? Officiellement, il existe deux mécanismes de transfert de connaissances inter-sessions. Ce chapitre couvre le premier :

Mécanisme	Qui l'écrit	Que contient-il
Fichier CLAUDE.md	Vous (ou /init pour le brouillon)	Instructions et règles : architecture, commandes de build, conventions
Mémoire auto (Auto Memory)	Claude lui-même	L'expérience acquise en travaillant, astuces de débogage

Attention, la mémoire automatique a une limite stricte : seules les premières 200 lignes ou 25 Ko par session sont chargées, le reste est ignoré. On ne peut donc pas se reposer uniquement sur l'Auto Memory. CLAUDE.md est le principal support.

CLAUDE.md (le fichier de mémoire du projet) est ce fameux manuel de bienvenue pour le "nouveau stagiaire de tous les jours" — vous l'écrivez, vous le placez dans le projet, et chaque jour, Claude le lit en arrivant, ce qui lui permet de se "rappeler" instantanément de l'environnement.

Et /init, c'est simplement la commande qui permet de générer automatiquement un premier brouillon de ce manuel.

💡 En un mot : Chaque session de Claude démarre « amnésique », CLAUDE.md est son support de mémoire inter-sessions, et /init vous aide à générer le brouillon de cette mémoire en un clic.

---

02 Qu'est-ce que /init : Laissez Claude écrire son propre mode d'emploi

/init est une commande "slash" intégrée à Claude Code (une commande tapée dans l'invite, commençant par /).

En résumé : Elle demande à Claude d'analyser votre projet et de créer une première version de CLAUDE.md spécifique à ce projet.

La documentation officielle le décrit avec justesse :

Exécutez /init pour générer automatiquement un CLAUDE.md de base. Claude analyse votre code source et crée un fichier contenant des commandes de compilation, des instructions de test et des conventions de projet qu'il a trouvées.

Analogie : Demander au nouvel employé de rédiger son propre manuel d'intégration. Normalement, c'est l'employé expérimenté qui rédige le manuel pour les nouveaux. Ici, c'est l'inverse — le « nouveau » Claude explore le projet en premier, puis rédige un manuel avec tout ce qu'il a compris (technos, architecture, commandes). Vous n'avez plus qu'à relire pour valider ses découvertes.

Le gros avantage de cette approche est évident : Claude est capable de relever tout seul les éléments objectifs (stack technique, structure des dossiers, scripts de démarrage), vous n'avez plus à les taper à la main. L'énergie économisée vous permettra d'ajouter les informations impossibles à deviner pour lui (comme les conventions de nommage des branches).

Quand s'en servir ? Voici les déclencheurs habituels :

• Reprendre le projet de quelqu'un d'autre — Vous ne le connaissez pas vous-même, laissez Claude l'explorer pour vous donner une base.
• Ajouter CLAUDE.md à votre propre projet — Vous ne l'aviez jamais fait, il est temps d'y remédier.
• Cloner un projet open source pour y contribuer — On lance /init pour avoir la carte du projet avant d'intervenir.

💡 En un mot : /init demande à Claude de lire le projet et d'en extraire les faits objectifs pour un premier CLAUDE.md — vous économisez l'effort d'énumération pour vous concentrer sur ce qu'il ne peut pas deviner.

---

03 Comment l'utiliser : Naviguer, lancer, taper

L'utilisation est d'une simplicité désarmante — démarrez claude, tapez /init, et c'est fait.

Étape 1 : Démarrez Claude Code à la racine du projet.

C'est crucial, il faut faire un cd dans le répertoire racine du projet avant de démarrer. Comme précisé au chapitre 07, là où vous le démarrez, Claude considère que c'est son espace de travail. Si vous faites /init dans le dossier utilisateur, il analysera pêle-mêle vos fichiers personnels, et le résultat n'aura aucun sens.

cd /chemin/vers/votre-projet
claude

Étape 2 : Tapez /init dans l'invite, puis appuyez sur Entrée.

/init

Voilà, c'est tout. Ensuite, vous ne faites plus rien, Claude s'occupe de tout le reste — l'analyse et la génération sont automatiques, sans aucune intervention de votre part.

Mais que fait-il en arrière-plan ? Après de nombreuses utilisations, voici le déroulé type :

Toute la procédure se résume ainsi : Démarrer claude à la racine → taper /init → Claude analyse l'architecture et les technologies → il crée un brouillon de CLAUDE.md → vous l'ajustez manuellement. Les quatre premières étapes sont presque automatiques, la dernière est la clé pour obtenir un bon manuel, et nous y reviendrons au chapitre 18.

La documentation parle d'« analyser votre code source ». Dans la pratique, voici ce qu'il va examiner systématiquement :

• Les gestionnaires de dépendances : package.json (Node), requirements.txt (Python), pom.xml (Java) — pour identifier la stack et les commandes.
• La documentation existante : les README etc. — pour comprendre l'objectif du projet.
• La configuration et l'architecture : pour déterminer comment les dossiers sont organisés et où sont les points d'entrée.

⚠️ Un détail à retenir : Si le projet possède déjà un CLAUDE.md, /init ne va pas le remplacer violemment. La documentation est claire — dans ce cas, il suggérera des améliorations plutôt que d'écraser le fichier. Si vous tapez /init par erreur sur un projet déjà bien configuré, pas de panique, il proposera simplement quelques recommandations d'ajout, sans modifier l'existant. Une conception très bien pensée.

💡 En un mot : Placez-vous à la racine, lancez claude, tapez /init et laissez faire — si un CLAUDE.md existe déjà, il ne l'écrase pas mais suggère des améliorations.

---

04 À quoi ressemble le résultat : Analyse du brouillon CLAUDE.md

Une fois le /init terminé, vous trouverez un nouveau fichier CLAUDE.md à la racine du projet. En l'ouvrant, vous verrez un Markdown bien structuré.

Analogie : Un manuel de projet standardisé. Ce n'est pas un texte au kilomètre, c'est un document divisé en sections — le but du projet, les technologies, les dossiers, les commandes, les conventions. Un nouvel arrivant (ou Claude, à chaque session « amnésique ») le parcourt pour comprendre le projet instantanément.

Le contenu généré couvrira généralement ces sections (Claude les adaptera à votre projet, mais voici un exemple type) :

# Nom du projet

## Aperçu du projet
Brève description de ce que fait le projet et de sa fonctionnalité principale.

## Stack technique
- Frontend : React + TypeScript
- Backend : Node.js + Express
- Base de données : PostgreSQL

## Structure des dossiers
- `src/components/` - Composants React
- `src/api/`        - Couche API
- `tests/`          - Fichiers de tests

## Commandes courantes
- Démarrer le serveur de développement : `pnpm dev`
- Lancer les tests : `pnpm test`
- Vérifier le code : `pnpm lint`

## Conventions de développement
- Utiliser TypeScript en mode strict
- Exécuter `pnpm test` avant de commiter

Chaque section a une valeur spécifique — ce sont précisément les informations que Claude vous demandait sans cesse avant :

Section	Contenu	Ce qu'elle vous évite de répéter
Aperçu du projet	Objectif et cœur du projet	Finies les questions du type « À quoi sert ce projet ? »
Stack technique	Frameworks, langages, bases de données	Finies les questions du type « C'est du React ou du Vue ? »
Structure des dossiers	Rôle des dossiers clés, points d'entrée	Finies les recherches pour « Où se trouve le code de l'API ? »
Commandes courantes	Comment build, tester, vérifier	Fini l'analyse du package.json pour trouver les commandes
Conventions de développement	Règles du projet (ex: mode strict)	Finis les rappels de type « N'oublie pas le mode strict »

Vous avez compris ? Les répétitions agaçantes sur "comment lancer les tests" ou "est-ce qu'on utilise npm ou pnpm" de l'exemple initial sont résolues en un coup par "Commandes courantes" et "Stack technique". Une fois le manuel en place, Claude le lit en premier, et les redondances s'évaporent.

Quant à l'emplacement du fichier — l'emplacement officiel est la racine du projet sous la forme de ./CLAUDE.md (ou ./.claude/CLAUDE.md). /init le place automatiquement au bon endroit, vous n'avez pas à vous en préoccuper. L'interaction entre un fichier global utilisateur et le fichier projet sera développée au chapitre 18.

💡 En un mot : Le CLAUDE.md généré comprend "Aperçu / Technologies / Dossiers / Commandes / Conventions", chaque section règle une question répétitive — /init se charge de le placer correctement.

---

05 La clé à retenir : /init est un point de départ, pas d'arrivée

Voici la phrase la plus importante du chapitre : /init génère un brouillon, pas un document définitif.

Pourquoi faut-il le modifier manuellement ? Parce que certaines informations, Claude ne les trouvera pas, même en analysant tout le code — elles ne sont pas dans le code, elles sont dans votre tête et celle de l'équipe.

Voici quelques exemples de ce que Claude est incapable de deviner :

• Règles de nommage des branches : Votre convention est feature/xxx ou fix/xxx, mais aucun fichier ne le dit. Claude ne peut pas le savoir.
• Processus de déploiement : Faut-il merger sur main pour déclencher un déploiement, ou y a-t-il une validation manuelle ? Ce n'est pas dans le code du projet.
• Critères de Code Review : « Une PR nécessite l'approbation de deux personnes », « Les modifications sur le cœur de l'app nécessitent un Plan Mode préalable » — ce sont des conventions d'équipe implicites.
• Contexte métier : Pourquoi cette fonctionnalité a-t-elle été conçue ainsi ? Quel module faut-il manipuler avec précaution ? — ces « pourquoi » sont dans votre tête.

La bonne attitude est l'amélioration itérative, et non une rédaction statique d'un seul jet.

Mon projet Node mentionné plus haut est un contre-exemple flagrant : après /init, j'ai cru que c'était bon, sans rien modifier. Mais la section « Commandes courantes » avait omis un script de déploiement personnalisé (car ce script était caché dans le répertoire scripts/ et non listé dans package.json). Claude ne pouvait pas l'inventer. J'ai dû l'ajouter manuellement dans le CLAUDE.md : « Pour déployer, utilisez ./scripts/deploy.sh ». La bonne pratique est fixe : après chaque /init, on relit le tout et on complète avec les règles tacites du projet.

Voici le bon et le mauvais usage de l'outil :

❌ Erreurs courantes	✅ Bonnes pratiques
Oublier /init après sa génération, le considérer comme fini.	Relire le résultat de /init comme un premier jet à valider.
Espérer que Claude devine toutes les conventions de l'équipe.	Renseigner manuellement les conventions strictes qu'il ne peut pas trouver (branches, déploiement, review).
Figer le CLAUDE.md pour toujours après la première création.	Mettre à jour en permanence en retirant l'obsolète et en ajoutant les nouveautés, au fur et à mesure du projet.

Gardez en tête ce partage du travail : /init extrait rapidement les éléments factuels (il excelle là-dedans), et vous apportez les conventions et l'expertise métier (vous êtes le seul à les connaître). C'est l'association de ces deux éléments qui donne un CLAUDE.md performant.

Quant à « comment peaufiner ce brouillon pour en faire un vrai manuel » — comment structurer les niveaux, utiliser des inclusions, et le maintenir à long terme —, c'est le sujet du chapitre 18 : « Guide d'utilisation de CLAUDE.md ». Pour l'instant, assurez-vous juste d'en créer un, l'optimisation viendra ensuite.

💡 En un mot : /init s'occupe des bases factuelles, les conventions d'équipes et les processus de déploiement doivent être complétés par vos soins — c'est une base de travail, pas le point final.

---

06 Mise en pratique : Exécuter /init sur un projet minimaliste

Rien de tel que la pratique. Prenons un petit projet de deux ou trois fichiers, et lançons /init pour constater par nous-mêmes la création du CLAUDE.md. Pas besoin d'environnement complexe, il suffit de suivre ces commandes.

Étape 1 : Créer un projet minimal (Mac / Linux)

mkdir init-demo
cd init-demo
echo '{"name": "init-demo", "scripts": {"test": "echo test ok"}}' > package.json
echo 'console.log("hello from init-demo");' > index.js

Utilisateurs Windows PowerShell : tapez mkdir init-demo puis cd init-demo. Créez ensuite package.json et index.js avec le Bloc-notes, et copiez-y le contenu entre les apostrophes simples.

Attendu : Le dossier init-demo contient les fichiers package.json et index.js. Lancez ls (ou dir sous Windows) pour le confirmer.

Étape 2 : Démarrer Claude Code dans le répertoire du projet

claude

Attendu : L'écran de bienvenue s'affiche avec la barre de saisie en bas. Confirmez que le terminal est bien dans le dossier init-demo.

Étape 3 : Lancer /init

Dans l'invite de commande, tapez :

/init

Attendu : Le texte défile — Claude parcourt package.json et index.js, analyse le projet, puis rédige le fichier. À la fin, il confirme la génération de CLAUDE.md. Le projet étant minuscule, l'opération prend de quelques secondes à une dizaine de secondes.

Étape 4 : Confirmer la génération de CLAUDE.md

Quittez Claude (tapez exit ou Ctrl+D), puis vérifiez dans le terminal :

cat CLAUDE.md

(Sur Windows PowerShell, utilisez type CLAUDE.md)

Attendu : Le terminal affiche un texte en Markdown. Vous devriez y trouver le nom du projet init-demo, la stack technique Node.js / JavaScript, et la commande de test (echo test ok) identifiée comme « Lancer les tests ». La présence de ces éléments confirme que /init a fonctionné, qu'il a compris et mémorisé le projet.

Étape 5 (Optionnelle) : Vérifier sa "mémoire"

Relancez claude et demandez-lui :

Quelle est la commande pour lancer les tests de ce projet ?

Attendu : Il vous donnera la commande de test directement, sans avoir besoin d'ouvrir et de lire package.json — la réponse figure dans le CLAUDE.md qu'il a lu en démarrant. C'est la preuve visuelle que l'« amnésie » est soignée.

⚠️ Petite remarque : Sur des projets réels, /init aura beaucoup plus de fichiers à examiner et de données à synthétiser, l'opération sera un peu plus longue. Laissez-le terminer son analyse, et n'oubliez pas le conseil de la section 05 — relisez le document pour y insérer les règles implicites qu'il ne pouvait pas détecter.

💡 En un mot : Créez un projet de deux fichiers, lancez /init dans claude, quittez et utilisez cat CLAUDE.md pour observer son analyse du projet — demandez la commande de test pour vérifier qu'il s'en souvient.

---

07 Résumé

Ce chapitre se concentre sur une action : le premier réflexe dans un nouveau projet, taper /init, pour laisser Claude générer le premier jet de son manuel d'instructions.

Les points clés à mémoriser :

Concept	Conclusion
Le problème résolu	Claude est « amnésique » à chaque session. CLAUDE.md est sa mémoire inter-sessions.
Qu'est-ce que /init	La commande qui lance l'analyse du projet par Claude pour générer le brouillon de CLAUDE.md.
L'exécution	Se positionner (cd) à la racine du projet → lancer claude → taper /init.
Son action	Scanner l'arborescence, repérer les technos, extraire les commandes, enregistrer un brouillon.
Structure du document	Aperçu / Technologies / Structure / Commandes / Conventions.
La limite importante	Un brouillon n'est pas définitif : les conventions d'équipe doivent être rajoutées à la main.

Vous devriez désormais être capable de : Ouvrir n'importe quel projet, vous placer à la racine, lancer claude puis /init, générer le CLAUDE.md, comprendre le rôle de chaque partie du contenu, et réaliser que c'est une base de travail — les faits objectifs sont posés, les règles subjectives sont à ajouter. Ainsi, Claude n'est plus ce "nouveau qui oublie tout", mais un habitué qui commence chaque session avec le manuel en tête.

---

Article suivant : 13 « Structure du projet » — Vous avez utilisé /init, la section « Structure des dossiers » du CLAUDE.md a été complétée. Mais un projet comprend d'autres fichiers spécifiques à Claude Code, comme le dossier .claude/, le settings.json, les commandes personnalisées, les configurations MCP, chacun ayant un rôle précis. Où sont-ils et à quoi ressemblent-ils ? Le prochain chapitre décortiquera l'architecture complète d'un projet pour Claude.

---

Lectures recommandées

• Agent teams (Équipes d'agents) : Collaboration multi-sessions
• Meilleures pratiques : Transformer les bonnes habitudes en méthodologie
• Configuration du dev : Ajuster l'environnement de travail de Claude