Portfólio GitHub prático para entrevistas: projetos, READMEs e métricas

Problema observado em code reviews de portfólios

Nos processos de entrevista que eu reviso ou participo, vejo padrões repetidos: repositórios com código bom enterrado em READMEs pobres, métricas vazias (stars como único critério), e projetos que não mostram responsabilidade técnica. Candidatos com 1-3 anos de experiência perdem oportunidades porque não traduzem trabalho em sinais de confiança técnica.

O que um entrevistador procura no GitHub

Entrevistadores procuram pistas rápidas: qualidade do README, commits claros, testes que falham intencionalmente, automações que refletem maturidade (CI, linters), e métricas relevantes (manutenibilidade, cobertura, recency). Esses elementos reduzem o custo de avaliar a competência do candidato.

Visão prática: um portfólio não é um catálogo estético — é um contrato técnico. Cada projeto deve responder rapidamente: o que faz, como rodar localmente, quais trade-offs e onde procurar código crítico.

Dica: trate o README como uma API pública. A primeira leitura deve permitir um fork com testes passando em <10 minutos.

Como funciona por baixo dos panos

O fluxo de decisão do entrevistador

Quando um recrutador ou engenheiro abre seu GitHub, eles aplicam heurísticas rápidas: README, atividade recente, número e qualidade de commits, existência de CI e testes. Essas heurísticas são baratas cognitivamente e, se satisfeitas, motivam uma leitura profunda do código.

Métricas que importam (e por quê)

As métricas válidas para entrevistas não são apenas número de stars. Priorize: atividade recente (recency), cobertura de testes em pontos críticos, tempo médio de fechamento de PRs (ou simulação), complexidade ciclomática em módulos centrais, e diversidade de tecnologias com proficiência demonstrada.

Dados falsos ou vazios (badges estáticos, métricas geradas manualmente) têm efeito contrário. Um bom pipeline que atualiza métricas automaticamente demonstra disciplina e familiaridade com devops básicos.

Implementação passo a passo

Escolhendo quais projetos destacar

Revisão prática: mantenha 3-5 projetos curtos e relevantes. Para cada projeto, escolha um foco: arquitetura, testes, performance, integração contínua. Não espalhe sinais; concentre evidências de competência.

README — o jeito errado e o jeito certo

Vou mostrar primeiro um README que encontro frequentemente e que funciona mal. Depois mostro a versão revisada; compare como a segunda facilita avaliação técnica.

Contexto: o bloco abaixo é um README mínimo mal escrito. Ele não explica dependências, não tem badges e não tem instruções de teste.

# Projeto X

Aplicativo de exemplo.

Como rodar:

- instale
- rode

Arquitetura: node express

O que acontece: esse README força o leitor a entrar no código para descobrir comandos e expectativas. Isso aumenta o custo de avaliação em minutos, e entrevistadores pulam projetos com custo alto.

Agora o README revisado. Ele é intencional, específico e orienta uma avaliação técnica rápida.

# projeto-x

Badges: build | coverage | license

Resumo

Projeto X é uma API REST minimalista que demonstra padrão hexagonal, testes de contrato e CI configurada. Ideal para entrevistas focadas em backend e testes.

Quickstart

1. git clone https://github.com/seu-usuario/projeto-x.git
2. cd projeto-x
3. docker-compose up --build
4. npm run test:unit

Expectativas de teste

- os testes unitários cobrem controllers e services (~80%)
- contratos de integração com banco são mockados

Pontos para revisar

- src/services/orderService.ts (algoritmo de reconciliation)
- src/controllers/webhookController.ts (tratamento de idempotência)

Decisões técnicas

- Node 18, TypeScript
- Postgres em Docker para integração local
- GitHub Actions para CI, lint e coverage

Como rodar localmente (sem Docker)

- npm install
- cp .env.example .env
- npm run dev

Contato

Para discutir trade-offs, abra uma issue com "review" no título.

O que acontece: esse README converte curiosidade em ação imediata. Indica pontos para revisão, comandos para rodar e expectativas de testes. Em entrevistas, isso leva o avaliador ao código certo em 30-90 segundos.

Automatizando métricas — script prático

Contexto: um script que calcula métricas simples a partir do git e gera um arquivo JSON usado pelo README (ou badge). Métricas: commits nos últimos 90 dias, porcentagem de commits com mensagens estruturadas (type: scope msg), número de arquivos modificados por commit médio.

// scripts/portfolio-metrics.js
// Gera metrics.json com dados úteis para o README

const { execSync } = require('child_process');
const fs = require('fs');

function run(cmd){
  return execSync(cmd, { encoding: 'utf8' }).trim();
}

function commitsLastNDays(n){
  const since = `--since="${n}.days"`;
  const out = run(`git rev-list --count HEAD --since=${n}.days`);
  return parseInt(out, 10) || 0;
}

function commitsStructured(){
  const out = run('git log --pretty=%B -n 200');
  const messages = out.split('\n\n');
  const structured = messages.filter(m => /^\w+(\([\w-]+\))?:/.test(m)).length;
  return { total: messages.length, structured };
}

const metrics = {
  commits_90d: commitsLastNDays(90),
  commits_check: commitsStructured(),
  generated_at: new Date().toISOString()
};

fs.writeFileSync('metrics.json', JSON.stringify(metrics, null, 2));
console.log('metrics.json generated', metrics);

O que acontece: ao rodar node scripts/portfolio-metrics.js o repositório passa a ter um metrics.json atualizado. Use esse arquivo para gerar badges ou informações no README. Isso demonstra automação e transparência.

Patterns e boas práticas

Pattern: README como checklist de avaliação

Transforme o README em um roteiro de leitura: quickstart, testes, pontos para revisão, decisões técnicas e métricas. Isso reduz fricção e demonstra pensamento crítico. Inclua links diretos aos arquivos críticos, por exemplo: src/services/orderService.ts#L10-L80.

Pattern: métricas que contam história

Evite métricas superficiais. Prefira métricas que explicam comportamento: recency (commits nos últimos 90 dias), cobertura em módulos críticos, tempo médio para fechar uma issue num projeto colaborativo (mesmo que seja um fork com issues fingidas para demonstração).

Use badges dinâmicos para indicar estado atual (CI passing, coverage) e um badge customizado para 'recency' se possível. Isso torna a primeira tela informativa.

Integração com CI e atualização automática

Automatize geração de metrics.json no pipeline e commit automático do badge/arquivo ao branch gh-pages ou ao README principal via bot-account com chave limitada.

# .github/workflows/update-metrics.yml
# Executa script e comita metrics.json quando testes passam

name: update-metrics
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Generate metrics
        run: node scripts/portfolio-metrics.js
      - name: Commit metrics
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add metrics.json
          git commit -m "chore: update metrics.json" || echo "no changes"
          git push

O que acontece: esse workflow roda nos pushes para main, valida os testes, gera metrics.json e comita. Em entrevistas, um pipeline assim mostra disciplina operacional.

Documentação de trade-offs

Inclua uma seção curta listando trade-offs técnicos: por que escolheu Postgres vs Mongo, por que foi usado uma lib X no lugar da Y. Isso evidencia capacidade de tomada de decisão.

Armadilhas comuns e como evitar

Vanidade vs sinal

Erro comum: encher o portfólio com stars, forks e badges estáticos. Isso é ruído. Em vez disso, mostre trabalho real — testes, PRs revisados e issues resolvidas. Se usar badges, conecte-os a dados reais (CI, cobertura).

README extenso demais vs inútil

Erro comum: README com um livro de detalhes, sem orientação. Outro erro: README minimalista demais. A regra prática: comece com 5-7 linhas de resumo, depois quickstart em 4 passos, depois seção "Pontos para revisar" com links diretos. Mais detalhe pode ficar em docs/.

Dica prática: se levar mais de 2 minutos para localizar o código que implementa a feature principal, seu README está ineficiente.

Automação insegura

Alguns candidatos cometem o erro de incluir secrets no pipeline ou comitar tokens. Nunca automatize commits com credenciais pessoais. Use a conta do Github Actions bot e limite permissões. Documente como gerar um token para uma chave de deploy — não inclua a chave no repositório.

Exemplos de mensagens de commit ruins e boas práticas

Visão de code review: commits como "changes" ou "fix" são inúteis. Prefira formato estruturado (tipo Conventional Commits) e mensagens que descrevam a intenção e o impacto.

// exemplo ruim de git log
// commit: changes
// message: updated files

// exemplo bom (conventional commits)
feat(auth): add refresh token rotation

// o bom mostra escopo e intenção; facilita revisão e release notes

O que acontece: commits estruturados facilitam análise de histórico e mostram disciplina de engenharia. Em entrevistas, é um sinal forte de maturidade.

Conclusão prática

Checklist rápido antes da entrevista

Finalize com uma checklist que você pode rodar 48 horas antes da entrevista para garantir que o portfólio esteja otimizado:

1. Todos os READMEs principais com quickstart e pontos para revisão

2. CI verde no branch principal

3. metrics.json ou badges que mostram recency e coverage

4. Commits recentes com mensagens estruturadas

5. PRs e issues de exemplo com comentários que demonstram revisão

Resumo final

Trate o seu GitHub como uma entrevista contínua: pequenos sinais consistentes (READMEs claros, pipelines, métricas automatizadas, commits com intenção) reduzem o trabalho do avaliador e aumentam suas chances. A diferença entre um portfólio que é lido e um que é ignorado é a redução do custo cognitivo do avaliador.

Cada mudança sugerida aqui é acionável: reescreva um README por prioridade, adicione um script simples para metrics.json, integre ao CI e garanta que seus commits contem uma história. Em code review, essa abordagem transforma impressões vagas em decisões positivas.

Próximo passo prático: escolha um repositório com atividade nos últimos 6 meses e aplique a checklist. Se algo quebrar no CI, corrija e documente o porquê da correção em uma issue — isso vira conteúdo de entrevista.