Update archi + augmentation agents après refacto de chemins

This commit is contained in:
MaksTinyWorkshop
2026-03-12 16:55:15 +01:00
parent 72958b4335
commit 39067b153a
16 changed files with 132 additions and 20 deletions

View File

@@ -28,10 +28,109 @@ Dernière mise à jour : 2026-03-10
- [Authentification et autorisation centrales](#decision-auth-central)
- [Idempotence et gestion des retries](#decision-idempotence-retries)
- [Structure Docker et données persistantes](#decision-structure-docker)
- [Accès réseau des VM de développement via Tailscale](#decision-reseau-tailscale-vm-dev)
---
<a id="decision-reseau-tailscale-vm-dev"></a>
## Accès réseau des VM de développement via Tailscale
- Date : 2026-03-12
- Statut : Accepted
- Périmètre : infra
### Contexte
Les machines de développement personnelles (NUC / homelab) hébergent plusieurs VM :
- Home Assistant
- Docker-dev
- OpenClaw
- autres services internes
Ces VM exposent parfois :
- SSH
- bases de données
- interfaces web dadministration
- services de développement
Exposer ces services sur le LAN local ou sur Internet augmente inutilement la surface dattaque et complique la lecture de linfrastructure.
Le réseau privé Tailscale est utilisé comme couche daccès sécurisée entre les machines de confiance.
### Options envisagées
- Exposer certains services sur le LAN local et filtrer “au cas par cas”
- Utiliser Tailscale comme frontière réseau principale pour les accès dadministration et de développement
- Lier directement les services à une interface donnée sans politique firewall explicite
### Décision
Les VM internes nacceptent les connexions entrantes que via linterface Tailscale.
Le pare-feu local (`ufw`) applique cette politique avec la configuration minimale suivante :
```bash
ufw default deny incoming
ufw default allow outgoing
```
Les services explicitement nécessaires sont autorisés uniquement sur `tailscale0`.
Exemples :
```bash
ufw allow in on tailscale0 to any port 22
ufw allow in on tailscale0 to any port 8080
ufw allow in on tailscale0 to any port 5432
```
Tout accès depuis Internet, le LAN local ou une autre interface réseau est refusé par défaut.
### Justification
- Réduit fortement la surface dattaque
- Évite les expositions accidentelles de services de dev ou dadministration
- Simplifie laccès distant sans ouvrir de ports ni gérer du NAT
- Rend la topologie réseau plus lisible et plus cohérente entre les VM
### Conséquences
- Tailscale devient la frontière réseau de confiance pour les VM internes
- SSH est accessible via Tailscale uniquement
- Les interfaces web de dev/admin et services de données ne sont ouverts que si un besoin réel existe
- Les règles `ufw` font partie de la configuration standard dune nouvelle VM
Quand cest possible, les services doivent écouter directement sur linterface Tailscale plutôt que sur toutes les interfaces.
Exemples :
- préférable : `100.x.x.x:5432`
- acceptable si le firewall est strict : `0.0.0.0:5432`
- à éviter : écoute large + politique réseau permissive
Certains services restent fermés par défaut tant quun besoin explicite nexiste pas, en particulier :
- Redis
- bases de données non nécessaires en accès distant
- interfaces dadministration
Modèle visé :
```txt
Internet → ❌
LAN local → ❌
Tailscale → ✅
```
Cette convention est recommandée pour toutes les nouvelles VM du NUC, notamment `docker-dev` et `openclaw`.
---
<a id="decision-story-sizing-foundations"></a>
## Story sizing — foundations bloquantes vs qualité non bloquante (CI mobile)
- Date : 2026-03-09
@@ -68,6 +167,7 @@ On distingue explicitement :
---
<a id="decision-code-review-adversariale"></a>
## Code review adversariale — passe dédiée en contexte frais
- Date : 2026-03-09
@@ -124,6 +224,7 @@ La code review doit être une passe **séparée** de limplémentation, en **c
---
<a id="decision-n8n-mini-systemes"></a>
## Workflows n8n complexes = mini-systèmes
- Date : 2025-12-19
@@ -160,6 +261,7 @@ Les considérer comme du code.
---
<a id="decision-frontend-production"></a>
## Le front-end est un logiciel en production
- Date : 2026-01-25
@@ -213,6 +315,7 @@ Il est soumis aux mêmes principes que le backend :
---
<a id="decision-backend-production"></a>
## Le back-end est un logiciel en production (qualité, observabilité, sécurité)
- Date : 2026-01-25
@@ -263,6 +366,7 @@ Exigences minimales :
---
<a id="decision-contrats-api"></a>
## Contrats dAPI explicites et versionnés
- Date : 2026-01-25
@@ -304,6 +408,7 @@ Minimum attendu :
---
<a id="decision-contrats-sso-zod"></a>
## Single source of truth des contrats — schémas runtime partagés (Zod) + z.infer (No-DTO)
- Date : 2026-03-10
@@ -345,6 +450,7 @@ Principe opérationnel :
---
<a id="decision-user-views"></a>
## User views — User public par défaut + MeUser explicite
- Date : 2026-03-10
@@ -387,6 +493,7 @@ Règles associées :
---
<a id="decision-erreurs-http"></a>
## Gestion standard des erreurs et des statuts HTTP
- Date : 2026-01-25
@@ -427,6 +534,7 @@ Les erreurs HTTP sont standardisées :
---
<a id="decision-migrations"></a>
## Migrations et évolution de schéma maîtrisées
- Date : 2026-01-25
@@ -468,6 +576,7 @@ Principes :
---
<a id="decision-observabilite"></a>
## Observabilité minimale obligatoire (logs, corrélation, signaux)
- Date : 2026-01-25
@@ -508,6 +617,7 @@ Observabilité minimale obligatoire :
---
<a id="decision-auth-central"></a>
## Authentification et autorisation comme responsabilités centrales
- Date : 2026-01-25
@@ -551,6 +661,7 @@ Principes :
---
<a id="decision-idempotence-retries"></a>
## Idempotence et gestion des retries pour les opérations sensibles
- Date : 2026-01-25
@@ -593,6 +704,7 @@ Principes :
---
<a id="decision-structure-docker"></a>
## Convention de structure pour les projets Docker et les données persistantes
- Date : 2026-03-06

View File

@@ -294,7 +294,7 @@ $LEADTECH/95_a_capitaliser.md
En pratique :
- Mac : `~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md`
- NUC : `/srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md`
- NUC : `/srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md`
## Quand capitaliser

View File

@@ -98,7 +98,7 @@ 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`
- NUC : `/srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md`
## Quand capitaliser

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable analysis pattern, requirements anti-pattern, or domain insight emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 10_backend_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable analysis pattern, requirements anti-pattern, or domain insight emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 10_backend_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during architecture or technical design, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <40_decisions_et_archi.md | 10_backend_patterns_valides.md | 10_backend_risques_et_vigilance.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during architecture or technical design, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <40_decisions_et_archi.md | 10_backend_patterns_valides.md | 10_backend_risques_et_vigilance.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during implementation, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / 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 | 90_debug_et_postmortem.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during implementation, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / 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 | 90_debug_et_postmortem.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a product decision, prioritization pattern, or recurring friction is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a product decision, prioritization pattern, or recurring friction is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable test pattern, tricky bug, or quality anti-pattern is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable test pattern, tricky bug, or quality anti-pattern is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during implementation, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / 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 | 90_debug_et_postmortem.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable pattern, difficult bug fix, anti-pattern, or architecture decision emerges during implementation, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / 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 | 90_debug_et_postmortem.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a process improvement, recurring friction, or architecture decision emerges during sprint work, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a process improvement, recurring friction, or architecture decision emerges during sprint work, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable documentation pattern, writing convention, or recurring documentation friction emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_conventions_redaction.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable documentation pattern, writing convention, or recurring documentation friction emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_conventions_redaction.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable UX/UI pattern, interaction anti-pattern, or UX decision emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_ux_patterns_valides.md | 10_ux_risques_et_vigilance.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable UX/UI pattern, interaction anti-pattern, or UX decision emerges, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_ux_patterns_valides.md | 10_ux_risques_et_vigilance.md | 40_decisions_et_archi.md> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "As the orchestrating agent, when any cross-cutting pattern, process improvement, recurring friction, or architectural decision emerges across the project, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_product_patterns_valides.md | 10_ux_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: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "As the orchestrating agent, when any cross-cutting pattern, process improvement, recurring friction, or architectural decision emerges across the project, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_product_patterns_valides.md | 10_ux_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: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -18,7 +18,7 @@ critical_actions: []
# Add persistent memories for the agent
memories:
- "When a reusable test pattern, tricky bug, or quality anti-pattern is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/projects/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
- "When a reusable test pattern, tricky bug, or quality anti-pattern is identified, write a proposal to ~/AI_RULES/_Assistant_Lead_Tech/95_a_capitaliser.md (NUC: /srv/helpers/_Assistant_Lead_Tech/95_a_capitaliser.md). Format: DATE — base / FILE_UPDATE_PROPOSAL / Fichier cible: <target file> / Pourquoi: <reason> / Proposition: <content>. Never write directly to Lead_tech validated files."
# Example:
# memories:
# - "User prefers detailed technical explanations"

View File

@@ -1 +1 @@
/srv/projects/_Assistant_Lead_Tech/CLAUDE.md
CLAUDE.md

View File

@@ -6,21 +6,21 @@
# (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"
elif [ -d "/srv/helpers/_Assistant_Lead_Tech" ]; then
export LEADTECH="/srv/helpers/_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'
alias gen-claude='~/AI_RULES/_Assistant_Lead_Tech/scripts/generate_project_claude.sh 2>/dev/null || /srv/helpers/_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'
alias mkproj='~/AI_RULES/_Assistant_Lead_Tech/scripts/mkproj.sh 2>/dev/null || /srv/helpers/_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'
alias sync-ai='~/AI_RULES/_Assistant_Lead_Tech/scripts/sync-ai-instructions.sh 2>/dev/null || /srv/helpers/_Assistant_Lead_Tech/scripts/sync-ai-instructions.sh'
# Initialiser la structure BMAD dans un projet existant
alias bmad-init='"$LEADTECH/scripts/bmad-init-project.sh"'