Revue d’architecture et ADR : garder le pourquoi à côté du code

2026-10-18

Chaque base de code a une partie qui paraît fausse à la prochaine personne qui la lit. Un processus relais que personne ne se souvient d’avoir ajouté, une table vidée chaque semaine, une file d’attente là où un appel direct suffirait. Les raisons ont été données à voix haute lors d’une revue d’architecture il y a des mois, et ceux qui les ont données sont partis dans d’autres équipes. Le nouvel ingénieur a deux options : demander autour de lui pendant une semaine, ou « corriger ».

Il existe un chemin plus court. Enregistrez la revue d’architecture, appuyez sur un raccourci quand une décision, un compromis ou une option écartée est dit, et partagez l’enregistrement dans un canal Architecture. Les marques restent sur les phrases, avec l’heure et le nom de l’intervenant. Juste après la revue, un assistant IA dans Claude Code, Cursor ou Claude lit ces marques via MCP et rédige le brouillon de l’Architecture Decision Record (ADR, l’enregistrement d’une décision d’architecture) pour le dépôt. Des mois plus tard, le débat est toujours là pour quiconque demande pourquoi.

Ce guide suit l’app Speak-Y pour macOS, vérifiée le 18 octobre 2026, et s’adresse à un tech lead dont l’équipe partage déjà ses réunions dans un espace de travail. Si vous n’en avez pas encore, commencez par le créer.

Pourquoi « pourquoi est-ce construit ainsi ? » reste-t-il sans réponse ?

La solution a été décrite en 2011. L’article de Michael Nygard Documenting Architecture Decisions (vérifié le 18 octobre 2026) propose un court document pour chaque décision importante — titre, contexte, décision, statut, conséquences — conservé dans le dépôt, à côté du code. Son raisonnement correspond au problème ci-dessus : une personne qui arrive sur un projet sans savoir pourquoi une décision a été prise ne peut que l’accepter aveuglément ou la défaire aveuglément. Le site de la communauté ADR appelle l’ensemble de ces documents le journal de décisions d’un projet.

Les équipes qui adoptent les ADR perdent quand même le pourquoi, à trois endroits prévisibles :

• Le contexte est reconstitué. Le document est écrit après la revue, de mémoire, par la personne qui a le temps. Les contraintes qui ont motivé la décision sont les premières à s’effacer.
• Les options écartées se réduisent à une ligne. « Nous avons envisagé le CDC » ne dit rien de la raison pour laquelle il a perdu, et c’est exactement ce dont la personne suivante a besoin avant de le proposer à nouveau.
• Le document n’est jamais écrit. Une revue qui se termine à 16 h est en concurrence avec le code attendu pour le lendemain.

Un enregistrement conserve les trois. Les marques les rendent faciles à retrouver, et un assistant en fait un brouillon avant que les détails ne s’effacent.

À régler une fois : trois marques et un canal Architecture

Les marques. Speak-Y est livré avec un seul type de note, Marquer le moment, sur ⌥1. Ajoutez-en trois dans Paramètres → Notes : cliquez sur Ajouter un type de note, saisissez Decision dans Nom du type, cliquez sur Enregistrer, puis sur Définir le raccourci et appuyez sur ⌥2. Recommencez pour Trade-off sur ⌥3 et Rejected sur ⌥4. Chaque marque correspond à une section du document :

• Decision — ce que l’équipe a convenu de construire. Cela devient la décision de l’ADR.
• Trade-off — le coût que l’équipe a accepté en contrepartie. Cela devient les conséquences.
• Rejected — une option qui a perdu, avec la raison. Cela devient les alternatives envisagées.

Le contexte, c’est la discussion autour des marques ; l’assistant le lit dans la transcription. Le format de Nygard n’a pas de section à part pour les options rejetées ; le modèle MADR leur en donne une, Considered Options.

Le canal. Un canal public pour les revues d’architecture, nommé Architecture, que chaque ingénieur peut rejoindre. Dans le menu ⋯ de l’espace de travail, choisissez New channel. Les revues de conceptions sensibles pour la sécurité — un modèle de menaces, un flux d’authentification — vont plutôt dans un canal privé ; les compromis sont détaillés dans qui voit quoi dans les canaux de réunions.

Pendant la revue : nommez le composant, puis appuyez sur la touche

Lancez l’enregistrement d’une réunion dans Speak-Y au début de la revue. Aucun bot ne rejoint l’appel : Speak-Y enregistre le microphone et le son de l’appel sur votre Mac, et fonctionne donc de la même façon sur Zoom, Google Meet, Teams ou dans une salle de réunion. Prévenez tout le monde que la revue est enregistrée.

La transcription ne connaît que ce qui a été dit ; trois habitudes sont donc payantes :

1. Nommez le composant avant d’en parler. « Le publisher d’événements de paiement dans payments-service » rend chaque marque qui suit retrouvable par le nom qu’un ingénieur cherchera plus tard.
2. Laissez la raison être dite, puis appuyez. Une marque couvre les 15 dernières secondes de la transcription avant la touche : la phrase qui contient le parce que se retrouve dans la marque.
3. Marquez aussi les perdants. Une marque Rejected sur « les doubles écritures perdent des événements quand le service plante entre les deux » est la ligne qui fera gagner une demi-heure à la prochaine revue.

En général, c’est le tech lead qui anime la revue qui enregistre et appuie sur les touches. Les raccourcis fonctionnent depuis n’importe quelle app, avec le schéma ou le code toujours au premier plan.

Après la revue : noms, tags, To channel

Deux minutes dans la fenêtre de l’enregistrement, tant que la discussion est encore fraîche :

1. Nommez les intervenants. Cliquez sur Speaker 1, Speaker 2 et ainsi de suite, et saisissez les vrais noms. Une marque ne vaut que par le nom qui l’accompagne.
2. Taguez l’enregistrement. Ajoutez le nom du service et le numéro du document que vous allez écrire, par exemple payments-service et adr-0012. C’est grâce à ces tags que l’assistant et vos coéquipiers retrouvent la revue.
3. Vérifiez les marques. Les pastilles au-dessus de la transcription les comptent par type : Toutes les notes · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Partagez-le. Appuyez sur To channel sous la transcription et choisissez Architecture. La transcription avec les noms et les horodatages, le résumé IA et les actions à suivre passent dans le canal, chiffrés de bout en bout ; l’audio reste sur votre Mac.
5. Affichez les marques. Les marques sont privées par défaut. Cliquez sur la pastille Privées au-dessus de la transcription et choisissez Afficher dans # Architecture — les membres du canal les verront, pour que les marques accompagnent l’enregistrement.

Rédiger l’ADR à partir des marques

Connectez votre assistant au serveur MCP de Speak-Y une fois : ouvrez Connecter un assistant IA dans le menu du compte en bas de la barre latérale, ou Paramètres → Intégrations, et cliquez sur Connecter à côté de Claude, ChatGPT ou Cursor. Pour Claude, un seul clic configure à la fois Claude Desktop et Claude Code. Le serveur est gratuit avec toutes les formules.

Ensuite, dans le dépôt, demandez :

Rédige l’ADR 0012 à partir de la revue de payments-service taguée adr-0012 : contexte, décision, conséquences et options écartées. Indique qui a dit chaque point et à quel moment.

L’assistant retrouve la revue grâce à son tag et la lit. En plus de la transcription, Speak-Y lui transmet les marques sous forme de liste — chacune avec son décalage dans l’enregistrement, son type, son intervenant et les premiers mots de la phrase — si bien que le brouillon revient avec trois décisions, trois coûts acceptés et deux options écartées, chacun avec un nom et une heure. Dans Cursor, l’assistant demande l’autorisation avant d’exécuter chaque outil, sauf si vous changez ce réglage.

Relisez le brouillon avant de le commiter. Trois champs vous reviennent, pas à l’assistant :

• Le statut. Proposé ou accepté, c’est une décision d’équipe, pas quelque chose qu’une transcription peut dire.
• Le responsable. La personne qui répondra aux questions à son sujet le trimestre prochain.
• Le renvoi. Indiquez où se trouve le débat — le canal, la date et le tag — pour que le prochain lecteur puisse retracer le raisonnement. L’enregistrement est chiffré de bout en bout dans le canal : le renvoi fonctionne pour les coéquipiers de l’espace de travail, pas pour le public.

Des mois plus tard : le nouvel ingénieur demande pourquoi

L’ADR dans le dépôt répond au quoi en une page. Quand cela ne suffit pas, le débat est à un pas.

Dans l’app. Les coéquipiers que vous invitez rejoignent l’espace gratuitement avec n’importe quelle formule. Un nouvel ingénieur qui rejoint l’espace de travail voit le canal public Architecture avec son historique. Ouvrez-le, cliquez sur la loupe dans l’en-tête du canal et saisissez le nom du composant, par exemple outbox. La recherche lit les transcriptions de toutes les revues du canal et affiche les lignes correspondantes avec leurs heures.

Dans l’éditeur. Dans Cursor ou Claude Code, avec le code ouvert :

Pourquoi payments-service écrit-il les événements dans une table outbox au lieu de les publier directement dans Kafka ? Qu’est-ce qui a été écarté ?

L’assistant cherche dans les enregistrements auxquels l’ingénieur a accès, retrouve la revue et répond à partir d’elle : la décision, qui s’est opposé aux doubles écritures et pourquoi, et ce que l’équipe a accepté en échange. La même approche pour les questions de code en général est décrite dans le contexte des réunions pour le codage vocal dans Cursor.

Ce que l’enregistrement d’une revue ne remplace pas

L’enregistrement garde le raisonnement. Quatre choses vivent toujours ailleurs :

• Le schéma. Les tableaux blancs, les slides et les diagrammes de séquence ne figurent pas dans l’enregistrement. Mettez-en le lien dans l’ADR.
• Le statut final. Une marque Decision enregistre que la salle était d’accord ; savoir si la décision a été remplacée par la suite se lit dans les documents du dépôt.
• Les décisions prises dans le chat. Un choix fait dans le fil d’une pull request n’est jamais arrivé jusqu’à la revue. Écrivez-le directement dans l’ADR.
• Le code lui-même. Si le code et l’ADR se contredisent, c’est le code qui tourne. Mettez à jour le document ou le code — l’enregistrement ne vous dit que ce qui était prévu.

Limites et coûts

• Durée. Vérifié sur speak-y.com le 18 octobre 2026 : Free arrête l’enregistrement d’une réunion à 30 minutes, Pro (10 $ par mois) à 60, Pro+ (15 $) et Max (30 $) à quatre heures. Une longue séance de conception demande Pro+ ou une pause au bout d’une heure.
• Une seule personne enregistre. Deux personnes qui enregistrent la même revue produisent deux demi-listes de marques.
• Les canaux, sur Mac. Les espaces de travail et les canaux se trouvent dans l’app macOS. La création d’un espace de travail demande Pro ou une formule supérieure ; les coéquipiers le rejoignent gratuitement avec n’importe quelle formule.

En bref

Trois types de note — Decision, Trade-off, Rejected — sur ⌥2, ⌥3 et ⌥4. Pendant la revue : nommez le composant, laissez la raison être dite, appuyez sur la touche. Après : les noms, les tags, To channel → Architecture, l’affichage des marques. Ensuite, une seule question à l’assistant dans le dépôt, et vous relisez le brouillon d’ADR au lieu de l’écrire de mémoire. La page Teams présente les espaces de travail et les canaux, et un journal de décisions qui se tient tout seul applique la même idée aux décisions produit.

FAQ

Comment garder une trace des raisons d’une décision d’architecture ?

Enregistrez la revue d’architecture dans Speak-Y et appuyez sur un raccourci quand une décision, un compromis ou une option écartée est dit à voix haute. Partagez l’enregistrement dans un canal d’équipe comme Architecture. Le canal garde le débat avec les noms et les horodatages, et un assistant IA connecté via MCP peut transformer les marques en brouillon d’Architecture Decision Record pour le dépôt.

Claude Code ou Cursor peuvent-ils rédiger un ADR à partir de l’enregistrement d’une réunion ?

Ils peuvent rédiger un brouillon. Connecté au serveur MCP de Speak-Y, l’assistant retrouve la revue grâce à son tag, lit la transcription et la liste des marques avec leur type, leur heure et leur intervenant, et remplit le contexte, la décision, les conséquences et les options écartées. Le statut, le responsable et la formulation finale restent à l’ingénieur qui commite le fichier.

Comment un nouvel ingénieur découvre-t-il pourquoi un service est construit d’une certaine façon ?

De deux façons. Ouvrez le canal Architecture dans l’app Speak-Y pour macOS et cherchez-y le nom du composant, ou demandez à un assistant dans l’éditeur, comme Cursor ou Claude Code, pourquoi le service fait ce qu’il fait. L’assistant cherche dans les enregistrements auxquels l’ingénieur a accès et répond avec qui a dit quoi, et quand.

Speak-Y enregistre-t-il le tableau blanc ou les schémas montrés pendant la revue ?

Non. Speak-Y enregistre l’audio du Mac qui lance l’enregistrement : le microphone et le son de l’application d’appel. Les schémas, les slides et les tableaux blancs ne figurent pas dans l’enregistrement. Dites le nom du composant à voix haute avant d’en parler, et mettez le lien vers le schéma dans l’ADR.

Combien coûte cette configuration ?

Le serveur MCP est gratuit avec toutes les formules. La création d’un espace de travail d’équipe demande Pro ou une formule supérieure, et les coéquipiers le rejoignent gratuitement avec n’importe quelle formule. Vérifié sur speak-y.com le 18 octobre 2026 : Free arrête l’enregistrement d’une réunion à 30 minutes, Pro (10 $ par mois) à 60, et Pro+ (15 $) et Max (30 $) à quatre heures.