Aller au contenu principal

Suprématie CLAUDE.md

Qu'est-ce que CLAUDE.md ?​

CLAUDE.md est le fichier de configuration central de Claude Code, situé dans le répertoire racine du projet. Il agit comme un manuel de projet pour Claude, définissant le contexte, les règles, conventions et attentes du projet.

Ce n'est pas juste un fichier de configuration, mais un pont pour la collaboration humain-IA.

Pourquoi CLAUDE.md est-il si important ?​

1. Le Contexte C'est le Pouvoir​

Les capacités de Claude Code dépendent largement de sa compréhension du projet. Un CLAUDE.md bien conçu peut :

  • 🧠 Construire la cognition du projet : Aider Claude à comprendre profondément les objectifs et la structure du projet
  • 🎯 Définir les standards de travail : Définir les exigences de qualité et style du code
  • ⚡ Améliorer l'efficacité d'exécution : Éviter les explications répétitives et les mauvaises directions
  • 🛡️ Assurer la cohérence : Les membres de l'équipe partagent le même ensemble de règles de collaboration

2. Du Chaos à l'Ordre​

Projet sans CLAUDE.md :

> Aidez-moi à refactoriser cette fonction

Claude : Que fait cette fonction ? Quel framework ? Des conventions ?
Vous : C'est un composant React, nous utilisons TypeScript...
Claude : Compris, d'autres règles ?
Vous : Nous utilisons des composants fonctionnels, pas de composants classe...
Claude : Compris, quel est le framework de test ?
Vous : Jest... (cycle sans fin)

Projet avec CLAUDE.md :

> Aidez-moi à refactoriser cette fonction

Claude : Compris, basé sur la configuration du projet, j'utiliserai des composants fonctionnels, des types TypeScript, suivrai vos conventions de nommage, et ajouterai les tests Jest correspondants. Début de la refactorisation...

Structure CLAUDE.md​

Modèle de Base​

# Nom du Projet

## Aperçu du Projet
[Description brève et objectifs principaux du projet]

## Stack Technique
- Frontend: React 18 + TypeScript
- Gestion d'État: Redux Toolkit
- Stylisation: Styled Components
- Tests: Jest + React Testing Library
- Build: Vite

## Structure du Projet

src/ ├── components/ # Composants réutilisables ├── pages/ # Composants de page ├── hooks/ # Hooks personnalisés ├── services/ # Services API ├── store/ # Store Redux ├── types/ # Types TypeScript ├── utils/ # Fonctions utilitaires └── styles/ # Fichiers de style


## Standards de Codage
- Utiliser composants fonctionnels + Hooks
- Tous les composants doivent avoir des types TypeScript
- Utiliser ESLint + Prettier pour le formatage
- Noms de composants utilisent PascalCase
- Noms de fichiers utilisent kebab-case
- Préférer les exports nommés

## Exigences de Tests
- Tous les composants doivent avoir des tests unitaires
- Exigence de couverture: >80%
- Nommage des fichiers de test: `*.test.tsx`

## Workflow Git
- Utiliser branche de fonctionnalité
- Format de message de commit: `type(scope): description`
- PR doit passer toutes les vérifications

## Notes Importantes
- Les appels API doivent avoir une gestion d'erreurs
- Les informations sensibles utilisent des variables d'environnement
- Les nouvelles fonctionnalités nécessitent des mises à jour de documentation

Conseils de Configuration Avancée​

1. Configuration Modulaire​

Pour les grands projets, la configuration peut être divisée en plusieurs parties :

# Mon Grande Application

## Informations Centrales
[Informations de base du projet]

## Architecture Decision Records (ADR)

### ADR-001: Choix de Gestion d'État
Nous avons choisi Redux Toolkit plutôt que Context API parce que :
- Logique d'état complexe
- Besoin de débogage time-travel
- Équipe familière avec l'écosystème Redux

### ADR-002: Design de la Couche API
Utilisation de RTK Query pour la récupération de données :
- Mise en cache et synchronisation automatiques
- États de chargement/erreur intégrés
- TypeScript first

## Workflow de Développement

### Processus de Développement de Nouvelle Fonctionnalité
1. Créer branche de fonctionnalité: `feature/nom-fonctionnalite`
2. Utiliser approche TDD: écrire les tests d'abord, puis implémenter
3. Assurer que TypeScript n'a pas d'erreurs
4. Exécuter suite complète de tests
5. Soumettre PR et demander révision de code

### Checklist de Révision de Code
- [ ] Types TypeScript sont corrects
- [ ] Tests couvrent la nouvelle fonctionnalité
- [ ] Gestion d'erreurs est complète
- [ ] Considérations de performance (memo, callback, etc.)
- [ ] Support d'accessibilité

2. Enrichissement du Contexte​

## Contexte Métier

### Utilisateurs Cibles
- Primaire: Professionnels de 25-40 ans
- Appareils: Mobile-first, support desktop
- Cas d'usage: Temps de trajet, pauses bureau

### Fonctionnalités Centrales
1. **Authentification Utilisateur**: OAuth2 + JWT
2. **Synchronisation de Données**: Sync temps réel, support hors ligne
3. **Système de Notifications**: Alertes push + email

### Exigences de Performance
- Chargement premier écran: <2 secondes
- Réponse d'interaction: <100ms
- Support 1000+ utilisateurs simultanés

3. Standards de Collaboration d'Équipe​

## Conventions d'Équipe

### Standards de Nommage
- **Composants**: `UserProfile.tsx`
- **Hooks**: `useUserData.ts`
- **Services**: `userService.ts`
- **Types**: `UserType.ts`

### Modèle de Gestion d'Erreurs
```typescript
// Gestion d'erreur unifiée pour les appels API
try {
  const data = await userService.getProfile();
  return { data, error: null };
} catch (error) {
  logger.error('Failed to get user profile', error);
  return { data: null, error: error.message };
}

Standards de Révision de Code​

  • Correction fonctionnelle ✅
  • Lisibilité du code ✅
  • Impact sur les performances ✅
  • Considérations de sécurité ✅

## Études de Cas du Monde Réel

### Cas 1: Échec de Refactorisation

**Problème**: Pas de configuration CLAUDE.md claire
```bash
> Refactoriser le module d'authentification utilisateur

# Confusion de Claude:
# - Quel schéma d'authentification utiliser ?
# - Quel est le style de code existant ?
# - Besoin de compatibilité ascendante ?
# - Quelles sont les exigences de test ?

Résultat: Direction de refactorisation ne correspondant pas aux exigences du projet, nécessité de plusieurs refontes.

Cas 2: Succès de Refactorisation​

Configuration: CLAUDE.md détaillé

## Configuration du Système d'Authentification
- Utiliser JWT + Refresh Token
- Support de plusieurs méthodes de connexion: email, OAuth tiers
- Gestion de session: stockage Redis
- Exigences de sécurité: support 2FA, application de politique de mot de passe

## Module d'Authentification Existant
- Le répertoire `src/auth/` contient tout le code lié à l'authentification
- `AuthContext` fournit l'état d'authentification global
- `authService` gère les appels API
- `authUtils` fournit les utilitaires d'authentification

Exécution:

> Refactoriser le module d'authentification utilisateur, améliorer la sécurité et ajouter le support 2FA

Résultat: Claude a compris précisément les exigences et complété une refactorisation de haute qualité en une fois.

Stratégie de Configuration Dynamique​

1. Amélioration Progressive​

Commencer simple, enrichir progressivement :

Semaine 1: Structure de base

# Nom du Projet
- React + TypeScript
- Utiliser composants fonctionnels

Mois 1: Spécifications détaillées

# Nom du Projet
[Stack technique détaillé, structure de fichiers, standards de codage]

Mois 3: Contexte profond

# Nom du Projet
[Incluant logique métier, décisions architecturales, conventions d'équipe]

2. Collaboration d'Équipe​

  • 📝 Contrôle de Version: Inclure CLAUDE.md dans la gestion Git
  • 🔄 Mises à Jour Régulières: Mettre à jour synchroniquement avec le développement du projet
  • 👥 Consensus d'Équipe: Assurer que tous les membres comprennent et suivent
  • 🔍 Révision Régulière: Vérifier l'efficacité et précision de la configuration

Résumé des Bonnes Pratiques​

✅ Choses à Bien Faire​

  1. Être Spécifique et Clair: Éviter les descriptions vagues
  2. Maintenir à Jour: Mettre à jour la configuration à mesure que le projet évolue
  3. Inclure des Exemples: Fournir des exemples de code et motifs
  4. Documenter les Décisions: Enregistrer les choix architecturaux et techniques importants
  5. Cohérence d'Équipe: Assurer que les membres de l'équipe partagent la configuration

❌ Pièges à Éviter​

  1. Trop Détaillé: Ne pas écrire un roman, garder concis et pratique
  2. Informations Obsolètes: Nettoyer régulièrement les informations inutiles ou incorrectes
  3. Préférences Personnelles: Éviter les configurations trop personnalisées
  4. Ignorer le Métier: La configuration technique doit s'aligner avec les besoins métier
  5. Pensée Statique: La configuration doit s'adapter aux changements du projet

Après avoir maîtrisé l'essence de CLAUDE.md, vous pouvez continuer à apprendre le Mode Plan pour comprendre comment gérer les tâches complexes multi-étapes.