SchotzIAD/.kiro/steering/spec-sync.md

Synchronisation des specs avec le code

Règle

Les documents de spécification du projet sont la source de vérité à long terme. Ils DOIVENT rester alignés avec le code.

Le projet sépare la spécification selon deux axes :

• Axe exigences (le « quoi ») :
  • requirements.md : exigences fonctionnelles métier au format EARS (attendu fonctionnel, mode opératoire, règles de gestion fournis par le PO business).
  • design-requirements.md : exigences techniques dérivées (rendu visuel détaillé, API externes et URL, codes HTTP précis, délais/débounce, sécurité, cache, fallbacks, rendu cartographique et documentaire), arbitrées conjointement par le PO business et le PO IT. Ce document est organisé en miroir de requirements.md : chaque section reprend le même numéro et le même titre, suivi de « — aspects techniques ». Seules les exigences comportant effectivement des critères techniques y figurent.
• Axe conception (le « comment ») :
  • design.md : conception technique qui met en œuvre les exigences des deux documents ci-dessus (architecture, modèles de données, endpoints, composants, décisions et alternatives rejetées).
• Journal :
  • tasks.md : journal d'implémentation, pas une source de vérité.

À chaque évolution fonctionnelle ou technique validée par l'utilisateur (« ça fonctionne », « tu peux committer »), mettre à jour les specs concernées dans le même commit que le changement de code, avant de committer.

Portée

• requirements.md : mettre à jour dès qu'un comportement observable métier change (nouvelle fonctionnalité, modification d'un critère d'acceptation fonctionnel, nouveau terme du glossaire métier, changement de portée comme l'ajout de l'authentification).
• design-requirements.md : mettre à jour dès qu'une exigence technique change ou est ajoutée (nouveau code HTTP, nouveau délai/débounce, nouvelle API externe, règle de sécurité, politique de cache, détail de rendu visuel). Conserver le miroir numéroté avec requirements.md : même numéro et même titre + « — aspects techniques ». Lorsqu'une exigence métier nouvelle ou modifiée a un pendant technique, mettre à jour les DEUX documents de façon cohérente ; ajouter tout terme technique au glossaire technique.
• design.md : mettre à jour dès qu'une décision d'architecture, un modèle de données, un endpoint d'API ou un composant important change.
• tasks.md : facultatif — le mettre à jour seulement si l'utilisateur le demande.

Note sur les specs séparées : certaines fonctionnalités disposent de leur propre spec autonome (ex. precision-distances-km, avec ses propres requirements.md/design.md). Lorsque le détail complet d'un sujet vit dans une spec séparée, la spec principale y renvoie par référence croisée plutôt que de dupliquer le contenu ; garder ces renvois cohérents lors d'une évolution.

Ce qui déclenche une mise à jour de spec

• Nouvelle capacité (ex. aller/retour, authentification, consultation par mois).
• Changement de contrat d'API (nouveau champ DTO, nouvel endpoint, changement de statut HTTP) → design-requirements.md (code HTTP) et/ou design.md (endpoint).
• Nouveau modèle de données ou migration EF Core → design.md.
• Changement de règle métier (ex. tranches de barème multiples, distance effective doublée) → requirements.md.
• Nouveau détail technique observable (délai, débounce, URL d'API, en-tête, fallback, rendu) → design-requirements.md.
• Changement de portée du produit (ex. passage de mono-utilisateur sans compte à compte unique authentifié).

Ce qui ne déclenche PAS forcément une mise à jour

• Ajustements purement cosmétiques (couleurs, espacements) sans exigence associée.
• Refactorisations internes sans effet observable et sans changement de décision d'architecture.

Format

• requirements.md et design-requirements.md : conserver le format EARS (WHEN / IF / WHILE / WHERE / THE ... SHALL). Numéroter les nouvelles exigences à la suite. Conserver le miroir numéroté entre les deux documents. Ajouter au glossaire approprié (métier ou technique) tout nouveau terme.
• design.md : conserver la structure existante (overview, périmètre, contraintes, décisions d'architecture, modèles, endpoints, composants, propriétés). Documenter les décisions et les alternatives rejetées.
• Valider le format avec l'outil de validation de spec après édition.

Workflow au moment du commit

1. Implémenter le changement de code et le faire valider par l'utilisateur.
2. Mettre à jour les specs concernées pour refléter le changement :
   • comportement métier → requirements.md ;
   • détail technique observable → design-requirements.md (en conservant le miroir avec requirements.md) ;
   • architecture / modèle / endpoint / composant → design.md.
3. Committer code + specs ensemble, avec un message décrivant les deux.