# 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/helpers/_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_risques_et_vigilance.md | 10_conventions_redaction.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md>

Pourquoi :
<raison en 1-2 phrases>

Proposition :
<contenu suggéré>
```

## 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.
