Dossier .claude/ : Structure et Configuration 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