diff --git a/00_INDEX.md b/00_INDEX.md index 0b2b58e..3e13ba9 100644 --- a/00_INDEX.md +++ b/00_INDEX.md @@ -31,6 +31,8 @@ Patterns éprouvés en production ou en projets réels. - `10_backend_patterns_valides.md` - `10_frontend_patterns_valides.md` - `10_ux_patterns_valides.md` +- `10_product_patterns_valides.md` +- `10_n8n_patterns_valides.md` --- @@ -45,15 +47,15 @@ Situations connues pouvant entraîner : - `10_backend_risques_et_vigilance.md` - `10_frontend_risques_et_vigilance.md` - `10_ux_risques_et_vigilance.md` +- `10_n8n_nodes_a_risques.md` --- -## Workflows et intégrations +## Conventions de rédaction -Procédures de travail et intégrations techniques. +Conventions de documentation et rédaction technique validées inter-projets. -- `20_workflows_README.md` -- `30_integrations_README.md` +- `10_conventions_redaction.md` --- diff --git a/10_conventions_redaction.md b/10_conventions_redaction.md new file mode 100644 index 0000000..e63a4d0 --- /dev/null +++ b/10_conventions_redaction.md @@ -0,0 +1,56 @@ +# Conventions de rédaction technique + +Ce fichier capitalise les **conventions de documentation et rédaction technique** validées +sur les projets Lead_tech : tone of voice, structure des docs, formats récurrents. + +Objectif : produire une documentation cohérente d'un projet à l'autre, +réduire le temps de rédaction et de relecture. + +Dernière mise à jour : 2026-03-08 + +--- + +## Règle d'or + +Une convention n'a sa place ici que si elle a été appliquée et validée sur au moins un projet réel. +Pas de "bonne pratique" théorique. + +--- + +## Périmètre couvert + +- Tone of voice par type de doc (API, user-facing, interne) +- Structure standard des fichiers README, CLAUDE.md, ADR +- Format des changelogs et release notes +- Conventions de nommage (fichiers, titres, sections) +- Règles de maintenance de la documentation (quand mettre à jour, quoi archiver) + +--- + +## Format standard d'une convention + +## Convention : + +- Scope : (type de document concerné) +- Règle : … +- Exemple : … +- Contre-exemple : … +- Validé le : DD-MM-YYYY +- Contexte projet : … + +--- + +## Conventions actives + +### Convention : Langue par type de document + +- Scope : tous les fichiers du repo Lead_tech et des projets +- Règle : français pour toute la documentation, commentaires de code, messages de commit. Anglais pour les identifiants de code (variables, fonctions, types). +- Validé le : 2026-03-08 +- Contexte projet : Lead_tech (convention globale) + +--- + +## Index + +_(à remplir au fil des validations)_ diff --git a/10_n8n_README.md b/10_n8n_README.md deleted file mode 100644 index 5c3b33a..0000000 --- a/10_n8n_README.md +++ /dev/null @@ -1,19 +0,0 @@ -# n8n — Règles générales - -## Objectifs - -- Automatisations fiables -- Lisibilité des workflows -- Facilité de reprise après plusieurs semaines - -## Conventions - -- Un workflow = un objectif clair -- Noms explicites pour les nodes -- Gestion des erreurs prévue dès le départ - -## Vigilance - -- Différences cloud / self-hosted -- Comportements implicites des nodes -- Expressions mal évaluées diff --git a/10_n8n_nodes_a_risques.md b/10_n8n_nodes_a_risques.md index 52a256a..705013b 100644 --- a/10_n8n_nodes_a_risques.md +++ b/10_n8n_nodes_a_risques.md @@ -11,6 +11,12 @@ Dernière mise à jour : 2025-12-19 --- +## Vigilance générale + +- Différences de comportement entre n8n **cloud et self-hosted** (certains nodes, credentials, timeouts) +- **Expressions mal évaluées** : `{{ $json.field }}` peut retourner `undefined` silencieusement +- **Comportements implicites** des nodes : toujours tester les cas limites (null, tableau vide, erreur HTTP) + ## Règles d’utilisation - On documente uniquement des cas vus en vrai (ou très probables + signalés). diff --git a/10_n8n_patterns_valides.md b/10_n8n_patterns_valides.md index 81e7a09..4773c37 100644 --- a/10_n8n_patterns_valides.md +++ b/10_n8n_patterns_valides.md @@ -10,6 +10,13 @@ Dernière mise à jour : 2025-12-19 --- +## Principes de conception + +- Un workflow = un objectif clair +- Noms de nodes explicites (décrivent ce que le node fait, pas ce qu’il est) +- Gestion des erreurs prévue dès le départ (Error Trigger ou Try/Catch) +- Facilité de reprise après plusieurs semaines : documenter les workflows non triviaux + ## Règle d’or Si ce n’est pas confirmé comme fonctionnel, **ça n’a rien à faire ici**. diff --git a/10_product_patterns_valides.md b/10_product_patterns_valides.md new file mode 100644 index 0000000..00f4a13 --- /dev/null +++ b/10_product_patterns_valides.md @@ -0,0 +1,59 @@ +# Patterns produit / métier validés + +Ce fichier contient des patterns de **cadrage produit, priorisation et analyse fonctionnelle** : + +- observés en conditions réelles, +- validés sur des projets livrés, +- utiles à réutiliser sur d'autres produits. + +Objectif : éviter de redélibérer sur des sujets déjà tranchés, capitaliser ce qui fonctionne +du point de vue product management et analyse métier. + +Dernière mise à jour : 2026-03-08 + +--- + +## Règle d'or + +Si ce n'est pas **validé par l'expérience projet**, ça n'a pas sa place ici. + +- Pas de frameworks théoriques génériques (pas de "appliquer le RICE scoring" sans contexte) +- Toujours préciser le contexte (type de produit, taille d'équipe, stade du projet) + +--- + +## Périmètre couvert + +- Patterns de cadrage et découverte (discovery) +- Priorisation et arbitrages (backlog, roadmap) +- Gestion des exigences et user stories +- Patterns d'analyse fonctionnelle récurrents +- Décisions produit structurantes validées +- Anti-patterns de pilotage produit (dans ce fichier ou dans un fichier dédié) + +--- + +## Format standard d'un pattern + +## Pattern : + +- Objectif : … +- Contexte : … +- Quand l'utiliser : … +- Quand l'éviter : … +- Avantage : … +- Limites / vigilance : … +- Validé le : DD-MM-YYYY +- Contexte produit : (obligatoire) ex. `SaaS B2B / early-stage` ou `App mobile / feature mature` + +### Description + +(comportement attendu, logique de décision, règles d'application) + +### Checklist (si pertinente) + +--- + +## Index + +_(à remplir au fil des validations)_ diff --git a/20_worklows_README.md b/20_worklows_README.md deleted file mode 100644 index da0bd41..0000000 --- a/20_worklows_README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Workflows documentés - -Chaque workflow non trivial mérite un fichier dédié. - -Objectifs : - -- comprendre rapidement la logique -- reprendre un workflow sans re-debug -- expliquer un choix technique - -Un fichier = un workflow. - ---- - -## Format recommandé pour un workflow - -Nom de fichier : - -- `20_workflows/.md` - -Contenu recommandé : - -- Objectif -- Trigger(s) -- Entrées / sorties (schéma léger) -- Logique (étapes) -- Points sensibles (rate limit, pagination, idempotence, timeouts, etc.) -- Stratégie d’erreurs (retries, dead letter, notification) -- État (En test / En prod / Deprecated) -- Liens (API docs, tickets, etc.) -- Optionnel (JSON) diff --git a/30_integrations_README.md b/30_integrations_README.md deleted file mode 100644 index db5189f..0000000 --- a/30_integrations_README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Intégrations externes - -Un fichier par service externe (API, SaaS, etc.). - -Contenu attendu : - -- auth -- limites / quotas -- pièges connus -- endpoints utiles diff --git a/70_templates/n8n_integration.md b/70_templates/n8n_integration.md new file mode 100644 index 0000000..99f595a --- /dev/null +++ b/70_templates/n8n_integration.md @@ -0,0 +1,36 @@ +# Template — Documentation d'une intégration externe (n8n) + +Un fichier par service externe. À créer dans le dossier de documentation du projet concerné. + +--- + +## Intégration : + +- **Type** : API REST | Webhook | OAuth | SDK +- **Utilisé dans** : (nom du workflow ou projet) + +### Auth + +- Méthode : (API Key / OAuth2 / Basic) +- Où stocker les credentials : (n8n Credentials / secret vault) +- Expiration / rotation : … + +### Limites et quotas + +- Rate limit : … +- Quotas : … +- Pagination : … + +### Pièges connus + +- … + +### Endpoints utiles + +| Endpoint | Méthode | Usage | +|----------|---------|-------| +| `/example` | GET | … | + +### Liens + +- Doc officielle : … diff --git a/70_templates/n8n_workflow.md b/70_templates/n8n_workflow.md new file mode 100644 index 0000000..6db68c6 --- /dev/null +++ b/70_templates/n8n_workflow.md @@ -0,0 +1,40 @@ +# Template — Documentation d'un workflow n8n + +Un fichier = un workflow. À créer dans le dossier de documentation du projet concerné. + +--- + +## Workflow : + +- **Objectif** : … +- **Trigger(s)** : (webhook / cron / manuel / event) +- **État** : En test | En prod | Deprecated + +### Entrées / Sorties + +(schéma léger : champs clés attendus en entrée, structure de sortie) + +### Logique (étapes) + +1. … +2. … + +### Points sensibles + +- Rate limits / pagination : … +- Idempotence : … +- Timeouts : … + +### Stratégie d'erreurs + +- Retries : … +- Dead letter / notification : … + +### Liens + +- API docs : … +- Tickets / contexte : … + +### Export JSON n8n + +_(optionnel — coller le JSON exporté ou lien vers fichier)_ diff --git a/70_templates/projet_CLAUDE.md b/70_templates/projet_CLAUDE.md index a5754e7..c576ab8 100644 --- a/70_templates/projet_CLAUDE.md +++ b/70_templates/projet_CLAUDE.md @@ -309,7 +309,7 @@ En pratique : DATE — PROJET FILE_UPDATE_PROPOSAL -Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> +Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_product_patterns_valides.md | 10_n8n_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 10_n8n_nodes_a_risques.md | 10_conventions_redaction.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> Pourquoi : diff --git a/95_a_capitaliser.md b/95_a_capitaliser.md index 2015e96..85c2aa7 100644 --- a/95_a_capitaliser.md +++ b/95_a_capitaliser.md @@ -12,8 +12,14 @@ vers les fichiers appropriés : - `10_backend_patterns_valides.md` - `10_frontend_patterns_valides.md` +- `10_ux_patterns_valides.md` +- `10_product_patterns_valides.md` +- `10_n8n_patterns_valides.md` - `10_backend_risques_et_vigilance.md` - `10_frontend_risques_et_vigilance.md` +- `10_ux_risques_et_vigilance.md` +- `10_n8n_nodes_a_risques.md` +- `10_conventions_redaction.md` - `40_decisions_et_archi.md` - `90_debug_et_postmortem.md` @@ -29,7 +35,7 @@ Chaque proposition doit suivre ce format : DATE — PROJET FILE_UPDATE_PROPOSAL -Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> +Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_product_patterns_valides.md | 10_n8n_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 10_n8n_nodes_a_risques.md | 10_conventions_redaction.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md> Pourquoi : diff --git a/_AI_INSTRUCTIONS.md b/_AI_INSTRUCTIONS.md index 57bd13b..7e5fb70 100644 --- a/_AI_INSTRUCTIONS.md +++ b/_AI_INSTRUCTIONS.md @@ -16,9 +16,13 @@ une solution dans leur domaine respectif. | `10_backend_patterns_valides.md` | Patterns backend validés en conditions réelles | | `10_frontend_patterns_valides.md` | Patterns frontend/mobile validés | | `10_ux_patterns_valides.md` | Patterns UX/UI validés | +| `10_product_patterns_valides.md` | Patterns produit / métier validés | +| `10_n8n_patterns_valides.md` | Patterns n8n validés | | `10_backend_risques_et_vigilance.md` | Risques et anti-patterns backend | | `10_frontend_risques_et_vigilance.md` | Risques et anti-patterns frontend | | `10_ux_risques_et_vigilance.md` | Risques et anti-patterns UX/UI | +| `10_n8n_nodes_a_risques.md` | Nodes et patterns n8n à risque | +| `10_conventions_redaction.md` | Conventions de documentation technique | | `40_decisions_et_archi.md` | Décisions techniques (mini-ADR) | | `90_debug_et_postmortem.md` | Post-mortems et bugs capitalisés | @@ -66,9 +70,13 @@ Après validation, le contenu est déplacé vers le fichier approprié : - `10_backend_patterns_valides.md` - `10_frontend_patterns_valides.md` - `10_ux_patterns_valides.md` +- `10_product_patterns_valides.md` +- `10_n8n_patterns_valides.md` - `10_backend_risques_et_vigilance.md` - `10_frontend_risques_et_vigilance.md` - `10_ux_risques_et_vigilance.md` +- `10_n8n_nodes_a_risques.md` +- `10_conventions_redaction.md` - `40_decisions_et_archi.md` - `90_debug_et_postmortem.md` diff --git a/scripts/post-bmad-install.sh b/scripts/post-bmad-install.sh index d9bb1cb..f96528d 100755 --- a/scripts/post-bmad-install.sh +++ b/scripts/post-bmad-install.sh @@ -98,16 +98,16 @@ build_memory() { echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." ;; bmm-analyst) - echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." + echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 10_backend_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." ;; bmm-pm) - echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." + echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: <10_product_patterns_valides.md | 40_decisions_et_archi.md> / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." ;; bmm-ux-designer) echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: <10_ux_patterns_valides.md | 10_ux_risques_et_vigilance.md | 40_decisions_et_archi.md> / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." ;; bmm-tech-writer) - echo "${base}, 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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." + echo "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 — ${PROJECT_NAME} / FILE_UPDATE_PROPOSAL / Fichier cible: <10_conventions_redaction.md | 40_decisions_et_archi.md> / Pourquoi: / Proposition: . Never write directly to Lead_tech validated files." ;; esac }