We wrote a design doc before touching the database schema.
Escrevemos um documento de design antes de mexer no schema do banco.Aula
Design documents e RFCs
Nível: B2
Objetivo
Escrever e revisar design documents e RFCs técnicos em inglês, usando a estrutura canônica de sete seções (problem statement, goals, non-goals, proposed solution, alternatives, risks, rollout plan) e a linguagem precisa de B2 para motivar decisões, discutir trade-offs, apresentar mitigations e descrever um phased rollout.
Explicação
Em engenharia, mudanças grandes quase nunca são implementadas depois de uma conversa de corredor. Elas passam por um design document (ou design doc): um texto escrito que propõe a mudança antes de qualquer linha de código ser mergeada. Quando esse texto é compartilhado para revisão assíncrona, ele costuma ser chamado de RFC — Request for Comments. O autor publica o doc, colegas leem, deixam comentários, e só depois a proposta é aceita, rejeitada ou marcada como superseded.
A distinção importante é entre RFC e ADR (Architecture Decision Record). O RFC propõe uma mudança e pede feedback; o ADR registra uma decisão que já foi tomada. Em times maduros, o RFC vem primeiro; quando o status passa para Accepted, o time escreve um ADR curto que resume a decisão final e o porquê.
Um design doc bem escrito segue uma estrutura reconhecível. As seções abaixo aparecem, em alguma ordem, em quase toda empresa:
- Context / Background — qual é o estado atual e por que a discussão está acontecendo agora.
- Problem statement — qual é o problema visível ao usuário ou ao sistema que a proposta tenta resolver.
- Goals — o que a mudança deve alcançar, idealmente com métricas.
- Non-goals — o que está explicitamente fora do escopo.
- Proposed solution — o que vamos construir, em alto nível.
- Alternatives considered — o que mais foi avaliado e por que foi rejeitado.
- Risks and mitigations — o que pode dar errado e como reduzir a probabilidade ou o impacto.
- Rollout plan — como a mudança será implantada (fases, métricas, rollback).
A ordem importa. O leitor espera o problema antes da solução e os goals antes dos non-goals. Colocar a solução antes do problema é uma das razões mais comuns para um RFC ser rejeitado: revisores não conseguem julgar um design sem saber o que ele se propõe a corrigir.
Frases úteis em B2 para abrir cada seção:
- Motivação / background: *The motivation for this RFC is…*, *This proposal addresses…*, *The current state of the system is…*
- Problem statement: *Today, X happens*, *The user-visible impact is…*, *We measured Y in production and it is above the SLO.*
- Goal: *Our goal is to reduce p99 latency below 200ms.*, *This RFC aims to eliminate the on-call pain caused by…*
- Non-goal: *Out of scope for this RFC…*, *We explicitly do not intend to…*, *This proposal does not cover…*
- Proposed solution: *We propose to migrate the read path to a new service.*, *The proposed solution introduces a queue between…*
- Alternative: *We considered X, but rejected it because…*, *Option B was discarded due to cost.*
- Risk: *The main risk is…*, *One concern is…*, *If the migration fails mid-way, …*
- Mitigation: *To mitigate this risk, we will…*, *As a safeguard, we will…*
- Rollout: *The rollout will be phased, starting with…*, *If the error rate exceeds 0.5%, we will roll back automatically.*
Estilo: prefira frases curtas, voz ativa, trade-offs explícitos e números. Evite linguagem de marketing, suposições escondidas ou generalidades. Toda afirmação na solução deve ser rastreável a um goal ou a uma mitigation.
Exemplos
| Inglês | Tradução | Observação |
|---|---|---|
| The motivation for this RFC is that unplanned database downtime has tripled in the last two quarters. | A motivação deste RFC é que o tempo de inatividade não planejado do banco triplicou nos últimos dois trimestres. | Problem statement em uma frase, com métrica concreta. |
| Our goal is to reduce p99 read latency below 200ms without changing the public API. | Nosso objetivo é reduzir a latência de leitura p99 para abaixo de 200ms sem alterar a API pública. | Goal com métrica e restrição explícita. |
| Out of scope for this RFC: analytics workloads and the offline data warehouse. | Fora do escopo deste RFC: workloads de analytics e o data warehouse offline. | Non-goal escrito em uma frase separada para deixar o limite óbvio. |
| We propose to introduce a queue between the API tier and the worker pool. | Propomos introduzir uma fila entre a camada de API e o pool de workers. | Proposed solution em alto nível; o detalhe fica em seções seguintes. |
| We considered increasing the worker pool size, but rejected it because the cost scales linearly with traffic and the SLA would still be at risk during spikes. | Consideramos aumentar o tamanho do pool de workers, mas rejeitamos porque o custo escala linearmente com o tráfego e o SLA continuaria em risco durante picos. | Alternative com motivo da rejeição. |
| The main risk is data loss if the migration fails mid-way. | O principal risco é perda de dados se a migração falhar no meio. | Risk nomeia a falha concreta, não um vago 'pode dar errado'. |
| To mitigate this risk, we will keep the old cluster in read-only mode for 24 hours after the cutover. | Para mitigar esse risco, manteremos o cluster antigo em modo somente leitura por 24 horas após o cutover. | Mitigation ligada ao risco nomeado antes. |
| The rollout will be phased: 1% of traffic for one week, then 10%, 50%, and 100%. | O rollout será em fases: 1% do tráfego por uma semana, depois 10%, 50% e 100%. | Rollout plan com percentuais explícitos, sem ambiguidade. |
Erros comuns
- Colocar a solução antes do problema: revisores precisam entender o que está sendo resolvido antes de avaliar o design.
- Misturar goals e non-goals: 'reduce latency' é um goal; 'support Windows' é um non-goal; listar os dois na mesma seção confunde o leitor.
- Esconder alternativas: um RFC sem alternatives considered parece superficial; mostrar o que foi rejeitado e por que constrói confiança.
- Listar risks sem mitigation: cada risk importante deve vir acompanhado de uma ação concreta de mitigação.
- Tratar o rollout plan como uma nota de rodapé: a fase e o critério de rollback são tão importantes quanto a arquitetura proposta.
- Confundir RFC com ADR: o RFC pede feedback antes da decisão; o ADR registra a decisão que já foi tomada. Misturar os dois papéis leva a documentos que ninguém sabe como responder.
- Usar linguagem de marketing ('this will dramatically improve…') em vez de métricas concretas e trade-offs explícitos.
Prática guiada
Pegue o texto informal abaixo e reescreva-o em três seções curtas de RFC.
Texto informal: `Nosso banco está caindo muito. Vamos migrar pro Aurora. Custou caro, mas vai ficar mais estável. A migração vai ser feita de uma vez num fim de semana. Se der ruim, a gente volta atrás. Não vamos mexer no data warehouse.`
Reescrita em tom de RFC:
- Problem statement: *Unplanned downtime of the primary database has averaged 45 minutes per month over the last quarter, exceeding our internal SLO of 15 minutes.*
- Goal: *This RFC aims to reduce unplanned database downtime to under 15 minutes per month.*
- Non-goal: *Out of scope for this RFC: the analytics data warehouse and any change to the reporting layer.*
Repare: o problema tem métrica (45 minutos vs. SLO de 15), o goal é mensurável e o non-goal marca um limite que o leitor não precisa adivinhar. As outras seções (proposed solution, alternatives, risks, rollout) viriam em seguida no doc real.
Resumo
Design docs e RFCs são o mecanismo padrão para propor mudanças grandes de forma assíncrona: o autor publica o doc, colegas revisam, e a proposta vira um ADR quando é aceita. A estrutura canônica tem sete seções — context, problem statement, goals, non-goals, proposed solution, alternatives, risks and mitigations, rollout plan — e a ordem existe para guiar o leitor do problema até a entrega. Linguagem de B2 para esse contexto é direta e mensurável: goals com números, risks nomeando a falha concreta, mitigations ligadas ao risco e rollouts com critério de rollback explícito. Misturar as seções, esconder alternativas ou tratar o rollout como detalhe é o que separa um RFC aprovado de um RFC que volta para a gaveta.
Vocabulário
Palavras principais
Please review the RFC and leave your comments by Friday.
Por favor, reveja o RFC e deixe seus comentários até sexta.After the RFC is accepted, we will write an ADR summarizing the decision.
Depois que o RFC for aceito, escreveremos um ADR resumindo a decisão.The problem statement should describe the user-visible impact, not the implementation detail.
A descrição do problema deve descrever o impacto visível ao usuário, não o detalhe de implementação.Our goal is to reduce p99 latency below 200ms.
Nosso objetivo é reduzir a latência p99 para abaixo de 200ms.Supporting Windows is a non-goal for this RFC.
Suportar Windows é um non-goal para este RFC.The proposed solution introduces a queue between the API and the workers.
A solução proposta introduz uma fila entre a API e os workers.We evaluated an alternative using shared memory, but it was too complex.
Avaliamos uma alternativa usando memória compartilhada, mas era complexa demais.There is a clear trade-off between cost and latency in this design.
Há um trade-off claro entre custo e latência neste design.Data loss is the main risk of this approach.
Perda de dados é o principal risco desta abordagem.As a mitigation, we will keep daily backups for the first month.
Como mitigação, manteremos backups diários durante o primeiro mês.The rollout will start with internal traffic only.
O rollout começará apenas com tráfego interno.If error rate exceeds 1%, we trigger an automatic rollback.
Se a taxa de erro passar de 1%, disparamos rollback automático.The scope of this RFC is limited to the EU region.
O escopo deste RFC é limitado à região EU.We need sign-off from the security and platform stakeholders.
Precisamos da aprovação dos stakeholders de segurança e plataforma.The platform team must sign off before we merge.
O time de plataforma precisa aprovar antes de fazermos o merge.Please add two reviewers from the storage group.
Por favor, adicione dois revisores do grupo de storage.We collected feedback from five engineers across three teams.
Coletamos feedback de cinco engenheiros de três times.História
História: Design documents e RFCs
Nível: B2
História em inglês
Drafting the RFC
Priya is a senior engineer at a payments company, and she is drafting an RFC to migrate the team's primary database. The motivation is simple: on-call engineers have spent more than thirty percent of the last quarter handling database incidents. She opens the doc with a one-paragraph problem statement: unplanned downtime has averaged forty-five minutes per month, which is three times the internal SLO. The proposed solution is to move to a fully managed PostgreSQL service, with a phased rollout starting with the read replicas. She is careful to list what is out of scope: the analytics warehouse and the offline reporting jobs.
The review
Priya shares the RFC in the engineering channel and asks for two reviewers from the platform team. Daniel, one of the reviewers, comments that the proposal is too narrow and that the team should also revisit the sharding strategy. Priya thanks him and points out that sharding is a non-goal for this RFC; it will be addressed in a separate proposal next quarter. Aisha, the second reviewer, pushes back on the risk section, arguing that it does not cover what happens to in-flight transactions if the migration fails mid-way. Priya updates the doc and adds a mitigation: in-flight transactions will be drained from the old cluster for at least fifteen minutes before the cutover.
The rollout
After two weeks of comments and one revision, the RFC is marked as Accepted. The rollout plan is phased: one percent of traffic for one week, then ten percent, fifty percent, and finally one hundred percent. Each phase has a clear rollback criterion: if the error rate exceeds zero point five percent or p99 latency rises above four hundred milliseconds, the team rolls back automatically. After the first week, the team reviews the metrics and decides to move to the next phase. The migration finishes on schedule, and the on-call rotation reports far fewer database incidents in the following month.
Tradução linha por linha
| Inglês | Tradução |
|---|---|
| Priya is a senior engineer at a payments company, and she is drafting an RFC to migrate the team's primary database. | Priya é engenheira sênior em uma empresa de pagamentos e está escrevendo um RFC para migrar o banco principal do time. |
| The motivation is simple: on-call engineers have spent more than thirty percent of the last quarter handling database incidents. | A motivação é simples: os engenheiros de plantão gastaram mais de trinta por cento do último trimestre lidando com incidentes de banco. |
| She opens the doc with a one-paragraph problem statement: unplanned downtime has averaged forty-five minutes per month, which is three times the internal SLO. | Ela abre o documento com um parágrafo de problem statement: o tempo de inatividade não planejado tem média de quarenta e cinco minutos por mês, três vezes o SLO interno. |
| The proposed solution is to move to a fully managed PostgreSQL service, with a phased rollout starting with the read replicas. | A solução proposta é migrar para um serviço PostgreSQL totalmente gerenciado, com rollout em fases começando pelas réplicas de leitura. |
| She is careful to list what is out of scope: the analytics warehouse and the offline reporting jobs. | Ela tem o cuidado de listar o que está fora do escopo: o warehouse de analytics e os jobs de relatórios offline. |
| Priya shares the RFC in the engineering channel and asks for two reviewers from the platform team. | Priya compartilha o RFC no canal de engenharia e pede dois revisores do time de plataforma. |
| Daniel, one of the reviewers, comments that the proposal is too narrow and that the team should also revisit the sharding strategy. | Daniel, um dos revisores, comenta que a proposta é estreita demais e que o time também deveria revisar a estratégia de sharding. |
| Priya thanks him and points out that sharding is a non-goal for this RFC; it will be addressed in a separate proposal next quarter. | Priya agradece e aponta que sharding é um non-goal deste RFC; será tratado em uma proposta separada no próximo trimestre. |
| Aisha, the second reviewer, pushes back on the risk section, arguing that it does not cover what happens to in-flight transactions if the migration fails mid-way. | Aisha, a segunda revisora, contesta a seção de riscos, argumentando que ela não cobre o que acontece com transações em andamento se a migração falhar no meio. |
| Priya updates the doc and adds a mitigation: in-flight transactions will be drained from the old cluster for at least fifteen minutes before the cutover. | Priya atualiza o documento e adiciona uma mitigação: as transações em andamento serão drenadas do cluster antigo por pelo menos quinze minutos antes do cutover. |
| After two weeks of comments and one revision, the RFC is marked as Accepted. | Depois de duas semanas de comentários e uma revisão, o RFC é marcado como Accepted. |
| The rollout plan is phased: one percent of traffic for one week, then ten percent, fifty percent, and finally one hundred percent. | O plano de rollout é em fases: um por cento do tráfego por uma semana, depois dez por cento, cinquenta por cento e, por fim, cem por cento. |
| Each phase has a clear rollback criterion: if the error rate exceeds zero point five percent or p99 latency rises above four hundred milliseconds, the team rolls back automatically. | Cada fase tem um critério de rollback claro: se a taxa de erro passar de zero vírgula cinco por cento ou a latência p99 subir acima de quatrocentos milissegundos, o time reverte automaticamente. |
| After the first week, the team reviews the metrics and decides to move to the next phase. | Depois da primeira semana, o time revisa as métricas e decide avançar para a próxima fase. |
| The migration finishes on schedule, and the on-call rotation reports far fewer database incidents in the following month. | A migração termina no prazo e a escala de plantão relata muito menos incidentes de banco no mês seguinte. |
Notas de vocabulário
- The motivation is simple: = abre a seção de background/problem statement do RFC em tom direto.
- out of scope = marca um non-goal; equivalente formal de 'isso não será coberto'.
- non-goal for this RFC = frase padrão para recusar ampliação de escopo em revisão.
- in-flight transactions = transações iniciadas mas ainda não concluídas; risco típico em cutover de banco.
- drained from the old cluster = drenadas: terminadas ou movidas antes do cutover; mitigation comum.
- rollout plan is phased = rollout em fases = implantação gradual com percentuais crescentes de tráfego.
- rollback criterion = métrica de saúde que, se violada, dispara reversão automática.
- marked as Accepted = status final positivo do RFC; em seguida costuma-se escrever um ADR.
Perguntas de compreensão
- What is Priya proposing to migrate?
- Why is the migration needed? (problem statement)
- Is sharding in scope for this RFC? Why?
- What mitigation did Priya add after Aisha's review?
- What is the rollback criterion for the rollout?
- What is the status of the RFC at the end of the story?
Prática com a história
- Reescreva em tom de RFC: The team is using a database that crashes a lot, so we want a new one.
- Classifique a frase: We will keep the old cluster in read-only mode for 24 hours after the cutover.
- Escreva um non-goal de uma frase para o RFC do story, deixando claro que o analytics warehouse está fora.
- Faça uma pergunta de review pedindo sign-off do time de plataforma.
Prática
Exercícios e teste
A próxima melhoria é transformar esses arquivos em perguntas com resposta no navegador. Por enquanto, esta página já organiza o estudo e permite seguir a aula inteira sem abrir os arquivos manualmente.