Guide de Configuration du Fichier CLAUDE.md

# Nom du Projet

## Aperçu du Projet

[Brève description de l'objectif du projet, des fonctions principales et des utilisateurs cibles]

## Stack Technologique

- Frontend : [Framework et bibliothèques principales]
- Backend : [Langage et framework]
- Base de données : [Type de base de données]
- Déploiement : [Plateforme de déploiement]

## Structure du Projet

\```
project/
├── src/ # Code source
├── tests/ # Fichiers de test
├── docs/ # Documentation
└── scripts/ # Fichiers de script
\```

## Normes de Développement

[Normes de codage spécifiques au projet]

## Notes

[Notes et restrictions spécifiques au projet]

# CLAUDE.md - Fichier de Configuration de Projet

## Règles Générales (obligatoires pour tous les projets)

### Langue de Communication

- Toujours utiliser le chinois simplifié pour penser et dialoguer
- Commentaires de code en anglais, documentation en chinois

### Gestion de Documents

- Documentation officielle dans le répertoire `docs/`
- Propositions de discussion dans le répertoire `discuss/`
- Garder README concis, documentation détaillée séparée

## Normes d'Architecture de Code

### Limites de Taille de Fichier

- Python/JavaScript/TypeScript : chaque fichier pas plus de 300 lignes
- Java/Go/Rust : chaque fichier pas plus de 400 lignes
- Pas plus de 8 fichiers par dossier
- Si dépassement, refactorisation ou division nécessaire

### Indicateurs de Qualité de Code

Éviter les code smells suivants :

1. **Rigidité** : Système difficile à changer
2. **Redondance** : Trop de code dupliqué
3. **Dépendances Circulaires** : Modules interdépendants
4. **Fragilité** : Changements causent des problèmes en chaîne
5. **Obscurité** : Intention du code pas claire
6. **Data Clumps** : Éléments de données apparaissent toujours ensemble
7. **Sur-conception** : Complexité inutile

## Contraintes de Stack Technologique

### Stack Technologique Frontend

- React 19+ (ne pas utiliser version 18 ou inférieure)
- Next.js 15.4+ (ne pas utiliser version 14 ou inférieure)
- Tailwind CSS v4 (ne pas utiliser v3)
- Préférer TypeScript, éviter JavaScript
- Interdire CommonJS, utiliser uniquement ES Modules

### Stack Technologique Backend

- Node.js 18+
- Utiliser TypeScript
- Express/Fastify comme framework web
- Prisma comme ORM

### Projets Python

- Utiliser uv pour gestion des dépendances (pas pip/poetry/conda)
- Nom de répertoire d'environnement virtuel : `.venv`
- Typage fort, éviter utilisation de dict
- Garder répertoire racine du projet propre

## Flux de Travail de Développement

### Gestion des Scripts

- Tous les scripts dans le répertoire `scripts/`
- Utiliser scripts `.sh` pour opérations de démarrage-arrêt
- Pas de commandes npm/pnpm/python directes
- Les échecs de script doivent être corrigés immédiatement

### Gestion des Logs

- Fichiers de configuration génèrent des logs
- Sortie unifiée vers le répertoire `logs/`
- Inclure horodatage et niveau de log
- Stocker logs d'erreur séparément

### Exigences de Tests

- Couverture de tests unitaires > 80%
- Fonctions critiques doivent avoir des tests d'intégration
- Fichiers de test dans le répertoire `tests/`
- Utiliser CI/CD pour exécuter tests automatiquement

## Conventions de Nommage

### Noms de Fichier

- Composants : PascalCase (ex. UserProfile.tsx)
- Fonctions utilitaires : camelCase (ex. formatDate.ts)
- Fichiers de constantes : UPPER_SNAKE_CASE (ex. API_CONSTANTS.ts)
- Fichiers de style : kebab-case (ex. user-profile.css)

### Noms de Variables

- Variables/Fonctions : camelCase
- Constantes : UPPER_SNAKE_CASE
- Classes/Interfaces : PascalCase
- Propriétés privées : \_camelCase

## Flux de Travail Git

### Stratégie de Branching

- main : Code de production
- develop : Code de développement
- feature/\* : Branches de fonctionnalités
- hotfix/\* : Branches de correction d'urgence

### Conventions de Commit

- feat : Nouvelle fonctionnalité
- fix : Correction de bug
- docs : Mise à jour de documentation
- style : Formatage de code
- refactor : Refactorisation de code
- test : Lié aux tests
- chore : Changements de build/outils

## Normes de Conception d'API

### Principes RESTful

- GET : Obtenir ressource
- POST : Créer ressource
- PUT : Mettre à jour ressource (complète)
- PATCH : Mettre à jour ressource (partielle)
- DELETE : Supprimer ressource

### Format de Réponse

\```json
{
"success": true,
"data": {},
"message": "Opération réussie",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Gestion des Erreurs

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Description de l'erreur",
"details": {}
}
}
\```

## Normes de Sécurité

### Informations Sensibles

- Ne pas coder en dur les clés dans le code
- Utiliser variables d'environnement pour gestion de configuration
- Ne pas committer fichier `.env` dans Git
- Mettre à jour régulièrement les dépendances

### Validation de Données

- Validation de données frontend et backend
- Utiliser bibliothèques de validation de schéma (ex. zod)
- Paramétrer requêtes SQL
- Prévenir attaques XSS et CSRF

## Optimisation de Performance

### Optimisation Frontend

- Lazy loading pour images
- Code splitting
- Stratégie de cache
- Scroll virtuel (grandes listes)

### Optimisation Backend

- Optimisation de requêtes de base de données
- Utiliser cache (Redis)
- Compression de réponses API
- Contrôle de concurrence

## Configuration de Déploiement

### Variables d'Environnement

- development : Environnement de développement
- staging : Environnement de test
- production : Environnement de production

### Containerisation

- Utiliser Docker pour déploiement
- Builds multi-étapes pour optimiser taille d'image
- Utiliser docker-compose pour orchestration de services

## Surveillance et Logs

### Métriques de Surveillance

- Temps de réponse API
- Taux d'erreur
- Utilisation des ressources
- Analyse du comportement utilisateur

### Niveaux de Log

- ERROR : Informations d'erreur
- WARN : Informations d'avertissement
- INFO : Informations générales
- DEBUG : Informations de débogage

## Notes Spéciales

⚠️ **Rappels Importants** :

1. Aborder immédiatement les problèmes de code
2. Poser activement des questions à l'utilisateur en cas d'incertitude
3. Maintenir code propre et maintenable
4. Respecter normes établies du projet

## Normes de Projet React/Next.js

### Normes de Composants

- Utiliser composants fonctionnels + Hooks
- Fichier de composant avec même nom que composant
- Un fichier, un composant
- Props définies avec interfaces TypeScript

### Gestion d'État

- État simple : useState
- État complexe : useReducer
- État global : Context API / Zustand
- État serveur : TanStack Query

### Solution de Styles

- Tailwind CSS v4 comme principal
- CSS Modules en complément
- Éviter styles inline
- Prioriser design responsive

### Optimisation de Performance

- Utiliser React.memo pour éviter rendu inutile
- useMemo/useCallback pour optimisation de calculs
- Importations dynamiques pour code splitting
- Utiliser composant next/image pour images

## Normes de Projet Python

### Structure du Projet

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Gestion des Dépendances

- Utiliser uv pour toutes les dépendances
- pyproject.toml pour définir configuration du projet
- requirements.txt pour déploiement de production
- requirements-dev.txt pour dépendances de développement

### Annotations de Type

- Toutes les fonctions doivent avoir des annotations de type
- Utiliser dataclass pour définir structures de données
- Combiner avec mypy pour vérification de types
- Éviter utilisation du type Any

### Programmation Asynchrone

- Prioriser async/await
- Utiliser asyncio pour gestion de concurrence
- Utiliser drivers asynchrones pour opérations de base de données
- Utiliser httpx pour requêtes HTTP

## Normes d'Architecture de Microservices

### Division des Services

- Diviser services par domaine métier
- Chaque service se déploie indépendamment
- Communication inter-services via API
- Code partagé via gestion de paquets

### API Gateway

- Gestion d'entrée unifiée
- Authentification et autorisation
- Limitation de débit et circuit breaking
- Routage de requêtes

### Communication de Services

- HTTP/REST : Appels synchrones
- Files de messages : Communication asynchrone
- gRPC : Scénarios haute performance
- WebSocket : Communication en temps réel

### Gestion de Données

- Chaque service a sa propre base de données
- Éviter transactions inter-services
- Utiliser event-driven pour maintenir cohérence
- Implémenter opérations idempotentes

> /init