# CLAUDE.md — Contexte et mémoire du projet {{PROJECT_NAME}} Ce fichier sert de **mémoire active du projet**. Ce projet hérite des règles globales définies dans **Lead_tech**. Dans l’environnement de travail, `Lead_tech` est généralement accessible via **un symlink local** pointant vers le repository contenant les règles globales. Pour les agents, la porte d’entrée de ces règles est : - `~/CLAUDE.md` : symlink vers `~/Lead_tech/CLAUDE.md` - `~/AGENTS.md` : symlink vers `~/Lead_tech/CLAUDE.md` Ce fichier sert de **point d’entrée vers la base de connaissance globale** (patterns, anti-patterns, décisions d’architecture, debug). Les règles définies dans ce fichier **complètent** ces règles globales. Ce mécanisme permet au projet de rester portable entre environnements (Mac, NUC, serveur, etc.) tout en conservant un socle de règles global partagé. Hiérarchie des règles : 1. contraintes réelles du code et de l’infrastructure 2. règles définies dans ce fichier (projet) 3. règles globales `Lead_tech` Ce fichier doit permettre à un agent (Claude, Codex, etc.) de comprendre rapidement : - la stack - les conventions importantes - les patterns appliqués - l’état actuel du projet - les pièges connus --- # Contexte du projet Nom : Objectif : Statut : (exploration / MVP / production / maintenance) Description rapide du produit ou du service. --- # Stack technique - backend : - frontend : - base de données : - cache : - infra : - tests : Préciser les frameworks et versions importantes. Exemple : - NestJS strict - Next.js / Expo - PostgreSQL - Prisma --- # Architecture du projet Structure principale du repo. Exemple : ``` apps/ api/ web/ packages/ contracts/ infra/ ``` Règles importantes : - responsabilités de chaque dossier - ce qui doit rester partagé - ce qui doit rester local à une app --- # Cartographie rapide du code Objectif : permettre à un agent de comprendre **où se trouvent les responsabilités principales du projet** sans scanner tout le repository. Exemple : Backend principal → `apps/api` Frontend web → `apps/web` Contrats partagés (types / schémas / validation) → `packages/contracts` Infrastructure / Docker / déploiement → `infra` Tests → `apps/api/tests` Principes : - la logique métier doit rester côté backend - les contrats doivent être centralisés - éviter la duplication de logique entre apps Adapter cette cartographie à la structure réelle du projet. --- # Commandes du projet Lister ici les commandes principales permettant de travailler sur le projet. Objectif : permettre à un agent ou à un développeur de comprendre rapidement comment installer, lancer et tester l’application. Exemple : Installation : ``` npm install ``` Lancer le backend : ``` npm run dev:api ``` Lancer le frontend : ``` npm run dev:web ``` Tests : ``` npm run test ``` Build : ``` npm run build ``` Ajouter également si nécessaire : - commandes de migration de base de données - commandes de seed - commandes Docker - commandes d’environnement local --- # Patterns critiques du projet Lister ici les patterns **spécifiques à ce projet**. Ils complètent les patterns globaux définis dans `Lead_tech`. Exemples : - contracts-first - architecture hexagonale - structure des modules - conventions d’erreurs API Chaque pattern doit expliquer **pourquoi il existe**. --- # Conventions spécifiques Conventions propres au projet. Exemples : - gestion des erreurs - nommage des modules - structure des services - conventions Prisma / ORM --- # Statut du projet Décrire l’état actuel du développement. Exemple : Epic / milestone en cours : - Epic 1 : done - Epic 2 : in-progress Ou bien : - MVP en production - refactor backend en cours --- # Leçons apprises Capitaliser ici les apprentissages importants du projet. Exemples : - décisions d’architecture validées - erreurs rencontrées - améliorations à appliquer sur les prochaines features --- # Dette technique Lister la dette technique identifiée. Format conseillé : - description - niveau (LOW / MEDIUM / HIGH) Exemple : - tests E2E incomplets (MEDIUM) - refactor service auth nécessaire (LOW) --- # Points sensibles Parties du projet nécessitant une vigilance particulière. Exemples : - sécurité - authentification - logique financière - migrations de base de données --- # Références Voir également : - règles globales : `Lead_tech/CLAUDE.md` - patterns backend - patterns frontend - debug et post-mortems --- # Mise à jour Ce fichier doit être mis à jour lorsque : - une décision d’architecture importante est prise - un pattern spécifique apparaît - une dette technique significative est identifiée Si une information devient **utile à plusieurs projets**, la remonter dans Lead_tech via la procédure de capitalisation décrite ci-dessous. --- # Capitalisation vers Lead_tech ## Zone de dépôt Toute proposition doit être écrite dans : ``` $LEADTECH/95_a_capitaliser.md ``` `$LEADTECH` est résolu automatiquement par le shell sur Mac et sur le NUC. En pratique : - Mac : `~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md` - NUC : `/srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md` ## Quand capitaliser - résolution d'un bug difficile - pattern réutilisable identifié - anti-pattern rencontré - décision d'architecture structurante ## Format ``` DATE — PROJET FILE_UPDATE_PROPOSAL Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_product_patterns_valides.md | 10_n8n_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 10_n8n_nodes_a_risques.md | 10_conventions_redaction.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> Pourquoi : Proposition : ``` ## Règle Les agents écrivent dans `95_a_capitaliser.md` uniquement. Jamais directement dans les fichiers de connaissance validée. La validation et l'intégration sont faites par le développeur.