From c4c7f3b7154053390f8447b89f786be1db0e0b0f Mon Sep 17 00:00:00 2001 From: MaksTinyWorkshop Date: Sun, 8 Mar 2026 18:56:36 +0100 Subject: [PATCH] =?UTF-8?q?feat:=20communication=20bi-directionnelle=20BMA?= =?UTF-8?q?D=20=E2=86=94=20Lead=5Ftech?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Ajout de $LEADTECH dans aliases.sh (variable d'env résolu Mac/NUC) - Refonte de 80_bmad/articulation_avec_lead_tech.md : lecture obligatoire par type de tâche, déclencheurs de capitalisation, chemin $LEADTECH explicite - Mise à jour du template projet_CLAUDE.md : section capitalisation actionnable - Ajout des fichiers 95_a_capitaliser.md et playbook capitaliser_un_apprentissage.md Co-Authored-By: Claude Sonnet 4.6 --- 60_playbooks/capitaliser_un_apprentissage.md | 102 ++++++++++++++ 70_templates/projet_CLAUDE.md | 45 +++++- 80_bmad/articulation_avec_lead_tech.md | 136 ++++++++++++++++--- 95_a_capitaliser.md | 96 +++++++++++++ scripts/aliases.sh | 26 ++++ 5 files changed, 381 insertions(+), 24 deletions(-) create mode 100644 60_playbooks/capitaliser_un_apprentissage.md create mode 100644 95_a_capitaliser.md create mode 100644 scripts/aliases.sh diff --git a/60_playbooks/capitaliser_un_apprentissage.md b/60_playbooks/capitaliser_un_apprentissage.md new file mode 100644 index 0000000..2854796 --- /dev/null +++ b/60_playbooks/capitaliser_un_apprentissage.md @@ -0,0 +1,102 @@ +# Playbook — Capitaliser un apprentissage + +Ce playbook décrit **quand et comment transformer un apprentissage +projet en connaissance globale dans `Lead_tech`.** + +--- + +# Principe + +Tous les apprentissages découverts dans un projet ne doivent pas +être ajoutés directement dans la base de connaissance globale. + +On utilise le workflow suivant : + +``` +Projet + ↓ +Observation / apprentissage + ↓ +Proposition + ↓ +95_a_capitaliser.md + ↓ +Validation + ↓ +Lead_tech +``` + +--- + +# Quand capitaliser + +Un apprentissage mérite d'être capitalisé lorsqu'il : + +- résout un bug difficile +- révèle un anti-pattern +- définit un pattern réutilisable +- documente une contrainte technique +- formalise une décision d'architecture + +--- + +# Où écrire selon le type de savoir + +| Type de savoir | Destination | +| ----------------------- | ------------------------------------- | +| Pattern backend validé | `10_backend_patterns_valides.md` | +| Pattern frontend validé | `10_frontend_patterns_valides.md` | +| Anti-pattern backend | `10_backend_risques_et_vigilance.md` | +| Anti-pattern frontend | `10_frontend_risques_et_vigilance.md` | +| Décision d'architecture | `40_decisions_et_archi.md` | +| Bug / postmortem | `90_debug_et_postmortem.md` | + +--- + +# Procédure + +1. Identifier un apprentissage dans un projet + +2. Ajouter une proposition dans : + +``` +95_a_capitaliser.md +``` + +3. Utiliser le format : + +``` +DATE — PROJET + +FILE_UPDATE_PROPOSAL +Fichier cible : ... + +Pourquoi : ... + +Proposition : ... +``` + +4. Attendre validation + +5. Déplacer la proposition vers le fichier cible + +6. Supprimer l'entrée du fichier `95_a_capitaliser.md` + +--- + +# Bonnes pratiques + +- privilégier les exemples concrets +- éviter les règles théoriques +- préférer les patterns validés en production +- garder les propositions courtes + +--- + +# Objectif + +Maintenir une base de connaissance : + +- fiable +- réutilisable +- validée par l'expérience diff --git a/70_templates/projet_CLAUDE.md b/70_templates/projet_CLAUDE.md index a5ecacb..4c0213a 100644 --- a/70_templates/projet_CLAUDE.md +++ b/70_templates/projet_CLAUDE.md @@ -275,10 +275,51 @@ Ce fichier doit être mis à jour lorsque : - un pattern spécifique apparaît - une dette technique significative est identifiée -Si une information devient **utile à plusieurs projets**, proposer : +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/projects/_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_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> + +Pourquoi : + + +Proposition : + ``` -pour la remonter dans la base `Lead_tech`. +## 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. diff --git a/80_bmad/articulation_avec_lead_tech.md b/80_bmad/articulation_avec_lead_tech.md index 387d675..5886030 100644 --- a/80_bmad/articulation_avec_lead_tech.md +++ b/80_bmad/articulation_avec_lead_tech.md @@ -1,4 +1,4 @@ -# BMAD — articulation avec Lead_tech +# BMAD — Articulation avec Lead_tech BMAD fournit une méthode de travail basée sur des agents spécialisés. @@ -48,37 +48,129 @@ Responsables de : - implémenter - reviewer - améliorer le code +- **capitaliser les apprentissages vers Lead_tech** --- -# Règle importante +# Lecture obligatoire avant de travailler -Avant d'introduire : +Avant d'introduire un nouveau pattern, une nouvelle convention ou une nouvelle +architecture, les agents DOIVENT lire les fichiers Lead_tech correspondants. -- un nouveau pattern -- une nouvelle convention -- une nouvelle architecture +| Type de tâche | Fichiers à lire en priorité | +| ---------------------- | --------------------------------------------------------------------------------- | +| Backend (API, services) | `10_backend_patterns_valides.md`, `10_backend_risques_et_vigilance.md` | +| Frontend / mobile | `10_frontend_patterns_valides.md`, `10_frontend_risques_et_vigilance.md` | +| Architecture / design | `40_decisions_et_archi.md` | +| Debug / investigation | `90_debug_et_postmortem.md` | +| n8n / automatisations | `10_n8n_patterns_valides.md`, `10_n8n_nodes_a_risques.md` | -les agents doivent vérifier la base `Lead_tech`. - ---- - -# Capitalisation - -Si un pattern devient réutilisable : - -Proposer une mise à jour : - -``` -FILE_UPDATE_PROPOSAL -Fichier : … -Pourquoi : … -``` +Règle : **si un pattern Lead_tech existe et couvre le besoin, l'appliquer +directement sans réinventer**. --- # Hiérarchie de contexte 1. contraintes techniques réelles -2. règles du projet +2. règles du projet (`CLAUDE.md` projet) 3. règles globales (`Lead_tech`) + +--- + +# Communication bi-directionnelle — Capitalisation + +Les agents BMAD ne se contentent pas de lire Lead_tech. +Ils y contribuent activement en remontant les apprentissages. + +## Zone de capitalisation + +Le fichier cible pour toutes les propositions est : + +``` +$LEADTECH/95_a_capitaliser.md +``` + +`$LEADTECH` est une variable d'environnement définie automatiquement sur Mac +et sur le NUC via `scripts/aliases.sh`. Elle pointe vers le repo Lead_tech +de la machine courante. + +En pratique : +- Mac : `~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md` +- NUC : `/srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md` + +## Quand capitaliser + +Un apprentissage mérite d'être remonté si : + +- un bug difficile a été résolu +- un anti-pattern a été identifié +- un pattern réutilisable a émergé +- une décision d'architecture structurante a été prise +- une contrainte technique inattendue a été rencontrée + +## À quel moment dans le workflow BMAD + +| Moment | Action | +| ----------------------------- | ------------------------------------------------------- | +| Fin d'une story | Vérifier si un pattern réutilisable a émergé | +| Résolution d'un bug difficile | Écrire une entrée dans `95_a_capitaliser.md` | +| Choix d'architecture notable | Proposer une entrée dans `40_decisions_et_archi.md` | +| Fin de sprint / milestone | Relire `95_a_capitaliser.md` et valider ou supprimer | + +## Format de la proposition + +``` +DATE — PROJET + +FILE_UPDATE_PROPOSAL +Fichier cible : + +Pourquoi : + + +Proposition : + +``` + +Exemple : + +``` +2026-03-08 — app-alexandrie + +FILE_UPDATE_PROPOSAL +Fichier cible : 10_backend_patterns_valides.md + +Pourquoi : +L'ordre d'enregistrement des guards NestJS a causé request.user undefined +dans EmailVerifiedGuard lors de l'implémentation de l'auth. + +Proposition : +Toujours enregistrer AuthGuard en premier dans providers[] avant tout guard +qui lit request.user. +``` + +## Règle importante + +Les agents peuvent **écrire librement** dans `95_a_capitaliser.md`. + +Ils ne doivent **jamais écrire directement** dans les fichiers de connaissance +validée (`10_*`, `40_*`, `90_*`). + +La validation et l'intégration finale sont faites **par le développeur**. + +--- + +# Résumé du flux complet + +``` +Lead_tech + ↓ (lecture avant implémentation) +Agent BMAD + ↓ (implémentation) +Apprentissage détecté + ↓ +$LEADTECH/95_a_capitaliser.md + ↓ (validation humaine) +Lead_tech (fichier approprié) +``` diff --git a/95_a_capitaliser.md b/95_a_capitaliser.md new file mode 100644 index 0000000..d347386 --- /dev/null +++ b/95_a_capitaliser.md @@ -0,0 +1,96 @@ +# Capitalisation en attente — Lead_tech + +Ce fichier sert de **zone tampon de capitalisation**. + +Les agents et les projets peuvent y déposer des propositions +d’amélioration de la base de connaissance globale (`Lead_tech`). + +Le contenu de ce fichier **n'est pas encore validé**. + +Une fois relues et confirmées, les propositions doivent être déplacées +vers les fichiers appropriés : + +- `10_backend_patterns_valides.md` +- `10_frontend_patterns_valides.md` +- `10_backend_risques_et_vigilance.md` +- `10_frontend_risques_et_vigilance.md` +- `40_decisions_et_archi.md` +- `90_debug_et_postmortem.md` + +Ce fichier ne doit donc **jamais devenir une documentation permanente**. + +--- + +# Format attendu + +Chaque proposition doit suivre ce format : + +``` +DATE — PROJET + +FILE_UPDATE_PROPOSAL +Fichier cible : + +Pourquoi : + + +Proposition : + +``` + +--- + +# Exemple + +``` +2026-03-08 — portfolio + +FILE_UPDATE_PROPOSAL +Fichier cible : 10_backend_patterns_valides.md + +Pourquoi : +Ordre d'enregistrement des Guards NestJS causant un bug +`request.user undefined` observé à plusieurs reprises. + +Proposition : + +## Ordre des Guards NestJS + +Toujours enregistrer `AuthGuard` avant les Guards dépendants +(`EmailVerifiedGuard`, `RoleGuard`, etc.). + +Sinon `request.user` peut être undefined dans les guards suivants. +``` + +--- + +# Règles + +1. Les agents peuvent **proposer librement** ici. +2. Les propositions doivent rester **courtes et factuelles**. +3. La validation et l'intégration finale dans `Lead_tech` + sont faites **manuellement**. +4. Une fois intégrée, la proposition doit être **supprimée + de ce fichier**. + +--- + +# Rôle dans l'architecture + +``` +Projet + ↓ +Proposition + ↓ +95_a_capitaliser.md + ↓ +Validation humaine + ↓ +Lead_tech +``` + +Ce mécanisme permet : + +- d'éviter la pollution de la base de connaissance +- de capitaliser progressivement l'expérience des projets +- de garder `Lead_tech` cohérent et fiable. diff --git a/scripts/aliases.sh b/scripts/aliases.sh new file mode 100644 index 0000000..47ebeac --- /dev/null +++ b/scripts/aliases.sh @@ -0,0 +1,26 @@ +# Aliases Lead_tech +# Chargé automatiquement par les shells Mac / Linux + +# Variable d'environnement pointant vers le repo Lead_tech +# Utilisable dans les scripts et par les agents pour construire des chemins absolus +# (ex: $LEADTECH/95_a_capitaliser.md) +if [ -d "$HOME/AI_RULES/_Assistant_Lead_Tech" ]; then + export LEADTECH="$HOME/AI_RULES/_Assistant_Lead_Tech" +elif [ -d "/srv/projects/_Assistant_Lead_Tech" ]; then + export LEADTECH="/srv/projects/_Assistant_Lead_Tech" +fi + +# Aller au repo Lead_tech +alias leadtech='cd "$LEADTECH"' + +# Générer mémoire projet +alias gen-claude='~/AI_RULES/_Assistant_Lead_Tech/scripts/generate_project_claude.sh 2>/dev/null || /srv/projects/_Assistant_Lead_Tech/scripts/generate_project_claude.sh' + +# Créer un projet +alias mkproj='~/AI_RULES/_Assistant_Lead_Tech/scripts/mkproj.sh 2>/dev/null || /srv/projects/_Assistant_Lead_Tech/scripts/mkproj.sh' + +# Sync mémoire agents +alias sync-ai='~/AI_RULES/_Assistant_Lead_Tech/scripts/sync-ai-instructions.sh 2>/dev/null || /srv/projects/_Assistant_Lead_Tech/scripts/sync-ai-instructions.sh' + +# Aller dans projets +alias projects='cd ~/Volumes/TeraSSD/Projets_Dev 2>/dev/null || cd /srv/projects' \ No newline at end of file