decision/docs/dev/tdd-methode.md

Méthode de travail TDD — libreDecision

Principe fondamental

Tu décris la règle métier. Claude traduit en test. Tu valides. Claude implémente.

Jamais l'inverse. Le test est la source de vérité ; l'implémentation n'est que le moyen de le faire passer.

---

Workflow par itération

1. Tu décris une règle en français naturel
   → "Si scope=personal, la décision est toujours individuelle"

2. Claude écrit le(s) test(s) — RED (le test échoue avant l'implémentation)
   → Tu valides que le test capture bien l'intention

3. Claude implémente le minimum pour que le test passe — GREEN
   → Rien de plus que ce que le test exige

4. Claude refactorise si nécessaire — REFACTOR
   → Sans casser les tests existants

5. Répétition avec la règle suivante

---

Commandes de prompt

Commande	Action
+test	Écrire le(s) test(s) sans implémenter
+impl	Implémenter pour faire passer les tests en attente
+test+impl	Test + implémentation d'un coup (règle simple)
+règle	Ajouter une règle au moteur existant
+règle remplace	Une nouvelle règle remplace une précédente (précise laquelle)
+régression	Vérifier qu'aucun test existant n'est cassé après un changement
+résumé	Afficher l'état des règles implémentées et en attente

---

Format d'une règle métier

Pour être efficace, une règle doit préciser :

ENTRÉES :  les variables concernées et leurs valeurs
RÉSULTAT : ce que le système doit retourner ou faire
EXCEPTIONS : cas qui brisent la règle générale (si aucune, dire "aucune")

Exemple :

ENTRÉES  : scope = "personal"
RÉSULTAT : decision_type = "individual", recommend_onchain = False
EXCEPTIONS : aucune — même si stakes = "critical", une décision personnelle reste individuelle

---

Structure des tests dans ce projet

backend/app/tests/
  test_qualifier.py         ← moteur de qualification (tunnel Décider)
  test_middleware.py        ← rate limiter, CORS, headers
  test_threshold.py         ← formules WoT existantes
  test_votes.py             ← logique de vote
  test_decisions.py         ← service décisions
  ...

Chaque fichier de test correspond à un module ou un bloc fonctionnel.
Les tests d'intégration (qui touchent la DB) sont marqués @pytest.mark.integration.

---

Les 4 blocs algorithmiques

┌─────────────────────────────────────────────────────────┐
│  TUNNEL "DÉCIDER"                                        │
│                                                          │
│  1. QUALIFIER    → nature / enjeu / réversibilité        │
│        ↓                                                 │
│  2. ROUTEUR      → individual / collective / delegated   │
│        ↓                 ↓                              │
│  3. PROTOCOLE    → sélection formule WoT + paramètres   │
│        ↓                                                 │
│  4. GRAVURE      → recommandation on-chain (IPFS+remark) │
└─────────────────────────────────────────────────────────┘

Les blocs sont testés indépendamment puis en intégration.
Un changement dans le bloc 1 ne doit jamais casser silencieusement le bloc 4.

---

Invariants fondamentaux (ne jamais casser)

Ces règles doivent avoir un test dédié et rester vertes en permanence :

1. Une décision individual ne génère jamais de session de vote
2. Une décision on_chain implique toujours recommend_onchain = True
3. recommend_onchain = True requiert reversibility = "impossible" ou stakes = "critical"
4. Le qualificateur ne retourne jamais un type inconnu (enum strict)
5. Un protocole WoT sélectionné doit exister en base (slug valide)

---

Règles de régression

• Après chaque implémentation : pytest backend/app/tests/ -v --tb=short
• Avant tout commit : zéro test rouge
• Si un test existant casse après un nouveau changement → stop, analyser, ne pas contourner
• RATE_LIMIT_AUTH en dev = 60/min minimum (pas de blocage en développement)

---

Où sont les règles métier documentées

Source	Contenu
docs/dev/tdd-methode.md	Cette méthode
docs/dev/qualifier-rules.md	Règles du moteur de qualification (créé au fil des itérations)
backend/app/engine/qualifier.py	Implémentation du qualificateur
backend/app/tests/test_qualifier.py	Tests — source de vérité exécutable

---

À propos de la mémoire de contexte

Entre les sessions, Claude peut perdre le contexte des règles en cours.
Pour reprendre efficacement :

"Résume les règles du qualificateur implémentées jusqu'ici"
→ Claude lit test_qualifier.py et qualifier.py et synthétise

Les tests sont leur propre documentation. Ne pas dupliquer les règles en commentaires.