Design Docs: como decidir antes do código sem criar burocracia

Introdução

Segunda-feira, 10h.

O time está discutindo como preparar a plataforma para o novo aplicativo mobile. A API atual foi construída para a web, devolve payloads maiores do que o app precisa e obriga o frontend a fazer várias chamadas para montar a tela inicial.

Em vinte minutos aparecem três soluções.

Uma pessoa quer adaptar a API existente. Outra propõe criar um BFF. Uma terceira sugere colocar GraphQL na frente de tudo.

A reunião termina com uma frase conhecida:

Vamos começar pelo BFF e ajustar no caminho.

Dois sprints depois, o BFF já conhece regras de negócio, o cache não tem estratégia clara de invalidação, Segurança descobre que os tokens estão sendo propagados de forma incorreta e ninguém lembra por que GraphQL foi descartado.

O problema não foi falta de código.

O problema foi assumir um compromisso técnico antes de tornar a proposta legível para quem precisava avaliá-la.

Um Design Doc existe para antecipar essa conversa: transformar uma direção técnica em algo que outras pessoas possam questionar, melhorar ou rejeitar antes que ela ganhe código, contratos e inércia.

Ele não precisa prever cada classe, método ou detalhe da implementação.

Também não deve virar um formulário de cinquenta campos. Seu papel é deixar claros o problema, os caminhos possíveis, a direção proposta e a evidência que mostrará se ela funcionou.

Se você já usa ADR, existe sobreposição: ele também pode começar como proposta e ser aceito ou rejeitado. A diferença mais útil está no foco. O Design Doc costuma avaliar uma solução inteira; o ADR concentra uma decisão arquitetural específica e suas consequências.

Para uma decisão menor, um ADR pode bastar. Quando a proposta envolve vários componentes, contratos, riscos, métricas e etapas de rollout, o Design Doc organiza o conjunto e pode originar vários ADRs. Mais adiante eles aparecem lado a lado, junto de RFC e Pull Request.

O que é um Design Doc

Um Design Doc é um documento relativamente informal que descreve como um problema técnico será atacado e por que aquela direção faz sentido.

A palavra importante é proposta.

Enquanto o documento está em discussão, a arquitetura ainda pode mudar. O autor não está apenas informando o que pretende construir.

Ele está expondo premissas e decisões para que outras pessoas encontrem problemas antes que a solução se materialize em banco de dados, contratos e infraestrutura e entre em uso.

Depois disso, usuários e sistemas passam a depender dela, e mudar de direção já exige migração, coordenação e mais risco.

Uma forma de enxergar seu papel é:

O modelo acima não é apenas uma forma didática de resumir o papel do documento. Uma das descrições mais conhecidas da prática vem do Google, onde Design Docs são escritos antes da implementação e se concentram na estratégia de alto nível, nas principais decisões e em seus trade-offs. A prática também ajuda a encontrar problemas cedo, reunir conhecimento distribuído, considerar preocupações transversais e preservar memória organizacional.

Isso não significa que um Design Doc seja uma descrição completa do sistema.

O documento precisa guardar aquilo que o código não preserva bem:

• as condições que tornaram o problema relevante;
• as alternativas que estavam realmente disponíveis;
• as restrições da época;
• os riscos aceitos;
• as dúvidas que ainda não tinham resposta;
• os resultados usados para validar a proposta.

O código mostrará a implementação final.

Ele não guardará sozinho que o time descartou GraphQL porque precisava lançar em oito semanas, que ninguém possuía experiência operacional com a tecnologia ou que a prioridade era reduzir tráfego mobile sem criar uma nova plataforma de APIs.

Design Doc não é Big Upfront Design

É fácil confundir documentação anterior ao código com Big Upfront Design.

A diferença está na pretensão.

Big Upfront Design tenta eliminar a incerteza por meio de detalhamento antecipado. O Design Doc tenta tornar a incerteza visível para que o time decida melhor.

Um documento saudável pode dizer:

Ainda não sabemos se o cache será necessário.

Vamos validar primeiro o payload e a latência sem cache. A decisão será reaberta se o p95 exceder 350 ms.

Isso é mais útil do que inventar uma estratégia completa de cache apenas para o documento parecer definitivo.

O Design Doc orienta a implementação, mas não finge que o contato com o código, a carga e a produção deixará de ensinar coisas novas.

Escrever também é uma forma de projetar

Uma ideia pode parecer perfeitamente clara enquanto está na cabeça de quem a formulou.

Quando ela vai para o papel, aparecem as lacunas:

• quem é dono desse dado?
• o que acontece se uma dependência ficar indisponível?
• como fazemos rollback?
• qual alternativa estamos realmente rejeitando?
• estamos movendo regra de negócio para o lugar errado?
• qual métrica prova que o problema foi resolvido?

Escrever força o raciocínio a deixar de depender de intuição.

O resultado final importa, mas o processo de formular o documento já produz valor. Ele transforma uma convicção individual em uma proposta que pode ser examinada por outras pessoas.

Quando vale escrever um Design Doc

O tamanho da tarefa não é a melhor régua.

Uma migração mecânica que altera quinhentos arquivos pode ter uma direção óbvia e baixo risco arquitetural. Já uma mudança de cinco linhas na forma como o sistema determina o tenant atual pode alterar uma fronteira de segurança inteira.

A pergunta não é "esta tarefa é grande?".

A pergunta é:

Existe uma decisão relevante que ficaria melhor se fosse discutida antes de ganhar inércia no código?

Cinco sinais ajudam a responder.

Uma mudança tende a justificar um Design Doc quando vários desses sinais aparecem juntos.

Um único sinal também pode bastar quando é crítico, como:

• mudança em autenticação ou autorização;
• alteração de uma API pública;
• migração irreversível de dados;
• nova dependência operacional central;
• modificação da semântica de consistência;
• mudança que atravessa uma trust boundary;
• rollout com risco significativo para usuários.

Quando não escrever

Design Docs também custam tempo.

Não vale escrever um documento completo para:

• refatoração local com comportamento preservado;
• endpoint simples que segue um padrão estabelecido;
• atualização mecânica de dependência;
• correção com causa e solução evidentes;
• experimento descartável cujo objetivo é apenas descobrir se algo funciona;
• tarefa em que não existe decisão real nem trade-off relevante.

Um sinal ruim é o documento que se transforma em manual de implementação:

1. Criar classe MobileCatalogController
2. Criar interface CatalogService
3. Adicionar método getCatalog()
4. Escrever teste unitário

Isso pode ser uma task, checklist ou descrição de Pull Request.

Se o documento apenas narra o código futuro, sem discutir alternativas, riscos ou escolhas, provavelmente seria melhor escrever o código.

Prototipar também pode fazer parte

Nem toda dúvida é resolvida com texto.

Algumas perguntas só têm resposta medindo, e é para isso que existe o spike:

• o driver realmente suporta o throughput esperado?
• o framework permite controlar o timeout necessário?
• a query usa o índice?
• o SDK funciona com o fluxo de autenticação existente?

Nesse caso, o Design Doc não compete com o protótipo. Ele faz a pergunta, aponta para o experimento e usa o resultado como evidência.

No documento, isso aparece nas duas pontas:

"Testamos e funcionou sob estas condições" é um argumento melhor do que "acreditamos que funcionará".

Falta uma regra, e é ela que separa o spike de simplesmente começar a construir: o experimento tem prazo e o código dele é descartável. Sem as duas coisas, ninguém decide que o protótipo virou a solução. Ele só nunca é apagado, e num certo dia já está em produção. É a cena que abriu este artigo, com outro nome.

O que um bom Design Doc precisa responder

Não existe um template universal.

Mesmo assim, bons documentos costumam responder a um conjunto parecido de perguntas.

Essas partes não precisam virar nove capítulos em todos os documentos.

Um Mini Design Doc pode resolver várias delas em poucos parágrafos.

O template deve lembrar perguntas importantes. Não deve obrigar o autor a inventar conteúdo apenas para preencher campos.

Contexto vem antes da solução

Compare as duas aberturas possíveis do mesmo documento:

No primeiro, a solução chegou antes de o problema ser demonstrado.

Perceba o que mudou: em vez de discutir como implementar um BFF, o time agora pode decidir qual caminho resolve melhor o problema.

Talvez o BFF seja a melhor direção.

Talvez a API existente possa fornecer uma representação mobile.

Talvez o problema esteja nas imagens, e uma nova camada de backend não resolva quase nada.

O contexto não precisa ser neutro a ponto de esconder urgência. Ele só não deve usar a solução como premissa.

Goals precisam virar evidência

"Melhorar performance" não é um objetivo utilizável.

Não diz qual aspecto da performance importa, de onde estamos partindo nem quanto precisa melhorar.

Um objetivo maduro funciona como um pequeno contrato de validação.

O exemplo abaixo é fictício:

## Goal

Reduzir os bytes transferidos na tela inicial do aplicativo.

**Baseline:** p50 = 420 KB por carregamento nos últimos 14 dias.

**Target:** p50 <= 290 KB após o rollout completo.

**Outcome metric:** mobile.home.payload_bytes

**Adoption metric:** pelo menos 95% das sessões mobile atendidas pelo BFF.

## Guardrails

- Taxa de erro <= baseline + 0,1 ponto percentual.
- Latência p95 do backend <= baseline + 5%.
- Custo mensal dentro do orçamento aprovado.

## Critérios de decisão

- Pausar o rollout se um guardrail for violado.
- Reavaliar o design se o target não for atingido após 7 dias.

## Goal

Reduzir os bytes transferidos na tela inicial do aplicativo.

**Baseline:** p50 = 420 KB por carregamento nos últimos 14 dias.

**Target:** p50 <= 290 KB após o rollout completo.

**Outcome metric:** mobile.home.payload_bytes

**Adoption metric:** pelo menos 95% das sessões mobile atendidas pelo BFF.

## Guardrails

- Taxa de erro <= baseline + 0,1 ponto percentual.
- Latência p95 do backend <= baseline + 5%.
- Custo mensal dentro do orçamento aprovado.

## Critérios de decisão

- Pausar o rollout se um guardrail for violado.
- Reavaliar o design se o target não for atingido após 7 dias.

Esse bloco separa três perguntas.

• Outcome metric: o benefício esperado apareceu?
• Adoption metric: a solução foi realmente adotada?
• Guardrails: aquilo que não poderia piorar foi preservado?

Reduzir payload e dobrar a taxa de erro não é sucesso.

Também não adianta melhorar a experiência de 10% das sessões e declarar vitória sobre o sistema inteiro.

Processos maduros, como o template de Kubernetes Enhancement Proposal, aproximam proposta e produção ao exigir planos de teste, estratégia de ativação e rollback, métricas e critérios de prontidão. Um Design Doc de produto não precisa copiar o processo do Kubernetes, mas pode aprender com o princípio: a decisão técnica não termina quando o desenho parece convincente.

Non-goal não cancela obrigação

Non-goal é algo relacionado ao problema que poderia entrar no escopo, mas foi deliberadamente deixado para fora.

Por exemplo:

Non-goal: substituir a API usada pelo frontend web.

Isso evita que a discussão do BFF vire uma reescrita de toda a plataforma.

Mas existe uma armadilha. Segurança mínima não é uma feature opcional que pode ser excluída do desenho:

O non-goal limita o espaço da mudança.

Ele não remove os requisitos necessários para que a solução possa entrar em produção.

O design mostra a direção

A seção de design começa com a visão geral.

Ela deve permitir que alguém entenda:

• quais componentes entram ou mudam;
• quem chama quem;
• onde os dados vivem;
• quem é owner de cada responsabilidade;
• quais contratos atravessam a fronteira;
• onde podem ocorrer falhas;
• que parte é nova e que parte já existe.

Só depois entram os detalhes necessários para avaliar a proposta.

Uma pergunta resolve boa parte da dúvida sobre nível de detalhe:

Este detalhe altera a avaliação da solução?

Se altera, ele pertence ao Design Doc.

Se apenas descreve trabalho mecânico, provavelmente pertence ao código, à API formal, à migration ou à task.

Alguns exemplos:

• Contrato público: mostre os campos e comportamentos que afetam compatibilidade.
• Modelo de dados: mostre ownership, chaves, cardinalidade, retenção e consistência relevantes.
• Algoritmo novo: use pseudocódigo quando o raciocínio determina corretude ou performance.
• Fluxo distribuído: mostre sequência, timeout, retry, idempotência e falhas.
• Classes e métodos comuns: deixe para o código.
• OpenAPI ou schema completo: linke o artefato, não cole centenas de linhas.

Diagramas também precisam de propósito.

Um diagrama de contexto pode mostrar onde o novo componente entra. Um diagrama de sequência pode revelar chamadas, dependências e pontos de falha. Nenhum deles é autoexplicativo: depois do desenho, descreva o fluxo e destaque o que precisa ser revisado.

Alternativas precisam perder de forma honesta

Uma proposta fraca faz a opção preferida parecer excelente e transforma as demais em caricaturas.

Um comparativo mais honesto permite que cada alternativa vença em algum eixo.

GraphQL não precisa ser tecnicamente inferior para perder.

Ele pode ser a opção mais flexível e ainda assim não caber no prazo, na capacidade operacional ou no tamanho atual do problema.

Isso é trade-off de verdade.

A opção escolhida não vence tudo. Ela atende melhor aos objetivos dentro das restrições disponíveis.

Produção faz parte do design

Algumas preocupações atravessam qualquer solução e costumam aparecer tarde demais:

• autenticação e autorização;
• privacidade e residência de dados;
• observabilidade;
• capacidade e custo;
• disponibilidade e degradação;
• compatibilidade;
• migração;
• rollout e rollback;
• suporte e ownership operacional.

Não é necessário escrever um tratado sobre cada item.

O documento precisa dizer como a proposta afeta cada preocupação relevante e apontar para análises separadas quando o tema exigir profundidade própria.

Por exemplo:

Observabilidade. O BFF propagará trace context para as três dependências. Teremos métricas por dependência, timeout e fallback.

Degradação. Falha em recomendações não derrubará a tela. O bloco será omitido e a resposta continuará com catálogo e preços.

Rollback. O aplicativo continuará capaz de usar a composição anterior durante o rollout inicial.

Isso já muda bastante a qualidade da revisão.

Da proposta à produção

Um Design Doc que termina em Approved está incompleto.

A aprovação mostra que a direção parece razoável com as informações disponíveis. Não prova que a implementação respeitou o desenho nem que o resultado apareceu em produção.

Um fluxo leve pode seguir cinco etapas.

1. Escreva o primeiro rascunho. O autor organiza contexto, goals, opções e proposta. Coautores podem participar quando o conhecimento está distribuído.

2. Revise com quem conhece o problema. Antes de enviar para uma audiência grande, envolva pessoas próximas do domínio. Elas corrigem premissas básicas sem consumir atenção de toda a organização.

3. Peça revisão direcionada. Segurança revisa a trust boundary. SRE analisa operação e falhas. Times consumidores verificam contratos. Cada pessoa precisa saber qual parte exige sua atenção.

4. Registre a decisão e implemente. A proposta pode ser aprovada, rejeitada, adiada ou devolvida para revisão. Durante a implementação, o documento acompanha descobertas que mudem o design.

5. Valide e preserve o histórico. Depois do rollout, compare métricas e guardrails. Quando a solução estabilizar, preserve o racional e ligue mudanças futuras a novos documentos ou amendments.

Autor, reviewer e approver não são a mesma coisa

Misturar os papéis cria dois problemas: ninguém sabe quem decide e todo comentário parece ter poder de veto.

Uma divisão prática:

• Autor ou DRI: conduz o documento, responde às dúvidas e mantém a proposta avançando.
• Contributor: fornece dados, protótipos, alternativas ou conhecimento específico.
• Reviewer: avalia a proposta e aponta riscos ou melhorias.
• Required reviewer: representa uma área cuja aprovação é obrigatória, como Segurança em uma mudança de trust boundary.
• Approver ou decision owner: possui autoridade para aceitar a direção.
• Informed: precisa saber que a decisão aconteceu, mas não bloqueia o processo.

Nem todo Design Doc precisa formalizar todos esses papéis.

Quanto maior o raio de impacto, mais importante fica deixar a autoridade explícita.

A revisão acompanha o impacto

O erro está nos extremos.

Sem revisão, o documento vira justificativa escrita depois que alguém já decidiu sozinho.

Com aprovação central para tudo, o Design Doc entra numa fila e o time aprende a contornar o processo.

A revisão não precisa reunir vinte pessoas.

Precisa incluir as pessoas que conseguem encontrar riscos que o autor não enxerga.

Dê prazo para o feedback

"Quando tiver um tempo, dá uma olhada" não é um processo de revisão.

O documento precisa informar:

• até quando o feedback é esperado;
• quem é obrigatório;
• quem é opcional;
• quem toma a decisão final;
• o que acontece se houver mudança material na proposta.

Não existe um prazo universal.

Uma decisão local pode receber comentários em poucos dias. Uma mudança de API pública ou infraestrutura compartilhada pode exigir uma janela maior.

O processo de RFC do Rust mostra uma versão formal dessa ideia: a proposta recebe discussão pública, o autor revisa em resposta ao feedback, e a decisão só acontece depois de um final comment period de dez dias corridos, anunciado publicamente. Um squad de produto não precisa copiar esse mecanismo, mas deveria copiar o princípio de que comentários possuem momento, responsabilidade e fechamento explícitos.

Atualize enquanto a solução ainda está nascendo

Durante a implementação, o plano encontra a realidade.

Uma API não suporta o comportamento esperado. O banco escolhe outro plano. Um requisito aparece tarde. O custo da solução muda.

Se o sistema ainda não foi lançado e a mudança altera o design, atualize o documento.

Depois que a solução entra em produção e estabiliza, o papel começa a mudar.

O Design Doc deixa de ser apenas proposta viva e passa a ser também registro histórico. Reescrever silenciosamente o racional original pode apagar o contexto que o documento deveria preservar.

Uma política simples:

• Antes do lançamento: atualize o documento conforme o design muda.
• Durante o rollout: registre desvios, decisões e evidências relevantes.
• Depois da estabilização: preserve o racional e use amendments ou novos documentos para mudanças materiais.
• Se uma decisão arquitetural específica precisar sobreviver: registre também um ADR relacionado.

Um Mini Design Doc na prática

O exemplo abaixo é fictício.

Ele não tenta ser um modelo universal. Mostra quanto contexto cabe em um documento curto quando cada seção possui uma função clara.

# DD-0042: Criar um BFF para a tela inicial mobile

* Status: Under Review
* Owner: Time Mobile Platform
* Autores: Ana Souza, Bruno Lima
* Required reviewers: Catálogo, Segurança, SRE
* Prazo para decisão: 2026-09-04
* Sistemas impactados: App Mobile, Catálogo, Preços, Recomendações

## Visão geral

Propomos criar um BFF para compor os dados da tela inicial do aplicativo
em uma única resposta orientada às necessidades mobile.

O componente agregará catálogo, preços e recomendações, sem assumir
regras de domínio pertencentes a esses serviços.

## Contexto e escopo

A tela inicial realiza cinco requisições e transfere 420 KB no
carregamento mediano.

O aplicativo replica lógica de composição e fallback que já existe em
outros clientes. Em redes de maior latência, a quantidade de round trips
atrasa a primeira renderização.

A API atual atende também o frontend web. Alterá-la para otimizar apenas
o mobile aumenta o acoplamento entre experiências diferentes.

## Goals

* Reduzir o payload p50 de 420 KB para no máximo 290 KB.
* Reduzir a quantidade de chamadas do aplicativo de cinco para uma.
* Preservar a taxa de erro atual.
* Manter a latência p95 do backend dentro de 5% do baseline.
* Permitir degradação parcial quando Recomendações estiver indisponível.

## Non-goals

* Substituir a API usada pelo frontend web.
* Introduzir um novo mecanismo de autenticação.
* Mover regras de catálogo, preço ou recomendação para o BFF.
* Criar uma plataforma GraphQL corporativa.

## Design proposto

O aplicativo chamará GET /mobile/v1/home.

O BFF consultará Catálogo, Preços e Recomendações em paralelo.

Catálogo e Preços são obrigatórios. Se um deles falhar, a requisição
falha.

Recomendações são opcionais. Em timeout ou erro, o bloco será omitido.

O BFF não terá banco próprio. Um cache de 30 segundos poderá ser usado
apenas para conteúdo não personalizado, depois de medirmos a solução
sem cache.

Fluxo:

App Mobile
|
v
Mobile Home BFF
|----> Catálogo
|----> Preços
|----> Recomendações

## Contrato inicial

GET /mobile/v1/home?storeId={storeId}

Resposta:

* hero
* categories[]
* featuredProducts[]
* recommendations[]
* generatedAt

A ausência de recommendations não representa erro da resposta inteira.

## Alternativas consideradas

### Adaptar a API atual

É a opção mais rápida e não cria outro serviço.

Foi rejeitada porque mistura necessidades web e mobile no mesmo
contrato e mantém a composição distribuída entre clientes.

### Manter composição no aplicativo

Evita um novo componente backend.

Foi rejeitada porque mantém cinco round trips, duplica fallbacks e
transfere ao cliente conhecimento sobre três serviços internos.

### GraphQL gateway

É a opção mais flexível para múltiplos clientes.

Não foi escolhida agora porque introduz uma mudança maior de plataforma,
governança de schema e operação. Deve ser reavaliada caso outros clientes
apresentem a mesma necessidade.

### BFF mobile

Adiciona um serviço e responsabilidade operacional.

Foi escolhido porque concentra composição específica do mobile sem
alterar os contratos dos domínios nem iniciar uma plataforma mais ampla.

## Segurança e privacidade

O BFF reutilizará o mecanismo atual de autenticação.

A autorização continuará sendo aplicada pelos serviços de domínio.
O BFF não confiará apenas em filtros enviados pelo aplicativo.

Tokens não serão registrados em logs.

## Observabilidade e operação

* Trace distribuído entre BFF e dependências.
* Métricas de latência, erro, timeout e fallback por dependência.
* Dashboard de payload e adoção mobile.
* Owner operacional: Time Mobile Platform.
* Runbook para falha total e degradação parcial.

## Rollout e rollback

O aplicativo manterá temporariamente o fluxo anterior atrás de uma
feature flag.

Rollout: 5% -> 25% -> 50% -> 100%.

O avanço depende dos guardrails de erro e latência.

Em caso de violação, o tráfego retorna ao fluxo anterior sem novo deploy.

## Validação

Outcome:

* mobile.home.payload_bytes p50 <= 290 KB.

Adoption:

* pelo menos 95% das sessões mobile usando o BFF.

Guardrails:

* error rate <= baseline + 0,1 ponto percentual;
* backend p95 <= baseline + 5%;
* custo mensal dentro do orçamento aprovado.

## Questões abertas

* O timeout de Recomendações deve ser 100 ou 150 ms?
* Precisamos de cache depois do rollout inicial?
* O campo generatedAt pertence à resposta ou à telemetria?

## Referências

* PRD do aplicativo mobile
* Dashboard da tela inicial
* Spike de composição paralela
* ADR de autenticação entre serviços

# DD-0042: Criar um BFF para a tela inicial mobile

* Status: Under Review
* Owner: Time Mobile Platform
* Autores: Ana Souza, Bruno Lima
* Required reviewers: Catálogo, Segurança, SRE
* Prazo para decisão: 2026-09-04
* Sistemas impactados: App Mobile, Catálogo, Preços, Recomendações

## Visão geral

Propomos criar um BFF para compor os dados da tela inicial do aplicativo
em uma única resposta orientada às necessidades mobile.

O componente agregará catálogo, preços e recomendações, sem assumir
regras de domínio pertencentes a esses serviços.

## Contexto e escopo

A tela inicial realiza cinco requisições e transfere 420 KB no
carregamento mediano.

O aplicativo replica lógica de composição e fallback que já existe em
outros clientes. Em redes de maior latência, a quantidade de round trips
atrasa a primeira renderização.

A API atual atende também o frontend web. Alterá-la para otimizar apenas
o mobile aumenta o acoplamento entre experiências diferentes.

## Goals

* Reduzir o payload p50 de 420 KB para no máximo 290 KB.
* Reduzir a quantidade de chamadas do aplicativo de cinco para uma.
* Preservar a taxa de erro atual.
* Manter a latência p95 do backend dentro de 5% do baseline.
* Permitir degradação parcial quando Recomendações estiver indisponível.

## Non-goals

* Substituir a API usada pelo frontend web.
* Introduzir um novo mecanismo de autenticação.
* Mover regras de catálogo, preço ou recomendação para o BFF.
* Criar uma plataforma GraphQL corporativa.

## Design proposto

O aplicativo chamará GET /mobile/v1/home.

O BFF consultará Catálogo, Preços e Recomendações em paralelo.

Catálogo e Preços são obrigatórios. Se um deles falhar, a requisição
falha.

Recomendações são opcionais. Em timeout ou erro, o bloco será omitido.

O BFF não terá banco próprio. Um cache de 30 segundos poderá ser usado
apenas para conteúdo não personalizado, depois de medirmos a solução
sem cache.

Fluxo:

App Mobile
|
v
Mobile Home BFF
|----> Catálogo
|----> Preços
|----> Recomendações

## Contrato inicial

GET /mobile/v1/home?storeId={storeId}

Resposta:

* hero
* categories[]
* featuredProducts[]
* recommendations[]
* generatedAt

A ausência de recommendations não representa erro da resposta inteira.

## Alternativas consideradas

### Adaptar a API atual

É a opção mais rápida e não cria outro serviço.

Foi rejeitada porque mistura necessidades web e mobile no mesmo
contrato e mantém a composição distribuída entre clientes.

### Manter composição no aplicativo

Evita um novo componente backend.

Foi rejeitada porque mantém cinco round trips, duplica fallbacks e
transfere ao cliente conhecimento sobre três serviços internos.

### GraphQL gateway

É a opção mais flexível para múltiplos clientes.

Não foi escolhida agora porque introduz uma mudança maior de plataforma,
governança de schema e operação. Deve ser reavaliada caso outros clientes
apresentem a mesma necessidade.

### BFF mobile

Adiciona um serviço e responsabilidade operacional.

Foi escolhido porque concentra composição específica do mobile sem
alterar os contratos dos domínios nem iniciar uma plataforma mais ampla.

## Segurança e privacidade

O BFF reutilizará o mecanismo atual de autenticação.

A autorização continuará sendo aplicada pelos serviços de domínio.
O BFF não confiará apenas em filtros enviados pelo aplicativo.

Tokens não serão registrados em logs.

## Observabilidade e operação

* Trace distribuído entre BFF e dependências.
* Métricas de latência, erro, timeout e fallback por dependência.
* Dashboard de payload e adoção mobile.
* Owner operacional: Time Mobile Platform.
* Runbook para falha total e degradação parcial.

## Rollout e rollback

O aplicativo manterá temporariamente o fluxo anterior atrás de uma
feature flag.

Rollout: 5% -> 25% -> 50% -> 100%.

O avanço depende dos guardrails de erro e latência.

Em caso de violação, o tráfego retorna ao fluxo anterior sem novo deploy.

## Validação

Outcome:

* mobile.home.payload_bytes p50 <= 290 KB.

Adoption:

* pelo menos 95% das sessões mobile usando o BFF.

Guardrails:

* error rate <= baseline + 0,1 ponto percentual;
* backend p95 <= baseline + 5%;
* custo mensal dentro do orçamento aprovado.

## Questões abertas

* O timeout de Recomendações deve ser 100 ou 150 ms?
* Precisamos de cache depois do rollout inicial?
* O campo generatedAt pertence à resposta ou à telemetria?

## Referências

* PRD do aplicativo mobile
* Dashboard da tela inicial
* Spike de composição paralela
* ADR de autenticação entre serviços

Repare no que o exemplo não faz.

Ele não define nomes de classes.

Não cola o OpenAPI inteiro.

Não descreve todos os campos dos serviços consultados.

Também não tenta resolver GraphQL para a empresa toda.

O documento preserva as decisões que mudam a avaliação da proposta: fronteira do BFF, dependências obrigatórias e opcionais, ownership, fallback, alternativas, rollout e evidência.

Para mostrar o contrato sem afundar em detalhes, uma representação curta poderia aparecer assim:

{
	"hero": {
		"title": "Ofertas da semana"
	},
	"categories": [],
	"featuredProducts": [],
	"recommendations": [],
	"generatedAt": "2026-08-30T18:20:00Z"
}

{
	"hero": {
		"title": "Ofertas da semana"
	},
	"categories": [],
	"featuredProducts": [],
	"recommendations": [],
	"generatedAt": "2026-08-30T18:20:00Z"
}

O restante pertence ao contrato formal e ao código.

Esse é o nível de detalhe decisório: suficiente para revisar a direção, curto o bastante para continuar legível.

Design Doc, ADR, RFC ou Pull Request

Esses nomes não possuem fronteiras universais.

Uma empresa chama o mesmo tipo de documento de Design Doc. Outra usa RFC, Engineering Review Doc, Technical Proposal ou Tech Spec.

A função importa mais do que o rótulo.

Um Design Doc pode originar um ADR.

O documento mais amplo guarda o problema, os fluxos, os experimentos e a estratégia de implantação. O ADR concentra uma decisão arquitetural específica, podendo começar como proposta e permanecer depois como registro histórico.

Por exemplo:

Um RFC pode cumprir exatamente o papel que este artigo atribui ao Design Doc.

Não existe problema nisso.

O erro é manter quatro formatos quase idênticos sem que ninguém saiba quando usar cada um.

Uma regra prática:

Use o artefato de menor custo que preserve contexto suficiente para a decisão em questão.

Se uma boa descrição no Pull Request resolve, pare ali.

Se existe uma solução inteira para revisar, use Design Doc.

Se uma decisão arquitetural específica precisa ser discutida e depois preservada, use ADR.

Se a proposta exige comentários amplos ou padronização organizacional, seu processo pode chamá-la de RFC.

Como adotar Design Docs sem criar um cartório

A adoção não começa comprando uma ferramenta ou criando um architecture board.

Começa pela próxima decisão ambígua.

1. Escolha um documento mínimo. Use visão geral, contexto, goals, non-goals, design, alternativas, riscos e validação. Retire o que não trouxer informação.

2. Defina quando ele se aplica. Use ambiguidade, impacto, reversibilidade, coordenação e longevidade. Não use número de arquivos ou tamanho da estimativa.

3. Escolha uma fonte oficial. Git, wiki ou editor colaborativo podem funcionar. O problema começa quando existem três cópias concorrentes.

4. Defina quem revisa e quem decide. Required reviewer, approver e prazo precisam estar claros quando o impacto justificar.

5. Ligue documento e implementação. Design Doc aponta para issues e Pull Requests. A implementação aponta de volta para o documento.

6. Valide depois do lançamento. Compare target, adoption e guardrails. Registre o resultado em vez de abandonar o documento no estado Approved.

7. Ajuste o processo com o uso. Campo que ninguém preenche sai. Review que não encontra risco é redirecionado. Documento que nunca é consultado exige investigação.

Onde guardar

Para times que trabalham naturalmente em Git, uma estrutura simples pode ser:

O README.md pode funcionar como índice, mostrando status, owner, domínio e sistemas impactados.

O GitHub permite usar CODEOWNERS para solicitar automaticamente revisões de pessoas ou times responsáveis por determinados caminhos e, quando a proteção da branch é configurada para isso, exigir a aprovação desses owners.

Isso pode servir para documentos altamente técnicos:

/docs/design/security/   @security-team
/docs/design/payments/   @payments-architecture
/docs/design/platform/   @platform-team

/docs/design/security/   @security-team
/docs/design/payments/   @payments-architecture
/docs/design/platform/   @platform-team

Mas Git não é automaticamente a melhor escolha para toda organização.

Se produto, jurídico, design ou operação participam regularmente, um editor colaborativo ou wiki pode reduzir atrito.

Em empresas maiores, um modelo híbrido costuma funcionar melhor:

• fonte canônica claramente definida;
• escrita perto de quem decide;
• publicação em um catálogo pesquisável;
• links entre documento, código, ADRs e operação.

A ferramenta deve facilitar escrita, revisão, descoberta e manutenção.

Todo o resto é preferência.

Cinco formas de matar a prática

• Transformar o template em prova de obediência: o autor preenche campos sem informação apenas porque eles existem.
• Escrever depois do código: o documento vira racionalização retrospectiva da primeira solução implementada.
• Convidar todo mundo para revisar tudo: a atenção se dilui e ninguém sabe quem realmente precisa responder.
• Não definir decisão nem prazo: o documento acumula comentários, mas nunca sai do estado de discussão.
• Medir quantidade de documentos: Design Docs podem servir como evidência de influência e raciocínio técnico, mas transformar o número deles em KPI incentiva volume, não qualidade.

O sinal de sucesso não é ter uma pasta cheia.

É encontrar problemas cedo, tomar decisões mais claras, reduzir discussões repetidas e conseguir explicar por que uma solução tomou determinada forma.

Antes de fechar, cinco situações para julgar: quando o documento se paga, o que um non-goal pode excluir, o que conta como sucesso depois do rollout e o que precisa virar ADR.

Conclusão

A primeira versão do BFF poderia ter começado com código. Um endpoint, três clients HTTP, um DTO e a promessa de arrumar o restante depois.

Isso parece rápido até a equipe descobrir, durante a implementação, que cada pessoa estava resolvendo um problema diferente.

O Design Doc coloca essa conversa no lugar certo.

Ele não elimina a incerteza. Impede que ela fique escondida até produção.

Esse é o ponto central:

Design Doc não existe para prever todo o código. Existe para tornar uma decisão técnica revisável antes que mudar de ideia fique caro.

Provavelmente existe uma decisão em aberto no seu time agora, daquelas que já apareceram em duas reuniões e continuam recebendo soluções diferentes.

Antes de escolher a tecnologia, escreva cinco coisas:

1. qual problema observável precisa ser resolvido;
2. quais caminhos são realmente plausíveis;
3. por que a opção preferida combina melhor com o contexto;
4. qual preço o time aceita pagar;
5. qual evidência fará a proposta continuar ou voltar para a mesa.

Se nenhum trade-off aparecer, talvez uma boa Pull Request seja suficiente.

Se a decisão ficar mais clara antes da primeira linha de produção, o Design Doc já se pagou.