Projeto B1: conduzir uma feature end-to-end

Nível: B1

Objetivo

Conduzir uma feature de software do requisito à apresentação final em inglês, integrando vocabulário de produto, PR, code review, documentação e demo: alinhar o requisito com o PM, propor uma solução com trade-offs claros, abrir um PR bem descrito, responder comentários de review, atualizar a documentação e apresentar o resultado para o time.

Explicação

Conduzir uma feature end-to-end em inglês é juntar seis conversas diferentes em uma só semana de trabalho: alinhar o requisito, propor a solução, escrever o PR, responder o review, documentar a mudança e apresentar o resultado. Cada conversa tem um vocabulário próprio, mas todas compartilham três habilidades B1: descrever o que se fez, justificar decisões e responder a feedback sem soar defensivo.

1. Discutir o requisito com o PM (ou stakeholder)

Antes de qualquer linha de código, é preciso entender o que o usuário precisa e como vamos medir sucesso. As perguntas mais úteis no início de uma feature são:

• `What problem are we trying to solve?` — o problema por trás da feature, não a solução.
• `What does success look like?` — o critério de sucesso em termos de impacto no usuário, não de linhas de código.
• `How will we measure the impact?` — métrica de produto (conversão, latência, NPS, tickets).
• `What's in scope and what's out of scope?` — delimita a feature e evita retrabalho.
• `Are there any constraints I should know about?` — prazos, compliance, dependências externas.

`requirement` é o que o usuário precisa; `feature` é a implementação. Misturar os dois leva a features que resolvem o problema errado. Em uma kickoff, repita o requisito em voz alta: `So if I understood correctly, the requirement is X, and success means Y. Is that right?` Confirmar o entendimento protege a feature inteira.

2. Propor uma solução com trade-offs claros

Depois de alinhar o requisito, escreva um design doc curto ou um comentário longo na issue. Estruture a proposta em três blocos:

1. Approach — a ideia central em uma frase: `I'll add a background job that retries failed requests with exponential backoff.`
2. Trade-offs — o que se ganha e o que se perde: `The trade-off is that we add latency to the happy path in exchange for fewer failed requests overall.`
3. Alternatives considered — o que foi descartado e por quê: `I considered a synchronous retry, but it would block the request thread.`

Frases típicas de proposta:

• `I'd suggest we start with a small proof of concept to validate the approach.`
• `Have you considered using the existing notification service instead of a new one?`
• `The trade-off here is X, but it keeps the API backward compatible.`
• `I think the simplest approach is ... because ...`

Evite propor solução sem mostrar o trade-off. `Let's just do X.` é fraco; `I'd suggest X. The trade-off is Y, but it keeps the migration small.` é a versão B1.

3. Escrever um PR que se explica sozinho

Um PR de qualidade B1 tem três partes na descrição:

1. Context — por que esta mudança existe: `This PR adds a retry mechanism to the payment webhook, addressing the increase in failed requests we saw last month.`
2. What changed — resumo técnico em tópicos: `Adds exponential backoff, updates the retry counter, and ships a new metric.`
3. How to test — passos para o reviewer validar: `Run the integration suite, then trigger a forced failure in staging.`

Frases úteis para a descrição do PR:

• `This PR addresses #1234.`
• `The main change is ...`
• `I've added tests for the happy path and the main edge cases.`
• `I left one open question about ...; happy to follow up.`

Manter o PR pequeno e focado facilita o review e reduz o tempo até o merge. Um PR de 800 linhas em cinco áreas diferentes é, na prática, cinco PRs disfarçados.

4. Responder review sem ficar defensivo

Code review não é ataque pessoal. As respostas B1 reconhecem o ponto, justificam a decisão e, quando o reviewer tem razão, aceitam a mudança:

• `Good catch. I'll fix that.`
• `That's a fair point. I went with X because ..., but I see how Y is simpler. Let me update.`
• `I disagree, because ... Are you okay with leaving it as is?`
• `I left a longer reply on the comment; let me know what you think.`

Frases para abrir ou encerrar uma rodada de review:

• `Could you take another look when you have a minute?`
• `I've addressed all comments. Let me know if anything is still blocking.`
• `Thanks for the review! I'll merge once the tests pass.`

`requested changes` é um sinal de que o review não está pronto; `approved` é o sinal verde. Se for `approved with comments`, o merge pode acontecer e os comentários viram follow-up.

5. Documentar a mudança

Depois do merge, três peças de documentação costumam acompanhar a feature:

• Release notes — uma linha por mudança visível para o usuário: `Adds automatic retry to the payment webhook.`
• Runbook entry — o que o on-call precisa saber em incidente: `If the retry metric spikes above 5%, check the upstream service health.`
• Docs update — mudança na documentação técnica ou de produto, se a API ou a UI mudou: `The webhook now returns 200 after the first attempt and 202 on retry.`

Frase útil: `I've updated the runbook and the release notes; let me know if anything is missing.` Em time maduro, a documentação faz parte da definição de done.

6. Apresentar o resultado

A apresentação final da feature é o demo. Dura de 5 a 15 minutos e tem três partes:

1. Contexto — `Last quarter, we saw 4% of payment webhooks failing on the first attempt.`
2. O que mudou — `We shipped an automatic retry with exponential backoff, behind a feature flag.`
3. Resultado — `The failure rate dropped from 4% to 0.5% in the canary, and customer tickets about failed payments fell by 30%.`

Frases úteis para abrir e fechar o demo:

• `Let me show you what we shipped this sprint.`
• `Quick demo of the new retry flow.`
• `Here's the before-and-after in metrics.`
• `Happy to take questions, and I'll follow up with the runbook link.`

Apresentar resultado inclui números, não só telas. `It works.` é fraco; `The metric moved from 4% to 0.5% in two weeks.` é a versão B1.

Exemplos

Erros comuns

• Confundir `requirement` com `feature`: requirement é o que o usuário precisa; feature é a implementação. `The requirement is faster checkouts; the feature is a one-click button.`
• Propor solução sem mostrar o trade-off: `Let's add retries.` é fraco; `I'd suggest adding retries. The trade-off is more load on the upstream, but it cuts failed payments by half.`
• Escrever um PR só com o diff: o reviewer precisa de context e de `How to test`, não só de uma lista de arquivos modificados.
• Ficar defensivo no review: `No, that's wrong.` deve ser `I see your point. I went with X because Y, but I'm open to changing it if you think Z is simpler.`
• Tratar documentação como trabalho extra: `release notes`, `runbook` e `docs update` fazem parte da feature; sem eles, o on-call e o suporte pagam o preço depois.
• Abrir o demo sem números: `It works better now.` é vago; `The metric moved from 4% to 0.5%.` é a versão B1.

Prática guiada

Reescreva cada item fraco em uma versão B1 com a estrutura certa.

• Requisito vago: `We need a retry button.`

Alinhamento: `What problem are we trying to solve here? If the requirement is to reduce failed webhooks, success looks like a 1% drop in customer tickets. Does that match what you have in mind?`

• Solução sem trade-off: `Let's add retries.`

Proposta B1: `I'd suggest adding automatic retries with exponential backoff. The trade-off is a bit more load on the upstream, but it keeps the API contract the same. Have you considered a synchronous retry instead?`

• PR sem context: `Adds retry logic.`

PR B1: `This PR adds a retry mechanism to the payment webhook, addressing the increase in failed requests we saw last month. The main change is exponential backoff plus a new metric. I added tests for the happy path and the main edge cases. How to test: run the integration suite and force a failure in staging.`

• Resposta defensiva: `No, that's wrong.`

Resposta B1: `Good point. I went with X because Y, but I see how Z is simpler. Let me update the code and push a new commit.`

Repare como cada versão tem uma estrutura clara: a versão B1 sempre mostra o que se fez, por que se fez e o que se mediu.

Resumo

Conduzir uma feature end-to-end em inglês é juntar seis conversas: alinhar o requisito (`What does success look like?`), propor solução com trade-off (`I'd suggest ..., the trade-off is ...`), escrever um PR com context, what changed e how to test, responder review com `Good catch` ou discordar com justificativa, documentar a mudança em release notes, runbook e docs, e apresentar o resultado com números (`The metric moved from X to Y`). A thread é a mesma: descrever, justificar e responder a feedback sem soar defensivo.

História: Projeto B1: conduzir uma feature end-to-end

Nível: B1

História em inglês

The kickoff with the PM

On Monday morning, the engineering team at Northwind sat down with Priya, the product manager, to align on a new feature for the payment webhook. Priya opened the meeting with a short slide: "Last quarter, 4% of our payment webhooks failed on the first attempt, and customer tickets doubled." Daniel, the senior engineer, asked the first clarifying question: "What problem are we trying to solve here? If the requirement is to reduce failed webhooks, what does success look like?" Priya replied, "The requirement is to cut failed webhooks in half. Success means a 1% drop in customer tickets, measured weekly in the support dashboard." Maya, the engineer who would own the work, asked, "Are there any constraints I should know about? For example, can we change the API contract, or does it have to stay backward compatible?" Priya said, "The API must stay backward compatible, and we cannot touch the merchant clients. Out of scope for this PR is the new UI; the scope is the webhook only."

The proposal and the PR

On Tuesday, Maya shared a short design doc in the team channel. She wrote, "I'd suggest we add automatic retries with exponential backoff behind a feature flag. The trade-off is a bit of added latency, but it cuts failed webhooks in half while keeping the API backward compatible." Maya added, "Have you considered doing a synchronous retry instead? I think the trade-off is worse for the happy path, but I'd like to hear your take before committing." Daniel replied on the same doc, "I agree with the background retry. A small proof of concept first, with a clear rollback plan, would lower the risk." On Thursday morning, Maya opened a pull request titled 'Add automatic retry to the payment webhook.' The PR description covered the context, the main changes, and how to test: "This PR adds an automatic retry with exponential backoff. The main change is a new retry counter and a metric. How to test: run the integration suite, then force a 500 in staging and confirm the job retries three times before giving up."

The code review

By Thursday afternoon, Daniel had left a long review on the PR. He wrote, "Have you considered a token bucket here? It might be a better fit for our traffic pattern, and it would also smooth out the retry bursts." Maya replied on the same comment, "Good catch. I went with a fixed backoff because it was simpler to roll out, but I see how a token bucket is more flexible. I disagree on changing it in this PR, because the scope would grow. Let me open a follow-up issue and we can iterate." Daniel approved the PR, but he left requested changes on the test coverage for the edge case of a flaky upstream service. Maya added a new test, pushed a follow-up commit, and asked Daniel to take another look. On Friday morning, Daniel re-reviewed and approved the PR with a small comment about the runbook.

Documentation and the demo

After the merge, Maya updated three pieces of documentation. She added a line to the release notes: 'Adds automatic retry with exponential backoff to the payment webhook.' She also updated the runbook: 'If the new retry metric spikes above 5%, check the upstream service health and consider pausing the rollout.' Finally, she updated the API docs to mention that the webhook may return 202 on retry. On the following demo day, Maya opened her five-minute slot with a clear context: 'Last quarter, 4% of our payment webhooks failed on the first attempt, and customer tickets doubled.' She added, 'We shipped an automatic retry with exponential backoff behind a feature flag. The failure rate in the canary moved from 4% to 0.5% in two weeks, and customer tickets about failed payments fell by 30%.' At the end of the demo, she said, 'Happy to take questions, and I'll follow up with the runbook link in the team channel.' In the retrospective that same afternoon, the team agreed to use the same proposal-to-demo structure for the next feature on the roadmap.

Tradução linha por linha

Notas de vocabulário

• What problem are we trying to solve with this feature? = abertura típica de kickoff; foca no problema do usuário, não na solução técnica
• What does success look like? = pergunta que define o critério de sucesso em impacto, não em linhas de código
• backward compatible = retrocompatível; mudança que não quebra clientes existentes
• out of scope = fora do escopo da feature; usado para delimitar o PR
• design doc = documento curto com a proposta, o trade-off e as alternativas consideradas
• The trade-off is a bit of added latency, but it cuts failed webhooks in half. = estrutura padrão de uma proposta B1: o que se perde em troca do que se ganha
• Have you considered a token bucket here? = abertura educada de code review para sugerir uma alternativa técnica
• Good catch. = resposta padrão a um comentário justo; reconhece o ponto sem defensividade
• I disagree, because ...; let me open a follow-up issue. = discordar com justificativa + agendar o assunto em uma issue separada
• requested changes = comentário de review que bloqueia o merge até ser resolvido
• How to test: run the integration suite, then force a 500 in staging. = fechamento padrão da seção de teste em uma descrição de PR B1
• release notes = resumo curto das mudanças visíveis para usuários e suporte
• runbook = guia de operação para o on-call; atualizado junto com a feature
• feature flag = interruptor de configuração; permite rollout gradual e rollback rápido
• canary = liberação pequena para um subconjunto de tráfego, usada para validar antes do rollout completo
• The failure rate moved from 4% to 0.5%. = fechamento de demo com número concreto em formato antes-e-depois

Perguntas de compreensão

1. What problem was the team trying to solve with the new feature?
2. What was the success criteria for the feature?
3. What constraint did Priya set for the API?
4. What solution did Maya propose in the design doc?
5. Why did Maya disagree with changing the retry to a token bucket inside the same PR?
6. What did Daniel leave as requested changes on the PR?
7. What three pieces of documentation did Maya update after the merge?
8. What new behavior did Maya mention in the API docs update?
9. How did Maya open her demo slot?
10. What was the result of the canary?
11. What did the team agree to do in the retrospective?

Prática com a história

1. Reescreva como proposta B1: 'Let's add retries to the webhook.'
2. Reescreva como resposta B1: 'No, the code is fine. Read it again.'
3. Reescreva como fechamento de demo B1: 'It works better now.'
4. Traduza: 'Eu abriria uma issue de follow-up para discutir a alternativa em vez de mudar este PR.'
5. Produção: você vai abrir um PR que adiciona um timeout configurável a um job em background. Escreva a primeira frase da descrição do PR (context) em inglês.