Escrever decisões técnicas formais

Nível: B2

Objetivo

Escrever decisões técnicas formais em inglês (ADRs, decision logs, RFCs) com estrutura clara: contexto, decisão, consequências, alternativas consideradas, e consequências negativas aceitas — sem virar ensaio nem sound bite.

Explicação

Uma decisão técnica formal B2 segue quatro blocos: Context (qual problema estamos resolvendo, com quais restrições), Decision (o que escolhemos, em uma frase clara), Consequences (o que fica melhor E o que fica pior, ambos honestos), e Alternatives considered (o que mais olhamos e por que descartamos). O padrão é o ADR (Architecture Decision Record), mas o princípio vale para qualquer log de decisão.

A frase-chave de abertura é *we are choosing X because of Y, and accepting Z as the cost*. Isso força honestidade: você não vende a decisão como perfeita, você documenta o trade-off. A frase de fechamento é *this decision can be revisited when ...*, o que reconhece que toda decisão tem data de validade.

Erros comuns: escrever a decisão como se fosse inevitável, esconder as alternativas (parece que nem considerou), exagerar consequências positivas, omitir as negativas, escrever em tom de venda, e não ligar a decisão ao contexto do time. O bom ADR B2 é curto o suficiente para ser lido em cinco minutos, longo o suficiente para sobreviver ao esquecimento.

Para receber crítica ao ADR: peça feedback específico no bloco *Consequences*. *'What did I miss in the trade-offs?'* Para escrever o ADR de uma decisão difícil: comece pelo Context, force a frase *we are choosing X because of Y, accepting Z as the cost*, e termine com a frase de revisão futura.

Exemplos

Erros comuns

• Escrever como se a decisão fosse inevitável: ADR deve documentar escolha, não destino.
• Esconder as alternativas: sem Alternatives, parece que a decisão não foi pensada.
• Exagerar consequências positivas: a parte de Consequences precisa incluir o que piora.
• Omitir as consequências negativas: a frase 'accepting Z as the cost' é o que blinda a decisão de ataque.
• Escrever em tom de venda: ADR não é pitch; é memória institucional.
• Não ligar ao contexto do time: o Context sem restrições é genérico, não específico.
• Tornar o ADR longo demais: se não cabe em cinco minutos, ninguém vai ler.
• Não dizer quando a decisão pode ser revisitada: sem horizonte, a decisão vira dogma.

Prática guiada

Reescreva cada bloco abaixo no padrão B2 de ADR. O objetivo é honestidade sobre trade-off e clareza sobre contexto.

• Bloco de decisão vendendo: 'Vamos adotar o novo cache porque ele é melhor.'

→ Versão B2: *Decision: we will adopt the new caching layer with a five-minute TTL. We are choosing it because it reduces p95 latency under batch load, and accepting a 20% increase in operational cost as the trade-off.* Explicação: decisão + razão + trade-off explícito.

• Consequências só positivas: 'Latência vai cair.'

→ Versão B2: *Consequences: latency will drop under batch load; operational cost will increase by approximately 20%; the on-call rotation will need a new runbook.* Explicação: prós + contras + impacto operacional.

• ADR sem data de validade: 'Essa é a decisão final.'

→ Versão B2: *This decision can be revisited when traffic grows past 10x current volume, or when the cost projection changes by more than 30%.* Explicação: horizonte explícito; a decisão tem data de validade.

Resumo

ADR B2 tem quatro blocos: Context (problema + restrições), Decision (uma frase clara), Consequences (prós E contras honestos), Alternatives considered (o que mais olhamos e por que descartamos). Frase-chave: *we are choosing X because of Y, accepting Z as the cost*. Frase de fechamento: *this decision can be revisited when ...*. Curto, honesto, datado.

História: Escrever decisões técnicas formais

Nível: B2

História em inglês

Drafting the ADR

After the design review, Marcus volunteered to write the ADR. He opened with a short context block. Context: the search index is shared with the analytics workload, causing p95 spikes during batch jobs. He listed the constraints under which the team is operating. Constraints: we have a 20% budget increase cap, and we cannot hire more SREs this quarter. He then wrote the decision in a single sentence. Decision: we will move the search index to a dedicated cluster with a five-minute TTL. He added the trade-off phrase right after the decision.

Consequences and alternatives

Marcus wrote the consequences honestly. Consequences: latency will drop under batch load; operational cost will increase by approximately 20%; the on-call rotation will need a new runbook. He added the reason that weighed most in the decision. The main reason we picked X over Y was operational simplicity, not raw performance. He then listed the alternatives the team had considered. Alternatives considered: we looked at a shared index with rate limiting, but rejected it because the cost was unpredictable. He also mentioned a second option the team had briefly discussed. We also considered moving the analytics workload instead, but rejected it because the analytics team is larger and the change would be more disruptive.

Closing with a validity horizon

Marcus closed the ADR with an explicit validity horizon. This decision can be revisited when traffic grows past 10x current volume, he wrote. He also added a second trigger for review. Or when the operational cost projection changes by more than 30%, he added. He asked Priya to review the trade-offs section specifically. What did I miss in the trade-offs? he asked. Priya answered: the on-call training is missing from the consequences. Marcus added the training as a follow-up action item, and the ADR went into the decision log.

Tradução linha por linha

Notas de vocabulário

• Context: the search index is shared with the analytics workload, causing p95 spikes during batch jobs. = Context descreve o problema e o sintoma, não a solução.
• Constraints: we have a 20% budget increase cap, and we cannot hire more SREs this quarter. = Constraints é o que limita as opções; sem elas, o ADR fica genérico.
• Decision: we will move the search index to a dedicated cluster with a five-minute TTL. = Decision em uma frase clara e acionável.
• the main reason we picked X over Y was operational simplicity, not raw performance = Razão explícita: o que pesou mais na escolha, não tudo.
• we looked at a shared index with rate limiting, but rejected it because the cost was unpredictable = Nomear alternativa + razão de descarte mostra que a decisão foi pensada.
• the on-call rotation will need a new runbook = Consequence operacional honesta: não só prós, também impacto em gente.
• this decision can be revisited when traffic grows past 10x current volume = Validity explícita: toda decisão tem horizonte; evita dogma.
• or when the operational cost projection changes by more than 30% = Segundo gatilho de revisão: o horizonte não é só crescimento, é também mudança de premissa.
• What did I miss in the trade-offs? = Pedido de crítica B2 sobre o ADR: foco no trade-off, não em grammar.
• the on-call training is missing from the consequences = Crítica construtiva em B2: aponta o que falta, não o que está errado.

Perguntas de compreensão

1. What was the context Marcus opened the ADR with?
2. What constraints did Marcus list, and why do they matter?
3. What was the decision, and what trade-off did Marcus accept in the decision line?
4. What two alternatives did the team consider and reject, and why?
5. What reason did Marcus give for picking X over Y, and what did he add to the consequences section?
6. What two triggers did Marcus add for revisiting the decision?
7. What did Priya catch in the trade-offs, and what did Marcus do?
8. Why did Marcus ask 'What did I miss in the trade-offs?' instead of 'Is this ADR good?'
9. What would have been wrong with an ADR that listed only the positive consequences?

Prática com a história

1. Reescreva: 'Vamos adotar o novo cache porque ele é melhor.' (ADR B2)
2. Reescreva: 'Latência vai cair.' (Consequences B2)
3. Reescreva: 'Olhamos outras opções.' (Alternatives B2)
4. Reescreva: 'É a decisão final.' (Validity B2)
5. Traduza: 'O que eu deixei passar nos trade-offs?'
6. Traduza: 'A principal razão de escolhermos X em vez de Y foi simplicidade operacional, não performance bruta.'