Guide complet Claude Code : structure `.claude`, `CLAUDE.md`, skills, hooks, mémoire et slash commands

Claude Code devient beaucoup plus puissant quand on arrête de l'utiliser comme un simple terminal assisté, et qu'on le traite comme un véritable environnement d'ingénierie configurable.

La vraie valeur n'est pas seulement dans le modèle. Elle est dans la manière dont vous structurez :

• votre dossier .claude
• vos fichiers CLAUDE.md
• vos skills
• vos hooks
• votre mémoire persistante
• vos permissions et conventions d'équipe

Si cette couche est propre, Claude Code devient plus stable, plus réutilisable, et surtout beaucoup plus rentable au quotidien.

Ce guide met à jour la structure classique que beaucoup d'équipes ont en tête, avec un point important :

dans la documentation actuelle, les custom commands ont été fusionnées dans le système de skills. Les fichiers .claude/commands/ continuent de fonctionner, mais Anthropic recommande désormais de privilégier les skills, parce qu'ils supportent mieux les fichiers annexes, les règles d'invocation et les sous-agents.

Vue d'ensemble : les deux niveaux de configuration

Claude Code fonctionne avec deux couches principales :

1. Le niveau utilisateur dans ~/.claude/
2. Le niveau projet dans votre repository

Dans la pratique, vous obtenez une architecture de ce type :

```text ~/.claude/ ← niveau utilisateur ├── CLAUDE.md # préférences personnelles globales ├── settings.json # config globale ├── skills/ # skills perso utilisables partout └── agents/ # sous-agents perso

mon-projet/ ├── CLAUDE.md # instructions d'équipe pour le projet └── .claude/ ├── settings.json # config partagée dans git ├── settings.local.json # overrides personnels gitignored ├── skills/ # skills du projet ├── commands/ # toujours supporté, mais plus legacy ├── rules/ # règles modulaires └── agents/ # sous-agents spécialisés ```

La logique est simple :

• ~/.claude/ = vos préférences perso
• ./CLAUDE.md et ./.claude/ = conventions projet partagées
• .claude/settings.local.json = vos overrides locaux non commités

L'ordre de priorité réel des settings

D'après la documentation officielle, les settings s'appliquent dans cet ordre de priorité :

1. Managed settings (niveau organisation, non surchargable)
2. Arguments de ligne de commande
3. `.claude/settings.local.json`
4. `.claude/settings.json`
5. `~/.claude/settings.json`

Autre détail important : les tableaux ne sont pas simplement remplacés. Pour certaines clés, les tableaux sont concaténés et dédupliqués, tandis que les objets sont fusionnés en profondeur.

En clair :

• les règles les plus spécifiques gagnent
• mais certaines listes s'additionnent au lieu de s'écraser

CLAUDE.md : la mémoire que vous contrôlez

Le fichier CLAUDE.md reste la brique la plus importante.

Il sert à donner à Claude Code un contexte persistant sur :

• votre stack
• vos conventions
• vos commandes essentielles
• votre architecture
• vos règles d'équipe

La doc officielle distingue bien deux mécanismes :

• `CLAUDE.md` : instructions que vous écrivez
• auto-memory : mémoire que Claude écrit lui-même à partir de vos corrections

Autre point utile : la documentation actuelle indique que `CLAUDE.local.md` est désormais déprécié. Le mécanisme recommandé pour garder des consignes supplémentaires est plutôt d'utiliser les imports @chemin-vers-fichier.md depuis CLAUDE.md, avec des fichiers gitignorés si nécessaire.

Où mettre CLAUDE.md ?

Les emplacements les plus utiles sont :

• ~/.claude/CLAUDE.md pour vos préférences globales
• ./CLAUDE.md pour les instructions projet
• des CLAUDE.md dans des sous-dossiers quand vous voulez du contexte plus local

Claude charge :

• les CLAUDE.md situés au-dessus du répertoire courant au démarrage
• les CLAUDE.md dans les sous-répertoires à la demande, quand il lit des fichiers dedans

Donc un monorepo peut très bien avoir :

• un CLAUDE.md racine
• des CLAUDE.md spécifiques par package
• des règles plus fines dans .claude/rules/

Bonne pratique clé : rester court

Anthropic recommande explicitement de viser moins de 200 lignes par CLAUDE.md.

Pourquoi :

• le fichier consomme du contexte à chaque session
• plus il est long, plus l'adhérence baisse
• des instructions courtes, concrètes et bien structurées sont mieux suivies

Si votre CLAUDE.md grossit trop, le bon move n'est pas d'en faire un pavé. C'est de le splitter :

• CLAUDE.md pour le socle
• .claude/rules/ pour les règles modulaires
• imports @fichier.md pour la doc annexe

.claude/rules/ : une excellente convention d'équipe

Point important : `.claude/rules/` n'est pas la primitive officielle principale documentée par Anthropic au même titre que CLAUDE.md, skills, agents ou settings.

En revanche, c'est une très bonne convention d'équipe si vous l'utilisez comme répertoire de règles modulaires référencées depuis CLAUDE.md.

Vous pouvez y placer des fichiers markdown par sujet :

``text .claude/ └── rules/ ├── typescript.md ├── testing.md ├── api-design.md └── security.md ``

L'idée est simple :

• une règle = un sujet
• noms explicites
• séparation claire entre standards de test, conventions API, style, sécurité

C'est beaucoup plus maintenable qu'un énorme CLAUDE.md, à condition de garder la logique explicite via des imports ou des références claires dans le guide principal.

settings.json et settings.local.json

Le fichier officiel de configuration est settings.json.

Les scopes utiles sont :

• ~/.claude/settings.json pour l'utilisateur
• .claude/settings.json pour le projet
• .claude/settings.local.json pour les préférences locales non partagées

La doc officielle confirme aussi que quand settings.local.json est créé, Claude Code configure git pour l'ignorer.

Ce qu'on met dans settings.json

En pratique, c'est là que vous placez :

• les permissions
• les hooks
• le modèle par défaut
• l'effort level
• certains plugins
• des variables d'environnement de session

Exemple minimal propre pour une équipe :

``json { "model": "claude-sonnet-4-6", "permissions": { "allow": [ "Read", "Write", "Bash(git *)", "Bash(npm *)", "Bash(node *)" ], "deny": [ "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Bash(git push --force *)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh" } ] } ] } } ``

Ce qu'on met dans settings.local.json

Réservez-le pour :

• vos outils machine-spécifiques
• des tests personnels de config
• des accès plus puissants non partageables

Typiquement :

• docker
• kubectl
• des scripts locaux
• des préférences modèle/effort propres à votre machine

Skills : le vrai centre de gravité aujourd'hui

Le changement important dans la doc Claude Code récente, c'est que les custom commands ont été absorbées par le système de skills.

Officiellement :

• un skill dans .claude/skills/<nom>/SKILL.md crée une commande /nom
• un fichier .claude/commands/*.md continue de fonctionner
• mais les skills sont recommandés

Pourquoi les skills sont meilleurs :

• ils supportent les fichiers annexes
• ils supportent le frontmatter riche
• ils supportent l'activation automatique
• ils peuvent tourner dans un sous-agent isolé
• ils peuvent embarquer leurs propres hooks

Structure recommandée d'un skill

``text .claude/skills/ └── review-pr/ ├── SKILL.md ├── examples.md └── scripts/ └── validate.sh ``

Exemple de SKILL.md

```md --- name: review-pr description: Review a pull request diff and identify critical, important, and minor issues. disable-model-invocation: true allowed-tools: Read, Grep, Bash(git *), Bash(gh *) ---

Pull request context

• Diff: !gh pr diff
• Changed files: !gh pr diff --name-only

Review this PR with three sections:

1. Critical
2. Important
3. Minor

```

Les champs frontmatter à connaître

Les plus utiles au quotidien sont :

• name
• description
• argument-hint
• disable-model-invocation
• user-invocable
• allowed-tools
• model
• effort
• context: fork
• agent
• hooks
• paths

Deux champs sont particulièrement importants :

• disable-model-invocation: true si vous voulez un workflow manuel comme /deploy
• context: fork si vous voulez exécuter le skill dans un sous-agent isolé

Les custom commands existent encore, mais ne sont plus le meilleur choix

Beaucoup de guides plus anciens présentent encore .claude/commands/ comme le mécanisme principal.

Aujourd'hui, la bonne lecture est :

• oui, .claude/commands/ fonctionne toujours
• non, ce n'est plus la structure la plus riche
• oui, pour un nouveau projet, il vaut mieux penser directement en skills

Si vous avez déjà :

``text .claude/commands/review.md .claude/commands/deploy.md ``

... vous n'êtes pas obligé de tout casser.

Mais si vous voulez une base durable pour une équipe, migrez progressivement vers :

``text .claude/skills/review/SKILL.md .claude/skills/deploy/SKILL.md ``

Sous-agents : quand il faut spécialiser vraiment

Claude Code supporte aussi des subagents dans :

• ~/.claude/agents/
• .claude/agents/

Chaque sous-agent a :

• un name
• une description
• éventuellement une liste de tools
• un prompt système spécialisé

Exemple :

```md --- name: code-reviewer description: Expert code review specialist. Use proactively for quality, maintainability, and security review. tools: Read, Grep, Glob ---

Review code for:

• logic bugs
• security issues
• maintainability risks
• missing tests

```

À utiliser quand vous voulez :

• préserver le contexte principal
• déléguer une tâche spécialisée
• mieux contrôler les outils autorisés

Mémoire : CLAUDE.md vs auto-memory

La doc officielle distingue bien les deux couches.

1. CLAUDE.md

C'est la mémoire que vous écrivez.

Utilisez-la pour :

• conventions de code
• architecture
• commandes build/test/lint
• règles absolues
• workflows d'équipe

2. Auto-memory

C'est la mémoire que Claude construit lui-même à partir de vos corrections et habitudes.

Elle vit dans :

``text ~/.claude/projects/<project>/memory/ ``

Le point important :

• MEMORY.md est relu au démarrage
• seule une partie est chargée automatiquement au startup
• Claude lit ensuite les autres fichiers mémoire à la demande avec ses outils habituels

La doc précise aussi que vous pouvez ouvrir et éditer cette mémoire via :

``text /memory ``

Le bon usage concret

Utilisez :

• CLAUDE.md pour les règles stables
• auto-memory pour les learnings opérationnels

Exemples de bonnes choses à mémoriser :

• "toujours utiliser notre logger interne"
• "les tests d'intégration se lancent avec tel script"
• "sur ce repo, éviter de toucher tel dossier sans validation"

Hooks : l'automatisation réactive qui change vraiment le jeu

Les hooks permettent d'exécuter des actions à certains moments du cycle de vie.

La doc officielle distingue plusieurs types d'événements, notamment :

• PreToolUse
• PostToolUse
• SessionStart
• Stop

Et plusieurs types de hooks :

• command
• http
• prompt
• agent

Le cas d'usage le plus rentable

Le meilleur point de départ n'est pas un système complexe.

C'est plutôt :

• formatter après écriture
• lancer un check ciblé
• bloquer certaines actions dangereuses

Exemple :

``json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"" } ] } ] } } ``

Et pour une règle de sécurité :

``json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"decision\":\"block\",\"reason\":\"No direct edits on main\"}'; exit 0; }" } ] } ] } } ``

Détail important

Les hooks peuvent aussi :

• tourner en arrière-plan avec async: true
• appeler un endpoint HTTP
• lancer une vérification par prompt
• lancer un sous-agent de validation

Autrement dit, ce n'est pas juste du shell post-formatage. C'est un vrai système d'orchestration légère.

Slash commands essentielles à connaître

La référence officielle liste aujourd'hui un grand nombre de commandes intégrées. Les plus utiles dans un workflow d'équipe sont :

• /init
• /clear
• /compact
• /memory
• /permissions
• /config
• /hooks
• /model
• /effort
• /agents
• /skills
• /doctor
• /status
• /cost
• /usage
• /rewind

Celles qu'il faut vraiment utiliser

/init

Très utile pour générer une première base CLAUDE.md.

La doc officielle précise aussi que :

• CLAUDE_CODE_NEW_INIT=true active un flux interactif plus riche
• ce flux peut aussi vous guider pour les skills, hooks et fichiers de mémoire personnelle

/compact

Indispensable dans les longues sessions.

Il compresse l'historique conversationnel tout en gardant le contexte utile.

/clear

À utiliser entre deux tâches vraiment différentes pour éviter la dérive de contexte.

/memory

Très utile pour :

• vérifier ce que Claude retient
• éditer les fichiers mémoire
• activer ou désactiver l'auto-memory

/permissions

Commande clé quand vous voulez ajuster rapidement les règles sans aller éditer le JSON à la main.

/hooks

Très pratique pour auditer les hooks actifs et voir d'où ils viennent.

Raccourcis clavier vraiment utiles

D'après la doc actuelle d'Interactive Mode, les raccourcis les plus utiles sont :

• Shift+Tab pour faire tourner les permission modes
• Option+P / Alt+P pour changer de modèle
• Option+T / Alt+T pour basculer l'extended thinking
• Ctrl+O pour activer le mode verbose
• Ctrl+R pour la recherche dans l'historique
• Ctrl+B pour passer une tâche bash en arrière-plan
• Ctrl+T pour afficher ou masquer la task list

Et pour l'input multi-ligne :

• Option+Enter
• Shift+Enter selon le terminal
• Ctrl+J
• ou simplement \ + Enter

Notre structure recommandée pour une équipe Neologix

Si vous devez industrialiser Claude Code sur plusieurs projets, une structure saine ressemble à ceci :

``text mon-projet/ ├── CLAUDE.md └── .claude/ ├── settings.json ├── settings.local.json ├── rules/ │ ├── typescript.md │ ├── testing.md │ └── security.md ├── skills/ │ ├── review-pr/ │ │ └── SKILL.md │ ├── deploy/ │ │ └── SKILL.md │ └── onboard/ │ └── SKILL.md └── agents/ ├── code-reviewer.md └── security-auditor.md ``

Ce qui va dans git

• CLAUDE.md
• .claude/settings.json
• .claude/rules/
• .claude/skills/
• .claude/agents/

Ce qui ne va pas dans git

• .claude/settings.local.json
• vos préférences personnelles
• les secrets
• les chemins machine-spécifiques

Ajoutez au minimum :

``gitignore .claude/settings.local.json CLAUDE.local.md ``

Les bonnes pratiques qui évitent 80 % des problèmes

1. Garder CLAUDE.md court et testable

Si une règle n'est pas vérifiable, elle sera mal suivie.

Mauvais :

• "écrire du code propre"

Mieux :

• "écrire des composants React en arrow functions"
• "toujours lancer npm run lint avant de finaliser"
• "ne jamais lire .env"

2. Mettre les règles durables dans CLAUDE.md, pas dans le chat

Si vous répétez une instruction plusieurs fois en session, elle doit probablement remonter dans :

• CLAUDE.md
• .claude/rules/
• ou un skill dédié

3. Réserver les hooks aux contrôles utiles

Un hook trop agressif devient vite une usine à friction.

Commencez avec :

• format
• lint ciblé
• blocage de certaines commandes

Puis élargissez seulement si l'équipe en tire une vraie valeur.

4. Préférer les skills aux commandes legacy

Les commandes dans .claude/commands/ ne sont pas mortes.

Mais si vous repartez proprement aujourd'hui, investissez directement dans :

• .claude/skills/
• des descriptions nettes
• du frontmatter maîtrisé
• des fichiers de support bien rangés

5. Utiliser /clear entre sujets

Beaucoup de sessions "moyennes" viennent simplement d'un contexte devenu sale.

Le bon réflexe :

• /compact pour une longue même tâche
• /clear quand on change vraiment de sujet

Verdict

Le vrai niveau "senior" sur Claude Code ne vient pas d'un meilleur prompt.

Il vient d'une meilleure architecture de contexte.

Si votre équipe structure proprement :

• CLAUDE.md
• .claude/settings.json
• .claude/rules/
• les skills
• les sous-agents
• les hooks
• la mémoire

... alors Claude Code devient beaucoup plus stable, plus prévisible, et beaucoup plus utile dans de vrais projets.

Et c'est précisément là que beaucoup d'équipes se trompent : elles optimisent le modèle, alors qu'elles devraient d'abord optimiser le système.

Si vous voulez structurer cela proprement dans votre équipe, commencez par un audit IA ou parlez à Opuslon pour cadrer une stack Claude Code, Copilot, Codex ou agents IA qui reste vraiment exploitable à l'échelle.