From 6d56061554ca27f4d7c9b669723de531606ce78c Mon Sep 17 00:00:00 2001 From: MaksTinyWorkshop Date: Mon, 30 Mar 2026 09:51:02 +0200 Subject: [PATCH] Add README and LICENSE for community sharing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- LICENSE | 17 ++ README.md | 454 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 471 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..e957ab8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,17 @@ +Creative Commons Attribution 4.0 International (CC BY 4.0) + +Copyright (c) 2026 MaksTinyWorkshop + +You are free to: + Share — copy and redistribute the material in any medium or format + Adapt — remix, transform, and build upon the material for any purpose, even commercially + +Under the following terms: + Attribution — You must give appropriate credit, provide a link to the license, + and indicate if changes were made. You may do so in any reasonable manner, + but not in any way that suggests the licensor endorses you or your use. + +No additional restrictions — You may not apply legal terms or technological measures +that legally restrict others from doing anything the license permits. + +Full licence text: https://creativecommons.org/licenses/by/4.0/legalcode diff --git a/README.md b/README.md new file mode 100644 index 0000000..6254786 --- /dev/null +++ b/README.md @@ -0,0 +1,454 @@ +# 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//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 # Chemin du projet (défaut : répertoire courant) +--project-name # Nom override +--stack # Stack override +--scope # perso | mindleaf | lab | archive +--state # É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//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