Décisions d'architecture (ADR)¶
Ce journal consigne les décisions structurantes du projet : les choix qui engagent l'architecture ou le domaine sur la durée, et surtout pourquoi ils ont été faits. Une décision oubliée se re-débat ; écrite, elle se relit.
Ce qu'est (et n'est pas) une ADR¶
Une ADR (Architecture Decision Record) décrit une décision : son contexte, ce qui a été tranché, ses conséquences, et les pistes écartées. Elle est immuable une fois acceptée : on ne la réécrit pas, on en écrit une nouvelle qui la remplace (statut « Remplacée par ADR NNNN »).
Une ADR n'est pas :
- un compte rendu de chantier (ça, c'est le bilan, déposé dans le corps de l'EPIC à sa clôture) ;
- une description de l'implémentation (ça, c'est le code et sa Javadoc, ou Patterns et principes) ;
- une note de rappel opérationnelle (« attention au piège X ») : ces notes vivent ailleurs.
On écrit une ADR quand un chantier prend une décision qu'un développeur futur pourrait raisonnablement remettre en cause faute d'en connaître les raisons : « pourquoi ne pas simplement comparer l'empreinte ? », « pourquoi une fenêtre courte plutôt qu'une moyenne ? ».
Quand en écrire une¶
Au fil d'un chantier, à la passe 3 (doc développeur) de sa clôture : chaque décision structurante prise pendant le chantier donne une ADR. La passe 10 (bilan) s'y réfère plutôt que de dupliquer le raisonnement.
Format¶
Copier le squelette suivant dans NNNN-titre-court.md (numéro à 4 chiffres, incrémental) :
# ADR NNNN — La décision, formulée comme une affirmation
- **Statut** : Accepté — AAAA-MM-JJ
- **Chantier** : EPIC #NNNN (titre court)
## Contexte
Les forces en présence, le problème, ce qui contraint.
## Décision
Ce qui est tranché, à l'impératif.
## Conséquences
Ce que cela implique, en bien comme en moins bien.
## Alternatives écartées
Les autres pistes, et pourquoi elles ont perdu.
Journal¶
Les premières entrées sont rétroactives : elles consignent, à partir des bilans de chantier, des décisions structurantes prises avant l'ouverture du journal.
| # | Décision | Chantier |
|---|---|---|
| 0001 | Identité d'un passage reconstruit : régénération structurelle, l'acoustique en indice | #1653 |
| 0002 | Détection acoustique par énergie de pointe, pas par moyenne globale | #1653 |
| 0003 | Une feature est un plugin désactivable ; dépendances entre features = ports optionnels | #923, #1057 |
| 0004 | Pas de cycle entre features : les ponts passent par un port dans commun |
ArchUnit |
| 0005 | Réactivation par cascade de preuves ; « archivé » est un état observé | #1297 |
| 0006 | Le dépôt par ZIP est le mode par défaut ; la perte de l'audio serveur est assumée | #984, #1297 |
| 0007 | Les retours de l'API sont un type scellé ReponseApi |
#1284 |
| 0008 | Aucun échec silencieux ; la sévérité de journalisation se décide à l'émission | #1523 |
| 0009 | La nuit (soir → matin, bornée à midi) est l'unité de traitement | #664, #1696 |
| 0010 | Les dialogues bloquants (confirmation, compte rendu) sont des ports injectables | #789, #1405 |
| 0011 | La transformation audio est pilotée par le log (fréquence réelle), pas par l'en-tête | import Tadarida |
| 0012 | L'audit rend tout écart visible, mais un état normal ne crie pas | #1154 |
| 0013 | Un passage local est ancré à sa participation serveur (lien explicite) | #720 |
| 0014 | Toute capacité métier est offerte aussi en CLI (parité CLI ↔ IHM) | #619, #1304 |
| 0015 | Cartes SD de recette : specs déclaratives + générateur déterministe | #1749, #1769 |
| 0016 | La synchro rapatrie les nuits en squelettes, hydratés à la demande | EPIC #1662 |
| 0017 | L'origine d'un point (rapatrié vs manuel) est un état porté, pas déduit | #1738 |
| 0018 | La synchro rapatrie aussi l'identité de la nuit (amende 0016) | #1814 |
| 0019 | L'ancrage s'acquiert quand il sert, pas à un moment décrété (amende 0016) | #1838 |
| 0020 | Écrire sur la plateforme : ne rien inventer, ne rien effacer, parler la langue du lecteur | #1828, #1844 |
| 0021 | Le double-clic est le miroir de l'action principale, et il rend compte quand il n'aboutit pas | EPIC #1792 |
| 0022 | Le verbe d'un geste dit le sens réel de l'échange | #1855, #1866 |
| 0023 | Rendre compte se fait au bandeau ; le modal est réservé à l'irréversible | EPIC #1870 |
| 0024 | Les heures d'une nuit viennent de ses preuves ; de l'utilisateur seulement à défaut | #1860, #1878, #1892 |
| 0025 | Une capture passe par le code de production, elle ne le reconstruit pas | #1468, #1865 |
| 0026 | Le nommage des tranches est une étape du pipeline, pas un détail de la découpe | EPIC #1944 |
| 0027 | Une attente porte toujours un nom, et c'est l'étape qui va attendre qui le pose | #1931, #1951, #1959 |
| 0028 | Un état n'est pas un compte rendu, et ils ne partagent pas de canal | EPIC #1870 |
| 0031 | Un retour d'opération n'est pas un compte rendu : le mot « compte rendu » se libère pour l'extensible | EPIC #1990 |
| 0032 | Le plan de dépôt précède l'écriture des archives | EPIC #1991 |
| 0033 | Une fenêtre bornée, pas un pipeline unitaire, et deux seuils disque au lieu d'un | EPIC #1991 |
| 0034 | La forme du dépôt se choisit, elle ne se déduit pas de la place disponible | EPIC #1991 |
| 0035 | Un pictogramme d'IHM est une icône ; un caractère dans une phrase reste un caractère | #1933, #700 |
| 0036 | La copie des enregistrements bruts est une option de ré-analyse, pas un défaut | EPIC #2061 |
| 0037 | Une barre d'actions plie ; et tout texte coupé n'est pas une barre qui ne plie pas | #2012, #1641, #1873 |
| 0038 | L'échelle de sévérité compte quatre niveaux, et son ordre de déclaration porte la sémantique (amendée : elle en ignorait une seconde) | #1990, #2004, #2159 |
| 0039 | Une barre de statut dit où l'on en est, pas si c'est bien ou mal | #1990, #2004 |
| 0040 | Le sujet d'un commit est une syntaxe, pas une phrase française : le : ne prend pas d'espace |
EPIC #2104, #2105 |
| 0041 | Un check requis ne gouverne pas les PR, il gouverne la branche : le contrôle du titre reste informatif | EPIC #2104, #2106 |
| 0042 | Un aperçu qui ment est refusé, et l'exception se déclare dans la vue | #2049, #1641, #1873, #1579 |
| 0043 | La mesure fait foi en CI, pas sur le poste (amende 0037) | #1873, #2129 |
| 0044 | Le mécanisme de parallélisme se choisit sur la nature de l'attente, la borne se chiffre sur autre chose | #2040 (EPIC #2116) |
| 0045 | L'UpgradeCode et le scope de l'installeur Windows sont des constantes d'identité, figées avant la première soumission winget | EPIC #2104, #2110, #2213 |
| 0046 | Une classe CSS a une seule feuille pour maison ; un cliquet refuse tout nom en double | #1974 |
| 0047 | L'identité de distribution est le projet Echonuit : produit « VigieChiro Companion », app-id fr.echonuit, éditeur Echonuit (fait évoluer #2108) |
#2240, #2213, #2111 |
| 0048 | L'utilisateur possède ses fichiers : l'application observe la disponibilité de l'audio au lieu de l'archiver, et peut le référencer en place (reformule #1038) | #1038, #2028, EPIC #1297 |