De RFC à ADR : Prendre la décision et conserver le raisonnement

La décision que personne ne pouvait reconstruire

Le nouveau responsable technique pose une question raisonnable : pourquoi chaque service communique-t-il avec le système de facturation via cette file d'attente ? Il y a un ADR — ADR-014, quatre phrases, rédigé il y a onze mois. Contexte : "nous avions besoin d'une intégration de facturation fiable." Décision : "utiliser la file d'attente." Conséquences : "une certaine latence ajoutée." C'est techniquement un enregistrement. Cela ne répond à rien.

Vous étiez là, donc vous savez ce que dit pas ADR-014 : l'argument de trois semaines à travers deux canaux Slack et un fil de discussion PR animé ; l'option API synchrone qui a perdu à cause d'une limite de taux qui a depuis été augmentée ; l'objection de l'ingénieur du personnel qui a été répondue par un benchmark que personne ne peut retrouver maintenant. Le débat a eu lieu. Le compte rendu a été écrit ensuite, de mémoire, par une personne, un vendredi.

C'est le mode de défaillance documenté, presque universel, d'une pratique véritablement bonne. Les recommandations prescriptives d'AWS et les documents Well-Architected de Microsoft recommandent tous deux les ADR — et notent tous deux la douleur : les maintenir à jour prend du temps, et les gérer devient complexe à mesure que les équipes et les choix se multiplient. La cause profonde est structurelle : le débat et le dossier vivent à des endroits différents, donc le dossier est toujours une transcription avec perte. La solution est de les rendre au même endroit. La pratique n'est pas spécifique à l'ingénierie, ni même spécifique aux ADR. Google exige un dossier de conception — problème, approche proposée, alternatives considérées, compromis — écrit et examiné avant que des travaux techniques significatifs ne commencent, une pratique énoncée dans le propre Software Engineering at Google de l'entreprise. C'est la même discipline qu'un ADR, appliquée une étape plus tôt : l'ADR enregistre le choix qu'un dossier de conception a argumenté. Les deux échouent de la même manière pour la même raison, et les deux sont corrigés par le même mouvement — tenir l'argument là où le dossier vit, plutôt que de transcrire l'un dans l'autre par la suite. Lisez chaque étape ci-dessous comme couvrant les deux artefacts.

Pourquoi les ADR se détériorent

Une phrase tirée du matériel de la communauté ADR porte tout le diagnostic : un RFC concerne généralement l'atteinte d'un accord ; un ADR enregistre l'accord une fois atteint. Deux artefacts, deux moments — et tout ce qui se trouve entre eux fuit. Les alternatives qui étaient "évidemment" fausses ne sont pas enregistrées (jusqu'à ce qu'elles cessent d'être évidentes). L'objection qui a façonné le design final survit uniquement en tant que commentaire PR sur un fil fermé. La section contexte est écrite en dernier, de manière médiocre, par celui qui a perdu le jeu du "pas moi". Les réunions qui auraient dû produire des décisions produisent des résumés à la place, et le raisonnement qui rend une décision durable — la chose sur laquelle toute la chaîne de qualité des décisions dépend — est exactement ce que la transcription laisse de côté.

Étape 1–3 : La proposition, le contexte, les options

1. 1Énoncez la proposition comme la revendication principale — la décision proposée, pas une question : "Nous acheminerons toutes les écritures de facturation via une file d'attente durable." Cette phrase est le titre de l'ADR futur. Point de contrôle : la racine existe, une phrase, rédigée par le proposeur.
2. 2Contexte en tant qu'arguments pro séparés. Chaque force qui rend la décision nécessaire — l'exigence de fiabilité, la limite de taux du système de facturation, le mandat d'audit — est son propre argument sous la racine. Un paragraphe "Contexte" monolithique ne peut pas être contesté ; trois revendications de contexte séparées peuvent chacune être remises en question, confirmées ou rejetées individuellement. Point de contrôle : ≥2 arguments de contexte, chacun une force.
3. 3Chaque option a son propre nœud. La file d'attente, l'API synchrone, le travail par lots — des arguments frères, chacun avec ses propres avantages et inconvénients. Les avantages/inconvénients sont relatifs au parent, donc les inconvénients d'une option dépendent de cette option, et non de la décision. Incluez les options que vous vous attendez à rejeter : le frère rejeté est ce qui répondra à la question de l'année prochaine "pourquoi n'avons-nous pas simplement...". Point de contrôle : chaque option sur laquelle un lecteur pourrait s'interroger existe.

Étape 4–6 : Le tour RFC qui laisse une trace

Maintenant, le tour de révision — normalement la partie qui se disperse dans les discussions, les commentaires et les couloirs. Ici, cela se déroule sous trois types d'échanges structurés, chacun étant un dialogue en quatre tours entre un évaluateur et l'auteur de l'option :

Étape 7 : Décider — et ce que la note n'est pas

Les décideurs évaluent les options : une étiquette de notation pour chacune. La distribution est une preuve authentique — où la salle se tenait, sur le registre, avant l'appel. Mais la notation n'est pas la décision. Un humain nommé décide toujours, et si l'appel va à l'encontre de la distribution, le nœud de décision est l'endroit où cela est expliqué. (Qui devrait être cet humain nommé, et comment attribuer le rôle avant le débat plutôt qu'après, est une discipline à part entière — voir le tutoriel sur les droits de décision.)

Étape 8–9 : L'ADR que vous n'avez pas eu à rédiger

Voici le résultat. L'enregistrement est pas un document que vous rédigez par la suite — c'est le nœud de l'option choisie plus tout ce qui y est déjà attaché : les arguments de contexte (Contexte), les frères et sœurs rejetés (Options Considérées), les chaînes complètes (la discussion, avec les auteurs), les évaluations (où en était la salle), et l'argument de décision avec sa justification (Décision). Rien n'est transcrit, donc rien n'est perdu dans la transcription.

1. 1Enregistrez les conséquences que vous acceptez. Les inconvénients connus — la latence supplémentaire, le fardeau opérationnel de la file d'attente — continuent en tant qu'enfants con de l'option choisie, reconnus par le décideur. Les écrire est ce qui en fait une décision plutôt qu'une préférence. Point de contrôle : ≥1 conséquence acceptée sur le registre.
2. 2Exportez si votre organisation nécessite des ADR suivis par le dépôt. Beaucoup le font, à juste titre — l'ADR en markdown à côté du code reste l'artefact de conformité. Rédigez le résumé en quatre sections à partir de l'arbre (cinq minutes, pas un vendredi), renvoyez à la discussion pour le débat complet. Point de contrôle : l'ADR du dépôt cite l'arbre ; l'arbre contient le raisonnement.

Désaccord et engagement, sur le registre

Le modèle qu'Amazon a rendu célèbre — désaccord et engagement — a un problème de lisibilité : comment savoir plus tard que le désaccord était réel, entendu et répondu, plutôt que simplement écrasé ? La mécanique de la chaîne y répond. Une chaîne de révision qui a effectué ses quatre tours complets et s'est terminée sans accord est précisément le reçu : l'objection a été formulée, répondue, pressée et à nouveau répondue, dans les archives, avant que le dissident ne s'engage. Le dissident est documenté comme ayant été entendu — ce qui rend l'engagement ultérieur raisonnable plutôt que simplement obéissant.

Étape 10 : Remplacer sans supprimer

L'âge des décisions. Lorsque la limite de taux qui a tué l'option synchrone est augmentée, le bon choix est une nouvelle décision qui fait référence à celle qu'elle remplace — un nouvel argument lié au nœud de l'ADR-014, indiquant ce qui a changé. L'ancienne décision reste lisible ; son raisonnement est exactement la raison pour laquelle la nouvelle décision sait ce qu'elle annule.

Un écart honnête à gérer explicitement : il n'y a pas de champ de statut ADR intégré. Proposé / accepté / remplacé n'est pas un état de première classe sur un argument — le remplacement est modélisé par le lien, et la convention vous appartient de la maintenir. Énoncez-le dans l'accord de travail de votre équipe plutôt que de supposer que le produit l'impose.

Limitations honnêtes

• ✗Cela ne remplace pas les ADR dans votre dépôt si votre organisation les exige versionnés à côté du code. Exportez et engagez le résumé ; utilisez l'arborescence pour la partie où le markdown est mauvais — le débat.
• ✗Aucun champ de statut ADR. Proposé/accepté/supplanté est une convention de liaison que vous maintenez, pas quelque chose que le produit impose.
• ✗Une chaîne est composée de quatre tours. Un profond désaccord architectural nécessitera un appel ; la chaîne est l'enregistrement de ce qui a déjà été essayé auparavant.
• ✗Les évaluations sont une valeur unique étiquetée, pas un score multi-critères pondéré.
• ✗Cela ne fait écrire à personne un bon contexte. La structure réduit le coût d'un bon enregistrement ; elle ne fournit pas le jugement.

Leçons pratiques

• ✓Un RFC, une discussion. Résistez à l'arbre méga couvrant l'architecture de tout le quartier — les liens de supersession connectent les décisions mieux que l'imbrication ne le fait.
• ✓Semence de ce qui existe. Un procès-verbal chargé de décisions ou votre ancien dossier ADR, extrait, donne un bon départ au débat — étiqueté comme importé, afin que les arguments en direct restent distincts.
• ✓Mettez les noms des évaluateurs sur leurs chaînes et laissez-les là. L'attribution est la responsabilité ; les objections architecturales anonymes se transforment en folklore.
• ✓La section des conséquences appartient au décideur, à personne d'autre. Les inconvénients acceptés écrits par la personne qui les a acceptés ont un poids différent de celui des avertissements d'un examinateur.

ADR-014, la version qui répond

Revenons à la question du nouveau responsable technique. Dans la version reconstruite, l'ADR-014 est un nœud : la décision de la file d'attente avec sa justification, trois forces contextuelles (dont une maintenant obsolète — visiblement), un frère de l'API synchrone rejeté dont le nom fatal mentionne l'ancienne limite de taux, quatre chaînes de révision complètes, y compris celle de l'ingénieur responsable, et le benchmark attaché comme preuve. Le responsable technique lit pendant dix minutes, voit que la limite de taux a changé, et ouvre une proposition de remplacement liée à l'ancien nœud. Personne n'excave Slack. C'est toute la promesse : les chaînes atteignent l'accord, l'arbre l'enregistre — et l'enregistrement répond à des questions auxquelles vous ne saviez pas qu'il serait posé.