Escrever RFCs Técnicos que Realmente São Lidos e Orientam as Decisões
As decisões técnicas mais caras numa organização de engenharia acontecem em threads de Slack que desaparecem, em reuniões onde metade das partes interessadas está ausente, ou na cabeça de um engenheiro sénior sem o contributo de mais ninguém. Depois seis meses mais tarde, quando a arquitetura começa a ranger e alguém pergunta "porque é que construímos assim?", ninguém se lembra. Ou pior, toda a gente se lembra de forma diferente.
Os RFCs — documentos de Pedido de Comentários — resolvem este problema. São uma das ferramentas mais poderosas disponíveis para as equipas de engenharia, e uma das mais subutilizadas. Já os vi transformar a forma como as equipas tomam decisões, se alinham através de fusos horários e constroem memória institucional. Também já os vi mal feitos, tornando-se romances de 40 páginas que ninguém lê e que atrasam tudo.
Aqui está como fazê-los bem.
Por Que os RFCs Importam
Um RFC é uma proposta escrita para uma decisão técnica significativa, partilhada com a equipa para feedback antes que a implementação comece. É tudo. Não uma especificação. Não documentação. Uma proposta que convida contributos.
O valor vem de três coisas:
Clareza forçada de pensamento. Escrever obriga-te a estruturar o teu raciocínio. A ideia vaga que parecia ótima na tua cabeça é testada quando tens de a explicar no papel. Já escrevi RFCs onde o ato de escrever revelou que a minha solução proposta tinha uma falha fundamental que não tinha notado. Esse é o ponto — é mais barato encontrar a falha num documento do que no código de produção.
Alinhamento assíncrono. Numa equipa distribuída que abrange múltiplos fusos horários, as reuniões síncronas são caras e exclusivas. Alguém está sempre a juntar-se numa hora inconveniente, alguém está sempre ausente. Um RFC permite que todos contribuam com a sua perspetiva no seu próprio horário. O engenheiro em Buenos Aires e o de Berlim leem o mesmo documento e adicionam os seus comentários sem precisar de encontrar uma sobreposição de 30 minutos.
Memória institucional. Daqui a seis meses, um novo membro da equipa vai perguntar por que o sistema usa event sourcing em vez de um padrão CRUD tradicional. Em vez de depender da história oral ("acho que a Maria decidiu isso, mas saiu em março"), apontas-lhe o RFC-047. O contexto, as alternativas e o raciocínio estão todos lá. Só isto vale o custo de escrever RFCs.
A Estrutura RFC que Funciona
Já iterei em templates de RFC em múltiplas equipas e organizações. Esta é a estrutura que produz consistentemente documentos úteis sem ser onerosa:
1. Título e metadados
- Número RFC e título. A numeração sequencial (RFC-001, RFC-002) facilita as referências.
- Autor(es) e data.
- Estado. Rascunho, Em Revisão, Aceite, Rejeitado, Substituído.
- Revisores. Nomeia as pessoas de cujo contributo precisas especificamente.
2. Contexto e declaração do problema (1-2 parágrafos)
Qual é a situação? Que problema estamos a resolver? Porquê agora? Esta secção ancora o leitor. Não assumas que têm o mesmo contexto que tu. Liga a tickets, métricas ou incidentes relevantes que tornam o problema concreto.
Mau: "Precisamos de melhorar a nossa pipeline de dados." Bom: "A nossa pipeline ETL em lote atual processa 2M de registos por noite. Com a nossa trajetória de crescimento, atingiremos 10M de registos até ao T1 de 2024. A arquitetura atual demora 4 horas a processar 2M de registos e não vai escalar linearmente. No mês passado tivemos dois incidentes onde o job em lote não completou antes do horário laboral (INC-234, INC-251)."
3. Solução proposta (o núcleo do documento)
Descreve o que queres construir, como funciona e por que razão esta abordagem. Inclui:
- Arquitetura ou design do sistema. Os diagramas ajudam. Um simples diagrama de caixas e setas comunica mais do que cinco parágrafos de texto.
- Decisões técnicas chave dentro da proposta e por que as tomaste.
- Âmbito. O que está incluído e, criticamente, o que está explicitamente não incluído.
4. Alternativas consideradas (secção não negociável)
Lista pelo menos duas alternativas que avaliaste e por que as rejeitaste. Esta secção faz três coisas: mostra que fizeste o teu trabalho de casa, previne os comentários "mas por que não consideraste X?" e documenta o panorama de decisão para futuros leitores.
Se não consegues pensar em alternativas, não pensaste suficientemente sobre o problema.
5. Riscos e questões em aberto
O que podia correr mal? Sobre o que estás incerto? Que assunções estás a fazer que podem estar erradas? Esta secção é onde vive a honestidade intelectual. Uma proposta que afirma zero riscos não é confiante — é ingénua.
6. Plano de implementação
Uma cronologia aproximada e fases. Não um plano de projeto detalhado — apenas o suficiente para mostrar que é exequível e para identificar dependências. "Fase 1: migrar a camada de ingestão (2 semanas). Fase 2: migrar a camada de transformação (3 semanas). Fase 3: desativar a pipeline antiga (1 semana)."
7. Decisão e resultado (preenchido após a revisão)
O que foi decidido? Quando? Por quem? Quaisquer modificações à proposta original? Isto fecha o ciclo e transforma o RFC de proposta em registo.
Erros Comuns que Matam os RFCs
Demasiado longo. Se o teu RFC tem mais de 4 páginas, a maioria das pessoas não o vai ler com atenção. Vão percorrê-lo, perder as nuances e ou aprová-lo sem refletir ou levantar objeções que já estão abordadas no texto. Sê impiedoso a cortar. Move detalhes de implementação, esquemas de API e modelos de dados para apêndices.
Demasiado abstrato. "Devíamos adotar uma arquitetura de microserviços" sem especificar quais serviços, quais são as fronteiras ou como comunicam não é uma proposta — é um desejo. Os RFCs precisam de ser suficientemente concretos para que alguém possa discordar de um aspeto específico.
Sem ponto de decisão claro. O RFC deve declarar explicitamente: "Precisamos de uma decisão sobre isto até [data]. Se não forem levantadas objeções até lá, prosseguimos com a abordagem proposta." Sem um prazo, os RFCs tornam-se rascunhos perpétuos que nunca se convertem em ação.
Escrever RFCs para tudo. Nem toda a decisão precisa de um RFC. Escolher entre dois pacotes NPM para formatação de datas não precisa de um documento. Os RFCs são para decisões difíceis de reverter, que afetam múltiplas equipas ou que implicam um investimento significativo. Uso esta regra: se a implementação demora menos de uma semana e é facilmente reversível, faz-o simplesmente. Se demora mais de uma semana ou é difícil de reverter, escreve um RFC.
Usar RFCs como licenças de permissão. O processo RFC deve ser sobre obter contributos, não obter aprovações. Se cada RFC precisa de ser "aprovado" por um comité, construíste um change review board com passos extra. O objetivo é melhores decisões através de contributos coletivos, não burocracia de aprovação.
Construir o Hábito RFC Sem Burocracia
O maior desafio não é escrever um RFC — é torná-lo um hábito da equipa. Aqui está o que funciona:
Começa com um template leve. Não cries um template de 15 campos no primeiro dia. Começa com Problema, Proposta, Alternativas, Riscos. Quatro secções. Podes adicionar estrutura mais tarde quando a equipa vir o que é útil.
Faz com que os primeiros RFCs sejam vitórias visíveis. Escolhe uma decisão sobre a qual a equipa tem andado para um lado e para o outro. Escreve-a como um RFC. Quando leva a uma decisão clara com raciocínio documentado, a equipa vê o valor. Isso vende a prática melhor do que qualquer mandato de processo.
Armazena os RFCs onde as pessoas já trabalham. Uma pasta Google Drive partilhada que ninguém visita é onde os RFCs vão morrer. Coloca-os no teu repositório (um diretório /rfcs), no Notion se é a casa da tua equipa, ou no Confluence se estás preso a ele. Onde quer que a equipa já procure informação.
Atribui revisores explicitamente. "Por favor revê" dirigido a ninguém é dirigido a ninguém. Nomeia 2-3 revisores específicos cuja expertise é relevante. Dá-lhes um prazo. Faz acompanhamento se não responderem.
Mantém o período de revisão curto. Cinco dias úteis são suficientes para a maioria dos RFCs. Se um RFC está em revisão durante três semanas, o autor já seguiu em frente mentalmente e o documento torna-se obsoleto.
Celebra os bons RFCs. Quando alguém escreve um RFC que salva a equipa de uma má decisão ou leva a uma arquitetura notavelmente melhor, destaca-o. "O RFC do Alejandro sobre a estratégia de caching salvou-nos de um design que teria quebrado com 10x de carga" faz com que escrever RFCs pareça valioso, não trabalho de casa.
RFCs para Equipas Distribuídas
Os RFCs tornam-se ainda mais valiosos quando a tua equipa é distribuída. São o grande equalizador — o engenheiro que é mais silencioso nas reuniões tem voz igual num documento escrito. O membro da equipa num fuso horário diferente não perde a discussão porque não há nenhuma discussão a perder. Todos contribuem de forma assíncrona.
Na Conectia, já vimos a prática de RFC fazer uma diferença tangível na forma como as equipas distribuídas operam. Quando os nossos engenheiros sénior se juntam à equipa de um cliente, ter um processo RFC claro significa que podem contribuir com pensamento arquitetural desde o primeiro dia, não apenas código. Compreendem o contexto por trás das decisões existentes (porque está escrito) e podem propor melhorias através do mesmo processo estruturado. É assim que as equipas distribuídas tomam decisões tão bem — ou melhor — do que as co-localizadas.
O investimento é pequeno: um template, um local de armazenamento e um compromisso de escrever antes de construir para decisões significativas. O retorno é enorme: melhores decisões, menos conversas "porque é que fizemos isto?", e uma equipa que pensa antes de escrever código.
A construir uma equipa distribuída que toma decisões técnicas sólidas de forma assíncrona? Fala com um CTO — os nossos engenheiros sénior LATAM trazem o pensamento estruturado e as competências de comunicação de que as equipas distribuídas precisam.
