Discuta a Arquitetura Onde Ela Vive

Alguém percebe que o Billing grava direto no banco de dados do ledger, embora o ADR-12 diga que só a Ledger API pode fazer isso. A pessoa pergunta em uma thread do Slack. Duas respostas, um "boa, vou dar uma olhada", e na hora do almoço a thread já sumiu da tela. Um mês depois a seta continua no diagrama, o ADR-12 continua parecendo que ninguém nunca o questionou, e a pessoa que disse "vou dar uma olhada" mudou de time. A pergunta foi feita e respondida, num lugar que a arquitetura não enxerga.

Essa é a lacuna em que trabalhamos nesta semana. Em 18 de outubro lançamos seis funcionalidades que levam a conversa sobre a arquitetura para dentro do próprio modelo: comentários fixados no diagrama, @menções, citações com # e uma lista "Citado em", prévias de links no app e no Slack, seguir e tarefas. Cada uma vincula uma discussão ao elemento, à decisão ou à página de que ela trata, e todas avisam na caixa de entrada que adicionamos em 10 de outubro.

A mesma pergunta, feita no modelo

Aqui está aquela pergunta sobre o ledger de novo, passando pelo que foi lançado. Os nomes e o projeto são exemplos. O comportamento é o do produto.

Marie fixa a pergunta onde a vê. Ela está revisando o projeto Checkout no nível de container. Pressiona C, o cursor vira uma mira, e ela clica na seta de Billing para Ledger DB. Uma caixa de comentário se abre no meio do relacionamento, e ela escreve:

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

Digitar # abriu uma lista dos elementos, decisões e páginas do projeto, e ADR-12 virou um chip que abre a decisão. Digitar @ listou as pessoas que podem abrir o projeto, e Sam, responsável pelo Billing, também virou um chip. Ela pressiona ⌘ Enter. A bolha recebe um número, #7, e todo mundo que abre essa visão do diagrama a vê.

Sam fica sabendo. O sino dele mostra que Marie o mencionou, com o comentário dela como trecho. Ele não precisa estar olhando o diagrama, nem o canal certo do Slack, para descobrir.

A resposta vira uma tarefa. Sam responde que é uma sobra da migração do ledger e que vai colocar isso atrás da Ledger API. Marie, que começou a discussão, recebe a resposta dele na caixa de entrada. Ela abre a discussão completa, clica em Tarefa sob a resposta de Sam, atribui a ele, escolhe sexta-feira como prazo e clica em Criar tarefa. Uma caixa de seleção aparece sob a resposta, e a tarefa cai na aba A fazer da caixa de entrada de Sam.

A decisão lembra que foi questionada. Abra o ADR-12 e a parte de baixo do card expandido agora lista o comentário de Marie em Citado em, com o texto ao redor da citação. Quem ler a decisão em seguida fica sabendo que o banco que ela protege ainda recebia gravações, e pode clicar até a discussão.

A correção se anuncia sozinha. Sam substitui a seta por meio de uma solicitação de mudança. A descrição dela cita #ADR-12 e cola o link para a discussão #7, que aparece como um card de prévia sob o texto. Todos que podem editar o projeto são avisados de que uma solicitação de mudança foi aberta, como antes. Léa, do time de dados financeiros, não pode revisá-la, mas segue o projeto Checkout, então também recebe uma linha: uma solicitação de mudança aberta em um projeto seguido notifica os seguidores que não podem revisá-la.

O ciclo se fecha. Sam marca a tarefa. Marie, que a criou, recebe "Sam concluiu uma tarefa que você criou". Ela resolve a #7 e a bolha desaparece do diagrama. Quando Sam cola o link da solicitação de mudança em #payments, o bot do Archyl o expande com título, status e projeto.

Cada peça dessa troca está vinculada a algo no modelo: o relacionamento, a decisão, o responsável, a solicitação de mudança. Nada depende de alguém lembrar onde estava uma thread.

O que cada funcionalidade faz

Comentários no diagrama

Pressione C, ou clique em Comentar na barra na parte de baixo do diagrama, e depois clique onde o comentário deve ficar:

  • em um espaço vazio, a bolha fica naquele ponto;
  • em um elemento, ela fica vinculada e acompanha o elemento quando ele se move, e a discussão também aparece no painel de detalhes do elemento;
  • em um relacionamento, ela fica no meio dele.

As bolhas são numeradas por projeto e mantêm o mesmo tamanho em qualquer zoom. Cada uma pertence ao nível e à visão em que foi colocada, então um comentário no system context não aparece dentro de um sistema. Bolhas resolvidas ficam ocultas; marque Mostrar resolvidos no modo de comentário para vê-las em cinza. Fora isso, uma discussão fixada é uma discussão comum: ela aparece na lista de discussões do projeto, e as respostas notificam as pessoas que participam dela. Docs: Comentários no diagrama.

@menções

Digite @ em um comentário ou resposta, no contexto, na decisão ou nas consequências de um ADR, em uma página de documentação, ou na descrição, em um comentário ou em uma revisão de uma solicitação de mudança. A lista mostra as pessoas que podem abrir o projeto e os times que têm pelo menos uma delas. Mencionar um time alcança os membros dele que podem abrir o projeto.

Cada pessoa é avisada uma vez: editar o texto de novo não notifica ninguém que já tinha sido mencionado. Menções em um título não são detectadas, então escreva-as no corpo. Quando lançamos a caixa de entrada, as menções eram o primeiro item da lista "o que ainda não faz". Agora elas estão aqui. Docs: Menções, citações e links.

Citações com # e "Citado em"

Digite # nos mesmos lugares para citar um sistema, container, component ou elemento de código (cada um mostrado com seu pai), uma decisão (listada como ADR-3 com o título) ou uma página de documentação. Clicar no chip abre o que ele cita. Um elemento abre no diagrama no próprio nível, já selecionado.

A outra metade é o backlink. Cada elemento, decisão e página lista onde é citado, do mais recente para o mais antigo, com o trecho ao redor de cada citação: na seção Citado em do painel de detalhes de um elemento, na parte de baixo do card expandido de uma decisão, no fim de uma página. Essa é a parte que uma thread do Slack não consegue dar. A conversa aponta para o ADR, e o ADR aponta de volta.

Prévias de links, no Archyl e no Slack

Copiar link fica no painel de detalhes de um elemento, em cada card de decisão e no topo de cada página de documentação. Um link de elemento abre o elemento no seu nível, selecionado. Solicitações de mudança e discussões são compartilhadas pela barra de endereço.

Cole um link do Archyl em um comentário, na descrição de uma solicitação de mudança ou em uma revisão e ele aparece como um card sob o texto: título, tipo e status, projeto e um trecho. Até três links por mensagem ganham prévia, e só para as pessoas que podem abrir o projeto. Todos os outros veem um link simples.

No Slack, o bot agora expande links para um projeto, um elemento, uma decisão, uma página de documentação, uma solicitação de mudança ou uma discussão na mesma prévia. Ele segue as regras que o bot já tinha. A prévia é montada com as permissões do admin que conectou o workspace, só para projetos da organização à qual o workspace está conectado, e em um canal com escopo um link para um projeto fora do escopo continua simples. Um link para algo que não existe, ou que o bot não consegue ver, também continua simples, então uma prévia nunca confirma que uma página existe. Docs: Prévias de links no Slack.

Seguir

Siga um elemento, uma decisão ou um projeto inteiro com o sino no painel de detalhes do elemento, no card da decisão ou na barra de ferramentas do diagrama. Um sino preenchido significa que você está seguindo. Os responsáveis por um elemento o seguem sem fazer nada, assim como os membros de um time responsável por ele. Clique no sino para deixar de seguir e o Archyl se lembra, mesmo que você continue responsável pelo elemento.

Os seguidores ficam sabendo quando o que seguem é alterado ou excluído (a notificação lista os campos que mudaram), quando um elemento seguido recebe um comentário e quando uma solicitação de mudança mexe em um elemento seguido. Quem segue um projeto também fica sabendo quando um elemento, uma decisão ou uma página é adicionado. Seguir não concede acesso: se você perder o acesso ao projeto, as notificações param. Docs: Seguir.

Tarefas

Sob qualquer comentário ou resposta em um projeto, clique em Tarefa, escolha um responsável entre as pessoas que podem abrir o projeto (você, por padrão), opcionalmente um prazo, e clique em Criar tarefa. Um comentário carrega no máximo uma tarefa. A tarefa aparece sob o comentário com uma caixa de seleção, o responsável e o prazo, que fica vermelho depois que passa. Remover a tarefa mantém o comentário.

Suas tarefas abertas ficam na aba A fazer da caixa de entrada, primeiro as de prazo mais próximo, com um contador na aba. O painel de detalhes de cada elemento tem uma seção A fazer que lista as tarefas de todas as suas discussões. O responsável é avisado quando uma tarefa é criada para ele ou reatribuída a ele, e quem criou é avisado quando outra pessoa a conclui. Docs: Tarefas.

Agentes também podem marcar

Agentes de código conectados pelo servidor MCP escrevem no mesmo modelo: abrem solicitações de mudança, registram decisões, deixam comentários. Até agora, um agente que escrevia "@Sam, você pode confirmar?" gerava texto simples que não avisava ninguém.

Agora o servidor lê o que um agente escreve do mesmo jeito que os seletores no app. Em um comentário, um ADR, uma página de documentação ou uma solicitação de mudança:

  • @Name menciona uma pessoa ou um time, que é avisado na caixa de entrada como em qualquer outra menção. O agente pode chamar list_mentionables para obter os nomes exatos.
  • #Label cita um elemento C4, uma decisão (#ADR-12) ou uma página, que então lista o texto do agente em Citado em.

Um comentário publicado por um agente também chega às pessoas que já participam da discussão e aos seguidores do elemento, como um publicado por uma pessoa. Cada escrita informa ao agente o que foi vinculado, para ele conferir se @Sam chegou mesmo ao Sam.

Os agentes também podem ler os vínculos de volta. get_backlinks retorna onde um elemento, uma decisão ou uma página é citado. Antes de mexer no Ledger DB, um agente pode encontrar o comentário #7 de Marie e a solicitação de mudança que citou o ADR-12, em vez de redescobrir a pergunta.

Seguir sem se afogar

Seguir vai contra a regra que definimos para a caixa de entrada: ela só guarda o que espera por você ou o que responde a algo que você fez. Um elemento seguido que muda não espera por você. Deixamos entrar porque você pediu, clicando no sino ou sendo responsável pelo elemento, e colocamos limites para o barulho que isso pode fazer:

  • Mover um elemento ou mudar o estilo dele não notifica ninguém.
  • Várias edições na mesma coisa dentro de uma hora viram uma notificação, desde que você não a tenha lido.
  • Se você segue um projeto mas não o elemento, recebe no máximo uma notificação de cada tipo por hora para esse projeto. Aprovar uma AI discovery que cria centenas de elementos é uma linha, não centenas.
  • Você não é avisado duas vezes. Um comentário que menciona você, ou uma resposta em uma discussão da qual você participa, chega só por essa notificação.
  • Você nunca é avisado sobre as próprias ações.

Se você quer cada mudança da organização inteira, as notificações por e-mail e a página Histórico continuam sendo o lugar para isso.

O que ainda não faz

  • Só caixa de entrada. Menções, seguir e tarefas não enviam e-mail.
  • Sem lembrete de prazo. Uma tarefa atrasada fica vermelha, e nada avisa você.
  • Sem lista do que você segue. Você gerencia isso em cada elemento, decisão ou projeto. Uma página de documentação não pode ser seguida sozinha; siga o projeto dela.
  • As bolhas ficam onde você as coloca. Depois de colocada, uma bolha não pode ser movida. A bolha de um relacionamento fica no ponto médio entre os dois elementos, não na curva da linha. As bolhas ficam ocultas enquanto Viagem no Tempo está aberta.
  • Sem prévias no Microsoft Teams. Só Slack, por enquanto. Workspaces do Slack conectados antes de 18 de outubro precisam ser conectados de novo em Organização → Bot para conceder as duas novas permissões, links:read e links:write.
  • Agentes não veem tarefas, seguir nem comentários fixados. Pelo servidor MCP eles podem mencionar e citar, mas ainda não ler nem concluir tarefas, seguir um elemento ou fixar um comentário no diagrama.
  • Sem tarefas fora de um projeto. Discussões da organização não podem ter uma.

Experimente

Abra um diagrama, pressione C e clique naquele relacionamento sobre o qual você queria perguntar há tempos. Mencione quem é responsável pela outra ponta e cite a decisão que ele deveria seguir. A documentação cobre cada peça em detalhe:

Leitura relacionada: uma caixa de entrada para o que espera por você, para as regras que cada notificação acima segue, e limitar o escopo do bot por canal, para o que um canal do Slack pode mostrar em prévia.