Méthodologie de Documentation
Ce document décrit la méthodologie pour éditer et maintenir la documentation Bindr, qui constitue les spécifications complètes transmises à un agent de codage pour implémenter la plateforme.
🎯 Objectif
Cette documentation n'est pas un simple wiki informatif. Elle sert de contrat de spécifications pour :
- Agents de codage IA : Claude Code, Cursor, etc.
- Développeurs humains : Équipe interne ou externe
- Parties prenantes : Product owners, investisseurs, organisations partenaires
Principe fondamental : La documentation doit être cohérente, consistante et non-ambiguë pour permettre une implémentation directe sans clarifications supplémentaires.
📋 Structure documentaire
La documentation suit un ordre séquentiel strict où chaque page s'appuie sur les précédentes :
1. Concept
↓
2. Use Cases
↓
3. Diagrammes UML
↓
4. Schéma DB
↓
5. Architecture
↓
6. Roadmap
↓
7. Analyse Critique
1. Concept (Fondation)
Rôle : Définit la vision, le modèle économique, les acteurs et le périmètre fonctionnel.
Contenu clé : - Modèle B2B gratuit - 3 acteurs (Organisations, Photographes, Clients) - Commissions (30% organisations, 0% photographes) - Produits V1 (digital + impressions) - Valeur ajoutée pour chaque acteur
Règle de cohérence : - Toutes les pages suivantes doivent respecter le modèle économique défini ici - Toute modification du concept invalide potentiellement les pages suivantes
2. Use Cases (Exigences fonctionnelles)
Rôle : Décrit les 20 use cases détaillés avec données, flux, critères d'acceptation.
Contenu clé : - UC01-05 : Organisations - UC06-10 : Photographes - UC11-18 : Clients - UC19-20 : Organisations (avancé)
Règle de cohérence : - Chaque use case doit être compatible avec le Concept - Les données requises doivent être présentes dans le Schéma DB - Les flux doivent être implémentables avec l'Architecture
Validation séquentielle :
Concept → Use Cases
- Les acteurs mentionnés existent-ils dans le Concept ?
- Le modèle économique est-il respecté ?
- Les produits mentionnés sont-ils dans le Concept V1 ?
3. Diagrammes UML (Visualisation des flux)
Rôle : Représente visuellement les 20 use cases avec diagrammes de séquence Mermaid.
Contenu clé : - 1 diagramme par use case - Acteurs, interfaces, backend, base de données - Flux chronologique des interactions
Règle de cohérence : - Chaque diagramme doit correspondre exactement au use case associé - Les entités dans les diagrammes doivent exister dans le Schéma DB - Les APIs mentionnées doivent être compatibles avec l'Architecture
Validation séquentielle :
Use Cases → Diagrammes UML
- Le diagramme UC05 représente-t-il fidèlement le texte UC05 ?
- Les tables DB utilisées existent-elles dans le Schéma DB ?
4. Schéma DB (Structure des données)
Rôle : Définit le schéma complet de la base de données optimisé pour les use cases.
Contenu clé : - 9 tables avec colonnes, types, contraintes - Relations entre tables (ERD) - Scripts SQL de création - Exemples de requêtes
Règle de cohérence : - Chaque donnée mentionnée dans les Use Cases doit avoir une colonne correspondante - Les relations doivent supporter tous les flux des Diagrammes UML - Le schéma doit être normalisé (3NF minimum)
Validation séquentielle :
Use Cases → Schéma DB
- UC12 mentionne "recherche par tags" → colonne photos.tags existe ?
- UC07 mentionne "commission organisation" → table organization_product_commissions existe ?
- UC16 mentionne "adresse de livraison" → colonnes orders.shipping_* existent ?
5. Architecture (Choix techniques)
Rôle : Spécifie les technologies, versions, librairies pour implémenter la plateforme.
Contenu clé : - Backend : Java 21, Spring Boot 3.3.x - Frontend : Next.js 15+ - Infrastructure : Infomaniak Object Storage (S3), PostgreSQL, Redis - Services externes : Stripe, SendGrid, Printful
Règle de cohérence : - Les librairies doivent supporter les use cases (ex: metadata-extractor pour UC07 EXIF) - Les services externes doivent supporter le modèle économique (ex: Stripe Connect pour commissions) - Les choix techniques doivent être compatibles avec la Roadmap (ex: SQLite V1, PostgreSQL V2)
Validation séquentielle :
Use Cases + Schéma DB → Architecture
- UC07 extrait EXIF → librairie metadata-extractor listée ?
- UC14 paiement Stripe → @stripe/react-stripe-js + stripe-java listés ?
- Schéma DB PostgreSQL → PostgreSQL 16+ listé dans Architecture ?
6. Roadmap (Plan d'implémentation)
Rôle : Planifie les fonctionnalités par version (V1 MVP, V2 Growth).
Contenu clé : - V1 (3 mois) : Fonctionnalités essentielles - V2 (6-12 mois) : IA, automatisation, expansion - Timeline, budget, métriques de succès
Règle de cohérence : - Toutes les fonctionnalités V1 doivent être présentes dans Use Cases, Schéma DB, Architecture - Les fonctionnalités V2 peuvent être absentes du Schéma DB V1 mais documentées en section "Évolutions futures" - Le budget doit être compatible avec les choix d'Architecture (ex: services payants)
Validation séquentielle :
Use Cases + Architecture → Roadmap
- Roadmap V1 mentionne "FTP sur demande" → UC07 le décrit ?
- Roadmap V2 mentionne "Reconnaissance faciale" → librairie Google Vision API listée ?
- Roadmap V1 budget 38-53k€ → compatible avec infra Railway/Render ?
7. Analyse Critique (Risques et solutions)
Rôle : Identifie les 10 risques majeurs et propose des solutions.
Contenu clé : - Risques business, techniques, opérationnels - Solutions concrètes avec impacts - Critères de succès et alertes
Règle de cohérence : - Les risques doivent être basés sur les choix du Concept, Use Cases, Architecture - Les solutions doivent être implémentables avec l'Architecture définie - Les critères de succès doivent correspondre aux métriques de la Roadmap
Validation séquentielle :
Toutes les pages → Analyse Critique
- Risque "photographes non motivés (0% commission)" → cohérent avec Concept ?
- Solution "profil public photographe" → implémentable avec Schéma DB ?
- Métrique "taux conversion >1.5%" → présente dans Roadmap V1 ?
🔄 Processus de modification
Règle d'or : Modification en cascade
Toute modification d'une page invalide potentiellement toutes les pages suivantes.
Exemple 1 : Modification du Concept
Changement : "Les photographes reçoivent 10% de commission (au lieu de 0%)"
Impact en cascade :
1. Use Cases → Modifier UC19 (calcul commissions)
2. Schéma DB → Ajouter colonne photographer_access.commission_rate
3. Architecture → Ajouter logique calcul commission photographe
4. Roadmap → Ajouter coût paiements photographes au budget
5. Analyse Critique → Modifier risque "motivation photographes"
Exemple 2 : Ajout d'un Use Case
Ajout : "UC21 - Client peut laisser un commentaire sur une photo"
Impact en cascade :
1. Diagrammes UML → Créer diagramme UC21
2. Schéma DB → Créer table photo_comments
3. Architecture → Lister librairie de modération (ex: Perspective API)
4. Roadmap → Ajouter "Commentaires" en V1 ou V2
5. Analyse Critique → Ajouter risque "modération commentaires"
Workflow de modification
graph TD
A[Identifier la modification] --> B{Quelle page ?}
B -->|Concept| C[Modifier Concept]
B -->|Use Cases| D[Modifier Use Cases]
B -->|Autre| E[Modifier la page]
C --> F[Vérifier impact sur Use Cases]
F --> G[Vérifier impact sur Diagrammes UML]
G --> H[Vérifier impact sur Schéma DB]
H --> I[Vérifier impact sur Architecture]
I --> J[Vérifier impact sur Roadmap]
J --> K[Vérifier impact sur Analyse Critique]
D --> G
E --> L{Pages suivantes impactées ?}
L -->|Oui| M[Mettre à jour en cascade]
L -->|Non| N[Modification terminée]
K --> N
M --> N🤖 Claude Skill de cohérence
Un Claude Skill dédié sera créé pour automatiser la vérification de cohérence.
Fonctionnalités du Skill
1. Vérification de cohérence globale
/bindr-coherence check
Le skill vérifie : - ✅ Tous les acteurs du Concept sont utilisés dans les Use Cases - ✅ Toutes les données des Use Cases ont une colonne dans le Schéma DB - ✅ Toutes les tables du Schéma DB sont utilisées dans au moins 1 Use Case - ✅ Toutes les librairies de l'Architecture supportent les Use Cases - ✅ Toutes les fonctionnalités de la Roadmap V1 sont dans les Use Cases - ✅ Tous les risques de l'Analyse Critique sont basés sur des éléments réels
2. Vérification après modification
/bindr-coherence check-impact <page>
Exemple :
/bindr-coherence check-impact concept.md
Le skill analyse : - Quels Use Cases sont potentiellement impactés - Quelles tables DB doivent être revues - Quelles librairies doivent être ajoutées/retirées - Quel budget de la Roadmap doit être recalculé
3. Génération de rapport de cohérence
/bindr-coherence report
Génère un fichier coherence-report.md avec :
- Score de cohérence global (0-100%)
- Liste des incohérences détectées
- Suggestions de corrections
- Pages à mettre à jour en priorité
4. Validation pré-transmission
/bindr-coherence validate-for-coding
Vérifie que la documentation est prête pour un agent de codage : - ✅ Aucune ambiguïté dans les Use Cases - ✅ Schéma DB complet et normalisé - ✅ Architecture complète avec versions exactes - ✅ Roadmap V1 100% spécifiée - ✅ Aucune incohérence détectée
✅ Checklist de validation
Avant de transmettre la documentation à un agent de codage, valider :
Concept
- [ ] Modèle économique clair et chiffré
- [ ] 3 acteurs définis avec motivations
- [ ] Produits V1 listés exhaustivement
- [ ] Workflow général décrit
Use Cases
- [ ] 20 use cases documentés
- [ ] Chaque UC a : Données, Flux, Critères d'acceptation
- [ ] Liens vers diagrammes UML présents
- [ ] Aucun acteur/produit non défini dans le Concept
Diagrammes UML
- [ ] 20 diagrammes Mermaid (1 par UC)
- [ ] Chaque diagramme correspond au UC textuel
- [ ] Liens Mermaid Live Editor fonctionnels
- [ ] Entités cohérentes avec Schéma DB
Schéma DB
- [ ] 9 tables complètes
- [ ] Toutes les données des UC ont une colonne
- [ ] Relations définies (clés étrangères)
- [ ] Scripts SQL fournis
- [ ] Diagrammes ERD divisés et accessibles
Architecture
- [ ] Backend : Java 21, Spring Boot 3.3.x spécifiés
- [ ] Frontend : Next.js 15+ spécifié
- [ ] Toutes les librairies listées avec versions
- [ ] Services externes configurés (Stripe, S3, etc.)
- [ ] Standards de code définis
Roadmap
- [ ] V1 (3 mois) complète
- [ ] V2 (6-12 mois) planifiée
- [ ] Budget estimé
- [ ] Métriques de succès définies
- [ ] Timeline semaine par semaine
Analyse Critique
- [ ] 10 risques identifiés
- [ ] Solutions concrètes pour chaque risque
- [ ] Cohérent avec les choix précédents
- [ ] Critères d'alerte définis
📝 Template de modification
Lors d'une modification, utiliser ce template :
## Modification [DATE]
### Page modifiée
[Nom de la page]
### Changement
[Description du changement]
### Justification
[Pourquoi ce changement ?]
### Impact en cascade
- [ ] Concept : [Impact ou N/A]
- [ ] Use Cases : [Impact ou N/A]
- [ ] Diagrammes UML : [Impact ou N/A]
- [ ] Schéma DB : [Impact ou N/A]
- [ ] Architecture : [Impact ou N/A]
- [ ] Roadmap : [Impact ou N/A]
- [ ] Analyse Critique : [Impact ou N/A]
### Actions réalisées
- [ ] Page X mise à jour
- [ ] Page Y mise à jour
- [ ] Vérification de cohérence exécutée
- [ ] Rapport de cohérence généré
### Validation
- [ ] Aucune incohérence détectée
- [ ] Prêt pour transmission à agent de codage
🎓 Bonnes pratiques
1. Principe de vérité unique (Single Source of Truth)
Chaque information doit être définie une seule fois dans la page appropriée :
- Modèle économique → Concept uniquement
- Données utilisateur → Schéma DB uniquement
- Versions logicielles → Architecture uniquement
Les autres pages référencent cette information sans la redéfinir.
2. Traçabilité des décisions
Documenter pourquoi une décision a été prise :
<!-- Bon -->
Commission photographe : 0%
Justification : Motivation intrinsèque (passion photo) + éviter complexité fiscale V1
<!-- Mauvais -->
Commission photographe : 0%
3. Versionning des modifications
Utiliser Git pour versionner la documentation :
git commit -m "feat(concept): passage commission photographe à 10%"
git commit -m "fix(schema-db): ajout colonne photographer_access.commission_rate"
git commit -m "docs(roadmap): mise à jour budget V1 avec paiements photographes"
4. Revue par paires
Avant de valider une modification majeure : - Revue par une 2e personne - Exécution du skill de cohérence - Test de transmission à un agent IA (simulation)
🚨 Anti-patterns à éviter
❌ Modifier une page sans vérifier l'impact
Mauvais : Ajouter "UC21 - Commentaires" sans mettre à jour le Schéma DB
Résultat : Agent de codage ne peut pas implémenter (table manquante)
❌ Dupliquer l'information
Mauvais : Définir "commission photographe" dans Concept ET Use Cases ET Roadmap
Résultat : Incohérence si modifié dans une seule page
❌ Spécifications ambiguës
Mauvais : "L'utilisateur peut rechercher des photos"
Bon : "L'utilisateur peut rechercher par : tags (fulltext), heure (±15min), zone, description"
❌ Oublier la cascade
Mauvais : Modifier Architecture (PostgreSQL → MongoDB) sans adapter Schéma DB
Résultat : Scripts SQL PostgreSQL incompatibles avec MongoDB
📚 Ressources
Documentation de référence
Outils
- MkDocs Material : Documentation générée
- Mermaid Live Editor : Édition diagrammes
- Claude Skill : Vérification cohérence (à créer)
- Git : Versionning
🔮 Évolution de la méthodologie
Cette méthodologie est vivante et doit évoluer avec le projet :
V1.1 (après premiers sprints)
- Ajouter section "Problèmes rencontrés" basée sur retours agents de codage
- Affiner les critères de validation par page
- Créer templates de pages réutilisables
V2.0 (passage en production)
- Ajouter méthodologie de maintenance post-launch
- Documenter processus de gestion des bugs vs. nouvelles features
- Intégrer feedback utilisateurs finaux dans la documentation
Dernière mise à jour: 12 mars 2026 Version méthodologie: 1.1