Como escrever um RFC técnico que as pessoas realmente leem

1. Por que a maioria dos RFCs falha em ser lida

O Request for Comments (RFC) é uma ferramenta clássica de engenharia de software, mas na prática muitos se tornam armadilhas de produtividade. O problema não é o formato — é como eles são escritos. Documentos de 30 páginas com diagramas complexos, jargão excessivo e falta de contexto claro fazem com que revisores pulem parágrafos ou, pior, ignorem o documento por completo.

A diferença fundamental está entre tratar o RFC como burocracia (preciso escrever porque o processo exige) versus tratá-lo como ferramenta de alinhamento (preciso escrever para que todos entendam a mesma coisa e tomem decisões informadas). O custo de ignorar o leitor é alto: decisões mal compreendidas geram retrabalho, retornos infinitos e conflitos de equipe.

2. Estrutura enxuta que prende a atenção desde o início

Um RFC que as pessoas leem começa pelo "porquê". Antes de qualquer detalhe técnico, responda: qual problema concreto estamos resolvendo e qual é o impacto mensurável? Se o leitor não entender o problema nos primeiros 30 segundos, o documento está perdido.

Resumo executivo de 3 parágrafos

Parágrafo 1 — Contexto: "Atualmente, o sistema de filas processa 500 requisições/minuto com latência média de 2.3s. 
Com o crescimento de 30% ao mês, estimamos que em 3 meses a latência ultrapassará 10s, afetando o SLA do cliente X."

Parágrafo 2 — Proposta: "Propomos migrar para uma arquitetura baseada em Kafka com 3 partições, 
substituindo o RabbitMQ atual. Isso reduzirá a latência para <500ms e permitirá escalabilidade horizontal."

Parágrafo 3 — Trade-offs: "O custo de infraestrutura aumenta 40%, mas elimina a necessidade de 
reescrever o consumidor atual. O risco principal é a complexidade operacional inicial durante a migração."

Use títulos descritivos que contem uma história. Em vez de "Arquitetura", use "Arquitetura proposta: Kafka com 3 partições e consumidor assíncrono". Cada seção deve ter no máximo 5-7 parágrafos — se passar disso, divida em subseções.

3. Linguagem e tom: como evitar jargão e manter clareza

A voz ativa é sua aliada. Em vez de "A migração será realizada pela equipe de infraestrutura", escreva "A equipe de infraestrutura realizará a migração". Frases curtas, com no máximo 25 palavras, mantêm o leitor engajado.

Defina siglas e termos técnicos na primeira menção:

O API Gateway (sistema de entrada de requisições) fará o roteamento para o Message Queue (MQ, fila de mensagens). 
O MQ atualmente utiliza RabbitMQ (RMQ), um sistema de mensageria baseado em AMQP (Advanced Message Queuing Protocol).

Nunca assuma que o leitor conhece o contexto. Um desenvolvedor backend pode não saber detalhes de infraestrutura, e vice-versa. Seja explícito sobre o que cada termo significa.

4. Elementos visuais que aceleram a compreensão

Diagramas de arquitetura simples em texto (ASCII art) funcionam surpreendentemente bem em RFCs:

[Cliente] --> [API Gateway] --> [Load Balancer] 
                                   |
                                   v
                            [Auth Service] --> [Database]
                                   |
                                   v
                            [Queue Service] --> [Worker Pool]

Tabelas comparativas de alternativas são essenciais para decisões técnicas:

Alternativa Prós Contras Custo estimado
RabbitMQ Já usado na empresa, equipe conhece Escalabilidade limitada a 5k msg/s $200/mês
Kafka Alta escalabilidade (50k+ msg/s) Curva de aprendizado, novo operador $800/mês
SQS Gerenciado, sem manutenção Vendor lock-in, latência variável $600/mês

Use checklists para sequências de decisão:

- [ ] 1. Testar Kafka com 1 partição em staging (3 dias)
- [ ] 2. Validar latência < 500ms com 10k mensagens
- [ ] 3. Migrar 10% do tráfego para Kafka (1 semana)
- [ ] 4. Monitorar erros e latência por 48h
- [ ] 5. Se estável, migrar 100% do tráfego

5. Como apresentar decisões técnicas sem parecer autoritário

Ninguém gosta de ler "A solução correta é X". Em vez disso, apresente trade-offs de cada alternativa e explique por que a escolhida é a melhor no contexto atual. Inclua "não decisões" — opções que foram consideradas e descartadas, com a justificativa:

Opção descartada: Usar gRPC em vez de REST.
Motivo: A equipe de frontend não tem experiência com gRPC, e o custo de treinamento 
(2 semanas) não justifica o ganho de performance (10% em requisições internas).

Use linguagem de recomendação, não de imposição:

  • "Recomendamos a migração para Kafka porque..."
  • "A alternativa B foi descartada devido a..."
  • "Sugerimos que a decisão final seja tomada após o teste de carga em staging"

6. O ciclo de feedback: antes, durante e depois do RFC

Um RFC não é um documento estático. Compartilhe um rascunho cedo com 2-3 revisores-chave — pessoas que entendem do assunto e vão dar feedback sincero. Isso evita surpresas na revisão final.

Defina um prazo claro para comentários:

Período de comentários: 10 a 17 de outubro (5 dias úteis)
Após essa data, as decisões serão consolidadas e o RFC será finalizado.

Documente as decisões pós-revisão em uma seção de "Decisões finais":

Decisão 1: Adotar Kafka com 3 partições (aceito)
- Comentário de Maria (DevOps): "Precisamos de 3 partições mínimas para garantir alta disponibilidade"
- Ação: Alterado de 1 partição para 3

Decisão 2: Manter RabbitMQ para filas de baixa prioridade (aceito)
- Comentário de João (Backend): "Podemos usar RMQ para jobs noturnos que não precisam de baixa latência"
- Ação: Adicionado à seção de arquitetura híbrida

7. Exemplo prático: antes e depois de um RFC

Versão "ruim" (longa, sem foco, cheia de jargão)

Título: Proposta de Migração de Sistema de Mensageria

O sistema atual utiliza RabbitMQ com configuração de exchanges e bindings complexos. 
Devido a limitações de throughput, propõe-se a adoção de Apache Kafka, que é um 
sistema de streaming distribuído com alta capacidade de processamento. 
A implementação seguirá o padrão de event sourcing com CQRS, utilizando 
Kafka Streams para processamento de eventos em tempo real. 
O consumidor atual será reescrito em Go para aproveitar goroutines...

Problemas: Título genérico, começa com implementação, jargão técnico (CQRS, event sourcing, Kafka Streams) sem contexto, não explica o problema.

Versão "boa" (enxuta, visual, com contexto claro)

Título: Migração para Kafka: resolvendo o gargalo de 2.3s de latência no serviço de filas

Problema: O sistema de filas atual (RabbitMQ) processa 500 requisições/minuto 
com latência média de 2.3s. Com crescimento de 30% ao mês, em 3 meses 
a latência ultrapassará 10s, quebrando o SLA do cliente X (máximo 5s).

Proposta: Migrar para Apache Kafka com 3 partições, mantendo o consumidor 
atual em Python (reescrita em Go será avaliada em fase 2).

Trade-offs:
- Custo: +$600/mês em infraestrutura
- Complexidade: nova ferramenta para a equipe de DevOps
- Ganho: latência reduzida para <500ms

Diagrama da arquitetura proposta:
[Cliente] --> [API Gateway] --> [Kafka (3 partições)] --> [Worker Python]
                                    |
                                    v
                              [Consumer Go] (fase 2)

Melhorias: Título descritivo, problema claro e mensurável, proposta direta, trade-offs honestos, diagrama visual simples.

Métricas de sucesso

Um RFC bem-sucedido gera:

  • Número de comentários relevantes: 5-15 comentários substanciais (não apenas "👍")
  • Decisões tomadas: pelo menos 3-5 decisões documentadas
  • Tempo de revisão: 2-5 dias úteis (não semanas)
  • Implementação: a solução proposta é implementada sem grandes alterações

Se você está recebendo 0 comentários ou comentários genéricos como "parece bom", seu RFC não está sendo lido de verdade. Volte à estaca zero e reescreva com foco no leitor.

Referências