# Lead_tech

![Licence CC BY 4.0](https://img.shields.io/badge/licence-CC_BY_4.0-green)
![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blue)
![Codex](https://img.shields.io/badge/Codex-compatible-blue)
![Shell](https://img.shields.io/badge/shell-bash-lightgrey)
![macOS](https://img.shields.io/badge/macOS-compatible-black)
![Linux](https://img.shields.io/badge/Linux-compatible-yellow)
![BMAD](https://img.shields.io/badge/BMAD-intégré-purple)

> **Cerveau externe inter-projets pour développeurs.**
> Une base de connaissance technique validée, couplée à un assistant IA (Claude Code, Codex) et réutilisée à travers tous vos projets.

---

## Principe fondamental

> Si quelque chose a coûté du temps une fois, ça mérite d'être documenté pour ne jamais le reperdre.

Lead_tech est un dépôt de **mémoire technique partagée** : patterns validés, risques identifiés, décisions d'architecture, post-mortems, playbooks opérationnels. Pas du code — de la doctrine.

Il est conçu pour fonctionner en tandem avec un copilote IA qui le consulte avant de vous répondre, vous évitant de répéter les mêmes erreurs et de re-expliquer votre contexte à chaque session.

---

## Comment ça marche — le modèle mental

### Vue d'ensemble

```
Lead_tech (ce repo)
    │
    ├── _AI_INSTRUCTIONS.md  ──► ~/.claude/CLAUDE.md  ← chargé automatiquement par Claude Code
    │                        ──► ~/.codex/AGENTS.md   ← idem pour Codex (symlink)
    │
    ├── knowledge/           ← consulté par le copilote avant chaque réponse
    ├── skills/              ──► ~/.claude/skills/     ← skills disponibles dans Claude Code
    │
    └── scripts/sync-ai-instructions.sh  ← publie tout ça en une commande
```

### 1. Le mécanisme de chargement de Claude Code (et Codex)

Claude Code charge automatiquement à chaque session le fichier `~/.claude/CLAUDE.md`.
C'est là que vivent les **instructions globales** : comment le copilote doit se comporter, quels fichiers consulter, quelle posture adopter.

Ce fichier ne vit **pas** dans `~/.claude/` à la main — il est **généré** depuis `_AI_INSTRUCTIONS.md` (la source de vérité dans ce repo) par le script `sync-ai-instructions.sh`. Ainsi :

- vous éditez `_AI_INSTRUCTIONS.md` dans Lead_tech
- vous lancez `sync-ai-instructions.sh`
- `~/.claude/CLAUDE.md` est mis à jour sur la machine
- Codex reçoit les mêmes instructions via un symlink `~/.codex/AGENTS.md → ~/.claude/CLAUDE.md`

Le fichier `_AI_INSTRUCTIONS.md` contient un placeholder `{{LEADTECH}}` qui est résolu au moment de la génération — ainsi les chemins absolus sont corrects sur chaque machine.

**Résultat** : le copilote sait, dès l'ouverture d'une session, où est Lead_tech, comment le consulter, et quels patterns appliquer systématiquement.

### 2. Les instructions au niveau projet

En plus des instructions globales, chaque projet peut avoir son propre `CLAUDE.md` à la racine.
Ce fichier est généré depuis un template (`70_templates/projet_CLAUDE.md`) via `generate_project_claude.sh`.

Il contient les règles **spécifiques au projet** : stack, conventions locales, contexte métier.

Un symlink `AGENTS.md → CLAUDE.md` est automatiquement créé pour la compatibilité Codex.

**Hiérarchie de contexte** (du plus prioritaire au moins prioritaire) :

```
1. Contraintes techniques réelles (ce qui compile, ce qui marche)
2. CLAUDE.md du projet  (règles spécifiques au projet)
3. ~/.claude/CLAUDE.md  (règles globales Lead_tech)
```

### 3. La base de connaissance est consultée à la demande

`_AI_INSTRUCTIONS.md` donne au copilote une procédure explicite :

> Avant de proposer une solution dans un domaine donné, lire le `README.md` du sous-dossier `patterns/` ou `risques/` correspondant, puis lire les fichiers pertinents.

Le copilote ne charge pas tout Lead_tech d'un coup — il navigue dedans selon le contexte de la question, comme un développeur qui ouvre ses notes avant de coder.

### 4. BMAD — et comment Lead_tech s'y articule

[BMAD](https://github.com/BMad-Dev/bmad-agent) est une méthode de travail basée sur des **agents spécialisés** : un agent qui cadre, un qui implémente, un qui review, etc. Chaque agent travaille sur une *story* (fichier Markdown) qui fait office de source de vérité partagée entre sessions.

**L'adaptation ici** : Lead_tech ne remplace pas BMAD, il s'y articule en amont et en aval.

```
Lead_tech (doctrine globale)
    ↓ lecture obligatoire avant implémentation
Agent BMAD (implémente une story)
    ↓ apprentissage détecté
95_a_capitaliser.md (staging)
    ↓ validation humaine
Lead_tech (fichier approprié)
```

- **En amont** : avant d'implémenter quoi que ce soit, l'agent lit les patterns Lead_tech qui couvrent le domaine. S'il existe un pattern validé, il l'applique directement sans réinventer.
- **En aval** : si l'implémentation révèle un nouveau pattern ou un anti-pattern, l'agent propose une entrée dans `95_a_capitaliser.md`. Il n'écrit **jamais** directement dans `knowledge/` — c'est une règle stricte. La validation reste humaine.

Cette séparation est intentionnelle : les agents peuvent apprendre vite et proposer beaucoup — mais seul le développeur valide ce qui entre dans la doctrine.

### 5. La capitalisation contrôlée

`95_a_capitaliser.md` est un **buffer de staging**. Tout apprentissage y atterrit d'abord, sous ce format :

```
DATE — mon-projet

FILE_UPDATE_PROPOSAL
Fichier cible : knowledge/backend/patterns/nestjs.md

Pourquoi :
L'ordre d'enregistrement des guards NestJS a causé request.user undefined
dans EmailVerifiedGuard.

Proposition :
Toujours enregistrer AuthGuard en premier dans providers[] avant tout guard
qui lit request.user.
```

Un skill dédié (`capitalisation-triage`) assiste ensuite la validation : il analyse le buffer, détecte les doublons, et aide à décider si le contenu va dans Lead_tech global ou dans le `CLAUDE.md` du projet source.

---

## Ce que contient ce dépôt

```
Lead_tech/
├── knowledge/              # Base de connaissance par domaine
│   ├── backend/            # patterns/ et risques/ : auth, contracts, prisma, stripe, nestjs…
│   ├── frontend/           # patterns/ et risques/ : state, forms, navigation, design-tokens…
│   ├── ux/                 # patterns/ et risques/ UX/UI
│   ├── n8n/                # patterns/ et risques/ automatisations
│   ├── product/            # patterns/ et risques/ produit
│   └── workflow/           # risques/ workflow agent (BMAD, LLM parallèle)
├── 60_playbooks/           # Procédures opérationnelles réutilisables
├── 70_templates/           # Modèles de fichiers (CLAUDE.md projet, patches knowledge…)
├── 80_bmad/                # Documentation de l'articulation BMAD ↔ Lead_tech
├── scripts/                # Automatisations (sync IA, bootstrap projet, secrets…)
├── skills/                 # Skills custom pour Claude Code / Codex
├── 10_conventions_redaction.md   # Conventions de documentation technique
├── 40_decisions_et_archi.md      # Décisions techniques (mini-ADR)
├── 50_idees_en_vrac.md           # Zone de réflexion non filtrée
├── 90_debug_et_postmortem.md     # Historique de bugs capitalisés
├── 95_a_capitaliser.md           # Buffer de capitalisation (staging)
├── _AI_INSTRUCTIONS.md           # Source des instructions copilote IA
└── _projects.conf                # Registre de vos projets actifs
```

---

## Pour qui ?

- **Devs solos** qui veulent capitaliser leur expérience et ne plus debugger deux fois le même problème
- **Tech leads** qui veulent maintenir une doctrine technique cohérente sur plusieurs projets
- **Équipes** qui veulent un référentiel partagé évolutif et validé par le terrain

---

## Prérequis

- [Claude Code](https://claude.ai/code) installé (et/ou Codex)
- `bash` (macOS / Linux)
- `git`

---

## Installation

### 1. Forker et cloner

```bash
# Forker ce dépôt sur GitHub, puis :
git clone https://github.com/<vous>/Lead_tech.git ~/AI_RULES/_Assistant_Lead_Tech
```

### 2. Charger les alias shell

Les alias Lead_tech définissent la variable `$LEADTECH` et exposent des raccourcis pour tous les scripts. Ajoutez cette ligne dans votre `~/.zshrc` ou `~/.bashrc` :

```bash
source "$HOME/AI_RULES/_Assistant_Lead_Tech/scripts/aliases.sh"
```

Rechargez votre shell :

```bash
source ~/.zshrc   # ou ~/.bashrc
```

`$LEADTECH` est maintenant défini, et les alias sont disponibles :

| Alias | Effet |
|-------|-------|
| `leadtech` | `cd` vers le repo Lead_tech |
| `sync-ai` | Synchronise les instructions vers Claude / Codex |
| `gen-claude` | Génère le `CLAUDE.md` du projet courant |
| `mkproj` | Crée un nouveau projet complet |
| `bmad-init` | Initialise la structure BMAD dans un projet existant |
| `loadg` | Charge les secrets globaux (Bitwarden → env) |
| `sync-project` | Sync les secrets du projet courant (Bitwarden → `.env`) |
| `sync-service` | Sync les secrets d'un service (Bitwarden → `service.env`) |

> **Note sur les chemins** : `aliases.sh` détecte automatiquement l'OS. Sur macOS, `$LEADTECH` pointe vers `~/AI_RULES/_Assistant_Lead_Tech`. Sur Linux, vers `/srv/helpers/_Assistant_Lead_Tech`. Adaptez ces valeurs à votre structure si nécessaire.

### 3. Synchroniser les instructions vers Claude / Codex

```bash
sync-ai
# ou sans alias :
bash "$LEADTECH/scripts/sync-ai-instructions.sh"
```

Ce script :
- Génère `~/.claude/CLAUDE.md` depuis `_AI_INSTRUCTIONS.md` (résout `{{LEADTECH}}` avec le chemin réel)
- Crée `~/.codex/AGENTS.md` comme symlink vers `~/.claude/CLAUDE.md`
- Publie chaque skill (`skills/*/SKILL.md`) dans `~/.claude/skills/` et `~/.codex/skills/` via symlink
- Génère des wrappers de commande dans `~/.claude/commands/` et `~/.codex/prompts/`

**À relancer** après toute modification de `_AI_INSTRUCTIONS.md` ou ajout d'un skill.

---

## Démarrage d'un projet

### Option A — Projet existant : générer le `CLAUDE.md`

Depuis la racine du projet :

```bash
gen-claude
# ou avec un nom explicite :
gen-claude mon-projet
```

Ce script :
- Génère `CLAUDE.md` depuis le template `70_templates/projet_CLAUDE.md`
- Remplace `{{PROJECT_NAME}}` par le nom du projet
- Crée le symlink `AGENTS.md → CLAUDE.md`
- Échoue proprement si `CLAUDE.md` existe déjà (pas d'écrasement silencieux)

### Option B — Nouveau projet from scratch : `mkproj`

```bash
mkproj mon-projet
```

Ce script interactif :
1. Demande le **type de projet** (perso, lab, archive…) — détermine le dossier cible
2. Demande la **stack principale** et l'**état initial**
3. Demande si vous voulez initialiser **BMAD** (optionnel)
4. Crée le dossier projet, initialise `git`, génère `README.md` et `.gitignore`
5. Génère `CLAUDE.md` (et `AGENTS.md → CLAUDE.md`)
6. Si BMAD : initialise la structure `_bmad/` avec symlinks vers la base centralisée
7. Enregistre le projet dans `_projects.conf`

Structure créée sans BMAD :

```
mon-projet/
├── CLAUDE.md       ← mémoire active du projet
├── AGENTS.md       → CLAUDE.md (symlink)
├── README.md
└── .gitignore
```

Structure créée avec BMAD :

```
mon-projet/
├── CLAUDE.md
├── AGENTS.md       → CLAUDE.md
├── README.md
├── .gitignore
├── _bmad/
│   ├── core/       → symlink (centralisé dans Lead_tech)
│   ├── bmm/        → symlink (centralisé)
│   ├── cis/        → symlink (centralisé)
│   ├── tea/        → symlink (centralisé)
│   ├── _config/    → symlink (centralisé)
│   └── _memory/    (copie locale — écrite par les agents)
├── .agents/        → symlink (centralisé)
├── .claude/        → symlink (centralisé)
└── _bmad-output/
    ├── brainstorming/
    ├── planning-artifacts/
    ├── implementation-artifacts/
    └── test-artifacts/
```

> Les modules BMAD sont des symlinks vers `80_bmad/base/` dans Lead_tech. Cela permet de mettre à jour la méthode BMAD en un seul endroit pour tous les projets. Seul `_memory/` est une copie locale — c'est là que les agents écrivent leur mémoire de session.

### Initialiser BMAD dans un projet existant

Si le projet existe déjà et que vous voulez ajouter BMAD après coup :

```bash
cd mon-projet
bmad-init
# ou explicitement :
bash "$LEADTECH/scripts/bmad-init-project.sh" /chemin/vers/mon-projet
```

---

## Gérer le registre de projets

`_projects.conf` est le registre central de vos projets. Format :

```
nom|stack|scope|état
```

Exemple :

```
mon-api|NestJS + Prisma + PostgreSQL|perso|Epic 2 en cours
mon-app|Expo + React Native|perso|dev
mon-lab|Next.js|lab|dev
```

**Synchroniser manuellement un projet existant** dans le registre (utile si vous avez des projets antérieurs à Lead_tech) :

```bash
bash "$LEADTECH/scripts/sync-projects-conf.sh" --project-root /chemin/vers/mon-projet
```

Ce script détecte automatiquement la stack en analysant `package.json`, `prisma/schema.prisma` et le `CLAUDE.md` du projet. Il infère le scope depuis le chemin et l'état depuis `sprint-status.yaml` si BMAD est actif.

Options disponibles :

```bash
--project-root <path>   # Chemin du projet (défaut : répertoire courant)
--project-name <name>   # Nom override
--stack <value>         # Stack override
--scope <value>         # perso | mindleaf | lab | archive
--state <value>         # État override
--sync-existing         # Met à jour une entrée existante (mode safe)
```

**Résoudre le chemin physique d'un projet** depuis son nom logique :

```bash
bash "$LEADTECH/scripts/resolve-project-path.sh" mon-api
# Retourne : /Volumes/TeraSSD/Projets_Dev/mon-api  (Mac)
#         ou /srv/projects/mon-api                  (Linux)
```

Utile dans les scripts pour naviguer vers un projet sans hardcoder le chemin.

---

## Gestion des secrets — Bitwarden / Vaultwarden

Lead_tech intègre un système de gestion des secrets basé sur **Bitwarden** (ou son fork auto-hébergé [Vaultwarden](https://github.com/dani-garcia/vaultwarden)). Aucun secret n'est jamais écrit dans un fichier versionné — tout passe par le coffre.

### Principe

Les secrets sont organisés en **trois dossiers** dans Bitwarden :

| Dossier Bitwarden | Contenu | Script | Alias |
|---|---|---|---|
| `global` | Variables d'env globales (ex: `OPENAI_API_KEY`) | `load-global-secrets.sh` | `loadg` |
| `services` | Secrets partagés entre projets | `sync-service-secrets.sh` | `sync-service` |
| `projects` | `.env` de chaque projet (un item par projet) | `sync-project-secrets.sh` | `sync-project` |

### Convention de nommage dans Bitwarden

- **Dossier `global`** : chaque item a pour nom le nom exact de la variable d'env (`OPENAI_API_KEY`, `STRIPE_SECRET_KEY`…). Le mot de passe de l'item est la valeur. Les scripts les exportent directement dans le shell.
- **Dossier `services`** : même convention — `NOM_VARIABLE=valeur`, exportés dans `~/.config/auto-secrets/service.env`.
- **Dossier `projects`** : un item par projet, nommé exactement comme le dossier projet. Le contenu du `.env` est stocké dans les **notes** de l'item. Le script l'écrit dans `.env` avec `chmod 600`.

### Configuration

Le fichier `scripts/env_paths.sh` définit :
```bash
export BW_SERVER_URL="https://votre-vaultwarden.example.com"
export AUTO_SCRIPTS_DIR="$HOME/.config/auto-secrets"
```

Adaptez `BW_SERVER_URL` à votre instance. Si vous utilisez Bitwarden cloud, la valeur par défaut (`https://bitwarden.com`) est utilisée automatiquement par la CLI si `bw config server` n'est pas appelé.

### Usage quotidien

```bash
# Charger les variables globales dans le shell courant
loadg

# Synchroniser le .env du projet courant depuis Bitwarden
cd mon-projet
sync-project

# Synchroniser les secrets de service partagés
sync-service
```

Les scripts demandent le master password Bitwarden si aucune session active (`$BW_SESSION`) n'est détectée. La session est réutilisée si elle existe déjà dans l'environnement.

### Adapter à votre gestionnaire de secrets

Si vous n'utilisez pas Bitwarden/Vaultwarden, les trois scripts (`load-global-secrets.sh`, `sync-project-secrets.sh`, `sync-service-secrets.sh`) sont les seuls fichiers à remplacer. Le reste de Lead_tech est indépendant de ce choix.

---

## Adapter à votre structure

Lead_tech est **stack-agnostique dans sa structure**, mais ce dépôt reflète une stack NestJS / Expo React Native / Prisma / n8n. Pour l'adapter :

1. **Gardez** la structure `knowledge/<domaine>/patterns/` et `risques/` — elle est universelle
2. **Remplacez** les patterns qui ne correspondent pas à votre stack
3. **Ajoutez** vos propres domaines si nécessaire (ex: `knowledge/devops/`, `knowledge/python/`)
4. **Adaptez** `_AI_INSTRUCTIONS.md` pour pointer vers vos domaines et vos patterns clés
5. **Adaptez** les chemins dans `aliases.sh` si votre structure de dossiers diffère
6. **Conservez** le mécanisme `95_a_capitaliser.md` — il est indépendant de la stack

> **Note** : les fichiers `knowledge/` contiennent des références à des projets réels qui ont servi de contexte de découverte pour les patterns. Ces références sont intentionnellement conservées — elles ancrent chaque entrée dans son contexte d'origine. Remplacez-les progressivement par vos propres références au fil de votre usage.

---

## Contribuer

Les contributions sous forme de **patterns génériques validés** (non liés à un projet spécifique) sont bienvenues.

Format attendu pour un pattern :

```markdown
## Nom du pattern

### Problème
[Description du problème résolu]

### Solution
[Pattern ou pratique recommandée]

### Exemple
[Code ou configuration concrète]

### Pourquoi
[Justification — ce que ça évite]

- Contexte technique : [stack / framework / version]
```

---

## Philosophie

- **Robustesse avant vitesse** — le code est traité comme du logiciel en production
- **Réduction du debug** — chaque entrée doit réduire le temps de diagnostic
- **Pas de sur-ingénierie** — un pattern doit être validé par le terrain, pas par la théorie
- **Documentation utile uniquement** — si ça ne sert à rien en situation réelle, ça n'a pas sa place ici
- **Validation humaine** — les agents proposent, le développeur valide