Registros de Decisões Arquiteturais São Ativos Estratégicos da Empresa

A arquitetura corporativa é frequentemente representada por meio de diagramas.

Criamos diagramas de contexto, paisagens de integração, modelos de dados, visões de segurança, modelos de deployment e diagramas de sequência. Esses artefatos são essenciais porque ajudam os stakeholders a compreender como a solução está estruturada e como seus componentes interagem.

Entretanto, os diagramas raramente explicam a parte mais importante da arquitetura:

Por que esse desenho foi escolhido?

Um diagrama pode mostrar que o Salesforce se comunica de forma assíncrona com uma plataforma core por meio de uma camada de integração orientada a eventos.

Mas talvez não explique:

• Por que a integração síncrona foi rejeitada

• Quais requisitos de disponibilidade influenciaram a decisão

• Qual trade-off de consistência foi aceito

• Como as falhas serão recuperadas

• Quais alternativas foram avaliadas

• Em quais condições o desenho deve ser revisitado

Sem esse contexto, as equipes futuras enxergam o resultado da decisão, mas não o raciocínio que a originou. É nesse ponto que os Architecture Decision Records se tornam essenciais.

Um Architecture Decision Record, ou ADR, é um registro estruturado de uma decisão arquitetural significativa, incluindo contexto, alternativas, justificativa, trade-offs, consequências e status.

Em um nível básico, um ADR é um documento. Em escala corporativa, porém, ele representa muito mais.

É memória institucional. É evidência de risco. É um mecanismo de governança. É uma referência para dívida técnica. É uma ferramenta para onboarding, auditorias, revisões arquiteturais e futuras transformações.

Uma organização madura não trata ADRs como documentação administrativa. Ela os trata como ativos estratégicos da empresa.

Arquitetura é uma Sequência de Decisões

A arquitetura é algumas vezes descrita como uma coleção de componentes, plataformas, integrações e padrões. Uma definição mais precisa é que a arquitetura representa o resultado acumulado de decisões.

Todo desenho relevante contém escolhas como:

• Org única ou múltiplas orgs

• Configuração ou customização

• Flow ou Apex

• Integração síncrona ou assíncrona

• Replicação de dados ou federação

• Salesforce como system of record ou system of engagement

• Serviço compartilhado ou implementação específica por domínio

• Capacidade padrão ou extensão customizada

• Modelo de segurança centralizado ou isolamento regional

• Aprovação humana ou execução autônoma pelo Agentforce

Essas decisões moldam a plataforma durante anos.

Elas influenciam:

• Velocidade de entrega

• Custo operacional

• Exposição de segurança

• Escalabilidade

• Experiência do usuário

• Dívida técnica

• Dependência de fornecedores

• Flexibilidade futura

Quando as decisões não são registradas, entretanto, a arquitetura acaba se tornando uma coleção de resultados sem explicação.

Um arquiteto futuro pode perguntar: “Por que mantemos esses dados do cliente externamente em vez de armazená-los no Salesforce?”

A resposta pode ser: “Porque foi assim que o desenho original foi feito.”

Isso não é conhecimento arquitetural. É folclore arquitetural.

O Custo do Raciocínio Não Documentado

Os ambientes tecnológicos corporativos mudam continuamente. Arquitetos deixam a organização. Parceiros de implementação são substituídos. Líderes de negócio mudam. As capacidades dos produtos evoluem. Regulamentações são atualizadas. Aquisições introduzem novas plataformas. As pessoas que tomaram as decisões originais podem não estar mais disponíveis quando essas decisões forem questionadas.

Sem um ADR, as equipes podem:

• Reabrir debates já resolvidos

• Reverter decisões intencionais sem compreender as consequências

• Introduzir padrões conflitantes com restrições existentes

• Classificar compromissos deliberados como erros técnicos

• Manter decisões ultrapassadas porque não existem condições de revisão

• Repetir a mesma análise em vários projetos

Isso gera desperdício organizacional. Imagine uma instituição financeira que decide não replicar todo o histórico de transações no Salesforce.

A decisão original pode ter sido baseada em:

• Restrições de residência dos dados

• Alto volume transacional

• Obrigações de retenção

• Ownership do core bancário

• Custo de armazenamento Salesforce

• Necessidade de acesso externo em tempo real

Três anos depois, uma nova equipe vê que os dados transacionais permanecem externos e conclui que a arquitetura está incompleta. Sem a justificativa documentada, a equipe pode propor a cópia de todo o histórico para o Salesforce. A empresa então repete a análise original ou, pior, aprova um desenho que viola as restrições regulatórias e operacionais originais. Um ADR bem elaborado evita esse problema ao preservar o contexto da decisão.

O que Torna uma Decisão Arquiteturalmente Significativa?

Nem toda escolha de implementação precisa de um ADR. Documentar cada campo, variável de Flow, alteração de page layout ou nome de classe criaria ruído e tornaria o processo insustentável. Um ADR deve registrar decisões que possuam consequências significativas, duradouras, cross-team ou difíceis de reverter.

Tópicos comuns de ADRs em Salesforce incluem:

• Estratégia de orgs

• Definição de sistema de registro

• Estratégia de identidade do cliente

• Arquitetura de integração

• Padrões orientados a eventos

• Grandes volumes de dados

• Arquitetura de segurança e compartilhamento

• Residência de dados

• Arquivamento e retenção

• Estratégia de DevOps

• Utilização de middleware

• Arquitetura de Data Cloud

• Autonomia do Agentforce

• Requisitos de human-in-the-loop

• Governança de prompts e grounding

• Ownership de capacidades cross-cloud

• Grandes exceções da plataforma

Um teste útil é perguntar:

• Essa decisão afetará várias equipes?

• Será cara ou arriscada de reverter?

• Criará uma restrição de longo prazo?

• Estabelece um padrão reutilizável?

• Aceita um risco material?

• Provavelmente será questionada no futuro?

• Afeta segurança, compliance, escalabilidade ou resiliência?

Quando a resposta é positiva, a decisão provavelmente merece um ADR.

Um Bom ADR Registra Mais do que a Escolha Final

Um ADR fraco diz: “Decidimos utilizar Platform Events.”

Isso não é suficiente. Um ADR útil explica o modelo completo da decisão.

Uma estrutura prática inclui as seções a seguir.

1. Título da decisão

O título deve descrever claramente a decisão.

Exemplo:

Utilizar um Padrão Orientado a Eventos para Atualizações do Customer Master

2. Status

Os status normalmente incluem:

• Proposto

• Em revisão

• Aprovado

• Rejeitado

• Substituído

• Descontinuado

O status é importante porque a arquitetura evolui.

3. Contexto

O contexto explica a situação de negócio e tecnologia.

Pode incluir:

• Objetivo de negócio

• Arquitetura atual

• Restrições

• Volumes

• Necessidades de disponibilidade

• Requisitos de segurança

• Obrigações regulatórias

• Dependências organizacionais

4. Direcionadores arquiteturais

São os requisitos que mais influenciam a decisão.

Exemplos:

• O atendimento não pode depender da disponibilidade do sistema core

• As atualizações devem se propagar em até cinco minutos

• Dados sensíveis não podem ser persistidos no Salesforce

• Vários consumidores precisam receber a mesma notificação

• Processamentos duplicados precisam ser evitados

5. Premissas

As premissas precisam ser explícitas.

Exemplos:

• A plataforma de integração suporta processamento durável de eventos

• Consistência eventual é aceitável

• O Salesforce não é o master da identidade do cliente

• Os consumidores processam mensagens de forma idempotente

6. Opções consideradas

O ADR deve registrar alternativas realistas.

Por exemplo:

• REST síncrono

• Batch agendado

• Change Data Capture

• Platform Events

• Mensageria controlada pelo middleware

7. Decisão

A opção selecionada deve ser descrita claramente.

8. Justificativa

A justificativa explica por que a opção foi escolhida considerando os direcionadores.

9. Trade-offs e consequências

Esta seção deve registrar benefícios e custos.

10. Riscos e mitigações

Os riscos residuais devem permanecer visíveis.

11. Gatilhos de revisão

O ADR deve definir quando a decisão precisa ser reavaliada.

Exemplos:

• Volume de eventos supera o limite definido

• Requisitos regulatórios mudam

• O sistema de origem é substituído

• Salesforce introduz uma capacidade materialmente diferente

• Os objetivos de recuperação tornam-se mais rígidos

12. Artefatos relacionados

Os links podem incluir:

• Diagramas de arquitetura

• Avaliações de segurança

• Modelos de dados

• Threat models

• Especificações de APIs

• Estratégias de testes

• Modelos de custo

Essa estrutura transforma uma decisão verbal em conhecimento corporativo durável.

ADRs Tornam os Trade-Offs Visíveis

Arquitetura não é a busca por uma solução sem desvantagens. É a seleção do compromisso mais apropriado sob um conjunto específico de restrições. Considere a decisão de utilizar External Objects ou outra abordagem de federação em vez de replicar dados históricos para o Salesforce.

Os benefícios podem incluir:

• Menor duplicação de dados

• Menor consumo de armazenamento

• Melhor alinhamento com o source of truth

• Gestão de retenção simplificada

As consequências podem incluir:

• Dependência da disponibilidade do sistema externo

• Possível latência

• Relatórios mais complexos

• Limitações em algumas capacidades Salesforce

• Novos requisitos de integração e monitoramento

Um ADR maduro registra os dois lados. Isso evita que futuros leitores interpretem a decisão como universalmente superior. O desenho escolhido não representa “a melhor arquitetura” em termos absolutos. É a arquitetura mais defensável sob as condições documentadas. Se essas condições mudarem, a decisão também pode precisar mudar. Isso representa uma arquitetura saudável.

ADRs Protegem Compromissos Intencionais

A arquitetura corporativa está cheia de compromissos. Um programa pode aceitar duplicação temporária para cumprir um prazo regulatório. Um projeto pode utilizar integração ponto a ponto durante uma aquisição enquanto um padrão estratégico de middleware é estabelecido. Uma equipe pode utilizar Apex em vez de Flow por exigências de controle transacional, desempenho ou testabilidade. Um CoE pode aprovar uma exceção de nomenclatura devido a uma restrição de managed package. Sem documentação, esses compromissos podem se tornar permanentes e sem explicação.

Um ADR deve diferenciar:

• Estado futuro estratégico

• Estado de transição aprovado

• Exceção temporária

• Workaround tático

• Restrição permanente

Também deve registrar:

• Data de expiração

• Responsável pela remediação

• Ação de follow-up

• Condições para remoção

• Dívida técnica aceita

Isso impede que decisões temporárias se tornem silenciosamente arquitetura permanente.

ADRs São uma Base para Governança

Um Architecture Review Board maduro não deve produzir apenas atas de reunião. Seu resultado mais valioso é uma decisão. Essa decisão deve ser registrada em um ADR. Por exemplo, um ARB pode revisar uma proposta para uma nova org Salesforce.

O board deve avaliar:

• Separação regulatória

• Autonomia do negócio

• Complexidade de identidade

• Custo de integração

• Necessidades de compartilhamento de dados

• Independência de releases

• Suporte operacional

• Impacto de licenciamento

O ADR preservará:

• Por que a nova org foi aprovada ou rejeitada

• Quais premissas foram aceitas

• Quais condições foram impostas

• Quais riscos permanecem

• Quando a decisão deve ser revisitada

Isso cria rastreabilidade entre governança e implementação. Também evita que a governança arquitetural se transforme em conversa informal. Uma decisão sem registro é difícil de aplicar. Um registro sem processo responsável de decisão é difícil de confiar. Os ADRs conectam os dois.

ADRs Fortalecem a Maturidade do Salesforce CoE

Um Salesforce Center of Excellence deve manter um repositório de decisões arquiteturais como parte de seu modelo de governança.

O repositório pode ajudar o CoE a:

• Preservar conhecimento institucional

• Reduzir análises repetitivas

• Padronizar a qualidade das decisões

• Controlar exceções arquiteturais

• Identificar problemas recorrentes

• Melhorar padrões reutilizáveis

• Apoiar onboarding

• Demonstrar efetividade da governança

Ao longo do tempo, o repositório de ADRs torna-se um mapa da evolução da plataforma.

Ele mostra:

• Por que existem múltiplas orgs

• Por que certas integrações utilizam eventos

• Por que alguns dados permanecem externos

• Por que limites específicos de segurança foram criados

• Por que um managed package foi selecionado

• Por que ações do Agentforce exigem aprovação humana

• Por que uma capacidade foi centralizada ou distribuída

Esse histórico ajuda o CoE a diferenciar arquitetura deliberada de complexidade acidental.

ADRs e Dívida Técnica

Dívida técnica é frequentemente descrita como um backlog de código antigo ou modernizações atrasadas. Mas ela também é consequência de decisões arquiteturais. Um ADR maduro deve registrar se a decisão cria dívida.

Por exemplo:

O projeto utilizará integração REST direta no MVP. Isso cria uma dependência tática que deverá migrar para a camada corporativa de integração antes da expansão regional.

O ADR deve especificar:

• Descrição da dívida

• Justificativa de negócio

• Risco

• Responsável

• Data prevista para remediação

• Gatilho de escalonamento

• Impacto estimado se não for corrigida

Isso torna a dívida técnica visível no momento em que é criada. Sem essa disciplina, ela aparece posteriormente como surpresa. A organização não deve fingir que sempre é possível evitar dívida. Em alguns casos, ela representa um trade-off racional. A falha de governança ocorre quando a dívida é aceita sem ownership, visibilidade ou estratégia de pagamento.

ADRs e Governança do Agentforce

O Agentforce aumenta a importância dos registros de decisão porque soluções de IA introduzem novas escolhas arquiteturais.

Exemplos incluem:

• Quais decisões de negócio podem ser delegadas

• Quais ações exigem confirmação

• Quais fontes de grounding são aprovadas

• Quais domínios de dados os agentes podem acessar

• Quando o escalonamento humano é obrigatório

• Qual limite de autonomia é aceitável

• Como a identidade do agente é gerenciada

• Qual modelo ou serviço pode ser utilizado

• Como prompts e instruções serão governados

• Qual padrão de avaliação é exigido antes do release

Considere um caso de uso de Agentforce que recomenda e executa reembolsos.

Um ADR deve registrar:

• Valor máximo de reembolso autônomo

• Autenticação necessária do cliente

• Tipos de transações elegíveis

• Fonte da política

• Limites de aprovação

• Requisitos de auditoria

• Override humano

• Estratégia de recuperação de erros

• Expectativas de monitoramento

Sem um registro de decisão, equipes futuras podem aumentar a autonomia do agente sem compreender os limites de risco originais. Para sistemas de IA, o ADR não documenta apenas tecnologia. Ele documenta autoridade delegada. Por isso, torna-se um artefato central de governança.

ADRs Melhoram Evidências de Segurança e Compliance

Equipes de segurança e compliance frequentemente perguntam:

• Por que este dado está armazenado aqui?

• Por que esta identidade de integração pode acessar esses registros?

• Por que a criptografia é aplicada a alguns campos e não a outros?

• Por que determinado atributo está disponível ao agente?

• Por que esta ação é permitida sem aprovação humana?

• Quem aceitou o risco residual?

Um ADR ajuda a responder essas perguntas.

Ele pode referenciar:

• Classificação dos dados

• Threat model

• Controles de segurança

• Avaliação de privacidade

• Interpretação jurídica

• Risk owner

• Requisitos regulatórios

• Aprovação de exceção

Isso não substitui as evidências formais de segurança. Mas conecta a decisão técnica à justificativa de governança. Durante auditorias ou investigações de incidentes, essa conexão pode ser extremamente valiosa.

ADRs Aceleram o Onboarding

Novos arquitetos e desenvolvedores frequentemente gastam muito tempo tentando descobrir por que a plataforma funciona da forma atual. Eles analisam metadados, código, integrações e diagramas. Mas artefatos de implementação raramente revelam intenção de negócio.

Um repositório de ADRs ajuda novos integrantes a compreender:

• Por que determinados padrões são obrigatórios

• Quais restrições são históricas

• Quais decisões continuam vigentes

• Quais desenhos são transitórios

• Quais riscos já foram aceitos

• Quais áreas estão programadas para modernização

Isso reduz o caminho entre familiaridade técnica e compreensão arquitetural. Sem ADRs, o onboarding depende fortemente de pessoas com longa permanência na organização. Isso cria risco de dependência individual. O conhecimento institucional deve pertencer à organização, e não apenas às pessoas que o lembram.

ADRs Apoiam o Pensamento em Nível CTA

O CTA Review Board avalia a capacidade do candidato de:

• Identificar direcionadores arquiteturais

• Tornar premissas explícitas

• Avaliar alternativas

• Explicar trade-offs

• Reconhecer riscos

• Defender recomendações

• Adaptar-se quando as condições mudam

Essas são as mesmas disciplinas necessárias para escrever um bom ADR. Praticar ADRs em projetos reais fortalece o raciocínio em nível CTA.

Ao documentar uma decisão, o arquiteto precisa responder:

• Qual problema estamos resolvendo?

• Quais restrições importam?

• Quais opções são viáveis?

• Por que esta opção é preferida?

• Quais são as consequências?

• O que nos faria mudar de direção?

A prática de ADRs desenvolve julgamento arquitetural estruturado. Ela transforma “este é meu padrão preferido” em “esta é a escolha mais defensável sob estas condições”.

ADRs Devem Ser Registros Vivos

Um ADR não deve ser silenciosamente editado sempre que a decisão mudar. Isso destruiria a rastreabilidade histórica. Em vez disso, as decisões devem evoluir por meio de status e substituição explícita.

Por exemplo:

• ADR-014 aprovou uma integração batch

• ADR-032 posteriormente substituiu essa decisão por integração orientada a eventos

• ADR-014 permanece disponível como contexto histórico

• ADR-032 explica o que mudou e por quê

Isso preserva a evolução da arquitetura.

Um ciclo de vida maduro inclui:

1. Proposto

2. Revisado

3. Aprovado ou rejeitado

4. Implementado

5. Monitorado

6. Reavaliado

7. Substituído ou descontinuado

Nem todo ADR precisa de revisões frequentes. Entretanto, decisões de alto impacto devem possuir gatilhos definidos de revisão.

O Repositório de ADRs Precisa de Governança

Criar ADRs não é suficiente. O próprio repositório precisa de padrões.

Um CoE deve definir:

• Template de ADR

• Nomenclatura e numeração

• Metadados obrigatórios

• Ownership

• Workflow de aprovação

• Local de armazenamento

• Capacidade de pesquisa

• Relacionamento com diagramas e itens de backlog

• Gestão de status

• Frequência de revisão

• Processo de substituição

Os ADRs devem ser fáceis de encontrar. Uma decisão existente em uma pasta inacessível é quase equivalente a uma decisão não documentada.

O repositório deve permitir pesquisas por:

• Domínio

• Cloud Salesforce

• Sistema

• Risco

• Status

• Capacidade de negócio

• Responsável arquitetural

• Data

• Padrão relacionado

Uma boa arquitetura do conhecimento faz parte da governança arquitetural.

Evite Transformar ADRs em Burocracia

Os ADRs podem falhar quando a organização os torna excessivamente complexos. Se cada registro exigir semanas de aprovação, os arquitetos evitarão criá-los. Se o template contiver dezenas de seções obrigatórias para pequenas decisões, o processo se tornará overhead administrativo. O processo deve ser proporcional ao risco. Uma decisão moderada pode exigir um ADR conciso.

Uma decisão de alto risco pode exigir:

• Análise detalhada de alternativas

• Estudo de custos

• Revisão de segurança

• Avaliação jurídica

• Análise de modos de falha

• Aceite executivo de risco

O objetivo não é o volume de documentação. O objetivo é a clareza da decisão.

Antipadrões Comuns em ADRs

Alguns antipadrões reduzem o valor dos Architecture Decision Records. Registrar apenas a tecnologia selecionada.

A justificativa e as consequências ficam ausentes. Documentar somente depois da implementação.

O ADR vira justificativa retrospectiva, e não evidência real da decisão. Omitir alternativas rejeitadas.

As equipes futuras não entendem por que outros padrões não foram escolhidos. Esconder consequências negativas.

O registro se transforma em defesa da solução, e não em arquitetura. Nunca revisitar decisões.

Premissas ultrapassadas continuam incorporadas indefinidamente. Registrar todas as pequenas escolhas/

O repositório se torna ruidoso e inutilizável. Armazenar ADRs separados dos artefatos de entrega.

A decisão se desconecta da implementação. Permitir decisões sem responsáveis.

Ninguém responde pela revisão ou pelas consequências. Alterar ADRs antigos sem histórico.

A evolução arquitetural torna-se invisível.

Exemplo Prático de ADR Salesforce

Título

Utilizar Salesforce como System of Engagement, e Não como Master da Identidade do Cliente

Contexto

O customer master corporativo é responsável pela identidade legal e pela criação do golden record. O Salesforce precisa de visibilidade quase em tempo real para operações de atendimento. Vários canais criam e atualizam dados dos clientes.

Direcionadores arquiteturais

• Evitar identidades duplicadas

• Preservar o ownership do master corporativo

• Suportar a disponibilidade do atendimento

• Propagar atualizações aprovadas de contato

• Manter controles regionais de privacidade

Opções consideradas

1. Tornar Salesforce o master do cliente

2. Manter sincronização bidirecional sem restrições

3. Preservar o master externo e utilizar sincronização controlada por eventos

4. Acessar todos os dados sob demanda sem persistência local

Decisão

O customer master externo permanece autoritativo. O Salesforce armazena os dados operacionais necessários para atendimento e publica alterações aprovadas de contato por meio de eventos governados.

Trade-offs

Benefícios:

• Ownership claro

• Menor conflito de identidade

• Melhor alinhamento corporativo

• Maior auditabilidade

Consequências:

• Consistência eventual

• Dependência externa

• Necessidade de reconciliação

• Tratamento de erros mais complexo

Riscos e mitigações:

• Eventos duplicados: chave de idempotência

• Atualizações atrasadas: monitoramento e SLA

• Indisponibilidade da integração: replay e dead-letter handling

• Alterações conflitantes: matriz de ownership por campo

Gatilhos de revisão:

• Substituição do customer master

• Mudança regulatória

• Aumento de volume além da previsão

• Novos canais de clientes em tempo real

Esse exemplo faz mais do que descrever a integração.

Ele preserva a intenção da arquitetura.

Reflexão Final

Arquitetura corporativa não é apenas aquilo que foi construído. o raciocínio que explica por que foi construído daquela forma. Sem preservar esse raciocínio, a organização perde contexto. Repete análises. Reabre debates resolvidos. Reverte trade-offs deliberados. Passa a depender da memória individual. Os Architecture Decision Records oferecem uma forma disciplinada de preservar esse raciocínio.

Eles conectam:

• Contexto de negócio

• Desenho técnico

• Risco

• Governança

• Consequências financeiras

• Responsabilidade operacional

• Revisão futura

Um diagrama mostra às equipes futuras como a arquitetura se parece. Um ADR explica por que ela existe. Os dois são necessários.

A maturidade arquitetural não é medida apenas pela qualidade dos diagramas, padrões ou soluções técnicas. Ela é medida pela capacidade da organização de preservar o raciocínio por trás das decisões relevantes. Architecture Decision Records transformam julgamento individual em conhecimento institucional, tornando a arquitetura corporativa explicável, governável, auditável e adaptável ao longo do tempo.