Revisão de arquitetura e ADR: o porquê guardado ao lado do código

2026-10-18

Toda base de código tem uma parte que parece errada para a próxima pessoa que a lê. Um processo de retransmissão que ninguém lembra de ter adicionado, uma tabela esvaziada toda semana, uma fila onde uma chamada direta bastaria. Os motivos foram ditos em voz alta numa revisão de arquitetura meses atrás, e quem os deu foi para outras equipes. O engenheiro novo tem duas opções: perguntar por aí durante uma semana ou «consertar».

Existe um caminho mais curto. Grave a revisão de arquitetura, pressione um atalho quando uma decisão, uma concessão ou uma opção rejeitada for dita e compartilhe a gravação em um canal Architecture. As marcas ficam nas frases, com o horário e o nome de quem falou. Logo depois da revisão, um assistente de IA no Claude Code, no Cursor ou no Claude lê essas marcas via MCP e rascunha o Architecture Decision Record (ADR, o registro de uma decisão de arquitetura) para o repositório. Meses depois, o debate continua lá para quem perguntar por quê.

Este guia segue o app do Speak-Y para macOS, conferido em 18 de outubro de 2026, e foi pensado para um tech lead cuja equipe já compartilha reuniões em um espaço de trabalho. Se você ainda não tem um, crie-o primeiro.

Por que «por que isso foi feito assim?» não tem resposta?

A solução foi descrita em 2011. O texto de Michael Nygard Documenting Architecture Decisions (conferido em 18 de outubro de 2026) propõe um registro curto para cada decisão importante — título, contexto, decisão, status, consequências — mantido no repositório ao lado do código. O raciocínio dele é o problema acima: alguém novo em um projeto que não sabe por que uma decisão foi tomada só pode aceitá-la às cegas ou revertê-la às cegas. O site da comunidade ADR chama o conjunto desses registros de registro de decisões do projeto.

Equipes que adotam ADRs ainda perdem o porquê, em três lugares previsíveis:

• O contexto é reconstruído. O registro é escrito depois da revisão, de memória, por quem tiver tempo. As restrições que motivaram a decisão são as primeiras a sumir.
• As opções rejeitadas encolhem para uma linha. «Consideramos CDC» não diz nada sobre por que ele perdeu, e é exatamente isso que a próxima pessoa precisa saber antes de propô-lo de novo.
• O registro nunca é escrito. Uma revisão que termina às 16h compete com o código que precisa ficar pronto amanhã.

Uma gravação guarda as três coisas. As marcas as tornam fáceis de achar, e um assistente as transforma em rascunho antes que os detalhes sumam.

Configure uma vez: três marcas e um canal Architecture

As marcas. O Speak-Y vem com um único tipo de nota, Marcar o momento, no ⌥1. Adicione três seus em Configurações → Notas: clique em Adicionar tipo de nota, digite Decision em Nome do tipo, clique em Salvar, depois em Definir atalho e pressione ⌥2. Repita para Trade-off no ⌥3 e Rejected no ⌥4. Cada marca corresponde a uma seção do registro:

• Decision — o que a equipe concordou em construir. Vira a decisão do ADR.
• Trade-off — o custo que a equipe aceitou junto com ela. Vira as consequências.
• Rejected — uma opção que perdeu, com o motivo. Vira as alternativas consideradas.

O contexto é a discussão em volta das marcas; o assistente o lê na transcrição. O formato de Nygard não tem uma seção própria para as opções descartadas; o modelo MADR tem: Considered Options.

O canal. Um canal público para as revisões de arquitetura, chamado Architecture, em que qualquer engenheiro possa entrar. No menu ⋯ do espaço de trabalho, escolha New channel. Revisões de projetos sensíveis para a segurança — um modelo de ameaças, um fluxo de autenticação — vão para um canal privado; os prós e contras estão em quem vê o quê nos canais de reuniões.

Durante a revisão: diga o nome do componente e depois pressione a tecla

Inicie uma gravação de reunião no Speak-Y quando a revisão começar. Nenhum bot entra na chamada: o Speak-Y grava o microfone e o som da chamada no seu Mac, então funciona do mesmo jeito no Zoom, no Google Meet, no Teams ou em uma sala de reunião. Avise a todos que a revisão está sendo gravada.

A transcrição só conhece o que foi dito, então três hábitos compensam:

1. Diga o nome do componente antes de discuti-lo. «O publicador de eventos de pagamento no payments-service» torna cada marca seguinte fácil de achar pelo nome que um engenheiro vai pesquisar depois.
2. Deixe o motivo ser dito e depois pressione. Uma marca cobre os últimos 15 segundos da transcrição antes da tecla, então a frase com o porque fica dentro da marca.
3. Marque também as opções que perderam. Uma marca Rejected em «escritas duplas perdem eventos quando o serviço cai entre uma e outra» é a linha que poupa meia hora à próxima revisão.

Normalmente quem grava e pressiona as teclas é o tech lead que conduz a revisão. Os atalhos funcionam a partir de qualquer app, com o diagrama ou o código ainda em primeiro plano.

Depois da revisão: nomes, tags, To channel

Dois minutos na janela da gravação, enquanto a conversa ainda está fresca:

1. Dê nome aos falantes. Clique em Speaker 1, Speaker 2 e assim por diante, e digite os nomes reais. Uma marca só é tão útil quanto o nome ao lado dela.
2. Coloque as tags. Adicione o nome do serviço e o número do registro que você vai escrever, como payments-service e adr-0012. É por essas tags que o assistente e os seus colegas encontram a revisão.
3. Confira as marcas. Os chips acima da transcrição as contam por tipo: Todas as notas · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Compartilhe. Pressione To channel abaixo da transcrição e escolha Architecture. A transcrição com nomes e marcações de tempo, o resumo de IA e os itens de ação vão para o canal, criptografados de ponta a ponta; o áudio fica no seu Mac.
5. Mostre as marcas. As marcas são privadas por padrão. Clique no chip Privadas acima da transcrição e escolha Mostrar em # Architecture — os membros do canal verão, para que as marcas acompanhem a gravação.

Rascunhe o ADR a partir das marcas

Conecte o seu assistente ao servidor MCP do Speak-Y uma única vez: abra Conectar assistente de IA no menu da conta, no rodapé da barra lateral, ou Configurações → Integrações, e clique em Conectar ao lado do Claude, do ChatGPT ou do Cursor. Para o Claude, um clique configura tanto o Claude Desktop quanto o Claude Code. O servidor é gratuito em todos os planos.

Depois, no repositório, peça:

Rascunhe o ADR 0012 a partir da revisão do payments-service com a tag adr-0012: contexto, decisão, consequências e opções rejeitadas. Cite quem disse cada ponto e quando.

O assistente encontra a revisão pela tag e a lê. Junto com a transcrição, o Speak-Y entrega a ele as marcas em forma de lista — cada uma com o deslocamento na gravação, o tipo, o falante e as primeiras palavras da frase —, então o rascunho volta com três decisões, três custos aceitos e duas opções rejeitadas, cada um com um nome e um horário. No Cursor, o assistente pede aprovação antes de executar cada ferramenta, a menos que você mude isso.

Edite o rascunho antes de fazer o commit. Três campos são seus, não do assistente:

• Status. Proposto ou aceito é uma decisão da equipe, não algo que uma transcrição possa dizer.
• Responsável. Quem responde às perguntas sobre isso no próximo trimestre.
• A referência de volta. Escreva onde está o debate — o canal, a data e a tag — para que o próximo leitor possa refazer o raciocínio. A gravação é criptografada de ponta a ponta no canal, então a referência funciona para os colegas do espaço de trabalho, não para o público.

Meses depois: o engenheiro novo pergunta por quê

O ADR no repositório responde ao quê em uma página. Quando isso não basta, o debate está a um passo.

No app. Os colegas que você convida entram de graça em qualquer plano. Um engenheiro novo que entra no espaço de trabalho vê o canal público Architecture com o histórico dele. Abra-o, clique na lupa no cabeçalho do canal e digite o nome do componente, como outbox. A busca lê as transcrições de todas as revisões do canal e mostra as linhas encontradas com os horários.

No editor. No Cursor ou no Claude Code, com o código aberto:

Por que o payments-service grava os eventos em uma tabela outbox em vez de publicá-los direto no Kafka? O que foi rejeitado?

O assistente pesquisa nas gravações a que o engenheiro tem acesso, encontra a revisão e responde com base nela: a decisão, quem argumentou contra as escritas duplas e por quê, e o que a equipe aceitou em troca. O mesmo padrão para perguntas sobre código em geral está em contexto de reuniões para programar por voz no Cursor.

O que a gravação de uma revisão não substitui

A gravação guarda o raciocínio. Quatro coisas continuam em outro lugar:

• O diagrama. Quadros brancos, slides e diagramas de sequência não estão na gravação. Coloque o link deles no ADR.
• O status final. Uma marca Decision registra que a sala concordou; se a decisão foi substituída depois, isso está nos registros do repositório.
• Decisões tomadas no chat. Uma escolha feita na thread de um pull request nunca chegou à revisão. Escreva-a direto no ADR.
• O próprio código. Se o código e o ADR divergem, o que roda é o código. Atualize o registro ou o código — a gravação só diz o que se pretendia.

Limites e custos

• Duração. Conferido em speak-y.com em 18 de outubro de 2026: o Free interrompe uma gravação de reunião aos 30 minutos, o Pro ($10 por mês) aos 60, o Pro+ ($15) e o Max ($30) às quatro horas. Uma sessão de design longa precisa do Pro+ ou de uma pausa ao completar uma hora.
• Uma pessoa gravando. Duas pessoas gravando a mesma revisão geram duas meias listas de marcas.
• Canais no Mac. Os espaços de trabalho e os canais ficam no app para macOS. Criar um espaço de trabalho exige o Pro ou um plano superior; os colegas entram de graça em qualquer plano.

Em resumo

Três tipos de nota — Decision, Trade-off, Rejected — no ⌥2, ⌥3 e ⌥4. Durante a revisão: diga o nome do componente, deixe o motivo ser dito, pressione a tecla. Depois dela: nomes, tags, To channel → Architecture, mostrar as marcas. Em seguida, uma pergunta ao assistente no repositório, e você edita o rascunho do ADR em vez de escrevê-lo de memória. A página Teams trata dos espaços de trabalho e dos canais, e um registro de decisões que se mantém sozinho aplica a mesma ideia às decisões de produto.

FAQ

Como manter um registro do porquê de uma decisão de arquitetura?

Grave a revisão de arquitetura no Speak-Y e pressione um atalho quando uma decisão, uma concessão ou uma opção rejeitada for dita em voz alta. Compartilhe a gravação em um canal da equipe como Architecture. O canal guarda o debate com nomes e marcações de tempo, e um assistente de IA conectado via MCP pode transformar as marcas em um rascunho de Architecture Decision Record para o repositório.

O Claude Code ou o Cursor conseguem escrever um ADR a partir da gravação de uma reunião?

Conseguem escrever um rascunho. Conectado ao servidor MCP do Speak-Y, o assistente encontra a revisão pela tag, lê a transcrição e a lista de marcas com o tipo, o horário e o falante, e preenche o contexto, a decisão, as consequências e as opções rejeitadas. O status, o responsável e a redação final ficam com o engenheiro que faz o commit do arquivo.

Como um engenheiro novo descobre por que um serviço foi construído de determinado jeito?

De duas formas. Abra o canal Architecture no app do Speak-Y para macOS e pesquise nele o nome do componente, ou pergunte a um assistente no editor, como o Cursor ou o Claude Code, por que o serviço faz o que faz. O assistente pesquisa nas gravações a que o engenheiro tem acesso e responde com quem disse o quê e quando.

O Speak-Y grava o quadro branco ou os diagramas mostrados durante a revisão?

Não. O Speak-Y grava o áudio do Mac que inicia a gravação: o microfone e o som do app de chamadas. Diagramas, slides e quadros brancos não estão na gravação. Diga o nome do componente em voz alta antes de discuti-lo e coloque o link do diagrama no ADR.

Quanto custa essa configuração?

O servidor MCP é gratuito em todos os planos. Criar um espaço de trabalho de equipe exige o Pro ou um plano superior, e os colegas entram de graça em qualquer plano. Conferido em speak-y.com em 18 de outubro de 2026: o Free interrompe uma gravação de reunião aos 30 minutos, o Pro ($10 por mês) aos 60, e o Pro+ ($15) e o Max ($30) às quatro horas.