Bien démarrer avec Claude Code : configuration, fichier CLAUDE.md, et la méthode qui change tout

Nous pilotons une partie de notre développement avec Claude Code — y compris par des profils non techniques qui ne lisent pas le code mais dirigent le travail. Après des mois d'usage quotidien, voici ce qu'on aurait aimé savoir le premier jour : la configuration compte moins qu'on le croit, le fichier CLAUDE.md compte plus qu'on le croit, et la méthode compte plus que tout.

1. Le fichier CLAUDE.md : la mémoire de votre projet

À chaque nouvelle session, Claude Code repart de zéro — sauf pour une chose : il lit automatiquement le fichier CLAUDE.md placé à la racine du projet. C'est votre levier le plus puissant : tout ce qui s'y trouve est connu de Claude dès la première seconde, à chaque session, sans que vous le répétiez.

Pour démarrer : lancez la commande /init dans une session — Claude analyse votre projet et génère un squelette de CLAUDE.md que vous corrigez ensuite. Versionnez-le dans git : c'est de la documentation d'équipe, pas une préférence personnelle.

Ce qu'il faut y mettre (et rien d'autre) :

• Les commandes exactes du projet : comment builder, tester, lancer en local. C'est la section au meilleur retour sur investissement — Claude ne devinera jamais vos scripts.
• Les règles dures apprises à vos dépens. Les nôtres, par exemple : « toujours npm run build en local avant de pousser quand on touche aux server actions » (une classe d'erreurs que le typage ne détecte pas), « vérifier qu'aucun job ne tourne sur le worker avant tout push » (notre déploiement redémarre le worker), « les fichiers .env sauvés sous Windows finissent parfois en .txt ». Chaque incident de projet doit devenir une ligne de CLAUDE.md — c'est comme ça qu'on ne le revit pas.
• Les conventions structurantes : architecture des dossiers, choix imposés (langue des commits, librairies bannies), et les interdits (« ne jamais modifier les migrations existantes »).

Ce qu'il ne faut PAS y mettre : tout ce que vos outils font déjà (les règles de style qu'un linter impose), les longues explications (pointez vers un fichier de doc avec @docs/architecture.md plutôt que de coller son contenu), et le contexte périssable. Un CLAUDE.md efficace reste court — l'ordre de grandeur communément admis est sous les 200 lignes. Trop long, il encombre le contexte à chaque session et dilue les règles qui comptent. La discipline tient en une phrase : n'y écrire que ce qui est vrai à chaque session, et que Claude se tromperait à ignorer.

À noter : les versions récentes ajoutent une mémoire automatique — Claude note lui-même ce qu'il apprend de vos corrections au fil des sessions (consultable et désactivable via /memory). Utile, mais ça ne remplace pas le CLAUDE.md : l'un est votre règlement versionné et partagé, l'autre ses notes personnelles.

2. La configuration de départ : trois réglages, pas trente

• Les permissions. Claude Code demande confirmation avant les actions sensibles. La tentation est de tout passer en automatique ; résistez au début. Notre règle : l'automatique pour la lecture et les éditions de fichiers, la confirmation manuelle pour tout ce qui est destructif ou irréversible (suppressions, opérations sur une base de production, push). Vous relâcherez plus tard, en connaissance de cause.
• Le modèle. La commande /model liste les modèles disponibles et permet d'en changer en cours de session — le plus capable pour les problèmes durs, un modèle plus rapide pour les tâches mécaniques.
• L'hygiène de session. /clear entre deux tâches sans rapport : une session chargée d'un long historique hors sujet raisonne moins bien qu'une session fraîche avec un bon CLAUDE.md.

C'est tout. Le reste (hooks, sous-agents, MCP) viendra quand un besoin réel le justifiera — pas avant. La sur-configuration du premier jour est le passe-temps favori de ceux qui ne shippent pas.

3. La méthode : c'est elle qui fait 80% du résultat

Diagnostic avant code. Notre premier prompt sur tout sujet non trivial commence par : « en LECTURE SEULE, ne modifie rien ». On demande l'état des lieux, on le lit, on décide — et seulement ensuite on demande le code. Un agent qui code avant de comprendre produit du plausible, pas du juste.

Un plan validé avant l'exécution. Pour tout chantier, demandez d'abord le plan (« propose, ne code pas encore »), corrigez-le, puis donnez le feu vert. Dix minutes de plan économisent des heures de code à défaire.

Des points STOP explicites. Nos prompts se terminent par « push, preview — STOP avant merge ». La validation humaine n'est pas de la défiance : c'est la barrière qui transforme un outil très rapide en outil sûr. Le jour où nous avons mergé trop vite, du contenu non validé s'est retrouvé en production — la règle existe parce qu'on a payé pour l'apprendre.

Une brique à la fois. Une branche = un sujet. Les corrections d'infrastructure ne voyagent jamais avec du contenu publiable ; un correctif urgent ne doit jamais être otage d'un chantier en cours de validation.

Des critères d'acceptation dans le prompt. Ne demandez pas « corrige les métas » ; demandez « corrige, puis montre-moi les balises telles quelles dans le HTML rendu ». Un résultat qui se vérifie par des preuves vaut dix comptes-rendus rassurants.

4. Le garde-fou qui n'est pas optionnel : ne jamais croire un fait généré

C'est la leçon la plus chère de notre apprentissage : un modèle peut produire un chiffre plausible avec une source crédible-sonnante — et les deux peuvent être inventés. Nous l'avons vécu : une statistique attribuée à un grand cabinet d'études, parfaitement vraisemblable, entièrement fabriquée. Depuis, la règle est absolue : aucun fait, chiffre ou citation généré ne part en production sans vérification contre une source primaire — par quelqu'un d'autre que le générateur. Demandez systématiquement les URLs, ouvrez-les, comparez. Claude Code est un exécutant remarquable ; il n'est pas une source.

Le corollaire pour les données : sur une base de production, tout script commence en lecture seule, toute suppression passe par un état des lieux puis une confirmation explicite avec identifiants précis — jamais un « vas-y » générique.

5. Les pièges du premier mois

• Faire confiance au « c'est bon » sans preuve. Exigez l'extrait, le test qui passe, la sortie de commande.
• Laisser gonfler le CLAUDE.md jusqu'à ce qu'il devienne un roman que Claude survole. Relisez-le une fois par mois, coupez.
• Tout automatiser trop tôt — permissions, merges, publications. L'automatisation se mérite : elle vient après que le processus manuel a prouvé sa fiabilité.
• Traiter Claude Code comme un moteur de recherche. Pour « comment marche X », la doc officielle répond mieux ; Claude Code brille quand il agit sur VOTRE projet avec VOTRE contexte.
• Oublier que le premier réflexe face à un blocage est de vérifier le fait simple (le build a-t-il vraiment fini ? le fichier existe-t-il ?) avant de bâtir des théories — et ça vaut pour l'humain comme pour l'agent.

La checklist de démarrage

1. /init dans votre projet → relire et couper le CLAUDE.md généré → commit.
2. Y inscrire vos commandes exactes de build/test et vos trois règles dures.
3. Permissions : manuel sur le destructif, automatique sur le reste.
4. Premier chantier réel : diagnostic lecture seule → plan validé → code → preuve d'acceptation → STOP avant merge.
5. Après chaque incident : une ligne de plus dans le CLAUDE.md.

La documentation officielle de référence : docs.claude.com (Claude Code, section memory pour le détail du système CLAUDE.md et de la mémoire automatique).

Sources : documentation officielle Claude Code (code.claude.com/docs — système de mémoire, /init, mémoire automatique) ; pratiques constatées dans notre usage quotidien en agence. Les règles internes citées proviennent de nos propres incidents, documentés au fil des sessions.