---
description: Conventions de rédaction des spécifications Circuy. S'applique aux documents du dossier specifications, notamment au cahier des charges technique.
globs: specifications/**/*.md
alwaysApply: false
---

# Rédaction des spécifications Circuy

`specifications/functional/` est la source du besoin et ne se modifie pas sans demande explicite. `specifications/technical/` est le cahier des charges technique, rédigé chapitre par chapitre.

## Ce qu'un chapitre doit contenir

- **Des décisions, pas des options.** Un chapitre tranche. Les alternatives écartées vivent dans le registre d'ADR, pas dans le corps du texte.
- **Des contrats exploitables** : formes JSON, signatures d'endpoints, colonnes et contraintes SQL. Un développeur doit pouvoir implémenter sans deviner.
- **Des chiffres quand une contrainte est énoncée.** « Rapide » ne veut rien dire ; une cible chiffrée et sa méthode de mesure, oui.

## Ce qu'un chapitre ne doit pas contenir

- Du code d'implémentation complet. Les extraits illustrent un contrat ou une forme de données, ils ne sont pas la solution.
- Des fonctionnalités absentes du besoin fonctionnel, introduites « pour plus tard ».
- Des couches, services ou dépendances supplémentaires sans ADR justifiant l'ajout.
- Des tableaux comparatifs de technologies : le choix est fait, sa justification tient en un ADR.

## Format des ADR

Un ADR fait une dizaine de lignes et suit toujours la même trame : le problème, la décision, l'alternative ennuyeuse rejetée et pourquoi, le coût opérationnel accepté. Il porte un identifiant stable (`ADR-01`, `ADR-02`) référencé depuis les chapitres.

## Forme

- Français, sans emoji, titres numérotés en miroir des chapitres fonctionnels.
- Un fichier par chapitre, nommé comme son homologue fonctionnel.
- Lisible par un humain fatigué à 3 h du matin : phrases courtes, aucun terme non défini au premier usage.