Recette : Ajouter une nouvelle fonctionnalité

Cette recette décrit le flux de travail SDD complet pour ajouter une nouvelle fonctionnalité à un projet existant. Nous utiliserons "l'ajout de l'intégration des paiements Stripe" comme exemple fil conducteur.

Prérequis

• SpecForge installé et configuré (Démarrage rapide)
• Projet initialisé (init_project déjà exécuté, vous avez un projectId)

---

Étape 1 — Clarifier les exigences

Avant d'écrire quoi que ce soit, faites émerger les ambiguïtés.

Prompt :

Utilise specforge pour clarifier les exigences pour l'ajout de l'intégration des paiements Stripe au projet proj_abc123

Ce à quoi s'attendre : Une liste de 5–10 questions ciblées telles que :

• Doit-on supporter les paiements uniques, les abonnements ou les deux ?
• Quelles devises doivent être supportées ?
• A-t-on besoin de la génération de factures ?
• Comment les paiements échoués doivent-ils être traités — logique de retry ? notifications ?
• Quelle est la politique de remboursement et qui peut initier des remboursements ?

Répondez à ces questions dans la conversation. SpecForge intégrera les réponses dans la spec.

---

Étape 2 — Créer la spec

Prompt :

Crée une spec pour l'intégration des paiements Stripe dans le projet proj_abc123.
Exigences : paiements uniques uniquement, USD et EUR, reçu par email au succès,
webhook pour les événements de paiement, capacité de remboursement admin.

Ce à quoi s'attendre : Un HU.md complet sauvegardé dans le stockage de specs du projet avec :

• 8–15 critères d'acceptation couvrant le chemin nominal, les cas d'erreur et les cas limites
• Schéma de base de données pour les tables payments et payment_events
• Contrat UI pour le composant formulaire de paiement
• Indication ADR sur les clés d'idempotence pour les appels API Stripe
• PLAN.md avec les étapes d'implémentation

SpecForge attribue à cette spec un identifiant comme SPEC-004. Notez-le.

---

Étape 3 — Réviser et ajuster

Lisez la spec générée et affinez si nécessaire.

Prompt :

Résume la spec SPEC-004 pour le projet proj_abc123

Si quelque chose manque ou est incorrect :

Prompt :

Ajoute un critère à SPEC-004 pour le projet proj_abc123 :
"Le système doit valider les détails de carte côté client avant l'envoi à Stripe pour minimiser les charges échouées"

---

Étape 4 — Tester la spec sous pression

Prompt :

Challenge la spec SPEC-004 pour le projet proj_abc123

Ce à quoi s'attendre : SpecForge sonder pour :

• Que se passe-t-il si le webhook Stripe arrive avant la réponse API ?
• Que se passe-t-il si l'utilisateur actualise pendant le paiement ? (idempotence)
• Que se passe-t-il si le service de conversion EUR est indisponible ?
• Concurrence : deux onglets complétant le paiement simultanément

Résolvez les lacunes trouvées avant de continuer.

---

Étape 5 — Vérifier la préparation

Prompt :

Vérifie si la spec SPEC-004 est prête pour l'implémentation dans le projet proj_abc123

Cela valide :

• Tous les critères sont testables et sans ambiguïté
• Pas de dépendances bloquantes (par ex., SPEC-001 auth doit être terminée en premier)
• Conformité à la Constitution

Si ça passe, vous verrez DoR: PASSED. Sinon, corrigez ce qui est signalé.

---

Étape 6 — Estimer l'effort

Prompt :

Estime la spec SPEC-004 pour le projet proj_abc123

Ce à quoi s'attendre :

Effort : 8–13 story points
Durée : 2–4 jours (dev solo) / 1–2 jours (pair)
Coût : 640–1 040 $ à 80 $/h
Estimation tokens IA : ~45k tokens
Facteurs de risque : fiabilité des webhooks Stripe, complexité d'idempotence

---

Étape 7 — Vérification de sécurité

Puisque cette spec implique des paiements :

Prompt :

Lance une vérification de sécurité sur la spec SPEC-004 pour le projet proj_abc123

Ce qu'il faut vérifier : Mapping OWASP Top 10, surface PCI DSS, validation de signature des webhooks, gestion des clés API Stripe.

---

Étape 8 — Générer le plan d'exécution

Prompt :

Génère un plan d'exécution pour la spec SPEC-004 dans le projet proj_abc123

Cela génère un PLAN.md avec des étapes RED/GREEN/VERIFY :

## Phase 1 : Fondation (peut paralléliser 1a, 1b, 1c)
- [ ] 1a : Migration BDD — créer les tables payments + payment_events
- [ ] 1b : Définir les interfaces TypeScript pour les payloads Stripe
- [ ] 1c : Écrire les tests échouants pour PaymentService (RED)

## Phase 2 : Implémentation principale
- [ ] 2a : Implémenter PaymentService.createCheckoutSession
- [ ] 2b : Implémenter le handler webhook avec validation de signature
- [ ] 2c : Implémenter AdminRefundService

## Phase 3 : Frontend
- [ ] 3a : Construire le composant CheckoutForm avec Stripe Elements
- [ ] 3b : Implémenter le polling de statut de paiement/webhook SSE

## Phase 4 : Vérification
- [ ] 4a : Exécuter la suite de tests complète (GREEN + VERIFY)
- [ ] 4b : Tester avec les cartes de test Stripe
- [ ] 4c : Mettre à jour le statut de SPEC-004 à review

---

Étape 9 — Générer les tests

Prompt :

Génère des tests pour la spec SPEC-004 dans le projet proj_abc123

Cela produit des stubs de tests mappés à chaque critère d'acceptation — prêts à être complétés ou utilisés comme point de départ pour le TDD.

---

Étape 10 — Mettre le statut à En cours

Prompt :

Mets à jour le statut de la spec SPEC-004 à in_progress dans le projet proj_abc123

---

Étape 11 — Implémenter

Utilisez le PLAN.md comme guide d'implémentation. Votre agent IA suivra le cycle RED/GREEN/VERIFY. La spec sert de contrat — chaque critère d'acceptation doit être satisfait.

---

Étape 12 — Valider l'implémentation

Prompt :

Valide la spec SPEC-004 contre le code dans /Users/moi/mon-app/src pour le projet proj_abc123

Ce à quoi s'attendre :

Critère 1 : Création du paiement ✅ couvert
Critère 2 : Gestion du webhook ✅ couvert
Critère 3 : Flux de remboursement ✅ couvert
Critère 4 : Reçu par email ⚠️ partiellement couvert — tests manquants pour le cas d'échec
Critère 5 : Validation de devise ✅ couvert

Couverture : 90 % (1 critère nécessite attention)

Corrigez la lacune, puis revalidez.

---

Étape 13 — Marquer comme terminé

Prompt :

Marque la spec SPEC-004 comme done dans le projet proj_abc123

SpecForge valide la checklist DoD avant d'accepter la transition. Une fois terminée, la spec fait partie du dossier permanent du projet.

---

Résumé des durées

Étape	Durée typique
Clarifier + Créer	5–15 min
Challenge + Vérification préparation	5 min
Estimer + Sécurité	3 min
Générer plan + tests	5 min
Implémentation	Variable selon la spec
Valider + Marquer terminé	5 min

La surcharge SDD est de 20–30 minutes. La contrepartie est une spec prête pour la production, une conception vérifiée en sécurité et la validation que l'implémentation correspond à ce qui a été convenu.