Votre Projet Claude Code N'est Pas Configuré. Il Fait Juste Semblant de l'Être.

Les bonnes instructions à Claude Code font la différence entre une app qui sort et un bordel buggé que personne ne veut déboguer. Le nouveau flux d'onboarding de projet a énormément simplifié ce travail, en gros un entretien. Il extrait ce qui n'est pas évident, configure les hooks et compétences, pose les questions qu'on oublierait de poser. Mais il faut encore savoir ce qui se passe quand il trouve votre CLAUDE.md déjà là.

Et ce qui se passe n'est pas ce que la plupart des posts ont décrit.

TLDR : /init n'est pas un générateur amélioré. Sur un repo avec un CLAUDE.md existant, il passe en mode audit : il lit votre fichier, fait des recoupements avec les lockfiles et configs, et remonte ce qui ne colle plus pendant que le code a évolué. Sur le 4e repo, 64 lignes, il a trouvé 5 mensonges silencieux. La différence entre générer et corriger, c'est tout l'article.

Sur un repo vierge, oui, il génère. La communauté a foncé là-dessus, logiquement. "Setup 10x plus facile," le CLAUDE.md s'écrit tout seul maintenant. Vrai pour une page blanche. Mais le cas le plus courant, c'est un repo qui a déjà de la doc, écrite tôt, avant que la codebase devienne ce qu'elle est vraiment. Dès que /init détecte un fichier existant, il ne remplace pas : il audite. Il fait des recoupements entre le CLAUDE.md et les lockfiles, configs, schémas, et remonte ce qui ne correspond plus. C'est ça le boulot.

Je l'ai lancé sur 4 repos en quelques jours.

Je M'Attendais à un Générateur. J'ai Eu un Auditeur.

Thariq de l'équipe Claude Code a posté le flag env var en mars : CLAUDE_CODE_NEW_INIT=1, mode preview, flux de setup basé sur un entretien. Un thread sur r/ClaudeAI de la même semaine avait 118 commentaires sur une question qui marquait : "Soyez honnêtes : quand Claude écrit un long plan, vous le lisez vraiment ? Ou vous dites juste ça a l'air bien ?" La doc que personne ne relit était déjà un point de douleur live dans la communauté.

J'ai mis le flag et lancé /init sur les 4 repos.

Ce que j'attendais sur chacun : un CLAUDE.md avec une section stack, un bloc de commandes, quelques conventions. Du boilerplate que je nettoierais manuellement. Le genre de sortie qui donne un point de départ et a besoin d'un passage humain pour être vraiment utile.

Ce que j'ai eu à la place : sur 3 des 4 repos, /init a détecté un fichier existant et a immédiatement changé de comportement. Sur un repo vierge il génère from scratch. Avec un fichier déjà présent, l'approche est différente. Il lit le CLAUDE.md actuel, lit la codebase, trouve les gaps où ce que vous avez écrit ne correspond plus à ce que le code est vraiment.

La dérive de documentation ne s'annonce pas. C'est pas comme une erreur de build ou un test qui fail. C'est plutôt comme de la corruption dans un fichier de sauvegarde : le jeu continue de tourner, les chiffres ont l'air corrects, et puis le boss fight arrive et les stats ne collent pas à ce qui était promis. Quand vous vous en rendez compte, ça fait un moment que vous jouez sur de mauvaises assumptions.

Les docs de Claude Code décrivent le nouveau /init comme suivant le principe "n'inclure que ce que Claude n'inférerait pas tout seul". Sur un repo existant ça veut dire : d'abord déterminer ce que le code est vraiment, puis comparer ça à ce qui est documenté, puis remonter le delta. Le delta, c'est ce qui compte.

2 Repos Qui Se Connaissaient Déjà

Le repo 1 était mon dashboard produit principal : le projet central, environ 150 lignes de CLAUDE.md, écrit tôt et mis à jour occasionnellement. /init a retourné 11 nouvelles lignes.

Les ajouts étaient des faits architecturaux qui n'étaient pas dans le fichier : l'entité de données centrale autour de laquelle tout le système tourne, une règle de routing qui canalise toute la logique helper vers un module spécifique, auth à 2 niveaux (end-user vs machine-to-machine), une tâche schedulée isolée qui tourne en dehors du cycle de requête normal. Rien de documenté. Tout inférable du code si vous lisez en profondeur et recoupez les imports.

Puis il a flaggé 1 mensonge. Le CLAUDE.md référençait npm install et localhost:3000. bun.lock était à la racine. Le projet tournait sur un port différent depuis des mois. Les deux avaient été vrais à un moment, les deux avaient silencieusement arrêté d'être vrais, et rien n'avait cassé. Les commandes npm s'exécutent encore sur un projet bun, la plupart du temps. Le mauvais port veut juste dire que vous essayez la mauvaise URL une fois, puis la bonne, et vous oubliez. Facile à rater. Facile à laisser.

Le repo 2 était un problème différent. Un projet avec près de 700 lignes de CLAUDE.md soigneusement maintenu, mis à jour après chaque changement significatif. /init a lu le tout, scanné la codebase, est revenu avec 3 lignes. Le runner bun test avait été ajouté récemment et n'était pas documenté. Pas de réécriture, pas de changements structurels, juste les commandes manquantes.

Et un verdict : "Votre CLAUDE.md va déjà bien au-delà de ce que /init générerait ici."

(Je maintiens une doc interne de 500 lignes sur un projet complètement séparé, rien à voir avec tout ça, que je mets à jour depuis 2 ans parce que je trouve l'écriture clarifiante. Ma fille est entrée une fois pendant que je réécrivais un header de section et a demandé pourquoi j'écrivais un livre sur mon code. J'avais pas de bonne réponse. Enfin bref.)

Un outil qui sait quand s'arrêter est aussi rare qu'un qui sait quand commencer.

Le Repo Sans Carte

Le 3e repo : un système de livraison de catalogue multi-frontend. Plusieurs frontends Astro, un backend Hono, SQLite, pas de CLAUDE.md, pas de README à la racine. Démarré rapidement parce que la forme était claire, la documentation c'était pour plus tard, et plus tard n'arrêtait pas de bouger.

/init a retourné une carte d'architecture complète en 4 passes d'outils parallèles. Les lectures indépendantes partent simultanément : config racine, routes Hono, configs Astro, scripts de build, notes de deploy. La reconstruction est rapide parce que les appels n'attendent pas les uns les autres.

Le même principe s'applique ici que dans comment Claude Code construit le contexte projet à partir d'une codebase existante : une carte structurée et précise est presque toujours le travail qui fait que les sessions suivantes arrêtent de partir en vrille. La carte existe et est correcte, ou le modèle improvise, et improviser sur la mauvaise image se compose rapidement.

L'invariant clé qu'il a remonté que je n'aurais pas écrit : Astro tourne sous Node, tout le reste sous Bun. Ce détail était enterré dans un commentaire du script de deploy et un appel fnm use 22 dans le script de build. Une contrainte architecturale spécifique à comment le processus de build d'Astro fonctionne, complètement non documentée. Chaque session Claude Code sur ce repo avait opéré sans ça.

Ce que les 4 passes ont assemblé concrètement : le schéma SQLite, un pipeline d'export sérialisant le contenu en bundles JSON par site, la séquence de build Astro sous Node 22 (pas Bun, parce que le renderer SSG d'Astro l'exigeait), une étape rsync vers nginx avec des règles de rewrite déjà définies, et un Cloudflare Worker gérant le routing edge devant le tout. La chaîne de livraison complète des rows SQLite brutes aux fichiers statiques rendus derrière Cloudflare, documentée en une passe. Pas d'arbre de répertoires, pas de conseils projet génériques. Assez spécifique pour naviguer sans demander.

5 Mensonges en 64 Lignes

Le 4e repo : mon pipeline de traitement produit. Full stack, backend Convex, frontend Vite/Express, secrets gérés via Infisical. Le CLAUDE.md avait 64 lignes, écrit 3 mois plus tôt, précis à l'époque.

/init a trouvé 5 endroits où la documentation était silencieusement devenue de la fiction.

1. Le gestionnaire de paquets

Le CLAUDE.md instruisait : npm install, npm run dev. bun.lock était à la racine. La migration vers bun s'était faite à un moment et les docs n'avaient pas suivi. Claude Code avait lancé des commandes npm sur un projet bun, silencieusement, sans erreur, parce que la plupart des commandes npm s'exécutent encore. L'incompatibilité se cache jusqu'à ce que la résolution de dépendances diverge et vous passez un après-midi à comprendre pourquoi.

2. Les états de workflow manquants

Le CLAUDE.md documentait 3 codes de statut de commande dans le schéma Convex : draft, published, archived. Le schéma réel en avait 7. Les 4 manquants géraient les cas limites : processing, failed, review, scheduled. Les états qui comptent pour toute opération non-triviale. Chaque session Claude Code avait écrit de la logique contre un modèle du système qui était short de 4 états.

3. Le dossier Convex

Le CLAUDE.md décrivait convex/ comme la couche de traitement principale. Ça avait été vrai au début. En 3 mois, le gros du travail avait migré dans server.js : génération PDF pour les fiches produit, redimensionnement d'images, dispatch webhook vers les intégrations partenaires. Les fonctions Convex étaient devenues du routing léger. Le traitement réel se passait dans un fichier que les docs avaient arrêté de mentionner.

4. Le switch de mode non documenté

Un script shell à la racine basculait la stack entre Convex Cloud managé et une instance Convex self-hosted selon la cible de déploiement. Zéro mention dans le CLAUDE.md. Chaque session Claude Code avait assumé une connexion backend statique, alors qu'il y avait une étape de switch manuel avec de vraies conséquences sur où les données atterrissaient.

5. Le port qui prend 3 fichiers à trouver

Le CLAUDE.md disait que le serveur de dev tourne sur le port 3150. Le port réel : 3002. Vite proxifiait vers Express sur 3002, PORT était injecté par Infisical, vite.config.ts était le pont entre les 3. Pour trouver le vrai port, il fallait recouper 3 fichiers. /init a fait ce recoupement. Moi pas. Pendant 3 mois.

Personne n'a menti délibérément. Le CLAUDE.md avait été précis. Le code avait bougé comme le code bouge toujours : pas en rewrites dramatiques mais en 10 décisions par semaine, chacune trop petite pour donner l'impression qu'elle méritait une mise à jour de doc. Après 3 mois, 5 de ces décisions avaient dérivé au-delà de ce qui était écrit.

Intermède : l'arbre git sale

Ce repo avait un état non commité. Un package-lock.json supprimé, un fichier de backup non tracké qui traînait à la racine. /init n'a pas sauté le repo, n'a pas forcé l'arbre, n'a pas écrit par-dessus le répertoire de travail.

Il a lancé 5 étapes git en séquence : créé un worktree sur une branche dédiée, fait les éditions en isolation, commité avec un message de commit conventionnel, fast-forward mergé dans main, puis nettoyé le worktree et supprimé la branche. WIP intact, historique git propre.

La raison pour laquelle ça a marché proprement : des git hooks versionnés qui forcent ce workflow. Le modèle n'a pas choisi la prudence. Il a opéré dans les contraintes projet qu'il ne pouvait pas contourner. C'est une garantie différente que de s'appuyer sur la bonne volonté du modèle, et ça vaut le coup de comprendre la différence entre la bonne volonté du modèle et la vraie discipline d'outillage avant de décider combien de confiance mettre dans l'un ou l'autre.

Ce Que /init Ne Peut Pas Faire

/init audite ce qui est traçable. Les fichiers qu'il peut lire, les configs qu'il peut recouper, les schémas qu'il peut comparer à la documentation. C'est une vraie capacité, sous-estimée parce que la sortie a l'air simple. Le mensonge du port seul m'a évité une session de debug que je ne voulais pas avoir.

Mais il y a une catégorie de connaissance qu'il ne peut pas toucher.

Le git hook qui a forcé le workflow worktree existe parce que, des mois avant que /init existe, j'ai failli effacer une session de travail live en laissant un run Claude Code commiter directement sur main sur un arbre sale. Le hook était le fix que j'ai codé cet après-midi-là. C'est documenté dans son propre code mais dans aucun CLAUDE.md. /init a vu le hook et l'a référencé correctement, mais il ne pouvait pas me dire pourquoi la séquence comptait, ou ce qui se passerait si quelqu'un le supprimait en assumant que c'était du nettoyage boilerplate, ou ce que l'après-midi qui l'a produit avait coûté en travail perdu.

Cette connaissance vit dans l'incident. Les règles projet les plus précieuses tendent à venir de quelque chose qui a cassé, pas d'un scan de fichier ou d'un entretien d'onboarding. Vous pouvez documenter le quoi mais pas l'historique du pourquoi, et le pourquoi est généralement la partie qui empêche l'erreur de se répéter. /init est un outil d'audit, pas une rétrospective. Il trouve les mensonges présents, pas les leçons passées, et connaître cette différence est la plupart de la raison de faire confiance à ce qu'il remonte.

Je pense que l'autre moitié pour rendre /init utile c'est d'amener votre documentation à un état qui vaut la peine d'être audité en premier lieu. Si vous êtes tôt dans un projet, le gap entre "ce que j'ai l'intention que cette codebase soit" et "ce que Claude Code a vraiment besoin de voir documenté" est le travail que Vibe Coding, For Real cartographie, spécifiquement la distinction entre documentation d'intention et documentation d'implémentation. /init n'est utile que sur l'implémentation. L'intention, c'est encore à vous de l'écrire.

---

Lancez /init ce soir sur votre repo le plus vieux. Pas pour avoir un CLAUDE.md propre. Pour découvrir combien de lignes mentent déjà. 😬

---

Sources

• Thariq (@trq212), équipe Claude Code : post X annonçant CLAUDE_CODE_NEW_INIT=1, mars 2026
• Claude Code Docs, changelog semaine 16 (13-17 avril 2026)
• r/ClaudeAI, données communauté GummySearch, juin 2026
• wmedia.es : "/init dans Claude Code : bien plus qu'un template CLAUDE.md," avril 2026

Ce post peut contenir des liens d'affiliation. Si vous cliquez dessus, je pourrais gagner une petite commission (ça ne vous coûte rien, et ça m'aide à continuer de livrer des articles de qualité chaque jour pour votre plaisir de lecture).