Portfólio técnico: provar impacto com ADRs, benchmarks e changelogs

Quando e por que usar

Contexto: o que o entrevistador ou gestor quer ver

Recrutadores e líderes não pedem portfólios para ver design bonito: pedem evidência de decisões e impacto. Um repositório com código exemplar é útil, mas sem contexto e métricas vira showcase estético. O que diferencia um desenvolvedor que entrega valor de um que apenas entrega código é a capacidade de documentar decisões (ADRs), medir mudança (benchmarks) e narrar evolução (changelogs).

No nível intermediário (1-3 anos) você deve sair do "isso funciona" para "isso resolveu X, melhorou Y% e exigiu trade-offs A/B". ADRs explicam o porquê; benchmarks comprovam o quanto; changelogs demonstram o que entrou em produção e quando. Juntos, viram prova tangível de impacto.

Quando priorizar cada artefato

Não é necessário usar todos sempre. Use ADRs quando a decisão tiver impacto arquitetural, quando o trade-off for não-trivial, ou quando a decisão precisará ser revisitada depois de meses. Use benchmarks quando performance ou custo operacional forem argumentos centrais. Use changelogs para comunicar releases e ligar commits a resultados de negócio.

Exemplo prático: você reescreveu um endpoint de agregação para reduzir latência. Um ADR registra por que reescreveu, o benchmark mostra a redução de latência média e o changelog comunica a equipe e os stakeholders sobre o rollout.

Comparação com alternativas

O jeito errado: notas soltas e commits genéricos

Erro comum: empilhar commits com mensagens como "ajustei isso" e esperar que o leitor entenda o contexto. Outro erro é ter um README com screenshots sem métricas. Isso cria ruído — os avaliadores perdem tempo tentando reconstruir a história. Em entrevistas, você será questionado por lacunas: por que escolheu aquela abordagem? quais foram os riscos?

Esse jeito errado raramente permite extrair impacto. Não há conexão clara entre decisão, implementação e resultado, o que fragiliza sua narrativa em entrevistas técnicas ou reviews de PR.

O jeito certo: ADRs, benchmarks e changelogs conectados

O padrão correto é simples: decisão (ADR) → implementação (PR/commit) → medição (benchmarks) → comunicação (changelog/release notes). Essa cadeia transforma atividade técnica em evidência de impacto.

Em um portfólio, você pode linkar o ADR para o PR e o benchmark que mostra antes/depois, e colocar o trecho do changelog que explica como foi entregue. Em code review, é exatamente isso que avaliadores vão procurar: rastreabilidade e dados.

Implementação progressiva

Passo 0: comece simples com um ADR

Comece pelo mínimo: um ADR curto contendo problema, decisão, opções consideradas, e consequências. Não precisa ser um tratado, mas deve permitir que alguém que chegou no seu repositório entenda o porquê da mudança sem ler todo o PR.

Exemplo de fluxo incorreto: abrir PR sem ADR e depois responder por e-mail. Fluxo correto: criar ADR antes do PR e referenciá-lo no corpo do PR. Isso reduz retrabalho e facilita revisão.

ADRs: template prático

Contexto antes do código: este bloco mostra um ADR minimalista. Coloque no diretório docs/adr ou adr/. No corpo do PR, coloque um link para ele. Abaixo um exemplo real e funcional de ADR em Markdown.

# ADR 001 - Trocar agregação por streaming parcial

Status: accepted

Contexto:
- Endpoint /reports agregava todos os registros na memória.
- Picos de tráfego causavam OOM e latência>2s.

Decisão:
- Implementar processamento por streaming usando cursors do banco e paginar internamente.

Alternativas consideradas:
- Aumentar memória do pod (rejeitado: custo e não resolve raiz).
- Usar cache completo em Redis (rejeitado: complexidade de invalidação).

Consequências:
- Latência média reduzida, menor uso de memória, incremento de complexidade no rollback.

Plano de rollout:
- Deploy em canary por 24h com feature flag, monitorar percentil 95 e OOM.

Referências: PR #123, benchmark/benchmark_reports.js

O que acontece: esse arquivo explica a motivação e direciona para métricas e PRs.

Passo 1: benchmark mínimo e comparativo

Antes de declarar "melhorou", meça. Benchmarks simples com Node.js podem comprovar redução de latência e CPU. Evite microbenchmarks irrelevantes; foque em cargas que se aproximem do padrão de uso real.

O erro comum aqui é medir apenas o happy path em ambientes diferentes do real. Execute benchmarks no mesmo build/artefato que irá para produção sempre que possível.

Benchmark prático: comparar duas implementações

O código a seguir simula duas versões de um processamento de relatório: a antiga (buffer completo) e a nova (streaming). Execute com Node.js para obter tempos médios e variações.

// benchmark/benchmark_reports.js
// O que faz: simula geração de relatório com 10000 itens. Compara duas funções.
const { performance } = require('perf_hooks');

function oldGenerate(items) {
  // monta tudo na memória
  const out = [];
  for (let i = 0; i < items; i++) {
    out.push('item:' + i);
  }
  return out.join('\n');
}

function newGenerate(items) {
  // simula streaming: processa em blocos sem acumular tudo
  const buffer = [];
  const chunk = 1000;
  for (let offset = 0; offset < items; offset += chunk) {
    for (let i = offset; i < Math.min(offset + chunk, items); i++) {
      buffer.push('item:' + i);
    }
    // simula envio parcial
    buffer.length = 0;
  }
  return true; // já enviado
}

function run(name, fn, items, reps = 20) {
  const times = [];
  for (let r = 0; r < reps; r++) {
    const t0 = performance.now();
    fn(items);
    const t1 = performance.now();
    times.push(t1 - t0);
  }
  const avg = times.reduce((a, b) => a + b, 0) / times.length;
  console.log(`${name} avg=${avg.toFixed(3)}ms reps=${reps}`);
}

const ITEMS = 10000;
run('old', oldGenerate, ITEMS);
run('new', newGenerate, ITEMS);

O que acontece: execute 'node benchmark/benchmark_reports.js' e compare as médias. No caso real, a versão streaming normalmente mostra menor uso de memória e tempos comparáveis ou melhores sob carga, dependendo do GC.

Passo 2: traduzir números em impacto

Depois de obter resultados, converta-os para impacto de negócio: redução de latência em percentil 95, redução de erros OOM, custo menor em autoscaling. Esses números são o que você deve exibir no seu portfólio.

Exemplo: "Reduziu p95 de 1.8s para 0.6s e eliminou OOMs em 3 deploys canary" — isso tem força em entrevistas.

Erros comuns e armadilhas

Medir em devbox ou com dados mockados geralmente leva a resultados inúteis. Outro erro é comparar builds diferentes ou ambientes onde otimizações do compilador/JIT variam. Sempre documente ambiente, seed, versões de dependências e flags de compilação.

Armadilha de interpretação: uma melhoria em média pode esconder regressões em p99. Sempre verifique percentis altos e uso de recursos.

Integracao com ecossistema real

Como ligar ADR, PR, benchmark e changelog

Rastreabilidade é chave. No seu PR, inclua: link para ADR, link para benchmark/resultado (artefato ou gráfico), e a linha do changelog que será criada no release. Isso reduz fricção e mostra maturidade profissional.

Faça isso automaticamente quando possível: scripts que rodem benchmarks no pipeline e anexem resultados ao PR tornan-se provas sólidas e reproduzíveis.

Automatizando benchmarks no CI

Adicionar um job de benchmark no CI permite gerar artefatos que podem ser referenciados. Um erro comum é colocar benchmark que falha o pipeline: prefira jobs não bloqueantes que publiquem resultados em um bucket ou como comentário no PR.

Outra prática útil é comparar contra a branch principal e publicar a regressão/ganho no PR para revisão técnica com dados.

Changelog: o que e um changelog útil

Changelog útil responde: o que mudou, por que mudou e quais são os riscos. Não confunda changelog com release notes marketing; um changelog técnico precisa ser conciso e ligado a PRs e ADRs.

Adote um formato consistente (ex: keep a changelog ou Conventional Commits) e gere um trecho legível que você pode colar no portfólio ou nos tickets de release.

Gerar changelog simples via Git

O exemplo abaixo gera linhas de changelog a partir de commits que usam conventional commits com prefixos feat/fix/perf. É um script bash prático para incluir em scripts de release.

# scripts/generate-changelog.sh
# O que faz: extrai commits entre duas tags e formata linhas de changelog
# Uso: ./scripts/generate-changelog.sh v1.2.0 v1.3.0
from=${1:-HEAD~10}
to=${2:-HEAD}

git log --pretty=format:"%h %s (%an)" ${from}..${to} | egrep "^(feat|fix|perf)" | sed -E 's/^(feat|fix|perf)\(?([^)]*)\)?: ?(.*)$/- \1(\2): \3/'

O que acontece: roda entre duas tags e produz linhas que você pode colar no changelog. Exemplo de saída: "- feat(api): suporte a streaming de relatórios (alice)".

Checklist de qualidade para producao

Itens mínimos antes de publicar no portfólio

Use esta checklist antes de incluir um projeto no portfólio ou referenciar em entrevistas. Ela garante que leitores encontrem evidência verificável.

• ADR presente e referenciado no PR
• Benchmark com script e instruções reproduzíveis
• Changelog com link para PRs incluídos
• Ambiente de benchmark documentado (CPU, Node/Python/Java versão, flags)
• Métricas traduzidas para impacto (latência p95, custos, erros)

Checklist de revisão técnica (code-review mindset)

Reveja PRs e portfólio como se fosse seu time avaliando entrega. Pergunte: existe um ADR? O benchmark foi rodado e o ambiente está documentado? O changelog explica o risco e rollback? Se alguma resposta for não, peça correção antes de marcar como "done".

Inclua checks automáticos no CI para garantir que ADRs foram criados quando o PR altera arquitetura (ex: regras de PR template que exigem tag ADR: #).

Conclusão prática

Resumo direto

ADRs provam intenção, benchmarks provam efeito, changelogs provam entrega. Sozinhos são bons; juntos, tornam seu portfólio verificável e narrativo. Em entrevistas, essa cadeia transforma uma história vaga em uma trilha de evidências que facilita perguntas e destaca seu impacto.

Agir como reviewer: mostre o erro (falta de contexto, ausência de métricas), depois a correção (documentar ADR, medir e publicar). Essa abordagem é reconhecível por recrutadores e líderes técnicos.

Próximo passo prático

Escolha um PR antigo que você fez e refatore-o: adicione um ADR curto, escreva um benchmark simples comparando antes/depois com o mesmo artefato, gere uma entrada de changelog e atualize o README do projeto com links. Em 1-2 horas terá material concreto para seu portfólio que demonstra impacto.

Dica: comece com mudanças pequenas e verificáveis. Entrevisores preferem provas pequenas e confiáveis a promessas grandes e vagas.

Esse processo não é apenas para o currículo: é prática de engenharia responsável. Padrões claros reduzem retrabalho e aumentam confiança em suas entregas. Traga a mentalidade de code review para como você documenta e comunica seu trabalho.