Pourquoi je demande un ADR avant chaque décision d'architecture

· Publié le · 1 min de lecture

Écrire un ADR suppose de ralentir au bon moment, avant de trancher.

Un ADR, Architecture Decision Record, c’est une page. Contexte, décision, conséquences. Trois paragraphes, pas plus.

L’idée vient de Michael Nygard, en 2011. Elle n’a pas pris une ride.

Ce que ça change dans une équipe

  1. On arrête de rediscuter la même décision tous les six mois.
  2. Le nouvel arrivant lit dix ADR et comprend pourquoi le code ressemble à ça.
  3. Une IA qui lit le dépôt trouve les règles du jeu : c’est un guide feedforward, gratuit.

C’est pour ça que j’en demande dans chaque équipe que je rejoins.

Le piège classique

Écrire l’ADR après coup, pour justifier une décision déjà prise.

Un ADR s’écrit avant, quand on hésite encore. S’il n’y a pas d’alternative sérieuse, il n’y a pas besoin d’ADR.

Où les ranger

Dans le dépôt, un dossier docs/adr, un fichier par décision, numéroté. Pas d’outil, pas de wiki. Le markdown suffit, et il vit avec le code.

Contrairement à une règle vérifiable par la CI, l’ADR reste une intention. Mais une intention écrite, datée, que tout le monde peut retrouver.

C’est aussi l’histoire que le code seul ne raconte pas : pourquoi cette décision, et pas une autre.

Bon designs !

Sources