Comprendre la structure du dossier .claude/ pour la configuration de Claude Code

Dossiers de configuration projet et global

Il existe deux répertoires .claude : un à la racine de votre projet pour la configuration d'équipe qui est versionnée dans git, et un autre dans votre répertoire personnel (~/.claude/) pour les préférences personnelles et les états locaux à la machine comme l'historique des sessions.

CLAUDE.md : Le manuel d'instructions

CLAUDE.md est chargé dans l'invite système de Claude au début de chaque session et suivi tout au long de la conversation. Vous pouvez avoir CLAUDE.md à la racine du projet, dans ~/.claude/ pour les préférences globales, ou dans des sous-répertoires pour des règles spécifiques aux dossiers.

Un contenu efficace de CLAUDE.md comprend :

• Commandes de construction, test et lint (npm run test, make build, etc.)
• Décisions architecturales clés
• Pièges non évidents
• Conventions d'importation, modèles de nommage, styles de gestion d'erreurs
• Structure des fichiers et dossiers pour les modules principaux

Gardez CLAUDE.md sous 200 lignes. Les fichiers plus longs commencent à consommer trop de contexte et l'adhésion de Claude aux instructions diminue.

Exemple de structure CLAUDE.md

# Projet : API Acme

Commandes
npm run dev # Démarrer le serveur de développement
npm run test # Exécuter les tests (Jest)
npm run lint # Vérification ESLint + Prettier
npm run build # Construction pour la production

Architecture

• API REST Express, Node 20
• PostgreSQL via l'ORM Prisma
• Tous les gestionnaires se trouvent dans src/handlers/
• Types partagés dans src/types/

Conventions

• Utilisez zod pour la validation des requêtes dans chaque gestionnaire
• La forme de retour est toujours { data, error }
• N'exposez jamais les traces de pile au client
• Utilisez le module logger, pas console.log

Attention à

• Les tests utilisent une vraie base de données locale, pas des mocks. Exécutez d'abord npm run db:test:reset
• TypeScript strict : aucune importation inutilisée, jamais

  Modifications personnelles avec CLAUDE.local.md

  Créez CLAUDE.local.md à la racine de votre projet pour les préférences personnelles qui ne s'appliquent pas à toute l'équipe. Claude le lit parallèlement au CLAUDE.md principal, et il est automatiquement ignoré par git pour que les ajustements personnels n'atterrissent jamais dans le dépôt.

  Instructions modulaires avec le dossier rules/

  Pour les équipes plus importantes, le dossier rules/ fournit des instructions modulaires qui évoluent mieux qu'un seul gros fichier CLAUDE.md.

  📖 Lire la source complète : HN AI Agents