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.)

[GN⁺]

Commentaires sur Hacker News

• Construire une boîte à outils d’agents IA donne l’impression de chercher la configuration de productivité parfaite
  On se crée des routines en regardant des billets de blog et des vidéos YouTube, mais au final, ceux qui avancent le plus sont souvent ceux qui travaillent régulièrement avec une simple to-do list
  D’après mon expérience, l’approche la plus simple reste la plus efficace : demander à Plain Claude de planifier, de relire, puis d’exécuter

  • Sur de grandes bases de code ou des systèmes distribués, c’est une autre histoire
    Les compétences techniques d’un agent — faire circuler des données, créer des requêtes, suivre le système et mettre à jour le code — augmentent énormément l’efficacité du développement
    Sur une base de code de 10 millions de lignes, j’ai observé un gain de productivité majeur, alors que la génération effective de code représente moins de 5 % du travail
    L’essentiel vient de la capacité à construire rapidement une toolchain pour les tests et la validation
  • Beaucoup de gens tombent dans ce piège et dépensent de l’argent pour ça
    En réalité, si l’on sait clairement ce que l’on veut et comment bien le formuler, on peut déjà accomplir énormément avec l’IA
    La plupart ne le savent pas. C’est pourquoi le fait de lui faire élaborer un plan devient un raccourci vers la compréhension
  • En tant que PM, j’aimerais que les agents me fassent gagner du temps et produisent un effet cumulatif sur la production (compounding)
    Mais il y a cette inefficacité qui consiste à répéter le contexte à chaque session et à copier des fichiers .md
    Mon objectif actuel est donc d’éliminer cette répétition.
    Je me demande comment les autres gèrent une « context bank » qui accumule le contexte — par exemple « mon rôle, le produit dont je suis responsable, la documentation la plus récente »
    Il y a trop de documents dupliqués et obsolètes pour simplement connecter tout Drive
    Si un même contexte revient plus de deux fois, je me demande s’il faut créer un fichier Skill, ou bien rassembler les documents dans un seul dossier
  • J’ai eu une expérience similaire. La plupart des artefacts produits en cours de travail finissent à la poubelle
    La sur-configuration (over-configuration) dégrade la qualité et provoque des problèmes de boucle
    Comme les modèles s’améliorent constamment, des consignes autrefois nécessaires peuvent aujourd’hui nuire aux performances
    J’ai aussi entendu dire que l’équipe Anthropic réinitialisait claude.md tous les 30 jours
  • À l’inverse, je travaille sur un projet qui doit intégrer une API comptable locale, totalement custom, que le LLM ne connaît pas
    J’ai donc demandé à Claude de créer un serveur MCP, et maintenant il automatise les tâches comptables
    Après la clôture de fin de mois, j’ai demandé à Claude d’extraire les tâches principales pour en faire des Skills, et il fonctionne presque comme un comptable junior
    Les MCP custom et les Skills me paraissent vraiment très utiles

• Beaucoup ont l’impression de devoir construire un énorme mur de configuration avant même de commencer l’agentic coding
  Pourtant, au départ, le mieux est de commencer avec un .claude vide et un AGENTS.md pour apprendre à le manipuler soi-même

  • Pour ma part, je pense qu’il faut n’utiliser que des skills créés par soi-même
    Installer en masse des skills conçus par d’autres augmente la non-détermination (nondeterminism) et gaspille aussi la fenêtre de contexte
    À la rigueur, playwright-cli est la seule installation externe que je recommanderais
  • Dans les grandes équipes, il faut des garde-fous (rules) cohérents
    Par exemple, en configurant la vérification de préconditions comme dans cette règle, on gagne en stabilité
    J’imagine que les équipes sécurité préfèreraient aussi ce type d’approche
    Moi aussi, en définissant des règles, j’ai empêché Claude de faire des commits sans signature GPG
    Mais ces règles ne doivent pas être figées : elles doivent évoluer en continu
  • Cet article ne cherche pas à imposer une configuration gigantesque
    Au contraire, il insiste sans cesse sur le fait de commencer petit et rester concis
    Même un débutant, en ajoutant seulement quelques lignes dans AGENTS.md, peut aider l’IA à mieux comprendre son intention
    Une configuration simple réduit fortement les dysfonctionnements de l’IA
  • Gérer du code seul et gérer un projet partagé en équipe, ce n’est absolument pas la même chose
    Dès que chaque développeur utilise des outils agentiques, la manière même de collaborer change
  • Rien qu’en utilisant le mode plan, on résout déjà 90 % du problème
    Avec l’évolution des modèles, j’ai l’impression que la plupart de ces discussions complexes sur la configuration auront disparu d’ici un an

• Le dossier ~/.claude/projects est la partie vraiment intéressante

• J’ai obtenu de meilleurs résultats avec le moins de configuration inutile possible
  Les gens sur-spécifient la documentation, mais une IA ressemble à un adulte compétent mais nerveux
  Si on lui donne trop d’instructions, elle devient au contraire plus bête

• Cet article donne l’impression d’avoir été généré plutôt que de venir d’une vraie expérience
  Mieux vaut garder Claude.md court, avec seulement quelques liens
  Quand le contexte s’accumule, les performances baissent ; il faut donc séparer planification et implémentation et réinitialiser à chaque fois

  • L’introduction ressemble tellement au style de Claude que je me suis dit que je pourrais tout aussi bien lui demander directement
  • La différence entre skills et commandes n’est pas très claire
    Est-ce que les skills sont toujours dans le contexte, tandis que les commandes ne peuvent être invoquées que manuellement ? Ce n’est pas évident

• J’aimerais que tous les fournisseurs de modèles partagent un ensemble standard de fichiers
  Cela faciliterait le passage entre Claude, Codex, Cursor et Opencode

  • Mais la combinaison du modèle et du harness a un impact énorme sur le résultat
    Un même prompt peut produire des réactions différentes selon le modèle, donc le prompt tuning doit aussi varier d’un modèle à l’autre
  • Il suffit de créer un agents.md unique, puis de le faire référencer par Claude.md et de relier les dossiers par symlink (sync)
    Ce n’est pas parfait, mais ça fonctionne plutôt bien
  • En ce moment, on est comme au début de l’ère des navigateurs. L’absence de standardisation a justement permis des innovations comme AJAX
    Donc cette diversité actuelle me semble au contraire positive
  • Pour l’instant, j’utilise dotagents by Sentry comme solution temporaire à ce problème
  • Je ne pense pas que les fournisseurs de modèles aient un quelconque intérêt à rendre le changement de plateforme plus facile

• Le document alternatif de Claude Fast est très utile
  Je ne vois pas pourquoi on détesterait la définition du dossier .claude
  On peut faire écrire les fichiers directement par l’agent principal, les mettre à jour en boucle et construire un système auto-améliorant
  Aujourd’hui, .claude se réplique, s’évalue et se met à jour tout seul — au fond, je ne code pas du code, je code .claude

  • Pour résumer, CLAUDE.md n’est pas un simple document, c’est le système d’exploitation de Claude
    Il définit son comportement, délègue le savoir à des skills et permet de construire un système qui s’améliore de lui-même avec le temps

• Un obstacle que beaucoup ne voient pas, c’est que même si l’on fait modifier un fichier par Claude, si on ne lui dit pas explicitement de le relire, la modification n’est pas prise en compte
  Par exemple, si CLAUDE.md a été réécrit, il faut le recharger pour que Claude le reconnaisse comme une nouvelle consigne

• Le dossier ~/.claude/plans contient les fichiers de plan générés lors de l’exécution du mode plan
  J’ouvre souvent ce répertoire pour faire des sauvegardes ou m’en servir comme référence

• J’organise ma configuration autour de serveurs MCP globaux et d’agents composites (composite agents)
  Chaque serveur MCP définit un ensemble d’outils, et les agents y travaillent de manière autonome
  .agent.md n’est qu’un document décrivant les outils disponibles ; une configuration complexe est inutile
  Je trouve que les skills et les prompts réutilisables ont peu de valeur
  Les modèles sont déjà suffisamment intelligents ; ce qu’il faut, c’est surtout une orientation