diff --git a/.kiro/steering/spec-sync.md b/.kiro/steering/spec-sync.md index c910613..8860576 100644 --- a/.kiro/steering/spec-sync.md +++ b/.kiro/steering/spec-sync.md @@ -2,22 +2,36 @@ ## Règle -Les documents de spécification du projet — `requirements.md` (exigences fonctionnelles au format EARS) et `design.md` (conception technique) — sont la source de vérité à long terme de ce projet. Ils DOIVENT rester alignés avec le code. +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 change (nouvelle fonctionnalité, modification d'un critère d'acceptation, nouveau terme du glossaire, changement de portée comme l'ajout de l'authentification). +- `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 — c'est un journal d'implémentation, pas la source de vérité. Le mettre à jour seulement si l'utilisateur le demande. +- `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). -- Nouveau modèle de données ou migration EF Core. -- Changement de règle métier (ex. tranches de barème multiples, distance effective doublée). +- 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 @@ -27,12 +41,15 @@ Les documents de spécification du projet — `requirements.md` (exigences fonct ## Format -- `requirements.md` : conserver le format EARS (WHEN / IF / WHILE / WHERE / THE ... SHALL). Numéroter les nouvelles exigences à la suite. Ajouter au glossaire tout nouveau terme. -- `design.md` : conserver la structure existante (contraintes, décisions d'architecture, modèles, endpoints, composants). Documenter les décisions et les alternatives rejetées. +- `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 `requirements.md` et/ou `design.md` pour refléter le changement. +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.