Structure du projet : Que place Claude Code dans votre projet

📚 Navigation dans la série : L'article précédent 12 Initialisation du projet vous a guidé à travers /init pour générer le premier CLAUDE.md de votre projet. Cet article poursuit la découverte : après /init, que contient exactement ce dossier .claude/ apparu discrètement dans votre projet, qui le gère, et doit-il être inclus dans git ?

On dit souvent du dossier .claude qu'il n'y a « pas besoin de s'en occuper, il gère ça tout seul », mais pour être honnête, le comprendre est la seule façon de vraiment savoir utiliser Claude Code.

Pourquoi ? Parce que presque tous les « usages avancés » de cet outil (commandes personnalisées, contrôle des autorisations, sous-agents, compétences), une fois sur le disque, se résument à quelques fichiers et dossiers dans .claude/. Si vous ne comprenez pas cette structure, vous serez désemparé face à des problèmes comme « pourquoi l'autorisation que j'ai configurée ne fonctionne-t-elle pas » ou « mes coéquipiers ont récupéré le code mais n'ont pas ma commande ».

À mes débuts, j'ai fait une bêtise : par facilité, j'ai écrit une configuration contenant le mot de passe de la base de données directement dans .claude/settings.json, et je l'ai poussée avec un git push. Quand je m'en suis rendu compte, le secret était déjà dans l'historique du dépôt — il m'a fallu changer le mot de passe, réécrire l'historique, et perdre une bonne demi-heure. J'ai compris plus tard que ce genre de chose devait aller dans settings.local.json, fichier que Claude Code ajoute par défaut au gitignore. Un fichier mal placé, et la différence est énorme.

Cet article ne vous apprendra pas à configurer chaque fichier en profondeur (cela sera abordé dans des articles dédiés), il n'a qu'un seul but : vous donner une vue d'ensemble, pour qu'en un coup d'œil sur un fichier, vous sachiez « à quoi il sert, où le placer, s'il appartient au projet ou à vous, et s'il faut le commiter ».

Après avoir lu cet article, vous obtiendrez :

• Une vue d'ensemble du répertoire .claude/ : ce que gère chaque fichier / sous-dossier
• La différence fondamentale entre les configurations de niveau « projet » et de niveau « utilisateur » (ce qui suit le projet vs ce qui vous suit)
• Un aide-mémoire : ce qui doit être commité dans git, ce qui doit aller dans .gitignore
• Une partie pratique facile à prendre en main, pour voir de vos propres yeux à quoi ressemblent ces deux niveaux de répertoires

---

01 Comprendre une chose d'abord : Claude Code a « deux maisons »

Donnons d'abord la conclusion : La configuration de Claude Code est stockée à deux endroits — un endroit qui suit le projet, et un endroit qui vous suit. Si vous comprenez cela, le reste suivra tout seul.

Analogie : L'« armoire à archives du projet » de l'entreprise et le « tiroir de votre bureau ». L'armoire à archives du projet (niveau projet) contient ce que tout le monde dans ce projet doit voir : les normes du projet, qui peut faire quelles opérations. Un nouveau venu peut s'y référer pour commencer. Le tiroir de votre bureau (niveau utilisateur) contient vos habitudes personnelles : vos raccourcis favoris, vos préférences privées, qui vous suivent même si vous changez de projet.

Sur le disque, cela correspond à deux emplacements :

Cet endroit	Où est-il	Qui impacte-t-il	Qui suit-il
Niveau Projet (Project)	./.claude/ dans le projet	Tous les collaborateurs de ce dépôt	Suit le projet (commité dans git, partagé en équipe)
Niveau Utilisateur (User)	~/.claude/ dans votre répertoire personnel	Vous, dans tous vos projets	Vous suit (sur votre machine, jamais commité)

Précisons deux termes ici :

Niveau projet (Project scope) : La configuration est stockée dans le dépôt, va dans git, est partagée par l'équipe. Si vous modifiez une règle et la soumettez, elle s'applique à tous vos coéquipiers lorsqu'ils la récupèrent.

Niveau utilisateur (User scope) : La configuration est stockée dans votre répertoire personnel ~/.claude/, ne s'applique qu'à vous et n'entre jamais dans aucun dépôt. Elle vous suit dans n'importe quel projet de l'entreprise.

Un cas d'utilisation courant : placez vos préférences purement personnelles comme « répondre en français » ou « quel préfixe utiliser pour les messages de commit » dans le ~/.claude/CLAUDE.md de niveau utilisateur — ainsi, en ouvrant n'importe quel projet, Claude suivra vos habitudes. En revanche, un fait lié au projet comme « ce projet utilise pnpm et non npm », doit être écrit dans le ./CLAUDE.md de niveau projet, pour être partagé avec toute l'équipe. Séparez dès le départ vos habitudes personnelles et les normes du projet dans ces deux endroits, cela vous facilitera la vie plus tard.

💡 En résumé : Claude Code a « deux maisons » — ./.claude/ dans le projet (suit le projet, va dans git, partagé en équipe) et ~/.claude/ dans votre répertoire personnel (vous suit, ne va pas dans git, ne s'applique qu'à vous).

---

02 Ouvrir le niveau projet .claude/ : Qu'y a-t-il dedans

Maintenant, ouvrons le dossier ./.claude/ dans le projet. Dans un projet actif, la structure ressemble à ceci :

your-project/
├── CLAUDE.md                ← Manuel du projet (peut aussi être mis dans .claude/CLAUDE.md)
├── CLAUDE.local.md          ← Vos préférences personnelles pour le projet (va dans .gitignore)
├── .mcp.json                ← Configuration du serveur MCP partagée en équipe (va dans git)
└── .claude/
    ├── settings.json        ← Configuration partagée : autorisations, hooks, valeurs par défaut des modèles
    ├── settings.local.json  ← Surcharge de configuration personnelle (ignoré automatiquement par git)
    ├── commands/            ← Commandes slash personnalisées, une commande / par .md
    ├── rules/               ← Règles de projet modulaires (extraites de CLAUDE.md)
    ├── skills/              ← Compétences : flux de travail pouvant être appelés par / ou automatiquement par Claude
    └── agents/              ← Sous-agents : assistants spécialisés avec des contextes indépendants

Voyons ce que fait chacun, cet article n'aborde que « ce qu'ils sont et qui les gère », les utilisations avancées auront leurs propres articles :

CLAUDE.md — Manuel du projet. Le tout premier fichier que Claude lit à chaque entrée dans le projet. Ce qu'est le projet, comment l'exécuter, quelles sont les conventions, tout est écrit ici. Il y a une différence fondamentale avec .claude/settings.json : CLAUDE.md est une « directive » pour Claude (il le lit et essaie de le suivre, mais ce n'est pas une contrainte stricte), tandis que settings.json est la « configuration » que Claude Code applique obligatoirement.

Un détail officiel : CLAUDE.md peut être placé à la racine du projet, ou dans .claude/CLAUDE.md — cette dernière option permet de garder la racine du projet plus propre.

CLAUDE.local.md — Vos préférences personnelles pour le projet. Des instructions qui s'ajoutent à CLAUDE.md et ne concernent que vous, comme « mon port de base de données local est 5433 ». Vous devez l'ajouter manuellement à .gitignore (choisir l'option personnelle lors de l'exécution de /init l'ajoutera pour vous).

settings.json — Centre de configuration partagé par l'équipe. Contrôle si Claude peut exécuter certaines opérations (autorisations), à quels moments exécuter vos scripts (hooks), et permet de définir le modèle par défaut pour ce projet. Va dans git, c'est la base de sécurité de l'équipe.

settings.local.json — Surcharge de configuration personnelle. Même format JSON que ci-dessus, mais ne s'applique qu'à vous et n'est pas soumis. Si vous voulez autoriser temporairement une permission sans affecter vos coéquipiers, écrivez-le ici. La première fois que Claude Code écrit ce fichier, il configure automatiquement git pour l'ignorer — c'est le fichier mentionné au début que « j'aurais dû utiliser mais que j'ai oublié ».

Un détail mentionné officiellement ici : il ajoute la règle d'ignorance à votre ~/.config/git/ignore global (pas au .gitignore du projet), donc vous ne trouverez pas cette ligne en fouillant dans le .gitignore du projet. Si vous voulez que toute l'équipe l'ignore, vous devez ajouter vous-même une ligne dans le .gitignore du projet.

commands/ — Commandes slash personnalisées. Chaque fichier .md dans le répertoire devient une commande /nomdufichier. Enregistrez cette longue instruction que vous tapez souvent dans un fichier, et appelez-la avec / la prochaine fois. Officiellement, les mécanismes sous-jacents de commands/ et skills/ ont été unifiés, il est recommandé d'utiliser skills/ pour les nouvelles commandes (prend en charge le regroupement de fichiers associés), commands/ reste compatible mais n'est plus le chemin recommandé.

rules/ — Règles de projet modulaires. Lorsque CLAUDE.md devient trop long (il est officiellement recommandé de le garder sous 200 lignes), divisez les règles par sujet en plusieurs fichiers sous rules/, par exemple testing.md, api-design.md.

skills/ — Compétences. Chaque compétence est un sous-dossier, contenant un SKILL.md. Vous pouvez soit l'appeler manuellement avec /nomdelacompétence, soit laisser Claude décider automatiquement de l'utiliser en fonction de la tâche.

agents/ — Sous-agents. Chaque .md définit un assistant spécialisé avec une fenêtre de contexte indépendante, qui ne pollue pas la conversation principale. Idéal pour le travail en parallèle ou l'isolation des tâches.

.mcp.json — Configuration du serveur MCP partagée en équipe. Placé à la racine du projet, au même niveau que .claude/. Les serveurs MCP (Model Context Protocol) peuvent être configurés à deux endroits : ce .mcp.json va dans git pour être partagé avec toute l'équipe, par exemple des outils de base de données ou des API internes que toute l'équipe doit utiliser ; la configuration MCP personnelle (par exemple, des outils que vous seul utilisez) est stockée dans ~/.claude.json et n'ira dans aucun dépôt. La différence est : partage de projet vs usage privé.

💡 En résumé : Au niveau du projet dans .claude/, CLAUDE.md / rules/ sont des « directives » pour Claude, settings.json est la configuration « imposée » par Claude Code, et commands/ skills/ agents/ sont les « extensions » que vous lui installez.

---

03 Les mêmes répertoires se retrouvent dans ~/.claude/

C'est ce qui déroute le plus facilement les débutants, mais c'est en fait très simple : les noms de répertoires ci-dessus se retrouvent presque à l'identique au niveau utilisateur dans ~/.claude/.

commands/, rules/, skills/, agents/, CLAUDE.md, settings.json — tout ce qui est dans le projet, se trouve aussi dans ~/.claude/. Il n'y a qu'une seule différence :

(Le niveau utilisateur ~/.claude/ possède aussi quelques répertoires exclusifs que le niveau projet n'a pas — themes/, keybindings.json, output-styles/, workflows/, etc., qui seront présentés un par un dans des articles ultérieurs.)

Ce qui est placé sous ~/.claude/ s'applique à tous vos projets ; ce qui est placé sous ./.claude/ d'un projet, ne s'applique qu'à ce projet-là.

Deux cas d'utilisation pour comprendre :

• Une commande /commit-fr (pour générer des messages de commit en français), placée dans ~/.claude/commands/ — vous pouvez ainsi l'utiliser dans n'importe quel projet, sans avoir à la reconfigurer pour chaque projet.
• Mais une commande comme « déployer sur l'environnement de test de l'entreprise » n'est clairement liée qu'à ce projet-là, elle doit donc aller dans le .claude/commands/ du projet, et être commitée pour être utilisée par toute l'équipe.

En plus de ces répertoires « jumeaux », le répertoire personnel ~/ contient deux fichiers qui n'apparaissent qu'au niveau utilisateur et que vous n'avez presque jamais besoin de toucher manuellement, il suffit de les identifier :

Fichier / Dossier	Où est-il	Qu'est-ce que c'est	Devez-vous vous en occuper
~/.claude.json	Répertoire personnel	État de l'application : état de connexion (session OAuth), thème, serveurs MCP personnels, historique de confiance de chaque projet et préférences d'interface utilisateur	N'y touchez presque jamais, modifiez via /config
~/.claude/projects/	Niveau utilisateur	Historique des sessions de chaque projet ; la mémoire automatique est placée dans son sous-répertoire <projet>/memory/	Pas besoin de l'écrire, il se gère tout seul

Un mot de plus ici sur la mémoire automatique (auto memory) : c'est un système complètement séparé de CLAUDE.md. CLAUDE.md ce sont les instructions que vous écrivez pour Claude ; la mémoire automatique ce sont les notes que Claude s'écrit à lui-même (par exemple, s'il a découvert votre commande de build, ou les pièges rencontrés), stockées sous ~/.claude/projects/<projet>/memory/, et réutilisables entre les sessions. Ne confondez pas les deux : l'un est écrit par vous, l'autre par lui.

💡 En résumé : Il existe un ensemble de répertoires comme commands/ et skills/ pour le niveau projet et un autre pour le niveau utilisateur, la seule différence est de savoir s'ils gèrent « un seul projet » ou « tous vos projets » ; ~/.claude.json et ~/.claude/projects/ sont exclusifs au niveau utilisateur et vous n'avez presque jamais à les toucher manuellement.

---

04 Qu'est-ce qui va dans git, et qu'est-ce qu'il ne faut surtout pas commiter

C'est la section la plus pratique, le piège de la fuite de secrets au début vient de là. Règle d'or : ce qui contient « local » ou des secrets, ne va jamais dans git.

Pourquoi commiter certains et pas d'autres ? La logique est très simple — ce qui doit être partagé avec l'équipe est commité, ce qui n'a de rapport qu'avec vous ou votre machine ne doit pas l'être.

Analogie : Ce qui est dans l'armoire à archives du projet doit être enregistré (dans git), les affaires personnelles dans le tiroir de votre bureau n'ont pas à être remises.

Classons les fichiers courants d'un projet selon s'ils doivent être commités ou non, suivez ce tableau et vous ne vous tromperez pas :

Fichier / Dossier	Dans git ?	Pourquoi
CLAUDE.md	✅ Commité	Manuel du projet partagé en équipe
.claude/settings.json	✅ Commité	Base de référence des autorisations / configurations partagées en équipe
.claude/commands/*.md	✅ Commité	Commandes standardisées réutilisées par l'équipe
.claude/rules/*.md	✅ Commité	Règles modulaires partagées en équipe
.claude/skills/、.claude/agents/	✅ Commité	Compétences et sous-agents partagés en équipe
.claude/settings.local.json	❌ Non commité	Remplacement personnel ; Claude Code l'ajoute automatiquement au gitignore
CLAUDE.local.md	❌ Non commité	Préférences personnelles pour le projet ; nécessite que vous l'ajoutiez manuellement à .gitignore
Tout fichier contenant secrets / tokens / mots de passe	❌ Jamais commité	Entrer dans l'historique du dépôt équivaut à une fuite

Quelques rappels pratiques :

Ne vous inquiétez pas pour le gitignore de settings.local.json. La documentation officielle indique clairement : lors de la création de ce fichier, Claude Code configurera automatiquement git pour l'ignorer. Si vous souhaitez autoriser temporairement une permission localement, écrivez-la ici, c'est le plus sûr.

Vous devez ajouter vous-même CLAUDE.local.md à .gitignore. Contrairement à settings.local.json, il ne sera pas ignoré automatiquement — choisir l'option « personnel » lors de l'exécution de /init l'ajoutera pour vous, sinon n'oubliez pas d'ajouter la ligne manuellement.

N'écrivez jamais de secrets en clair dans aucun fichier de configuration. La pratique recommandée par les autorités officielles est d'utiliser des variables d'environnement dans la configuration, par exemple écrire ${GITHUB_TOKEN} au lieu de coller le token en clair — Claude Code les lira depuis votre environnement shell au démarrage, le token ne sera jamais enregistré dans un fichier. Appliquez ce conseil sans exception.

💡 En résumé : Ce qui est partagé par l'équipe (CLAUDE.md, settings.json, commands/, etc.) va dans git ; ce qui contient « local » et tout ce qui contient des secrets ne doit jamais être soumis — le système ignore automatiquement settings.local.json, vous devez ajouter manuellement CLAUDE.local.md.

---

05 Conflit de configuration : qui a raison ? La priorité expliquée en un schéma

Vous avez peut-être déjà pensé à un problème : Si settings.json au niveau utilisateur et settings.json au niveau projet définissent le même paramètre, lequel l'emporte ?

L'ordre de priorité donné par la documentation officielle est le suivant (du plus élevé au plus bas) :

Managed (Géré par l'organisation, le plus élevé, rien ne peut le remplacer)
  ↓
Arguments de ligne de commande (comme --permission-mode, uniquement pour la session en cours)
  ↓
Local (settings.local.json)
  ↓
Project (settings.json du projet)
  ↓
User (settings.json de l'utilisateur ~/.claude/, le plus bas)

Moyen mnémotechnique : Le plus « spécifique » et le plus « proche de l'opération en cours » a la priorité la plus élevée. Ce qui est géré par l'organisation > ce que vous avez spécifié temporairement en ligne de commande cette fois-ci > votre local pour ce projet > ce qui est partagé par le projet > votre valeur par défaut globale.

Ce schéma place les deux arborescences côte à côte : à gauche, le niveau projet ./.claude/ (qui suit le projet, soumis dans git selon les besoins pour un partage en équipe) ; à droite, le niveau utilisateur ~/.claude/ (qui vous suit personnellement, et gère tous vos projets) — rappelez-vous ce que gère chaque arbre, et vous ne vous perdrez plus dans vos configurations par la suite.

Mais il y a un piège dans lequel on tombe très facilement, et qu'il faut souligner — tous les paramètres ne suivent pas la logique de « remplacement » :

Type de paramètre	En présence de multiples portées simultanément	Exemple
Valeur scalaire (valeur unique)	Prend la plus spécifique, remplace	model : si défini par le projet, utilise celui du projet
Valeur de tableau (liste)	Fusionné entre les portées, pas remplacé	permissions.allow : superposition de l'utilisateur + projet + local

Il est très facile de se faire avoir par cette différence : je me suis moi-même trompé une fois — j'avais refusé (deny) une commande dans le settings.json de niveau utilisateur, pensant qu'elle serait désactivée globalement, mais en passant sur un projet, elle s'exécutait toujours. J'ai passé un long moment à fixer la configuration sans comprendre. J'ai fini par découvrir que les règles d'autorisation sont fusionnées, pas remplacées. Si le niveau projet l'autorise (allow), cela se superposera aux règles du niveau utilisateur lors de l'évaluation. Ne vous attendez donc pas à « tout bloquer d'un coup » via le niveau utilisateur, comprenez bien les règles de fusion.

💡 En résumé : La priorité décroissante est Managed → Ligne de commande → Local → Project → User ; mais faites la distinction — pour un scalaire comme model c'est un « remplacement », pour un tableau comme permissions.allow c'est une « fusion/superposition ».

---

06 Pratique : Voir ces deux niveaux de répertoires de ses propres yeux

Il vaut mieux vérifier par soi-même que de se contenter des schémas. L'ensemble de commandes suivant ne fait que de la lecture, aucune écriture, c'est totalement sûr, vous pouvez l'exécuter pour bien comprendre les « deux maisons ».

Première étape : Regardez le niveau utilisateur ~/.claude/ dans votre répertoire personnel

Ouvrez un terminal, tapez (Mac / Linux) :

ls -a ~/.claude

Pour Windows PowerShell, utilisez :

dir $HOME\.claude

Résultat attendu : Vous devriez voir settings.json, projects, et peut-être commands, skills, etc. — ce qu'il y a dépend de la profondeur à laquelle vous utilisez Claude Code. S'il liste des éléments, cela signifie que cette « maison » de niveau utilisateur existe et est active.

Deuxième étape : Regardez le niveau projet .claude/ dans un projet

Utilisez cd pour vous placer dans n'importe quel projet où vous avez exécuté Claude Code (si vous n'en avez pas, retournez à l'article précédent et utilisez /init pour en créer un), puis :

ls -a .claude

Résultat attendu : Vous devriez au moins voir settings.local.json (si vous avez approuvé des autorisations auparavant), et peut-être settings.json. C'est l'« armoire à archives » du niveau projet, c'est un ensemble distinct de celui de votre répertoire personnel.

Troisième étape : Vérifiez que settings.local.json est bien ignoré par git

Dans ce projet (qui doit être un dépôt git), tapez :

git check-ignore .claude/settings.local.json

Résultat attendu : Le terminal affiche le chemin du fichier (.claude/settings.local.json), ce qui prouve qu'il a déjà été ignoré par git — c'est exactement ce que Claude Code a fait automatiquement pour vous. S'il n'affiche rien, cela signifie qu'il n'est pas ignoré, et vous feriez bien d'ajouter manuellement cette ligne à votre .gitignore.

Quatrième étape (facultative) : Jetez un œil au manuel du projet

cat CLAUDE.md

(Pour Windows PowerShell, utilisez type CLAUDE.md)

Résultat attendu : Imprime le contenu généré par le /init de l'article précédent. C'est le premier fichier que Claude lit à chaque entrée dans le projet, vous savez maintenant où il se trouve.

⚠️ Un rappel : git check-ignore n'a de sens que dans un dépôt git. Si le projet n'a pas encore été initialisé avec git init, la commande affichera fatal: not a git repository, transformez-le d'abord en dépôt git avant d'essayer.

💡 En résumé : ls -a ~/.claude pour voir le niveau utilisateur, ls -a .claude pour le niveau projet, git check-ignore .claude/settings.local.json pour vérifier l'ignorance par git — trois commandes en lecture seule pour voir clairement les « deux maisons » et « qui est ignoré par git ».

---

07 Résumé

Dans cet article, nous avons passé en revue tout le « patrimoine » de Claude Code dans votre projet. Pour résumer :

Ce que vous avez retenu	Concrètement
Deux maisons	Le projet ./.claude/ (suit le projet, va dans git) + Le répertoire personnel ~/.claude/ (vous suit, ne va pas dans git)
Directives vs Configuration	CLAUDE.md / rules/ sont des directives pour Claude ; settings.json est la configuration appliquée obligatoirement
Répertoires jumeaux	Un ensemble commands/ skills/ agents/ au niveau projet et au niveau utilisateur, la différence est s'ils gèrent un projet ou tous
Ligne rouge pour git	Ceux contenant « local » et les secrets ne vont jamais dans git ; settings.local.json est ignoré automatiquement par le système
Priorités	Managed → Ligne de commande → Local → Project → User ; les scalaires se remplacent, les tableaux se fusionnent

Maintenant, vous devriez pouvoir : Ouvrir n'importe quel projet, jeter un œil à un fichier dans .claude/ et savoir à quoi il sert, s'il appartient au projet ou à vous, et s'il faut le commiter ; et vous savez également qui a raison en cas de conflit de configuration. Cette carte d'ensemble est la base de tous les articles dédiés à venir — que vous appreniez comment configurer en détail settings.json, comment bien rédiger CLAUDE.md, ou comment créer des compétences et des sous-agents, vous pourrez trouver leur place sur cette carte.

---

Article suivant 14 « Interface d'interaction et Raccourcis » — Maintenant que vous avez compris la « carte statique » de la structure des répertoires, il est temps de vous familiariser avec le « panneau de commande » de Claude Code. Le prochain article vous guidera pour reconnaître chaque partie de l'interface, puis pour inscrire les raccourcis les plus utilisés dans votre mémoire musculaire, afin de taper plus vite et avec plus de précision.

---

Lectures recommandées

• Hooks : Appuyer sur la gâchette au bon moment
• Gestion du contexte : Ne le laissez pas perdre la mémoire ni exploser le quota de tokens
• Intégration JetBrains