Guia de ADR

Um ADR — Architecture Decision Record — registra uma decisão de arquitetura: o contexto em que ela foi tomada, as alternativas consideradas, a escolha feita e as consequências que ela cria. É um documento curto, de uma a duas páginas, versionado junto com o código que ele explica.

Vale 15% da nota. Mas o motivo de ele ocupar tanto espaço na disciplina não é o peso: é que a decisão de banco de dados é o objeto de estudo. Escolher entre PostgreSQL e MongoDB, entre Iceberg e Delta, entre Airflow e Dagster, é o trabalho de quem projeta a camada de dados de um sistema. O ADR é onde esse trabalho fica visível — e, portanto, avaliável.

O Método de Decisão em seis passos

Todo ADR da disciplina aplica os mesmos seis passos. Não é burocracia: cada passo elimina um jeito específico de errar.

1. Caracterizar a carga

Volume, taxa de escrita e de leitura, cardinalidade, padrão de acesso, latência tolerada, sazonalidade. Com números do seu domínio.

O erro que este passo evita: escolher tecnologia para um problema imaginado. “Precisamos escalar” não é caracterização; “180 mil linhas/dia, 95% de leitura, consultas de agregação sobre janelas de 30 dias” é.

2. Explicitar as restrições não funcionais

Consistência exigida, disponibilidade, custo, requisitos legais, competência da equipe, licenciamento.

O erro que este passo evita: descobrir a restrição depois de construir. Competência da equipe é restrição legítima e costuma ser omitida por parecer confissão de fraqueza — não é. Uma equipe que não sabe operar Kafka tem uma razão real para não escolher Kafka, e essa razão merece estar escrita.

3. Levantar candidatos

No mínimo três, incluindo obrigatoriamente a opção nula — “continuar no PostgreSQL que já temos”.

O erro que este passo evita: justificar a decisão que já foi tomada. A opção nula é obrigatória porque é a mais frequentemente certa e a menos frequentemente considerada. Um ADR em que a opção nula não aparece, ou aparece como espantalho, não passa da faixa 5–6.

4. Prototipar e medir

Benchmark mínimo, com dados do próprio domínio — nunca sintético genérico. Reproduzível: script no repositório, dado de entrada disponível, comando documentado.

O erro que este passo evita: decidir por reputação. O que o fornecedor mede é o caso em que ele ganha. O que importa é o que acontece com a sua carga.

5. Registrar o compromisso

O que se ganha, o que se perde, o que se torna irreversível.

O erro que este passo evita: a decisão parecer gratuita. Toda escolha arquitetural custa algo; se você não consegue nomear o custo, provavelmente não entendeu a escolha. É neste passo que a maioria dos ADRs perde nota.

6. Definir o gatilho de revisão

Sob qual métrica esta decisão deixa de valer.

O erro que este passo evita: a decisão virar dogma. “Revisar se a latência do p95 passar de 400 ms” transforma uma escolha em hipótese com prazo. Sem gatilho, ninguém revisita — e o sistema carrega decisões cujo contexto já morreu.

Template

Formato Nygard. Copie, salve em docs/adr/NNNN-titulo-em-kebab-case.md no repositório da Squad, e substitua o que está entre colchetes.

# NNNN — [Título: a decisão, em uma frase afirmativa]

- **Status:** proposto | aceito | substituído por [ADR-NNNN] | revogado
- **Data:** AAAA-MM-DD
- **Decisores:** [quem participou]

## Contexto

[Que problema motivou esta decisão? Qual é a carga de trabalho, com números?
Quais restrições não funcionais valem aqui — consistência, custo, legislação,
competência da equipe?]

## Alternativas consideradas

### A. [Opção nula: continuar como está]
[Por que ela é viável. Por que ela não foi escolhida — se não foi.]

### B. [Alternativa]
[O que ela oferece. O que ela cobra.]

### C. [Alternativa]
[Idem.]

## Medição

[O que foi medido, com que dado, em que condição. Como reproduzir: comando,
script, versão. Resultado em tabela.]

| Alternativa | Métrica 1 | Métrica 2 |
|---|---|---|
| A | | |
| B | | |
| C | | |

## Decisão

[Escolhemos X.]

## Consequências

**O que ganhamos:** [...]

**O que perdemos:** [seja específico — esta seção é a que separa 7–8 de 9–10]

**O que se torna irreversível:** [migração de volta custa o quê?]

## Gatilho de revisão

[Sob qual métrica esta decisão deixa de valer.]

Checklist de autoavaliação

Passe por esta lista antes de entregar. Cada item corresponde a um ponto que a correção verifica.

• A carga está caracterizada com números do meu domínio, não com adjetivos
• Há pelo menos três alternativas, e a opção nula é uma delas
• A opção nula foi tratada com seriedade, não como espantalho
• A medição usa dado do próprio domínio e é reproduzível por terceiro — script e comando estão no repositório
• A seção "o que perdemos" nomeia perdas concretas, não "aumento de complexidade"
• Está dito o que se torna irreversível, e quanto custaria voltar atrás
• Há gatilho de revisão com métrica e limiar
• O título é uma frase afirmativa que diz a decisão, não o tema
• O ADR cabe em duas páginas

A avaliação completa está na página de avaliação.

Exemplos anotados: os ADRs deste site

Os exemplos da disciplina são os ADRs do próprio site que você está lendo. Estão em docs/adr/, versionados junto com o código, e registram decisões reais tomadas na construção deste site.

A colisão de nomes é deliberada. “ADR” aqui tem dois autores possíveis: a Squad, que produz o artefato avaliado, e a docência, que registra decisões sobre o site. Você desambigua por quem escreve, não por um termo diferente.

Por que eles ficariam na faixa 5–6

Vale dizer abertamente: aplicada a avaliação da disciplina, esses ADRs não passariam da faixa 5–6. Eles têm contexto, alternativas com a opção nula, consequências específicas e o que se torna irreversível. O que não têm é medição reproduzível.

Isso não é descuido — é o ponto pedagógico. Medição é exigível quando existe algo a medir.

Uma decisão de esquema de banco tem: você popula as duas modelagens, roda a consulta que importa, lê o plano de execução e compara. Quem não mede está adivinhando, e a avaliação cobra isso com razão.

Uma decisão sobre a unidade de conteúdo de um site não tem. O ADR-0003 escolhe entre “um arquivo por Encontro” e “um arquivo por Semana”. O critério real é conflito de edição entre duas autoras e clareza de titularidade — não há benchmark que produza esse número, e inventar uma métrica para parecer rigoroso seria pior do que assumir a ausência.

O que a avaliação pede, então, não é medição sempre. É evidência apropriada à natureza da decisão, e honestidade quando ela não existe. Um ADR que diz “não medimos, porque o critério aqui é organizacional, e eis o raciocínio” é melhor do que um que fabrica um benchmark irrelevante — este último cai na faixa 0–4, por benchmark irreprodutível.

No Projeto Integrado, praticamente toda decisão que vocês vão registrar tem o que medir. Se você concluir que a sua não tem, essa conclusão precisa estar argumentada no ADR — e ela mesma será avaliada.

As cinco decisões do semestre

Os 5 ADRs obrigatórios não são livres: cada Entrega carrega ao menos um, sobre a decisão estrutural daquela etapa.