mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-05-18 08:18:15 +02:00
capitalisation: intégration ~60 entrées RL799_V2 (triage 2026-05-02)
Triage du 95_a_capitaliser.md (~75 propositions) : - 60 entrées intégrées dans knowledge/ (backend, frontend, workflow) - 4 nouveaux fichiers : backend/patterns/tests.md, backend/risques/tests.md, frontend/patterns/general.md, workflow/patterns/general.md - 6 doublons rejetés - Mise à jour des READMEs index pour refléter les nouvelles entrées - 95_a_capitaliser.md restauré à sa structure initiale - 40_decisions_et_archi.md : décision mono-tenant déployable vs SaaS multi-tenant - 90_debug_et_postmortem.md : sub-agents Write indisponible, effet iceberg CI, prisma migrate diffs cosmétiques Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MaksTinyWorkshop
11
knowledge/workflow/patterns/README.md
Normal file
11
knowledge/workflow/patterns/README.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Workflow — Patterns validés — Index
|
||||
|
||||
Patterns liés au process de développement, aux agents BMAD et au pilotage des chantiers.
|
||||
|
||||
Avant toute proposition workflow, identifie le fichier dont le nom et la description matchent le contexte traité, puis lis-le.
|
||||
|
||||
---
|
||||
|
||||
| Fichier | Domaine | Entrées clés |
|
||||
|---------|---------|--------------|
|
||||
| `general.md` | Review adversarial, isolation de hunks, méthode de chantier | Review adversarial obligatoire sur chemin critique, isolation chirurgicale d'un hunk via `git apply --cached` |
|
||||
157
knowledge/workflow/patterns/general.md
Normal file
157
knowledge/workflow/patterns/general.md
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Workflow — Patterns : Général
|
||||
domain: workflow
|
||||
bucket: patterns
|
||||
tags: [review, adversarial, git, chantier, agent]
|
||||
applies_to: [analysis, implementation, review]
|
||||
severity: high
|
||||
validated_on: 2026-04-27
|
||||
source_projects: [RL799_V2]
|
||||
---
|
||||
|
||||
# Workflow — Patterns : Général
|
||||
|
||||
> Extrait de la base de connaissance Lead_tech. Voir `knowledge/workflow/patterns/README.md` pour l'index complet.
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-review-adversarial-chemin-critique"></a>
|
||||
## Pattern : Review adversarial obligatoire sur chemin critique
|
||||
|
||||
- Objectif : détecter avant commit les race conditions, assertions trop molles et dépendances cachées qui ne sont pas visibles à la lecture du spec mais le sont à la lecture du code écrit.
|
||||
- Contexte : chantier qui touche un chemin critique (atomicité, audit, sécurité, intégrité financière, lifecycle d'entité métier) — même petit (< 100 lignes).
|
||||
- Quand l'utiliser : systématique sur les chemins critiques, indépendamment de la taille du chantier.
|
||||
- Quand l'éviter : refactor cosmétique, polish UX, documentation, tests d'un chemin déjà couvert.
|
||||
- Avantage :
|
||||
- capture les défauts post-spec (l'intention est cadrée, l'implémentation peut diverger)
|
||||
- moins coûteuse à corriger avant commit qu'en post-prod (incident, debug, rollback)
|
||||
- Limites / vigilance :
|
||||
- pas un substitut à la code review classique (posture différente : "qu'est-ce qui casse" vs "est-ce conforme au spec")
|
||||
- pas un substitut aux tests qui passent (les tests valident ce qu'on a pensé tester)
|
||||
- Validé le : 27-04-2026
|
||||
- Contexte technique : workflow agent / BMAD — RL799_V2
|
||||
|
||||
### Identifier un chemin critique
|
||||
|
||||
Au moins **une** des conditions :
|
||||
- mutation atomique d'une entité métier (close, cancel, lock, archive)
|
||||
- émission d'audit log (la traçabilité est non-négociable)
|
||||
- émission de notification (mauvais target = bug visible utilisateur)
|
||||
- logique d'autorisation, RBAC, gates de permission
|
||||
- calculs financiers (paiements, soldes, totaux)
|
||||
- intégrité référentielle (FK, soft-delete)
|
||||
- concurrence : plusieurs process peuvent toucher la même entité
|
||||
|
||||
### Format de review efficace
|
||||
|
||||
Posture : œil fâché, on cherche à casser ce qu'on vient de livrer.
|
||||
|
||||
Pour chaque finding :
|
||||
- **Sévérité** : HIGH / MEDIUM / LOW / NIT
|
||||
- **Localisation** : `file:line`
|
||||
- **Problème** : ce qui peut casser, dans quel scénario
|
||||
- **Mitigation possible** : 1-3 options
|
||||
- **Verdict** : fix dans le scope, dette explicite, ignorer
|
||||
|
||||
Sortie : tableau synthétique. Si > 0 HIGH ou > 2 MEDIUM, on fixe avant commit.
|
||||
|
||||
### Anti-règle
|
||||
|
||||
- Confondre review adversarial et code review classique
|
||||
- Confondre "tests verts" et "implémentation correcte"
|
||||
- Lire son propre code en attendant de le valider (biais cognitif fort)
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-isolation-hunk-git-apply-cached"></a>
|
||||
## Pattern : Isolation chirurgicale d'un hunk via `git apply --cached <patch>`
|
||||
|
||||
- Objectif : commiter uniquement les hunks d'un chantier A dans un fichier également modifié par un chantier B, sans interaction `git add -p`.
|
||||
- Contexte : plusieurs chantiers parallèles touchent le même fichier central (catalog audit, schema partagé, fichier d'enums).
|
||||
- Quand l'utiliser : agent IA en environnement non-interactif qui prépare un commit avec sélection de hunks.
|
||||
- Quand l'éviter : si on commit la totalité du fichier (`git add <file>` direct suffit), ou si les hunks sont logiquement indissociables.
|
||||
- Avantage :
|
||||
- non-interactif, scriptable
|
||||
- le worktree garde tous les changements (mes hunks A commités + hunks B unstaged pour le chantier B)
|
||||
- Limites / vigilance :
|
||||
- en interactif humain, `git add -p` reste plus rapide
|
||||
- le patch filtré doit rester valide (en-têtes `diff --git`, `index`, `@@` cohérents)
|
||||
- Validé le : 27-04-2026
|
||||
- Contexte technique : git / chantiers parallèles — RL799_V2
|
||||
|
||||
### Recette
|
||||
|
||||
```bash
|
||||
# 1. Capturer le diff du fichier mixte
|
||||
git diff <file> > /tmp/mixed.patch
|
||||
|
||||
# 2. Éditer le patch pour ne garder que les hunks à commiter
|
||||
# (un agent peut le faire via Read + Write — c'est un fichier texte)
|
||||
|
||||
# 3. Appliquer le patch filtré uniquement à l'index (pas au worktree)
|
||||
git apply --cached /tmp/mine_only.patch
|
||||
|
||||
# 4. Vérifier le staged
|
||||
git diff --cached <file>
|
||||
|
||||
# 5. Commit
|
||||
git commit ...
|
||||
|
||||
# 6. Le worktree garde TOUS les changements
|
||||
git diff <file> # affiche les hunks de l'autre chantier
|
||||
```
|
||||
|
||||
### Format minimal d'un hunk
|
||||
|
||||
```diff
|
||||
diff --git a/<file> b/<file>
|
||||
index <hash_old>..<hash_new> 100644
|
||||
--- a/<file>
|
||||
+++ b/<file>
|
||||
@@ -<line>,<count> +<line>,<count> @@ <context>
|
||||
<ligne contexte avant>
|
||||
+<ligne ajoutée>
|
||||
<ligne contexte après>
|
||||
```
|
||||
|
||||
Les `index` et `@@` viennent du `git diff` original — pas besoin de recalculer les hashes.
|
||||
|
||||
---
|
||||
|
||||
<a id="pattern-sub-agents-trianguler-localisations"></a>
|
||||
## Pattern : Trianguler par grep les localisations rapportées par un sub-agent
|
||||
|
||||
- Objectif : ne jamais agir directement sur les localisations précises rapportées par un sub-agent d'analyse — toujours vérifier avant de patcher.
|
||||
- Contexte : workflow multi-agent où un sub-agent (Explore, audit BMAD, lecture de code) retourne un rapport avec findings.
|
||||
- Quand l'utiliser : à la réception de tout rapport de sub-agent qui cite des fichiers, lignes, ou snippets.
|
||||
- Quand l'éviter : pour les comptages globaux et tendances — fiables même sans triangulation.
|
||||
- Avantage :
|
||||
- évite de "corriger" du code déjà correct (pollution de commit, perte de confiance)
|
||||
- distingue les findings actionables des extrapolations
|
||||
- Limites / vigilance :
|
||||
- ajoute ~15-20 % de temps à la phase d'action — largement compensé par les commits évités
|
||||
- Validé le : 24-04-2026
|
||||
- Contexte technique : workflow multi-agent / BMAD — RL799_V2
|
||||
|
||||
### Règle
|
||||
|
||||
> Ne jamais agir sur les **localisations précises** d'un sub-agent sans vérification.
|
||||
> - Sub-agent dit "fichier X ligne Y a pattern Z" → `grep Z fichier X` doit confirmer
|
||||
> - Sub-agent dit "fichiers A, B, C, D ont pattern Z" → grep chaque fichier
|
||||
> - Si un finding s'effondre à la vérif, relire critiquement les autres findings du même sub-agent
|
||||
|
||||
### Ce qui reste fiable chez un sub-agent
|
||||
|
||||
- Comptages globaux (X fichiers sur Y ont le pattern Z — l'ordre de grandeur est généralement juste)
|
||||
- Tendances (ex: "le projet a un problème de cleanup" — juste, même si les fichiers cités sont faux)
|
||||
- Patterns de risque identifiés (`vi.stubEnv` sans restauration est un vrai pattern à risque)
|
||||
|
||||
### Ce qui est peu fiable
|
||||
|
||||
- Numéros de ligne précis (peuvent être hallucinés)
|
||||
- Listes de fichiers exhaustives pour un pattern rare
|
||||
- Snippets de code cités (peuvent être reconstruits de mémoire plutôt que lus)
|
||||
|
||||
### Communication au user
|
||||
|
||||
> *"Sub-agent X signale 4 fichiers, j'ai validé 1/4 et invalidé 3/4. Voici le plan d'action corrigé."*
|
||||
@@ -6,4 +6,4 @@ Risques liés au process de développement, aux agents BMAD, et au tracking des
|
||||
|
||||
| Fichier | Domaine | Entrées clés |
|
||||
|---------|---------|--------------|
|
||||
| `story-tracking.md` | BMAD, agents, story completion | Story "completed" avec tâches ❌, story "done" sans fichiers source dans File List |
|
||||
| `story-tracking.md` | BMAD, agents, story completion | Story "completed" avec tâches ❌, story "done" sans fichiers source dans File List, stratégie de fix d'une suite E2E qui rote en masse |
|
||||
|
||||
@@ -270,3 +270,47 @@ source_projects: [app-alexandrie, app-template-resto, RL799_V2]
|
||||
- Contexte technique : BMAD / traçabilité adaptation story — RL799_V2 15-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-strategie-fix-suite-e2e-en-masse"></a>
|
||||
## Stratégie de fix d'une suite E2E qui rote en masse (post-refactor)
|
||||
|
||||
### Risques
|
||||
|
||||
- Quand un projet enchaîne plusieurs refactors UI/lifecycle sans run E2E entre chaque, on découvre souvent N fails (10-20) d'un coup
|
||||
- Tentation de fixer fail-by-fail dans l'ordre où ils apparaissent — erreur : on se disperse sur N causes-racines mélangées et chaque commit n'est pas reviewable
|
||||
- Sans capitalisation immédiate des patterns, on perd le bénéfice de la session pour les futurs refactors
|
||||
|
||||
### Symptômes
|
||||
|
||||
- 13 fails d'un coup après une période de refactor intense
|
||||
- Tentative de fix fail-par-fail qui produit un commit géant difficile à reviewer
|
||||
- Capitalisation reportée → patterns oubliés à la session suivante
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
**Process recommandé** :
|
||||
|
||||
1. **Run complet en mode list** d'abord : `playwright test --reporter=list`. On veut **la liste exhaustive** des fails, pas un comptage one-shot par fichier (qui peut masquer des fails qui apparaissent uniquement quand on lance la suite entière à cause d'effets de bord seed).
|
||||
|
||||
2. **Catégoriser par cause-racine** plutôt que par fichier (cf. `knowledge/frontend/risques/tests.md` — Tests E2E qui rotent — 6 causes-racines récurrentes) :
|
||||
- testid changé sans MAJ tests
|
||||
- label métier changé (lifecycle, statut)
|
||||
- menu/dropdown conditionnel
|
||||
- feature supprimée (query param, route)
|
||||
- refactor visuel (texte → icône)
|
||||
- cleanup post-test à rendre best-effort
|
||||
|
||||
3. **1 commit = 1 cause-racine**. Pas "fix 19 fails" en un commit géant. Permet :
|
||||
- Review plus simple (chaque commit a un thème clair)
|
||||
- Revert chirurgical si une cause-racine s'avère mal diagnostiquée
|
||||
- Capitalisation : chaque commit message documente le pattern
|
||||
|
||||
4. **Validation entre commits** : run la suite complète après chaque commit pour savoir avant le push que le commit n'a pas régressé d'autres tests.
|
||||
|
||||
5. **Capitaliser les patterns à > 2 occurrences** : si on voit le même type de fail 3 fois sur 3 fichiers différents, c'est un pattern. Le poser dans `knowledge/frontend/risques/tests.md` immédiatement, pas plus tard.
|
||||
|
||||
**Anti-pattern à éviter** : "je fixe les 5 fails P1 d'abord, je verrai les P2 après". Si la cause-racine est la même (ex : labels lifecycle v3), on perd 30 min à re-comprendre quand on retourne sur les P2 plus tard. Mieux : grouper par cause-racine, pas par priorité.
|
||||
|
||||
**Métrique de référence** : 19 fails fixés en 4 commits / ~3 h dont 1 h de capitalisation. Effort par fail : ~6 min de fix + 4 min de validation.
|
||||
|
||||
- Contexte technique : Playwright / refactor UI — RL799_V2 25-04-2026
|
||||
|
||||
Reference in New Issue
Block a user