Tomada de decisão técnica em grupo: RFCs, ADRs e design docs

1. Por que a tomada de decisão técnica em grupo é essencial

Em times de engenharia, decisões técnicas moldam o futuro do produto. Uma escolha mal documentada ou tomada unilateralmente pode gerar retrabalho, aumentar o débito técnico e até acelerar a rotatividade do time — especialmente quando novos membros herdam decisões sem contexto. O custo do consenso mal feito é alto: semanas de implementação descartadas, conflitos de arquitetura e a famosa "dívida de conhecimento".

A diferença fundamental está no escopo. Decisões individuais (como um spike para validar uma biblioteca) são rápidas e reversíveis. Já decisões coletivas — que afetam a arquitetura, o fluxo de dados ou a stack tecnológica — exigem documentação, transparência e alinhamento. É aí que entram RFCs, ADRs e design docs como ferramentas complementares.

A documentação funciona como "memória do time". Ela permite que qualquer pessoa, em qualquer momento, entenda não apenas o que foi decidido, mas por quê. Isso acelera o onboarding e reduz a dependência de conhecimento tácito.

2. RFCs (Request for Comments): o motor da discussão aberta

RFCs são o ponto de partida para discussões técnicas abertas. Inspiradas no modelo da IETF, elas estruturam propostas de forma que todos possam contribuir antes da decisão final.

Uma RFC eficaz contém:
- Problema: descrição clara do que se busca resolver
- Contexto: restrições, dependências e decisões anteriores relevantes
- Proposta: solução detalhada, com alternativas consideradas
- Trade-offs: prós e contras de cada abordagem

O ciclo de vida típico é: rascunho → comentários → decisão → arquivamento. Boas práticas incluem definir prazos para feedback (ex.: 5 dias úteis), manter neutralidade na redação e priorizar revisão assíncrona para evitar reuniões desnecessárias.

RFC: Adoção de GraphQL no gateway de APIs
Status: Em discussão
Problema: Over-fetching e under-fetching nas chamadas REST atuais
Proposta: Substituir endpoints REST por esquema GraphQL unificado
Trade-offs: Curva de aprendizado do time, complexidade de caching

3. ADRs (Architecture Decision Records): capturando o "porquê"

Enquanto RFCs são para discussão, ADRs são para registro. Eles documentam decisões arquiteturais de forma leve e rastreável. O formato mais comum inclui status, contexto, decisão e consequências.

ADRs evoluem com o tempo. Uma decisão pode ser aceita, depreciada ou substituída. O versionamento permite rastrear o histórico completo — essencial quando uma escolha anterior precisa ser revisitada.

Exemplo de ADR:

Status: Aceito
Contexto: Precisamos de cache distribuído para reduzir latência em 40%
Decisão: Adotar Redis Cluster com replicação cross-region
Consequências: Aumento de custo de infra, mas ganho de resiliência

ADRs são especialmente úteis para:
- Justificar escolhas para auditorias ou novos membros
- Evitar repetição de debates já encerrados
- Servir como fonte de verdade para a arquitetura atual

4. Design docs: o blueprint antes do código

Design docs são documentos mais detalhados que descrevem como uma solução será implementada. Eles são o "blueprint" antes do código, ideais para mudanças complexas que envolvem múltiplos sistemas.

Quando escrever um design doc:
- A mudança afeta mais de um serviço ou equipe
- Existem requisitos não-funcionais críticos (performance, segurança, escalabilidade)
- A solução envolve trade-offs significativos

Seções obrigatórias:
- Objetivos não-funcionais: latência, throughput, disponibilidade
- Diagramas de alto nível: fluxo de dados, componentes, interações
- Alternativas descartadas: com justificativa clara

A revisão estruturada deve incluir um checklist de completude: o documento cobre fallbacks? Há planos de rollback? Os riscos foram mapeados? O alinhamento com produto precisa ser explícito — uma solução tecnicamente elegante que não atende às necessidades de negócio é uma falha.

5. Integração das ferramentas no fluxo de desenvolvimento

Cada ferramenta tem seu papel no ciclo de vida da decisão:

  • RFC: abertura da discussão, exploração de alternativas
  • ADR: registro formal da decisão, com contexto e consequências
  • Design doc: detalhamento da implementação, com diagramas e planos

Os gatilhos típicos para iniciar esse fluxo são: nova feature com impacto arquitetural, mudança de stack tecnológica, ou necessidade de escalar um sistema existente.

Exemplo de workflow integrado:

RFC → Discussão → Decisão → ADR → Design Doc → Implementação → Revisão

Na prática, o RFC gera o ADR, que por sua vez referencia o design doc. Tudo fica versionado no repositório do projeto, acessível a todos.

RFC #42: Migração de banco relacional para NoSQL
  ├── ADR-001: Escolha do MongoDB como banco primário
  │     └── design-docs/mongodb-migration.md
  └── ADR-002: Estratégia de migração por shadow reads
        └── design-docs/shadow-reads-strategy.md

6. Armadilhas comuns e como evitá-las

"Paralisia por análise" — quando o processo se torna mais importante que a decisão. Para evitar, defina prazos máximos para cada etapa. Uma RFC que não recebe feedback em 5 dias úteis pode ser considerada aprovada por silêncio.

Decisões não documentadas — geram "dívida de conhecimento". A solução é criar um PR obrigatório para qualquer ADR ou design doc, com revisão mínima de um arquiteto ou tech lead.

Discordância persistente — quando o grupo não chega a um consenso. Nesse caso, tenha critérios de desempate claros: o tech lead ou arquiteto principal decide, documentando a justificativa. A discordância não precisa ser eliminada, mas o bloqueio precisa ser quebrado.

Outra armadilha comum é tratar RFCs, ADRs e design docs como documentos estáticos. Eles devem ser atualizados conforme a implementação revela novos aprendizados. Um ADR "aceito" pode se tornar "depreciado" seis meses depois — e isso é saudável.

Conclusão

RFCs, ADRs e design docs formam um ecossistema de tomada de decisão técnica que equilibra transparência, velocidade e rastreabilidade. RFCs abrem o debate, ADRs fixam o "porquê" e design docs detalham o "como". Juntos, eles transformam decisões isoladas em conhecimento compartilhado, reduzem retrabalho e fortalecem a cultura técnica do time.

Adotar esse fluxo não elimina discordâncias, mas garante que elas sejam produtivas e documentadas. O resultado é um time mais alinhado, uma arquitetura mais coesa e um código que reflete escolhas conscientes — não apenas o caminho mais rápido.

Referências