La user story qui a tout cassé
Il y a 3 ans, je travaillais sur un SaaS de gestion de stock. Le PM avait écrit cette user story :
US-42: "En tant qu'utilisateur, je veux filtrer mes produits pour trouver facilement ce que je cherche."
Le dev a passé 2 semaines à build une feature magnifique : filtres par catégorie, prix, date, couleur...
Le jour du review, le PM :
"Euh... je voulais juste une search bar. Pas tout ça."
Résultat :
- ✗ 2 semaines perdues
- ✗ Dev frustré ("pourquoi tu m'as pas dit clairement ?")
- ✗ PM frustré ("j'ai écrit une user story, t'avais qu'à lire !")
- ✗ Feature à refaire from scratch
Le problème : Les user stories sont trop vagues
La structure standard des user stories, c'est ça :
En tant que [rôle],
Je veux [action],
Afin de [bénéfice].
C'est joli sur le papier, mais ça laisse 1000 questions sans réponse :
- 🤔 Comment ça marche exactement ?
- 🤔 Qu'est-ce qui se passe si l'utilisateur fait X ?
- 🤔 Quels sont les edge cases ?
- 🤔 Comment je teste ça ?
La solution : Format Gherkin + 5 sections révolutionnaires
Voici la structure qu'on utilise chez CharliA (inspirée de ce que j'ai vu chez Google/Spotify) :
Structure User Story v2.2 (RÉVOLUTIONNAIRE)
1. User Story classique
US-42: Filtrer produits par catégorie
En tant que gérant de boutique,
Je veux filtrer mes produits par catégorie,
Afin de retrouver rapidement un produit spécifique.
2. Gherkin (Given/When/Then)
Given je suis sur la page "Produits"
When je sélectionne la catégorie "Électronique"
Then seuls les produits de catégorie "Électronique" sont affichés
And le compteur affiche "23 produits trouvés"
3. Test Scenarios (3-5 tests)
✓ Test 1: Filtrer par 1 catégorie → affiche uniquement cette catégorie
✓ Test 2: Filtrer par catégorie vide → message "Aucun produit dans cette catégorie"
✓ Test 3: Combiner filtres catégorie + prix → intersection des 2 filtres
✓ Test 4: Reset filtres → retour liste complète
4. Edge Cases (4-6 cas limites)
⚠️ Edge 1: Catégorie supprimée pendant que filtre actif → afficher erreur graceful
⚠️ Edge 2: 10,000+ produits dans catégorie → pagination automatique (50/page)
⚠️ Edge 3: Caractères spéciaux dans nom catégorie → sanitize input
⚠️ Edge 4: Offline mode → cache derniers filtres, sync au retour online
5. Tech Hints (Indices implémentation)
💡 Frontend: React Query pour cache + URL params pour persistance filtres
💡 Backend: Indexed DB query sur category_id (already indexed)
💡 Performance: Debounce 300ms si filtres multiples
💡 Accessibility: aria-label sur dropdowns, keyboard navigation (Tab + Enter)
Avant/Après : La différence qui change tout
❌ User Story AVANT (classique)
US-42: Filtrer produits
"En tant qu'utilisateur, je veux filtrer mes produits pour retrouver ce que je cherche."
Problèmes :
- • Quels filtres exactement ?
- • Comment ça marche si catégorie vide ?
- • Comment je teste ?
- • Quid de la perf si 10K produits ?
✅ User Story APRÈS (v2.2)
US-42: Filtrer produits par catégorie
Structure complète : Gherkin + 4 test scenarios + 4 edge cases + tech hints (React Query, indexed DB)
Résultats :
- ✓ Dev sait exactement quoi build
- ✓ Test scenarios = tests auto prêts
- ✓ Edge cases couverts dès le début
- ✓ Tech hints = pas de mauvaises décisions archi
Impact réel : -50% bugs, -30% dev time
Depuis qu'on utilise ce format chez mes clients, voici les métriques :
- 📉 -50% de bugs en prod (edge cases anticipés dès les specs)
- ⚡ -30% de dev time (dev ne perd pas de temps à deviner)
- 🎯 100% d'alignement PM/Dev/QA (tout le monde lit la même chose)
- 🧪 Tests auto écrits en 10 min (scenarios = tests Cypress direct)
Comment CharliA génère ces user stories
CharliA ne génère pas des user stories vagues. Chaque user story suit ce format v2.2 :
- ✅ Gherkin automatique (Given/When/Then/And)
- ✅ 3-5 test scenarios par user story
- ✅ 4-6 edge cases anticipés (offline, perf, erreurs...)
- ✅ Tech hints adaptés à ton stack (React, Vue, Angular...)
- ✅ Acceptance criteria mesurables
Template : Copie-colle ce format maintenant
US-[ID]: [Titre court de la feature]
📝 User Story
En tant que [rôle],
Je veux [action],
Afin de [bénéfice mesurable].
🥒 Gherkin
Given [contexte initial]
When [action utilisateur]
Then [résultat attendu]
And [résultat secondaire]
🧪 Test Scenarios
1. [Scénario nominal - happy path]
2. [Scénario avec données manquantes]
3. [Scénario avec données invalides]
4. [Scénario de performance (1000+ items)]
⚠️ Edge Cases
1. [Cas limite réseau/offline]
2. [Cas limite données (null, empty, huge)]
3. [Cas limite permissions]
4. [Cas limite concurrence/race conditions]
💡 Tech Hints
- Frontend: [Lib/pattern recommandé]
- Backend: [API endpoint + méthode]
- DB: [Query optimization]
- Perf: [Cache, debounce, lazy load...]
- A11y: [ARIA labels, keyboard nav]
✅ Acceptance Criteria
- [ ] Tous les test scenarios passent
- [ ] Edge cases couverts
- [ ] Tests E2E écrits (Cypress/Playwright)
- [ ] Performance <200ms (p95)
- [ ] Accessibility score >90 (Lighthouse)
Acceptance Criteria : La Clé de Voûte des User Stories
Les acceptance criteria (ou critères d'acceptation) sont ce qui transforme une user story vague en spécification testable. Sans eux, impossible de savoir quand une feature est "finie".
Qu'est-ce que les Acceptance Criteria ?
Les acceptance criteria définissent les conditions minimales qu'une feature doit remplir pour être considérée comme terminée. Ils répondent à la question : "Comment je sais que c'est fini ?"
💡 Acceptance Criteria vs Test Scenarios
Les acceptance criteria sont des règles métier ("Le panier doit afficher le total TTC"). Les test scenarios sont des cas de test ("Ajouter 3 produits → vérifier total = somme des prix").
Les 3 Types d'Acceptance Criteria
📋 Fonctionnels
Comportements attendus du système.
Ex: "Le filtre affiche uniquement les produits de la catégorie sélectionnée"
⚡ Non-fonctionnels
Performance, sécurité, accessibilité.
Ex: "Temps de réponse < 200ms (p95)"
🔒 Règles métier
Contraintes business.
Ex: "Un utilisateur gratuit ne peut créer que 3 projets"
Format INVEST pour des Acceptance Criteria de Qualité
Tes acceptance criteria doivent être INVEST :
| I | Independent | Testable isolément |
| N | Negotiable | Peut être discuté avec le dev |
| V | Valuable | Apporte de la valeur utilisateur |
| E | Estimable | Peut être chiffré en temps/effort |
| S | Small | Assez petit pour être testé rapidement |
| T | Testable | Peut être vérifié objectivement |
Exemple Complet : Acceptance Criteria en Gherkin
US-42: Filtrer produits par catégorie
✅ Acceptance Criteria :
AC1: Quand l'utilisateur sélectionne une catégorie, seuls les produits de cette catégorie sont affichés
AC2: Le compteur affiche le nombre de produits correspondant ("X produits")
AC3: Si aucun produit dans la catégorie, afficher "Aucun produit trouvé" avec lien vers toutes les catégories
AC4: Le filtre peut être combiné avec la recherche texte (intersection)
AC5: Temps de réponse < 200ms pour 1000 produits
AC6: Accessible au clavier (Tab + Enter pour sélectionner)
🚨 Acceptance Criteria ANTI-PATTERNS
- ❌ Trop vague : "Le filtre doit bien fonctionner" → Pas testable
- ❌ Trop technique : "Utiliser Redux pour state management" → C'est un détail d'implémentation
- ❌ Non mesurable : "Le filtre doit être rapide" → Rapide = combien exactement ?
- ❌ Scope creep : "Le filtre doit aussi gérer les favoris" → Nouvelle user story
Definition of Done vs Acceptance Criteria
Acceptance Criteria
Spécifiques à cette user story
- • Le filtre affiche les bons produits
- • Le compteur est à jour
- • Performance < 200ms
Definition of Done (DoD)
Applicables à toutes les stories
- • Code review passée
- • Tests unitaires écrits
- • Documentation mise à jour
- • Déployé en staging
Action item : Réécris 1 user story maintenant
Choisis la user story la plus vague de ton backlog. Celle qui fait dire "WTF" à ton dev.
Réécris-la avec ce format. Ajoute Gherkin, test scenarios, edge cases, tech hints.
Montre-la à ton dev. Il va t'aimer. Promis.
