De RFC a ADR: Chegando à Decisão e Mantendo o Raciocínio

A decisão que ninguém conseguiu reconstruir

O novo líder técnico faz uma pergunta razoável: por que todos os serviços se comunicam com o sistema de faturamento através daquela fila? Há um ADR — ADR-014, quatro frases, escrito há onze meses. Contexto: "precisávamos de uma integração de faturamento confiável." Decisão: "usar a fila." Consequências: "alguma latência adicional." É tecnicamente um registro. Não responde a nada.

Você estava lá, então sabe o que o ADR-014 não diz: a discussão de três semanas em dois canais do Slack e um thread de PR acalorado; a opção de API síncrona que perdeu por causa de um limite de taxa que desde então foi aumentado; a objeção do engenheiro da equipe que foi respondida com um benchmark que ninguém consegue encontrar agora. O debate aconteceu. O registro foi escrito depois, de memória, por uma pessoa, em uma sexta-feira.

Este é o modo de falha documentado e quase universal de uma prática genuinamente boa. A orientação prescritiva da AWS e os documentos Well-Architected da Microsoft recomendam ambos os ADRs — e ambos notam a dor: mantê-los atualizados leva tempo, e gerenciá-los se torna complexo à medida que as equipes e as escolhas se multiplicam. A causa raiz é estrutural: o debate e o registro vivem em lugares diferentes, então o registro é sempre uma transcrição com perda de informações. A solução é torná-los o mesmo lugar. A prática não é específica de engenharia, ou mesmo específica de ADR. O Google exige um documento de design — problema, abordagem proposta, alternativas consideradas, trade-offs — escrito e revisado antes que um trabalho técnico significativo comece, uma prática estabelecida no próprio Software Engineering at Google da empresa. É a mesma disciplina que um ADR, aplicada um passo antes: o ADR registra a escolha que um documento de design argumentou. Os dois falham da mesma maneira pela mesma razão, e ambos são corrigidos pelo mesmo movimento — mantenha o argumento onde o registro vive, em vez de transcrever um no outro depois. Leia cada passo abaixo como cobrindo ambos os artefatos.

Por que os ADRs apodrecem

Uma frase do próprio material da comunidade ADR carrega todo o diagnóstico: um RFC geralmente trata de alcançar um acordo; um ADR registra o acordo uma vez alcançado. Dois artefatos, dois momentos — e tudo entre eles vaza. As alternativas que eram "obviamente" erradas não são registradas (até que deixem de ser óbvias). A objeção que moldou o design final sobrevive apenas como um comentário de PR em um thread fechado. A seção de contexto é escrita por último, da pior forma, por quem perdeu o jogo do não-é. Reuniões que deveriam ter produzido decisões produzem resumos em vez disso, e o raciocínio que torna uma decisão durável — a coisa da qual toda a cadeia de qualidade de decisão depende — é exatamente o que a transcrição descarta.

Passo 1–3: A proposta, o contexto, as opções

1. 1Declare a proposta como a reivindicação principal — a decisão proposta, não uma pergunta: "Rotearemos todas as gravações de faturamento através de uma fila durável." Esta frase é o título do futuro ADR. Ponto de verificação: raiz existe, uma frase, autoria do proponente.
2. 2Contexto como argumentos pró-separados. Cada força que torna a decisão necessária — o requisito de confiabilidade, o limite de taxa do sistema de faturamento, o mandato de auditoria — é seu próprio argumento sob a raiz. Um parágrafo "Contexto" monolítico não pode ser contestado; três reivindicações de contexto separadas podem ser questionadas, confirmadas ou refutadas individualmente. Ponto de verificação: ≥2 argumentos de contexto, cada um uma força.
3. 3Cada opção tem seu próprio nó. A fila, a API síncrona, o trabalho em lote — argumentos irmãos, cada um com seus próprios filhos prós e contras. Prós/contras são relativos ao pai, então as desvantagens de uma opção estão ligadas a essa opção, não à decisão. Inclua as opções que você espera rejeitar: o irmão rejeitado é o que responde à pergunta do próximo ano "por que não apenas...". Ponto de verificação: cada opção que um leitor pode perguntar existe.

Passo 4–6: A rodada RFC que deixa um registro

Agora a rodada de revisão — normalmente a parte que se dispersa em chats, comentários e corredores. Aqui ela ocorre como três tipos de intercâmbio estruturado, cada um um diálogo de quatro turnos entre um revisor e o autor da opção:

Passo 7: Decidindo — e o que a classificação não é

Os tomadores de decisão avaliam as opções: uma rotulada com cada classificação. A distribuição é uma evidência genuína — onde a sala estava, registrado, antes da chamada. Mas a classificação não é a decisão. Um humano nomeado ainda decide, e se a chamada for contra a distribuição, o nó de decisão é onde isso é explicado. (Quem esse humano nomeado deve ser, e como atribuir o papel antes do debate em vez de depois, é uma disciplina própria — veja o tutorial sobre direitos de decisão.)

Passo 8–9: O ADR que você não precisou escrever

Aqui está o resultado. O registro não é um documento que você escreve depois — é o nó da opção escolhida mais tudo o que já está anexado a ele: os argumentos de contexto (Context), os irmãos rejeitados (Options Considered), as cadeias completadas (a discussão, com autores), as classificações (onde a sala estava) e o argumento da decisão com sua justificativa (Decision). Nada é transcrito, então nada se perde na transcrição.

1. 1Registre as consequências que você está aceitando. As desvantagens conhecidas — a latência adicional, o ônus operacional da fila — continuam como consequências indesejadas da opção escolhida, reconhecidas pelo decisor. Anotá-las é o que torna isso uma decisão em vez de uma preferência. Ponto de verificação: ≥1 consequência aceita registrada.
2. 2Exporte se sua organização exigir ADRs rastreados por repositório. Muitas exigem, corretamente — o ADR em markdown ao lado do código permanece como o artefato de conformidade. Escreva o resumo de quatro seções da árvore (cinco minutos, não uma sexta-feira), vincule de volta à discussão para o debate completo. Ponto de verificação: o ADR do repositório cita a árvore; a árvore contém o raciocínio.

Discordar e se comprometer, oficialmente

O padrão que a Amazon tornou famoso — discordar e se comprometer — tem um problema de legibilidade: como alguém pode saber depois que a discordância foi real, ouvida e respondida, em vez de ser ignorada? A mecânica da cadeia responde a isso. Uma cadeia de Revisão que passou por suas quatro etapas completas e foi finalizada sem acordo é precisamente o recibo: a objeção foi feita, respondida, pressionada e respondida novamente, registrado, antes que o dissidente se comprometesse. O dissidente está documentado como tendo sido ouvido — o que torna o compromisso posterior razoável em vez de meramente obediente.

Passo 10: Substituição sem exclusão

Decisões envelhecem. Quando o limite de taxa que matou a opção síncrona é elevado, a decisão correta é uma nova decisão que faz referência à que está substituindo — um novo argumento ligado ao nó do ADR-014, afirmando o que mudou. A antiga decisão permanece legível; seu raciocínio é exatamente o motivo pelo qual a nova decisão sabe o que está revogando.

Uma lacuna honesta a ser gerida explicitamente: não há um campo de status ADR embutido. Proposto / aceito / substituído não é um estado de primeira classe em um argumento — a substituição é modelada por meio de links, e a convenção é sua para manter. Declare isso no acordo de trabalho da sua equipe em vez de assumir que o produto o impõe.

Limitações honestas

• ✗Isso não substitui os ADRs no seu repositório se a sua organização exigir que eles sejam versionados ao lado do código. Exporte e faça o commit do resumo; use a árvore para a parte em que o markdown é ruim — o debate.
• ✗No campo de status ADR. Proposto/aceito/superado é uma convenção de ligação que você mantém, não algo que o produto impõe.
• ✗Uma cadeia é quatro voltas. Um profundo desacordo arquitetônico precisará de uma chamada; a cadeia é o registro do que já foi tentado antes dela.
• ✗Avaliações são um único valor rotulado, não uma pontuação multi-critério ponderada.
• ✗Não faz ninguém escrever um bom contexto. A estrutura reduz o custo de um bom registro; não suplanta o julgamento.

Aulas práticas

• ✓Um RFC, uma discussão. Resista à mega-árvore que cobre toda a arquitetura do trimestre — links de supersessão conectam decisões melhor do que a aninhamento.
• ✓Semear a partir do que existe. Um transcript carregado de decisões ou sua antiga pasta ADR, extraída, dá ao debate um bom começo — rotulado como importado, para que os argumentos ao vivo permaneçam distinguíveis.
• ✓Coloque os nomes dos revisores em suas correntes e os deixe lá. A atribuição é a responsabilidade; objeções arquitetônicas anônimas envelhecem em folclore.
• ✓A seção de consequências é do decisor, de mais ninguém. Os contras aceitos escritos pela pessoa que os aceitou têm um peso diferente das advertências de um revisor.

ADR-014, a versão que responde

Voltando à pergunta do novo líder técnico. Na versão reconstruída, o ADR-014 é um nó: a decisão da fila com sua justificativa, três forças de contexto (uma agora obsoleta — visivelmente), um irmão de API síncrona rejeitado cujo nome fatal menciona o antigo limite de taxa, quatro cadeias de Revisão concluídas, incluindo a do engenheiro responsável, e o benchmark anexado como evidência. O líder técnico lê por dez minutos, vê que o limite de taxa foi alterado e abre uma proposta substitutiva vinculada ao antigo nó. Ninguém escava no Slack. Essa é toda a promessa: as cadeias chegam ao acordo, a árvore o registra — e o registro responde a perguntas que você não sabia que seriam feitas.