Portfólio tech que mostra habilidades reais: estrutura, projetos e evidências

Um portfólio técnico não é uma galeria de telas bonitas: é um conjunto de evidências verificáveis de que você resolve problemas com código. Recrutadores e líderes técnicos passam poucos minutos por candidato, e o que decide não é a quantidade de repositórios, e sim a clareza com que cada projeto explica o problema, a decisão técnica e o resultado. Este guia mostra como estruturar esse material.

O que um portfólio precisa provar

Antes de escolher tecnologias, defina o que cada projeto comprova. Um portfólio eficiente responde a quatro perguntas: você entende o domínio do problema, você escreve código legível, você sabe operar o que constrói (deploy, logs, erros) e você comunica decisões. Projetos que só exibem um layout copiado de tutorial não respondem a nenhuma delas.

Três projetos bastam (e por quê)

A recomendação de manter poucos projetos não é estética: é sobre profundidade. Manter três projetos ativos permite iterar, refatorar e adicionar testes, o que gera histórico de commits realista. Quinze repositórios com um commit inicial cada comunicam o oposto.

• Projeto 1 — utilitário pessoal: algo que você mesmo usa toda semana. Prova motivação genuína e entendimento de requisito.
• Projeto 2 — integração com dados externos: consumo de API pública, tratamento de erros de rede, cache e paginação. Prova competência em assincronia e resiliência.
• Projeto 3 — aplicação com persistência e autenticação: banco de dados, controle de acesso e regras de negócio. Prova capacidade full-stack.

O README é a peça mais importante

Na prática, o README é lido antes do código. Ele deve permitir que alguém entenda o projeto em menos de um minuto e rode o projeto em menos de cinco. Uma estrutura que funciona bem começa pelo problema, não pela stack.

# Controle de Escalas

Ferramenta para montar escalas de plantão em clínicas pequenas, substituindo
planilhas compartilhadas que quebravam quando duas pessoas editavam ao mesmo tempo.

## Problema
Escalas em planilha geravam conflitos de horário e não avisavam sobre
limite de horas semanais por profissional.

## Solução
Aplicação web com validação de conflitos no servidor e histórico de alterações.

## Stack e por quê
- PostgreSQL: restrições de exclusão (EXCLUDE) evitam sobreposição de horários no banco.
- TypeScript: contratos entre API e front conferidos em build.
- Vitest: testes das regras de horas semanais.

## Rodando localmente
\`\`\`bash
cp .env.example .env
npm install
npm run db:migrate
npm run dev
\`\`\`

## Limitações conhecidas
- Não há suporte a fuso horário diferente do servidor.
- Notificações por e-mail estão em fila simples, sem retry exponencial.

Repare no bloco de limitações. Admitir o que não está pronto é um sinal de maturidade técnica: mostra que você conhece as fronteiras da própria solução, algo que entrevistadores costumam sondar.

Demonstre decisões, não apenas resultado

Registrar decisões arquiteturais em arquivos curtos (ADRs, Architecture Decision Records) diferencia um portfólio. Um ADR tem quatro partes: contexto, decisão, alternativas descartadas e consequências. Não precisa ter mais de vinte linhas.

# ADR 003 — Fila em tabela do Postgres em vez de Redis

## Contexto
Envio de e-mails de confirmação precisa de retry e não pode bloquear a requisição.
Volume atual: ~200 mensagens/dia.

## Decisão
Usar uma tabela "jobs" no Postgres com SELECT ... FOR UPDATE SKIP LOCKED.

## Alternativas descartadas
- Redis + BullMQ: adiciona um serviço a operar para volume baixo.
- Envio síncrono: aumenta latência e perde mensagens em falha de SMTP.

## Consequências
- Menos infraestrutura, transações no mesmo banco.
- Escala limitada a alguns milhares de jobs/dia; revisitar acima disso.

Código que aguenta leitura

Quem avalia costuma abrir dois ou três arquivos aleatórios. O objetivo é que qualquer arquivo aberto pareça intencional. Funções pequenas, nomes que descrevem intenção e ausência de código comentado morto valem mais do que padrões sofisticados aplicados fora de contexto.

// Fraco: nome genérico, responsabilidade dupla, erro silencioso
async function handle(data: any) {
  try {
    const r = await fetch("/api/x", { method: "POST", body: JSON.stringify(data) });
    return await r.json();
  } catch {
    return null;
  }
}

// Melhor: intenção explícita, erro propagado com contexto
export async function criarAgendamento(input: NovoAgendamento): Promise<Agendamento> {
  const resposta = await fetch("/api/agendamentos", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });

  if (!resposta.ok) {
    throw new Error(
      `Falha ao criar agendamento (${resposta.status}): ${await resposta.text()}`
    );
  }

  return AgendamentoSchema.parse(await resposta.json());
}

Deploy público muda a percepção

Um link funcionando remove atrito. O avaliador testa em segundos, sem clonar nada. Além disso, colocar algo no ar obriga você a lidar com variáveis de ambiente, build de produção, domínio e erros que só aparecem fora do localhost — exatamente o tipo de experiência que o mercado valoriza.

• Inclua dados de demonstração para que o visitante veja a aplicação preenchida, não uma tela vazia.
• Ofereça uma conta de teste quando houver login, com permissões limitadas.
• Monitore erros com uma ferramenta gratuita e cite isso no README; observabilidade é diferencial.
• Configure um domínio próprio quando possível, mesmo barato: sinaliza cuidado com apresentação.

A página do portfólio em si

A página que agrega os projetos deve carregar rápido, ser legível no celular e ter contato visível. Evite animações longas antes do conteúdo aparecer. Uma estrutura simples costuma performar melhor do que experiências elaboradas que atrasam a leitura.

1. Nome, função pretendida e uma linha sobre o que você faz.
2. Três projetos com screenshot, problema resolvido em uma frase, stack e dois links: demo e código.
3. Experiência e formação em formato enxuto, incluindo transições de carreira quando houver.
4. Contato direto: e-mail, LinkedIn e GitHub, sem formulário obrigatório.

Erros comuns que reduzem credibilidade

Como evoluir o portfólio ao longo do tempo

Trate o portfólio como produto: revise a cada dois ou três meses, aposente projetos que não representam mais seu nível e aprofunde os que geram conversa em entrevistas. Anote as perguntas que recebe sobre cada projeto — elas indicam o que está mal explicado no README.

Contribuições em projetos abertos, mesmo pequenas (correção de documentação, teste adicional, correção de bug reprodutível), complementam bem o conjunto porque mostram trabalho em código que você não escreveu, revisão por terceiros e uso de fluxo de pull request.

Conclusão

Um portfólio forte é pequeno, específico e verificável. Ele parte de problemas reais, explica decisões com honestidade, roda em produção e permite que qualquer pessoa entenda o valor em poucos minutos. Volume impressiona menos do que profundidade demonstrável, e cada linha de documentação bem escrita economiza minutos preciosos de quem avalia.

Perguntas frequentes

Fontes consultadas

• GitHub Docs — Sobre READMEs
• Architecture Decision Records (adr.github.io)
• MDN — Boas práticas de acessibilidade web