_Assistant_Lead_Tech/README.md

Lead_tech

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.

Depuis mars 2026, le repo peut aussi exposer cette doctrine sous forme de serveur MCP sidecar pour des workflows BMAD. L'objectif n'est pas de remplacer la lecture des Markdown, mais de rendre la consultation, les gates et la capitalisation actionnables par tool call.

---

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 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
├── mcp/                    # Serveurs MCP sidecar et prototypes associés
├── 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

---

MCP Sidecar BMAD

Le prototype actuel vit dans mcp/leadtech_bmad_mcp/.

Il expose deux types de primitives :

• guidance : retrouver les patterns, risques et docs globaux pertinents pour une story
• gates : valider un plan, un diff, ou la checklist attendue selon le rôle BMAD
• capitalisation : proposer des ajouts dans 95_a_capitaliser.md et aider au tri
• resources : lire l'index Lead_tech, les docs globaux, les entrées de connaissance, et les projets actifs

Le positionnement visé est volontairement sobre :

• BMAD garde l'orchestration
• Lead_tech garde la doctrine
• le MCP sidecar fournit une couche d'interactivité et de contrôle qualité

Voir :

• 80_bmad/integration_mcp_sidecar.md
• mcp/leadtech_bmad_mcp/README.md

Niveau de maturité actuel

Ce sidecar est déjà utile pour un rollout advisory.

Il est pertinent dès maintenant pour :

• injecter des patterns/risques en entrée de story
• faire un contrôle "pré-plan" et "post-patch"
• sécuriser la capitalisation sans donner un accès d'écriture direct à knowledge/

Avant un usage plus strict en production, il est recommandé d'ajouter :

• un score de pertinence plus riche que le simple comptage de tokens
• des gates paramétrables par domaine critique
• des métadonnées structurées sur les fichiers knowledge/
• une vraie stratégie de versioning et de compatibilité pour les tools MCP

Roadmap conseillée

1. Stabiliser le contrat MCP actuel. Geler les noms de tools/resources, formaliser leurs inputs/outputs, et documenter les cas limites.
2. Ajouter des métadonnées structurées à la base de connaissance. Exemple : domain, bucket, tags, severity, applies_to, validated_on, source_projects.
3. Introduire un index de recherche compilé. Un petit pipeline local qui prépare un index JSON/SQLite sera plus robuste et plus rapide qu'un scan Markdown brut à chaque appel.
4. Distinguer clairement advisory et enforced gates. Un mode "conseil" pour l'adoption et un mode "blocant" limité à quelques règles à forte valeur.
5. Journaliser l'usage. Conserver pour chaque story les tools appelés, leurs recommandations, et la décision humaine associée.

---

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 installé (et/ou Codex)
• bash (macOS / Linux)
• git

---

Installation

1. Forker et cloner

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

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

Rechargez votre shell :

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

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 :

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

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 :

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 "$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 :

--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 "$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). 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 :

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

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

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