Portfólio de programador iniciante: projetos com evidência

Um portfólio de programador iniciante precisa provar que você identifica um problema, constrói uma solução e consegue explicar as escolhas. Nesta lição, você vai transformar repositórios soltos em projetos que alguém consegue abrir, executar e usar como ponto de partida para uma entrevista.

O nome técnico portfólio significa uma seleção de trabalhos. Não é o lugar para guardar tudo que você já digitou. É uma rota curta entre “quem é essa pessoa?” e “que evidência mostra que ela sabe fazer o que a vaga pede?”.

Os nomes e links usados nos exemplos são fixtures fictícias. O auditor em Node foi executado localmente, mas não acessa a internet; ele confirma se os campos existem, não se um deploy está no ar. Essa limitação fica visível para o checklist não prometer uma verificação que não fez.

Sua vitrine precisa deixar o projeto ser experimentado

Imagine uma loja com dez caixas fechadas e nenhuma etiqueta. Pode haver um produto ótimo ali, mas a pessoa na calçada não sabe o que cada caixa resolve, quanto trabalho exige para abrir nem se está funcionando. Uma vitrine escolhe alguns itens, mostra o uso e deixa a porta acessível.

No paralelo, os itens são projetos; a etiqueta é o README; a demonstração é o produto funcionando; o repositório deixa inspecionar a construção; e os testes mostram comportamentos conferidos. O limite da analogia: software não é objeto parado. Dependências vencem, serviços caem e um projeto pode funcionar na sua máquina e falhar em outra. Por isso a evidência inclui reprodução e versão.

Este é o caminho que cada projeto destacado precisa permitir:

problema -> demonstração -> decisão técnica -> execução local -> teste

Se você ainda não tem um projeto publicável, construa uma funcionalidade menor com o passo a passo de React com Vite. Um fluxo completo e pequeno ensina mais sobre seu trabalho que uma tela enorme com metade dos botões desconectados.

Escolha projeto pela conversa que ele abre

“Clone de uma plataforma famosa” descreve aparência, não sua participação. Para selecionar projetos, faça estas perguntas:

• qual problema eu consigo explicar sem ler o código?
• que decisão foi realmente minha?
• qual comportamento consigo demonstrar agora?
• qual erro encontrei e como investiguei?
• o que eu faria diferente numa segunda versão?

Compare dois cartões:

Clone de streaming
React, CSS e JavaScript.

Agora uma versão que abre perguntas técnicas:

Agenda Sorriso — agenda de quatro profissionais
React no front-end; API Node e PostgreSQL no servidor.
Bloqueia conflito de horário no servidor para dois atendentes não reservarem
o mesmo intervalo. Inclui dados fictícios, teste da regra e demonstração.

O segundo texto não usa “inovador”, “completo” ou “profissional”. Ele descreve comportamento observável. Se o projeto nasceu de um curso, diga qual era a base e qual decisão você adicionou. Transparência não diminui o trabalho; ela separa aprendizado guiado de contribuição própria.

README é a recepção do repositório

O GitHub mostra o README para quem abre o repositório. A documentação oficial recomenda explicar o que o projeto faz, por que é útil, como começar, onde pedir ajuda e quem mantém. Para uma candidatura, acrescente arquitetura, testes, limites e demonstração.

Use esta estrutura, ajustando ao projeto:

# Agenda Sorriso

Uma frase: problema, público e comportamento principal.

## Demonstração
- URL ou vídeo curto
- usuário de teste com dados fictícios, quando necessário

## Decisões técnicas
- onde a regra crítica fica
- alternativa considerada e motivo da escolha

## Como executar
- versões necessárias
- instalação, variáveis de exemplo e comando de início

## Como testar
- comando
- comportamentos cobertos

## Limites atuais
- o que ainda não foi implementado

Não coloque chave real num .env.example. O arquivo de exemplo contém nomes e valores seguros; .env entra no .gitignore. Se um segredo já foi commitado, apagar a linha num commit novo não o remove do histórico: revogue a credencial e siga a orientação do provedor.

Os comandos também precisam bater com o repositório:

npm ci
npm test
npm run dev

Essa saída descreve o contrato do README, não uma execução deste projeto fictício. No seu repositório, copie a saída real do terminal e corrija a documentação quando um comando não funcionar.

Deploy é porta aberta; repositório é planta do imóvel

Uma interface deveria oferecer link de demonstração. Uma API pode expor uma rota de saúde e exemplos de requisição. Uma biblioteca pode ter uma pequena aplicação de exemplo. Quando não for seguro manter serviço público, grave um vídeo curto e torne a execução local previsível.

Registre versões sem escrever “use a versão mais recente”:

{
  "engines": {
    "node": ">=24 <27"
  },
  "scripts": {
    "dev": "vite",
    "test": "vitest run",
    "build": "vite build"
  }
}

O deploy não substitui código compreensível. O código não substitui produto acessível. As duas evidências se complementam. Para uma API, a lição de deploy com Node mostra porta, variável de ambiente e healthcheck que deixam a publicação verificável.

O perfil do GitHub aponta para o que merece ser visto primeiro

O GitHub permite um README de perfil quando existe um repositório público com o mesmo nome do usuário e um README.md na raiz. Também permite fixar trabalhos. A própria documentação voltada a currículo sugere destacar uma seleção pequena e relevante, incluindo contribuições quando fizer sentido.

Um README de perfil pode ser curto:

## Marina Bispo — desenvolvedora front-end

Construo interfaces React ligadas a APIs Node.
Hoje estou melhorando validação, testes e acessibilidade.

Projetos destacados:
- Agenda Sorriso — conflito de horário validado no servidor
- Faltômetro — transforma CSV em indicadores para a recepção

Contato: linkedin.com/in/marina-bispo-dev

Evite um mural de badges que empurra projetos para baixo. Também não trate o gráfico de contribuições como ponto eletrônico. O objetivo é facilitar a leitura do trabalho relevante, não fabricar movimento diário.

Um auditor local encontra caixas sem etiqueta

Crie projetos.json. Todos os endereços abaixo usam nomes de exemplo e não são deploys reais:

[
  {
    "slug": "agenda-sorriso",
    "problema": "Evita conflito de horário numa agenda de clínica.",
    "demonstracao": "https://example.com/agenda-sorriso",
    "repositorio": "https://github.com/exemplo/agenda-sorriso",
    "execucao": "npm ci && npm run dev",
    "teste": "npm test",
    "decisao": "A validação de conflito fica no servidor."
  },
  {
    "slug": "clone-streaming",
    "problema": "",
    "demonstracao": "",
    "repositorio": "https://github.com/exemplo/clone-streaming",
    "execucao": "",
    "teste": "",
    "decisao": ""
  }
]

Agora crie auditar-portfolio.mjs:

import { readFile } from "node:fs/promises";

const arquivo = process.argv[2];

try {
  const projetos = JSON.parse(await readFile(arquivo, "utf8"));
  const campos = [
    ["problema", "problema não explicado"],
    ["demonstracao", "demonstração ausente"],
    ["repositorio", "repositório ausente"],
    ["execucao", "execução não documentada"],
    ["teste", "teste ausente"],
    ["decisao", "decisão técnica ausente"],
  ];

  let prontos = 0;
  for (const projeto of projetos) {
    const falhas = campos
      .filter(([campo]) => !String(projeto[campo] ?? "").trim())
      .map(([, mensagem]) => mensagem);

    if (falhas.length === 0) prontos += 1;
    console.log(`${projeto.slug}: ${falhas.length === 0 ? "PRONTO" : "REVISAR"}`);
    for (const falha of falhas) console.log(`  - ${falha}`);
  }

  console.log(`portfolio: ${prontos}/${projetos.length} pronto(s)`);
} catch (erro) {
  if (erro?.code === "ENOENT") {
    console.error("ERRO: ARQUIVO_NAO_ENCONTRADO");
    process.exitCode = 1;
  } else {
    throw erro;
  }
}

Execute:

node auditar-portfolio.mjs projetos.json

O auditor não decide se a solução é boa e não abre as URLs. Ele transforma ausências visíveis em uma fila de trabalho. Para testar o erro de uso, passe um arquivo inexistente:

node auditar-portfolio.mjs ausente.json

Agora a mensagem diz qual camada falhou: o inventário sequer foi encontrado. Isso é melhor que preencher o relatório com zero projetos e fingir que a análise ocorreu.

A candidatura precisa contar a mesma história em três lugares

Portfólio, currículo de programador e LinkedIn não são três personagens. Se o currículo diz TypeScript e nenhum projeto contém TypeScript, a afirmação fica sem apoio. Se o GitHub mostra back-end e o LinkedIn pede apenas design, a pessoa precisa adivinhar seu objetivo.

Use esta conferência antes de enviar uma vaga:

cargo_alvo: Desenvolvedor Front-end Júnior
evidencia_principal: agenda-sorriso
curriculo_menciona: conflito de horário no servidor
linkedin_menciona: React, API REST e validação
github_mostra: README, teste, deploy e decisão técnica

Alinhamento não significa copiar o mesmo parágrafo. Currículo resume, LinkedIn oferece contexto e repositório permite verificar.

Missão: deixe um projeto explicável sem abrir o editor

Escolha apenas um projeto. Preencha os seis campos do projetos.json, rode o auditor e corrija até aparecer 1/1 pronto(s). Depois entregue o link para uma pessoa que nunca viu o código e peça que responda, usando só o README:

1. Que problema o projeto resolve?
2. Como eu vejo funcionando?
3. Qual decisão técnica foi sua?
4. Como eu executo e testo?
5. Qual limite ainda existe?

Se alguma resposta exigir explicação por mensagem, a documentação ainda tem um buraco. Corrija primeiro esse projeto, fixe-o no GitHub e só então acrescente o segundo. Na entrevista técnica, essas decisões viram histórias e perguntas reais — exatamente o trabalho que um portfólio bem montado deve abrir.