--- title: "README de projeto para junior: o que colocar no GitHub antes de mandar CV" url: "https://eu.dev.br/carreira/readme-projeto-junior/" markdown_url: "https://eu.dev.br/carreira/readme-projeto-junior.MD" description: "Um projeto junior pode ser bom e ainda assim parecer fraco se o README não explica problema, stack, como rodar, decisões e próximos passos. Veja o modelo." date: "2026-05-25" author: "" --- # README de projeto para junior: o que colocar no GitHub antes de mandar CV Um projeto junior pode ser bom e ainda assim parecer fraco se o README não explica problema, stack, como rodar, decisões e próximos passos. Veja o modelo. Projeto de portfólio sem README é entrevista desperdiçada. Você pode ter feito uma API decente, um dashboard útil, um app bonito, uma automação real ou um clone transformado em algo próprio. Se o recrutador abre o GitHub e encontra só uma lista de arquivos, ele precisa adivinhar o que você fez. Recrutador não adivinha. Pessoa técnica também não tem tempo para clonar tudo só para entender se vale entrevista. README bom não é enfeite. É a embalagem operacional do projeto. Ele responde rápido: - que problema esse projeto resolve; - por que ele existe; - quais tecnologias aparecem de verdade; - como rodar; - como testar; - o que você decidiu; - o que ainda falta; - onde está o deploy, vídeo ou screenshot. Para junior, isso pesa muito porque mostra comunicação, cuidado e maturidade. Código bom com README vazio parece exercício abandonado. Código simples com README claro parece projeto terminado. Se você ainda está escolhendo projetos, leia primeiro o guia de [portfólio com 3 projetos certos](/carreira/portfolio-3-projetos/). Se já tem projeto, este texto é para transformar o repositório em evidência de contratação. ## o objetivo do README O README precisa fazer três pessoas entenderem seu projeto sem te chamar no privado. A primeira é a pessoa de RH ou recrutamento. Ela não vai avaliar arquitetura, mas precisa entender se o projeto combina com a vaga. A segunda é a pessoa técnica que vai olhar antes ou durante a entrevista. Ela quer ver decisão, organização, teste, limitação e se você consegue explicar trade-off. A terceira é você daqui a três meses. Se nem você consegue rodar o projeto depois de um tempo, o README falhou. Então não escreva README como diário de curso: ```text Projeto feito durante a aula 07 do bootcamp X. ``` Escreva como entrega: ```text API para organizar candidaturas de vagas junior, com cadastro de empresas, status de processo, follow-up e histórico de entrevistas. O objetivo é ajudar candidatos a controlar aplicações sem depender de planilha solta. ``` A segunda frase diz problema, domínio e uso. A primeira só diz que você assistiu aula. ## estrutura mínima que funciona Use esta ordem. Ela serve para frontend, backend, dados, mobile simples, automação e teste técnico. ```markdown # Nome do projeto Resumo em 2 ou 3 linhas. ## Demo Link do deploy, vídeo curto, GIF ou screenshot. ## Problema Que dor o projeto resolve e para quem. ## Funcionalidades - funcionalidade principal 1 - funcionalidade principal 2 - funcionalidade principal 3 ## Stack - linguagem/framework - banco/API externa - testes - deploy/infra ## Como rodar localmente Passos claros do zero. ## Como testar Comando e o que ele cobre. ## Decisões técnicas 2 a 5 escolhas importantes. ## Limitações e próximos passos O que ficou fora e por quê. ## Screenshots Imagens pequenas com legenda. ``` Isso parece básico. É exatamente por isso que funciona. Muito projeto junior falha no básico. ## comece pelo resumo, não pela stack O topo do README não deve ser uma parede de badges, logos e nomes de tecnologia. Ruim: ```markdown # Fullstack App React + Node + Express + Prisma + PostgreSQL + Tailwind + Docker + JWT + Vite. ``` Melhor: ```markdown # Mapa de candidaturas tech Aplicação para candidatos junior registrarem vagas, etapas, contatos e próximos follow-ups. O projeto nasceu para evitar que entrevistas, testes técnicos e retornos se percam entre LinkedIn, Gupy e email. Demo: https://exemplo.com ``` A stack entra depois. Primeiro vem o problema. Se o projeto é simples, não esconda. Simples com clareza é melhor do que inflar. ```markdown # Organizador de estudos de SQL App local para montar uma lista semanal de exercícios de SQL por tema, marcar resolução e revisar erros comuns. Fiz para estudar joins, group by e subqueries com rotina em vez de aula solta. ``` Isso soa honesto. Honestidade técnica é sinal bom para vaga junior. ## coloque demo, screenshot ou vídeo Nem todo projeto precisa de deploy público. Mas todo projeto visual precisa de alguma prova visual. Ordem de força: 1. link funcionando em produção; 2. vídeo curto mostrando fluxo principal; 3. GIF no README; 4. screenshots com legenda; 5. só instrução para rodar localmente. Se for frontend, portfolio, dashboard ou app, deploy ajuda muito. Vercel, Netlify, Cloudflare Pages, GitHub Pages, Render ou Fly.io podem resolver dependendo da stack. Não precisa infra sofisticada. Se for backend, uma coleção de requests, Swagger, Bruno, Insomnia, Postman ou exemplos `curl` ajudam. Exemplo: ```markdown ## Demo - Deploy web: https://mapa-candidaturas.example.com - API docs: https://mapa-candidaturas.example.com/docs - Vídeo de 90s: https://youtu.be/... ![Tela de vagas com filtros por status](docs/screenshot-vagas.png) ``` Se o projeto não está mais no ar porque o plano gratuito dorme ou acabou, diga isso: ```markdown A demo pública pode hibernar no plano gratuito. O fluxo principal aparece no vídeo e o projeto roda localmente com Docker Compose. ``` Melhor explicar do que deixar link morto. ## como rodar: escreva para uma máquina limpa A seção de instalação precisa funcionar para alguém que acabou de clonar. Evite: ```markdown npm install npm start ``` Às vezes basta, mas geralmente falta versão, variável, banco, seed e comando de teste. Modelo melhor: ```markdown ## Como rodar localmente Pré-requisitos: - Node 22+ - PostgreSQL 16 ou Docker Passos: ```bash git clone https://github.com/seu-user/mapa-candidaturas.git cd mapa-candidaturas cp .env.example .env docker compose up -d postgres npm install npm run db:migrate npm run db:seed npm run dev ``` Abra `http://localhost:3000`. Usuário de teste: ```text email: demo@example.com senha: demo1234 ``` ``` Não suba segredo real. Use `.env.example` com nomes de variável e valores falsos. ```env DATABASE_URL=postgres://user:password@localhost:5432/app JWT_SECRET=change-me-local ``` Se seu README tem comando que não funciona, ele trabalha contra você. Teste do zero antes de mandar CV. ## testes: pouco é melhor do que nada Junior não precisa ter cobertura perfeita. Mas mostrar que você pensou em teste te separa de muita gente. Exemplo simples: ```markdown ## Como testar ```bash npm test ``` Cobertura atual: - criação de candidatura; - mudança de status; - regra de follow-up atrasado; - validação de email inválido. Ainda não cobre autenticação e upload de currículo. ``` Perceba a última linha. Assumir limite é maturidade. Fingir que está completo quando não está é fraco. Se o projeto não tem teste automatizado, crie pelo menos um checklist manual: ```markdown ## Checklist manual - [ ] criar conta demo - [ ] cadastrar vaga - [ ] mover vaga para entrevista - [ ] registrar follow-up - [ ] arquivar processo recusado ``` Mas use isso como ponte, não como desculpa eterna. Um projeto de portfólio com 3 ou 5 testes reais já melhora muito. ## decisões técnicas: mostre pensamento A parte mais valiosa para entrevista é explicar por que você escolheu algo. Não precisa escrever tese. Escreva decisões curtas: ```markdown ## Decisões técnicas - Usei SQLite no primeiro deploy para reduzir custo e facilitar execução local. O modelo pode migrar para PostgreSQL porque as queries estão isoladas no repositório `applicationsRepository`. - Separei `status` de `nextActionAt` porque uma candidatura pode estar em entrevista e ainda exigir follow-up. - Não implementei login social para manter o escopo pequeno; autenticação por email e senha cobre o fluxo principal. - O frontend usa componentes simples em vez de biblioteca de UI para deixar o código mais legível para revisão. ``` Isso gera conversa boa. Pessoa técnica pode discordar, mas vai ver raciocínio. Evite decisões falsas: ```markdown Usei microservices para escalar. ``` Se é projeto de uma pessoa, sem tráfego, isso soa fantasia. Para junior, a melhor decisão muitas vezes é reduzir escopo. ## limitações deixam o projeto mais confiável Projeto junior sem limitação parece mentira. Todo projeto tem limite. Escreva o que ficou fora: ```markdown ## Limitações e próximos passos - O envio de email ainda é simulado no console. - O dashboard usa dados do usuário logado, mas não tem página administrativa. - Ainda falta paginação na lista de candidaturas. - O deploy gratuito pode hibernar depois de inatividade. - Próximo passo: adicionar testes de integração para os filtros principais. ``` Isso mostra que você entende o que fez e o que não fez. Só cuidado para não transformar a seção em autodestruição: Ruim: ```markdown Projeto incompleto, cheio de bug, fiz correndo. ``` Bom: ```markdown O escopo atual cobre cadastro, status e follow-up. Relatórios e notificações reais ficaram fora para manter a versão inicial pequena. ``` ## README para projeto de curso Projeto de curso pode entrar no portfólio se você transformou. O README precisa deixar claro o que é seu: ```markdown Este projeto começou como exercício do curso X. Depois da aula, fiz estas alterações próprias: - troquei o domínio de produtos para candidaturas de vaga; - adicionei autenticação; - criei testes para status de processo; - publiquei demo; - escrevi seed com dados realistas; - documentei limitações e próximos passos. ``` Isso é melhor do que fingir autoria total. Pessoa técnica reconhece projeto famoso de curso em cinco segundos. Transparência evita constrangimento. Se você só copiou a aula e mudou cor, não coloque como projeto principal. Volte ao guia de [GitHub para junior](/carreira/github-junior/) e transforme antes. ## o que não colocar Evite ruídos que enfraquecem o projeto. Não coloque: - vinte badges que não significam nada; - gif enorme que demora carregar; - texto motivacional genérico; - segredo em print, `.env`, token ou URL privada; - instrução quebrada; - link de deploy morto sem aviso; - stack listada que não aparece no código; - "em breve" em metade do README; - licença copiada sem entender; - commit de `node_modules`, `.venv`, `dist` ou arquivo gigante desnecessário. Também evite inglês automático se você não consegue defender. README em português é aceitável para vaga brasileira. Se a vaga pede inglês ou seu projeto mira remoto internacional, escreva em inglês simples e revise. ## checklist antes de mandar no CV Antes de colocar o link no CV, LinkedIn ou Gupy, faça este checklist: - [ ] o repositório é público ou acessível; - [ ] o nome do projeto é claro; - [ ] o resumo explica problema e usuário; - [ ] existe demo, screenshot ou vídeo; - [ ] o comando de instalação funciona do zero; - [ ] `.env.example` existe quando precisa; - [ ] não existe segredo real no histórico recente; - [ ] testes ou checklist manual estão documentados; - [ ] decisões técnicas aparecem em 2 a 5 bullets; - [ ] limitações estão explicadas sem drama; - [ ] links do README funcionam; - [ ] o projeto principal está pinado no GitHub; - [ ] o mesmo projeto aparece no [CV sem experiência](/carreira/primeiro-cv-sem-experiencia-tech/) com uma descrição parecida. Se você falha em metade, não precisa refazer o projeto. Arrume README, demo e instrução primeiro. É o jeito mais rápido de aumentar a força do portfólio. ## modelo pronto Copie, adapte e corte o que não fizer sentido. ```markdown # Nome do projeto Resumo em 2 ou 3 linhas explicando o problema, o usuário e o fluxo principal. Demo: https://... ![Screenshot da tela principal](docs/screenshot.png) ## Problema Explique a dor em linguagem simples. Por que esse projeto existe? ## Funcionalidades - Criar ... - Listar ... - Filtrar ... - Exportar ... ## Stack - Frontend: ... - Backend: ... - Banco: ... - Testes: ... - Deploy: ... ## Como rodar ```bash git clone ... cd ... cp .env.example .env ... ``` ## Como testar ```bash ... ``` ## Decisões técnicas - Decisão 1 e motivo. - Decisão 2 e motivo. - Decisão 3 e motivo. ## Limitações e próximos passos - Limitação real 1. - Limitação real 2. - Próximo passo mais provável. ``` ## como usar na entrevista README não serve só para passar triagem. Ele vira roteiro de entrevista. Quando perguntarem "me fala de um projeto seu", siga a mesma ordem: 1. problema; 2. usuário; 3. decisão técnica principal; 4. dificuldade; 5. como você testou; 6. o que faria diferente. Exemplo: > Fiz uma API para controlar candidaturas porque eu mesmo estava perdendo follow-up em planilha. Escolhi PostgreSQL porque queria praticar modelagem relacional, mas mantive o domínio pequeno: vaga, empresa, etapa e próximo contato. A parte mais difícil foi decidir como representar status sem travar o fluxo. Testei criação, mudança de etapa e follow-up atrasado. Se refizesse, adicionaria fila de email e mais testes de integração. Isso soa como alguém que terminou e aprendeu. Não como alguém que só empilhou tecnologia. O README é a cola entre GitHub, CV, entrevista e teste técnico. Se você está mandando candidatura sem ele, está pedindo para a pessoa fazer trabalho que você podia ter resolvido em uma tarde.