Planejamentos de engenharia com RFC, documentos de design e ADRs
Mais do que apenas registrar, a documentação resolve problemas
Muitos times de desenvolvimento acreditam que a documentação atrasa o processo de execução do produto. Mas, na prática, é o oposto, ao dar clareza, previsibilidade e contexto às escolhas, ela evita retrabalho e impede o caos de decisões mal comunicadas, e com a ascensão da IA sendo cada vez mais utilizada pelas empresas e pelos times de desenvolvimento, torna-se ainda mais importante documentar, para dar contexto aos modelos de linguagem e padronizar seus usos. Para Elton Minetto, principal software engineer no PicPay, documentar a solução antes de começar a implementar permite que o time pense nos prós e contras, nas alternativas, nos problemas a serem resolvidos antes de se começar a colocar a mão na massa. Isso pode salvar projetos inteiros, reduzir incertezas e tornar o desenvolvimento mais suave.
Mais do que relatórios extensos e esquecidos em uma pasta, ferramentas como RFCs (Request for Comments), Design Docs e ADRs (Architecture Decision Records) funcionam como um mapa descritivo do sistema. Eles registram o raciocínio por trás da solução, ajudam o time a alinhar expectativas e criam uma base sólida para quem entra no projeto no futuro.
RFCs (Request For Comments): são documentos de padronização. Usados para definir padrões que serão usados por por um time, empresa ou mesmo pelo mercado como um todo.
Documento de Design (Design Doc): Documenta o escopo de uma funcionalidade, refatoração ou novo produto. Nele são descritos objetivos, alternativas, prós e contras de diferentes decisões.
ADRs (Architecture Decision Records): Documentam as decisões tomadas pela equipe ou empresa, como a escolha de um banco de dados, arquitetura ou linguagem.
RFCs e padronização
RFCs são usados quando existe a necessidade de padronizar as escolhas técnicas em vários projetos ou times. É utilizado quando precisa definir uma forma única para padrões arquiteturais, protocolos de comunicação ou linguagens.
O principal benefício de um RFC, segundo Minetto, é permitir que a equipe avalie prós e contras e alternativas antes de começar a implementar, o que reduz incertezas e pode salvar projetos inteiros ao solucionar problemas na fase de planejamento.
Um exemplo prático é a criação de um RFC para padronizar o desenvolvimento de APIs Rest (formatos de parâmetros, tratamento de erros, etc.). Isso torna o processo de integração entre as APIs muito mais simples e ordenado, prevenindo problemas futuros de compatibilidade.
Design docs como parte do ciclo de desenvolvimento
Se a sua equipe costuma descobrir falhas e gargalos apenas na fase de implementação, ela está falhando caro. O Design Doc muda essa lógica ao forçar a resolução do problema no papel, antes de uma linha de código ser escrita.
Resumidamente, como explica Minetto, um Design Doc de qualidade precisa responder essas principais perguntas para o negócio e a arquitetura:
Motivação e contexto: por que estamos fazendo isso agora?
Critérios de metas: como vamos mensurar se a solução deu certo?
Propostas avaliadas: quais alternativas foram pensadas no momento da decisão?
Proposta escolhida: qual alternativa foi selecionada e o porquê?
Como referência de boas práticas, o post “Design Docs at Google” mostra que um design doc eficaz inclui seções como Contexto e escopo, Objetivos e não-objetivos, Alternativas consideradas e Proposta escolhida, além de enfatizar os trade‑offs envolvidos nas decisões.
A dica de ouro para times com dificuldade de documentar é integrar a escrita ao ciclo de desenvolvimento. A primeira entrega de uma nova funcionalidade pode ser o Design Doc, e só depois o time começa a desenvolver.
ADRs e contextualização
Times ágeis tendem a tomar decisões mais rapidamente, e é aqui que se utilizam as ADRs, para dar contexto a essas decisões.
Documentar as decisões arquiteturais também ajudam para o onboarding de novas pessoas e para evitar confusão no futuro. A ausência de um registro simples pode levar a situações como a que Minetto já viveu: ter que responder a perguntas como “por que estamos usando X ao invés de Y?” e ter dificuldade em explicar o contexto que existia no momento daquela escolha.
As ADRs precisam ser um documento simples e de fácil compreensão, para facilitar a contextualização do projeto e dos envolvidos.
Boas práticas
Em resumo, a força de um time de engenharia não está em fugir da documentação, mas em utilizar esse processo como ferramenta.
Documentar demais é um problema quando o processo se torna uma desculpa para não tomar decisões. A solução é o equilíbrio. O conselho final do Minetto para engenheiros que querem evoluir o planejamento é: “Comece simples e vá aumentando a complexidade apenas se necessário.”
Documentar, escrever sobre suas decisões, é um exercício que dá retornos tanto em qualidade quanto em agilidade. Ao evitar o retrabalho e aumentar a certeza das escolhas, o time passa a focar no que realmente importa: na entrega de valor ao usuário e na assertividade do negócio.
Referências do artigo
UBL, Malte. Design Docs at Google. Industrial Empathy, 6 jul. 2020. Disponível em: https://www.industrialempathy.com/posts/design-docs-at-google/. Acesso em: 6 out. 2025.
DAGDEVIREN, Candost. ADRs vs RFCs: Differences, When & Which? Candost.blog, [s.d.]. Disponível em: https://candost.blog/adrs-rfcs-differences-when-which/. Acesso em: 6 out. 2025.
BEN SALEM, Ahmed. Architecture Decision Record: How and why use ADRs? Scrum-Master.org, 13 maio 2024. Disponível em: https://scrum-master.org/en/architecture-decision-record-how-and-why-use-adrs/. Acesso em: 6 out. 2025.