mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-06 21:41:42 +02:00
6d56061554
- README: modèle mental complet (Claude/Codex, BMAD, capitalisation), scripts détaillés, gestion secrets Bitwarden - LICENSE: CC BY 4.0 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
455 lines
18 KiB
Markdown
455 lines
18 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 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
|