Analyse de la structure du dossier `.claude/`

• Le dossier .claude/ est le répertoire central de contrôle de Claude Code, qui gère, pour chaque projet, les règles, les commandes, les permissions et l’état de la mémoire
• CLAUDE.md est le fichier central qui définit les principes de comportement et les règles du projet pour Claude, en fusionnant et appliquant plusieurs couches de configuration
• Les dossiers commands/, skills/ et agents/ structurent respectivement des commandes personnalisées, des workflows automatiques et des sous-agents spécialisés, afin d’améliorer l’efficacité de la collaboration
• settings.json contrôle les autorisations d’exécution de commandes et la portée d’accès aux fichiers, avec des surcharges personnelles possibles via settings.local.json
• L’ensemble de la structure fonctionne comme un protocole qui transmet à Claude l’identité et les règles du projet, et une configuration claire maximise la productivité et l’efficacité de la collaboration

---

Structure et composants du dossier .claude/

• Le dossier .claude/ est le répertoire central qui contrôle le fonctionnement de Claude Code, en gérant les règles, les commandes, les permissions et l’état de la mémoire par projet
• Le dossier situé à la racine du projet contient les paramètres d’équipe et est versionné dans Git
• Le dossier du répertoire personnel (~/.claude/) stocke les préférences personnelles et l’historique des sessions, y compris la mémoire automatique et les commandes personnelles

• CLAUDE.md — le guide d’instructions de Claude

  • C’est le premier fichier lu au démarrage d’une session Claude Code, et il définit les principes de comportement et les règles du projet pour Claude
  • Le CLAUDE.md à la racine du projet porte les règles communes à l’équipe, ~/.claude/CLAUDE.md contient les règles personnelles globales, et les CLAUDE.md des sous-dossiers gèrent les règles propres à chaque dossier
  • Claude fusionne et applique plusieurs fichiers CLAUDE.md
  • Le contenu recommandé inclut les commandes de build et de test, les grandes décisions d’architecture, les contraintes non intuitives, ainsi que les règles de nommage et de gestion des erreurs
  • Il est recommandé de le garder sous 200 lignes, car une longueur excessive réduit le taux de respect des consignes par Claude

• CLAUDE.local.md — surcharge personnelle

  • Fichier permettant de refléter des préférences individuelles en plus des règles communes à l’équipe
  • Si l’on crée CLAUDE.local.md à la racine du projet, Claude le lira également
  • Il est automatiquement inclus dans .gitignore et n’est pas commité dans le dépôt

• Dossier rules/ — gestion modulaire des règles

  • Lorsque CLAUDE.md devient trop volumineux, on peut le scinder et le gérer via le dossier .claude/rules/
  • Chaque fichier de règles est séparé par thème, ce qui facilite la maintenance
    • Ex. : code-style.md, testing.md, api-conventions.md, security.md
  • Le champ paths du front matter YAML permet de définir des règles appliquées uniquement à certains chemins
    • Ex. : appliquer les règles API uniquement au chemin src/api/**/*.ts
  • Les règles sans chemin défini sont toujours chargées dans toutes les sessions

• Dossier commands/ — commandes slash personnalisées

  • Chaque fichier Markdown du dossier .claude/commands/ est enregistré comme commande slash (/)
    • Ex. : review.md → /project:review, fix-issue.md → /project:fix-issue
  • La syntaxe avec backticks ! permet d’insérer dans le prompt Claude le résultat d’exécution d’une commande shell
    • Ex. : !git diff main...HEAD
  • La variable $ARGUMENTS permet de transmettre des arguments à l’exécution de la commande
    • Ex. : /project:fix-issue 234 → chargement automatique du contenu de l’issue GitHub 234
  • Les commandes de projet sont partagées avec l’équipe, tandis que les commandes personnelles sont stockées dans ~/.claude/commands/ et utilisables dans tous les projets

• Dossier skills/ — workflows à exécution automatique

  • Ils fonctionnent comme des workflows similaires aux commandes, mais déclenchés automatiquement
  • Claude analyse le contenu de la conversation et les exécute automatiquement dans les situations appropriées
  • Chaque skill est défini par un fichier SKILL.md dans un sous-dossier, avec des conditions de déclenchement et des outils autorisés spécifiés via le front matter YAML
    • Ex. : le skill security-review se lance automatiquement lors d’une conversation liée à la sécurité
  • Le dossier d’un skill peut contenir des documents auxiliaires ou des modèles, comme DETAILED_GUIDE.md
  • Les skills personnels sont stockés dans ~/.claude/skills/ et peuvent être utilisés globalement

• Dossier agents/ — sous-agents spécialisés

  • Le dossier .claude/agents/ définit des sous-agents (personas) remplissant des rôles spécifiques
  • Chaque agent dispose de son propre prompt système, modèle et droits d’accès aux outils
    • Ex. : code-reviewer.md, security-auditor.md
  • Le champ tools permet de limiter les outils accessibles afin d’assurer la sécurité et la séparation des rôles
  • Le champ model permet de choisir le modèle Claude adapté à la tâche (ex. : Haiku, Sonnet, Opus)
  • Si nécessaire, Claude exécute cet agent dans un contexte séparé et n’en rapporte qu’un résumé des résultats

• settings.json — permissions et configuration du projet

  • .claude/settings.json définit les autorisations d’exécution de commandes et la portée d’accès aux fichiers pour Claude
  • Le champ $schema prend en charge l’autocomplétion et la validation dans des outils comme VS Code
  • La liste allow définit les commandes automatiquement approuvées, tandis que la liste deny définit les commandes totalement bloquées
    • Ex. : autorisé — Bash(npm run *), Read, Write, Edit
    • bloqué — Bash(rm -rf *), Bash(curl *), lecture des fichiers .env
  • Les commandes qui ne figurent dans aucune liste demandent une confirmation de l’utilisateur avant exécution
  • Les modifications de permissions propres à chaque personne sont stockées dans .claude/settings.local.json et ne sont pas incluses dans Git

• Dossier ~/.claude/ — configuration globale et mémoire

  • ~/.claude/CLAUDE.md contient les instructions personnelles communes à tous les projets
  • ~/.claude/projects/ stocke l’historique des sessions par projet et la mémoire automatique
    • Claude y conserve les commandes apprises, les schémas récurrents et les enseignements structurels
    • Consultation et modification possibles via la commande /memory
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ servent de dépôt pour les commandes, skills et agents personnels globaux

• Exemple de structure complète

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Étapes de configuration initiale

  • Étape 1 : créer un CLAUDE.md de base avec la commande /init, puis ne garder que l’essentiel
  • Étape 2 : rédiger .claude/settings.json et définir les règles d’autorisation et de blocage d’exécution

  • Étape 3 :ajouter des commandes adaptées aux workflows fréquemment utilisés (ex. : revue de code, correction d’issue)

    • Étape 4 : si CLAUDE.md grossit, le scinder dans .claude/rules/
    • Étape 5 : ajouter des règles de préférence personnelle dans ~/.claude/CLAUDE.md

Points clés

• Le dossier .claude/ est un protocole qui transmet à Claude l’identité et les règles du projet
• CLAUDE.md est le fichier le plus important, et plus il est défini clairement, plus la productivité de Claude est maximisée
• Les autres composants forment une couche d’optimisation complémentaire, extensible progressivement
• Une configuration claire se traduit par moins de demandes de correction de la part de Claude et une collaboration plus efficace

Discussions complémentaires

• La liste deny de settings.json est sûre pour un usage humain, mais en mode agent, une protection supplémentaire peut être nécessaire en raison de l’accès Bash
• OneCLI fournit, au niveau réseau, une couche proxy qui remplace les jetons d’identification, afin d’éviter l’exposition d’informations sensibles
• Le besoin d’une future configuration .claude dédiée au mode agent (séparation des règles, permissions et skills) est évoqué
• D’après la documentation la plus récente, les commandes (commands) et les skills (skills) ont été unifiés : .claude/commands/deploy.md et .claude/skills/deploy/SKILL.md génèrent tous deux la commande /deploy, les skills apportant des fonctions supplémentaires (fichiers auxiliaires, déclenchement automatique, etc.)