Discuter de l'architecture là où elle vit

Quelqu'un remarque que Billing écrit directement dans la base de données du ledger, alors que l'ADR-12 dit que seule la Ledger API en a le droit. La question part dans un thread Slack. Deux réponses, un « bien vu, je regarde », et à midi le thread est sorti de l'écran. Un mois plus tard, la flèche est toujours sur le diagramme, l'ADR-12 se lit toujours comme si personne ne l'avait jamais remise en question, et la personne qui avait dit « je regarde » a changé d'équipe. La question a été posée et a reçu une réponse, à un endroit que l'architecture ne voit pas.

C'est le manque sur lequel nous avons travaillé cette semaine. Le 18 octobre, nous avons livré six fonctionnalités qui déplacent la conversation sur l'architecture dans le modèle lui-même : des commentaires épinglés sur le diagramme, les @mentions, les citations avec # et une liste « Cité dans », les aperçus de liens dans l'application et dans Slack, le suivi et les tâches. Chacune rattache une discussion à l'élément, à la décision ou à la page dont elle parle, et toutes remontent dans la boîte de réception ajoutée le 10 octobre.

La même question, posée dans le modèle

Reprenons cette question sur le ledger, avec ce qui vient d'être livré. Les noms et le projet sont des exemples. Le comportement est celui du produit.

Marie l'épingle là où elle la voit. Elle relit le projet Checkout au niveau container. Elle appuie sur C, le curseur devient une croix, et elle clique sur la flèche qui va de Billing à Ledger DB. Une zone de commentaire s'ouvre à mi-chemin de la relation, et elle écrit :

Billing writes to Ledger DB directly here. #ADR-12 says ledger writes
go through the Ledger API. @Sam, is this still intended?

Taper # a ouvert une liste des éléments, décisions et pages du projet, et ADR-12 est devenu une puce qui ouvre la décision. Taper @ a listé les personnes qui peuvent ouvrir le projet, et Sam, responsable de Billing, est devenu une puce lui aussi. Elle appuie sur ⌘ Enter. La bulle reçoit un numéro, #7, et tous ceux qui ouvrent cette vue du diagramme la voient.

Sam est prévenu. Sa cloche indique que Marie l'a mentionné, avec son commentaire en extrait. Il n'a pas besoin de surveiller le diagramme, ni d'être dans le bon canal Slack, pour l'apprendre.

La réponse devient une tâche. Sam répond que c'est un reste de la migration du ledger et qu'il va le faire passer derrière la Ledger API. Marie, qui a lancé la discussion, reçoit sa réponse dans sa boîte de réception. Elle ouvre la discussion complète, clique sur Tâche sous la réponse de Sam, la lui assigne, choisit vendredi comme échéance et clique sur Créer la tâche. Une case à cocher apparaît sous la réponse, et la tâche arrive dans l'onglet À faire de la boîte de réception de Sam.

La décision se souvient d'avoir été questionnée. Ouvrez l'ADR-12 : le bas de sa carte dépliée liste désormais le commentaire de Marie sous Cité dans, avec le texte autour de la citation. La prochaine personne qui lit la décision apprend que la base qu'elle protège recevait encore des écritures, et peut cliquer jusqu'à la discussion.

Le correctif s'annonce de lui-même. Sam remplace la flèche via une demande de changement. Sa description cite #ADR-12 et colle le lien vers la discussion #7, qui s'affiche en carte d'aperçu sous le texte. Tous ceux qui peuvent modifier le projet sont prévenus qu'une demande de changement a été ouverte, comme avant. Léa, de l'équipe données finance, ne peut pas la relire, mais elle suit le projet Checkout, donc elle reçoit une ligne elle aussi : une demande de changement ouverte dans un projet suivi notifie les abonnés qui ne peuvent pas la relire.

La boucle se referme. Sam coche la tâche. Marie, qui l'a créée, reçoit « Sam a terminé une tâche que vous avez créée ». Elle résout la #7 et la bulle disparaît du diagramme. Quand Sam colle le lien de la demande de changement dans #payments, le bot Archyl le déplie avec son titre, son statut et son projet.

Chaque morceau de cet échange est rattaché à quelque chose dans le modèle : la relation, la décision, le responsable, la demande de changement. Rien ne dépend de quelqu'un qui se souviendrait de l'endroit où se trouvait un thread.

Ce que fait chaque fonctionnalité

Commentaires sur le diagramme

Appuyez sur C, ou cliquez sur Commenter dans la barre en bas du diagramme, puis cliquez là où le commentaire doit se trouver :

  • sur un espace vide, la bulle reste à cet endroit ;
  • sur un élément, elle y est rattachée et le suit quand il bouge, et la discussion apparaît aussi dans le panneau de détails de l'élément ;
  • sur une relation, elle se place à mi-chemin de celle-ci.

Les bulles sont numérotées par projet et gardent la même taille quel que soit le zoom. Chacune appartient au niveau et à la vue où elle a été placée, donc un commentaire sur le system context n'apparaît pas à l'intérieur d'un système. Les bulles résolues sont masquées ; cochez Afficher les résolus en mode commentaire pour les voir grisées. Pour le reste, une discussion épinglée est une discussion ordinaire : elle figure dans la liste des discussions du projet, et ses réponses notifient les personnes qui y participent. Docs : Commentaires sur le diagramme.

@mentions

Tapez @ dans un commentaire ou une réponse, dans le contexte, la décision ou les conséquences d'un ADR, dans une page de documentation, ou dans la description, un commentaire ou une relecture d'une demande de changement. La liste affiche les personnes qui peuvent ouvrir le projet et les équipes qui en comptent au moins une. Mentionner une équipe atteint ceux de ses membres qui peuvent ouvrir le projet.

Chaque personne est prévenue une fois : modifier à nouveau le texte ne notifie personne qui était déjà mentionné. Les mentions dans un titre ne sont pas détectées, écrivez-les donc dans le corps. Quand nous avons livré la boîte de réception, les mentions étaient en tête de sa liste « ce qu'elle ne fait pas encore ». Elles sont là maintenant. Docs : Mentions, citations et liens.

Citations avec # et « Cité dans »

Tapez # aux mêmes endroits pour citer un système, un container, un component ou un élément de code (chacun affiché avec son parent), une décision (listée sous la forme ADR-3 avec son titre) ou une page de documentation. Cliquer sur la puce ouvre ce qu'elle cite. Un élément s'ouvre dans le diagramme à son propre niveau, déjà sélectionné.

L'autre moitié, c'est le lien retour. Chaque élément, décision et page liste les endroits où il est cité, du plus récent au plus ancien, avec l'extrait autour de chaque citation : dans la section Cité dans du panneau de détails d'un élément, en bas de la carte dépliée d'une décision, en bas d'une page. C'est la partie qu'un thread Slack ne peut pas vous donner. La conversation pointe vers l'ADR, et l'ADR pointe en retour.

Aperçus de liens, dans Archyl et dans Slack

Copier le lien se trouve dans le panneau de détails d'un élément, sur chaque carte de décision et en haut de chaque page de documentation. Un lien vers un élément ouvre l'élément à son niveau, sélectionné. Les demandes de changement et les discussions se partagent depuis la barre d'adresse.

Collez un lien Archyl dans un commentaire, la description d'une demande de changement ou une relecture, et il s'affiche en carte sous le texte : titre, type et statut, projet et un extrait. Jusqu'à trois liens par message ont un aperçu, et seulement pour les personnes qui peuvent ouvrir le projet. Les autres voient un lien simple.

Dans Slack, le bot déplie désormais les liens vers un projet, un élément, une décision, une page de documentation, une demande de changement ou une discussion dans le même aperçu. Il suit les règles que le bot avait déjà. L'aperçu est construit avec les permissions de l'admin qui a connecté le workspace, uniquement pour les projets de l'organisation à laquelle le workspace est connecté, et dans un canal restreint, un lien vers un projet hors du périmètre reste un lien simple. Un lien vers quelque chose qui n'existe pas, ou que le bot ne peut pas voir, reste lui aussi simple, si bien qu'un aperçu ne confirme jamais qu'une page existe. Docs : Aperçus de liens dans Slack.

Le suivi

Suivez un élément, une décision ou un projet entier avec la cloche du panneau de détails de l'élément, de la carte de la décision ou de la barre d'outils du diagramme. Une cloche pleine signifie que vous suivez. Les responsables d'un élément le suivent sans rien faire, tout comme les membres d'une équipe qui en est responsable. Cliquez sur la cloche pour vous désabonner et Archyl s'en souvient, même si vous restez responsable de l'élément.

Les abonnés sont prévenus quand ce qu'ils suivent est modifié ou supprimé (la notification liste les champs qui ont changé), quand un élément suivi reçoit un commentaire, et quand une demande de changement touche un élément suivi. Les abonnés d'un projet sont aussi prévenus quand un élément, une décision ou une page est ajouté. Suivre ne donne pas d'accès : perdez l'accès au projet et les notifications s'arrêtent. Docs : Suivi.

Les tâches

Sous n'importe quel commentaire ou réponse d'un projet, cliquez sur Tâche, choisissez un assigné parmi les personnes qui peuvent ouvrir le projet (vous, par défaut), éventuellement une échéance, et cliquez sur Créer la tâche. Un commentaire porte au plus une tâche. La tâche s'affiche sous son commentaire avec une case à cocher, l'assigné et l'échéance, qui passe en rouge une fois dépassée. Supprimer la tâche conserve le commentaire.

Vos tâches ouvertes sont dans l'onglet À faire de la boîte de réception, les plus proches de l'échéance en premier, avec un compteur sur l'onglet. Le panneau de détails de chaque élément a une section À faire qui liste les tâches de toutes ses discussions. L'assigné est prévenu quand une tâche est créée pour lui ou lui est réassignée, et le créateur est prévenu quand quelqu'un d'autre la termine. Docs : Tâches.

Les agents aussi peuvent taguer

Les agents de code connectés via le serveur MCP écrivent dans le même modèle : ils ouvrent des demandes de changement, consignent des décisions, laissent des commentaires. Jusqu'ici, un agent qui écrivait « @Sam, tu peux confirmer ? » produisait du texte brut qui ne prévenait personne.

Désormais, le serveur lit ce qu'écrit un agent comme le font les sélecteurs dans l'app. Dans un commentaire, un ADR, une page de documentation ou une demande de changement :

  • @Name mentionne une personne ou une équipe, prévenue dans sa boîte de réception comme pour n'importe quelle autre mention. L'agent peut appeler list_mentionables pour obtenir les noms exacts.
  • #Label cite un élément C4, une décision (#ADR-12) ou une page, qui liste alors le texte de l'agent sous Cité dans.

Un commentaire posté par un agent atteint aussi les personnes qui participent déjà à la discussion et les abonnés de l'élément, comme celui posté par une personne. Chaque écriture indique à l'agent ce qui a été lié, pour qu'il puisse vérifier que @Sam a bien atteint Sam.

Les agents peuvent aussi relire les liens. get_backlinks renvoie les endroits où un élément, une décision ou une page est cité. Avant de toucher à Ledger DB, un agent peut retrouver le commentaire #7 de Marie et la demande de changement qui citait l'ADR-12, au lieu de redécouvrir la question.

Suivre sans se noyer

Le suivi va à l'encontre de la règle que nous avons fixée pour la boîte de réception : elle ne contient que ce qui vous attend ou ce qui répond à quelque chose que vous avez fait. Un élément suivi qui change ne vous attend pas. Nous l'avons laissé entrer parce que vous l'avez demandé, en cliquant sur la cloche ou en étant responsable de l'élément, et nous avons limité le bruit qu'il peut faire :

  • Déplacer un élément ou changer son style ne notifie personne.
  • Plusieurs modifications de la même chose en une heure donnent une seule notification, tant que vous ne l'avez pas lue.
  • Si vous suivez un projet mais pas l'élément, vous recevez au plus une notification de chaque type par heure pour ce projet. Approuver une AI discovery qui crée des centaines d'éléments, c'est une ligne, pas des centaines.
  • Vous n'êtes pas prévenu deux fois. Un commentaire qui vous mentionne, ou une réponse dans une discussion dont vous faites partie, vous parvient uniquement par cette notification.
  • Vous n'êtes jamais prévenu de vos propres actions.

Si vous voulez chaque changement dans toute l'organisation, les notifications par e-mail et la page Historique restent l'endroit pour ça.

Ce que ça ne fait pas encore

  • Boîte de réception uniquement. Les mentions, les suivis et les tâches n'envoient pas d'e-mail.
  • Pas de rappel d'échéance. Une tâche en retard passe en rouge, et rien ne vous relance.
  • Pas de liste de ce que vous suivez. Vous le gérez depuis chaque élément, décision ou projet. Une page de documentation ne peut pas être suivie seule ; suivez plutôt son projet.
  • Les bulles restent là où vous les posez. Une fois placée, une bulle ne peut pas être déplacée. La bulle d'une relation se place au milieu de ses deux éléments, pas sur la courbe du trait. Les bulles sont masquées tant que Voyage dans le temps est ouvert.
  • Pas d'aperçus dans Microsoft Teams. Slack uniquement, pour l'instant. Les workspaces Slack connectés avant le 18 octobre doivent être reconnectés depuis Organisation → Bot pour accorder les deux nouvelles permissions, links:read et links:write.
  • Les agents ne voient ni les tâches, ni les suivis, ni les épingles. Via le serveur MCP, ils peuvent mentionner et citer, mais pas encore lire ou terminer des tâches, suivre un élément ou épingler un commentaire sur le diagramme.
  • Pas de tâches hors d'un projet. Les discussions d'organisation ne peuvent pas en porter.

Essayez

Ouvrez un diagramme, appuyez sur C et cliquez sur la relation à propos de laquelle vous vouliez poser une question depuis un moment. Mentionnez le responsable de l'autre bout et citez la décision qu'elle est censée respecter. La documentation couvre chaque élément en détail :

À lire aussi : une boîte de réception pour ce qui vous attend, pour les règles que suit chacune des notifications ci-dessus, et restreindre le bot par canal, pour ce qu'un canal Slack a le droit de prévisualiser.