Um README de portfólio não precisa contar toda a história do projeto. Ele precisa permitir que outra pessoa entenda o problema, encontre uma decisão de engenharia e veja como conferir a afirmação principal. Uma galeria de telas pode chamar atenção, mas não explica o que você escolheu, o que testou ou o que ainda desconhece.

Para escrever esse README, organize a leitura em cinco passagens: problema, contribuição, decisões, verificação e limites. O guia sobre o que um portfólio de software engineer com IA deve provar trata o conjunto de projetos. Aqui, a pergunta é mais prática: como transformar um repositório em um artefato que sustenta uma conversa técnica?

Diagrama mostra um README de portfólio ligando problema, decisões, verificação e limites.

Resposta curta

  • Explique qual problema o projeto resolve e para quem, antes de listar a stack.
  • Mostre uma decisão que poderia ter sido diferente e o trade-off aceito.
  • Dê um caminho curto para instalar, executar e verificar o comportamento principal.
  • Separe o que você fez, adaptou, delegou ou apenas reutilizou.
  • Declare limites, casos não testados e o que mudaria em seguida.

O que um README de portfólio precisa provar?

O README de um repositório tem uma função mais ampla que a apresentação pessoal. A documentação do GitHub sobre arquivos README descreve o arquivo como um lugar para explicar por que o projeto é útil, o que ele faz e como começar. Também recomenda informar onde pedir ajuda e quem mantém o projeto.

Para um portfólio, acrescente a pergunta que um revisor provavelmente fará: que tipo de engenharia este projeto permite observar? A resposta não precisa prometer senioridade. Pode apontar para uma fronteira específica, como autenticação, processamento assíncrono, validação de entrada, recuperação de falhas ou avaliação de uma saída de modelo.

Uma boa abertura responde quatro perguntas sem exigir que o leitor abra o código:

Pergunta O README precisa mostrar
O que é? uma frase com o comportamento principal
Por que existe? o problema, o usuário ou operador e o limite do recorte
O que foi feito? sua contribuição e as partes adaptadas ou reutilizadas
Como conferir? um comando, uma entrada, uma saída esperada ou uma demonstração reproduzível

O estudo Categorizing the Content of GitHub README Files analisou 4.226 seções de 393 repositórios. Ele encontrou informações sobre o que o projeto faz e como usá-lo com frequência, mas propósito e status com menos presença. A amostra é de 2018 e não mede contratação. Ainda assim, oferece uma pergunta útil para o portfólio: o seu README explica apenas o funcionamento ou também o motivo e o estado atual do projeto?

Comece pelo problema, não pela tecnologia

Abra com duas ou três frases que definam o recorte. "API em Node.js com PostgreSQL" nomeia ferramentas, mas não permite avaliar uma decisão. "API que registra pedidos e rejeita uma atualização quando a versão do recurso mudou" já informa um comportamento e um risco que pode ser discutido.

Um projeto pessoal não precisa ter usuários reais nem funcionar como um produto comercial. O README deve dizer se a finalidade é estudar uma técnica, demonstrar um contrato ou explorar uma hipótese. Isso evita que uma pessoa atribua ao projeto uma promessa que você nunca fez.

Use uma estrutura simples no topo:

# Nome do projeto

Uma frase sobre o que o sistema faz e para quem.

Este projeto explora [problema ou técnica]. Ele cobre [escopo]
e não pretende resolver [fora de escopo].

## Demonstração rápida

Comando ou link que mostra o caminho principal.

O guia do GitHub para deixar um repositório pronto para colaboração também coloca no README o propósito do projeto, como usá-lo e como ele é mantido. No portfólio, "mantido" inclui dizer se o repositório está ativo, congelado, experimental ou limitado a uma demonstração.

Registre decisões que o código sozinho não explica

Uma lista de dependências não mostra julgamento. Para cada decisão escolhida, registre o risco que ela atende, a alternativa considerada e o custo que você aceitou. Não é necessário documentar toda escolha de sintaxe. Escolha uma ou duas que mudam o comportamento, a operação ou a possibilidade de verificação.

Decisão Pergunta que o README responde Evidência que ajuda
Armazenamento Por que esse banco ou arquivo cabe no recorte? consulta, modelo de dados ou limite declarado
Concorrência O que acontece quando duas ações chegam juntas? teste, regra de conflito ou cenário não coberto
Falha Como o sistema reage a timeout ou entrada inválida? fixture, estado de erro ou log redigido
Dependência de IA O que foi delegado e como a saída foi verificada? diff, teste, critério ou decisão rejeitada

Um registro curto funciona melhor quando liga causa e consequência:

## Decisão: rejeitar atualização com versão antiga

Escolhi comparar `version` antes da escrita porque duas requisições podem
editar o mesmo recurso. A alternativa seria aceitar a última gravação, mas
isso esconderia uma alteração concorrente. O teste `npm test -- conflict`
mostra o caso aceito e o caso rejeitado.

O exemplo é ilustrativo. Troque o comando, o risco e a decisão por algo que exista no seu projeto. Um README que descreve uma arquitetura que o código não possui produz uma prova pior que um README curto e honesto.

Mostre um caminho de verificação

Uma demonstração ajuda, mas uma demonstração isolada não explica como o resultado foi obtido. Escreva o caminho mínimo que outra pessoa pode repetir:

  1. quais versões, pré-requisitos ou variáveis são necessárias;
  2. qual comando instala e qual comando inicia o projeto;
  3. qual entrada representa o caso principal;
  4. qual saída ou efeito deve ser observado;
  5. qual caso de erro mostra o limite da implementação.

Se a instalação depende de segredo, serviço pago ou conta privada, não esconda essa dependência. Inclua um exemplo seguro, um modo local ou uma descrição do que não pode ser reproduzido. A documentação do GitHub recomenda que o README ajude o leitor a começar, mas isso não significa prometer uma execução sem configuração quando o projeto não oferece essa condição.

O teste não precisa ser grande. Um comando npm test, uma fixture pequena ou um exemplo de entrada e saída pode ser suficiente para a pergunta escolhida. Para um projeto com modelo, registre também o critério de avaliação e uma entrada que deveria ser recusada. Uma resposta bonita não demonstra que o comportamento é consistente.

Não coloque no README um resultado que você não executou. Se o comando é apenas um exemplo, escreva "ilustrativo". Se você conferiu a fixture local, diga o ambiente e o que ela não cobre. Essa diferença é parte da evidência.

Explique autoria sem transformar o README em defesa

O revisor precisa saber quais partes podem ser atribuídas a você. Isso importa para um projeto em grupo, um fork, uma base de tutorial e um projeto assistido por IA.

Use uma seção curta:

## Autoria e limites da contribuição

Implementei o contrato da API, a validação e os testes de conflito.
Adaptei a configuração inicial de [fonte]. Não medi carga de produção
e não afirmo que o projeto cobre recuperação após queda do banco.

Não é preciso publicar uma transcrição inteira de uma conversa com um agente. Se você usou Codex, Claude Code ou outra ferramenta, explique o que delegou, o que revisou e que prova executou depois. Para sessões longas, o autor usa o RemoteCode para manter o contexto entre sessões; essa é uma informação sobre o método de trabalho, não uma prova de que o projeto tem qualidade.

O checklist para avaliar um portfólio de software engineer faz a leitura do outro lado. Ele pergunta se a contribuição, as decisões, a verificação e os limites estão visíveis. Use essas perguntas para revisar o próprio README antes de pedir que outra pessoa o avalie.

Diga o que ainda não foi provado

Um projeto de portfólio fica mais confiável quando separa três estados:

  • Não implementado: a função não existe.
  • Não verificado: a função existe, mas a prova disponível não cobre o caso.
  • Fora do objetivo: o projeto não pretende resolver aquela situação.

Essa distinção evita dois exageros. O primeiro é chamar uma demo de sistema pronto para produção. O segundo é esconder um projeto útil porque ele não tem a escala de um serviço comercial.

Inclua limites ligados às decisões que você mostrou. Se escolheu SQLite para manter a instalação simples, diga que a escolha não prova comportamento sob carga distribuída. Se usou uma API externa, diga que a fixture não verifica a disponibilidade do fornecedor. Se o agente gerou parte do código, diga qual revisão e quais testes continuam sob sua responsabilidade.

Também informe o estado do repositório: ativo, congelado, experimental ou arquivado. O leitor precisa saber se um erro aberto representa trabalho em andamento ou uma decisão abandonada.

Separe o README da documentação longa

O README deve levar o leitor até o primeiro uso e à prova principal. Ele não precisa conter toda a referência da API, a história de cada commit ou o manual completo de operação. A própria documentação do GitHub sobre wikis diferencia o README, que explica rapidamente o que o projeto pode fazer, de uma documentação mais extensa.

Mova detalhes longos para docs/ quando isso melhorar a leitura, mas deixe o caminho explícito:

README.md                 problema, decisão principal e quickstart
docs/architecture.md      desenho e alternativas descartadas
docs/testing.md           fixtures, comandos e lacunas da prova
docs/operations.md        configuração, recuperação e manutenção

Não use essa separação para esconder a informação mais importante. O README ainda precisa conter o problema, o caminho inicial, a decisão que você quer discutir e o link direto para a evidência complementar.

Checklist antes de publicar

Leia o README como alguém que não conhece o projeto. Você consegue responder sem abrir cinco arquivos?

  • O projeto explica o problema e o fora de escopo?
  • O primeiro bloco diz o que fazer e o que observar?
  • Existe uma decisão técnica ligada a um risco ou requisito?
  • A alternativa descartada e o trade-off aparecem?
  • O comando de instalação foi conferido em um ambiente limpo ou está marcado como ilustrativo?
  • Um teste, fixture ou exemplo mostra o comportamento principal?
  • Há um caso de falha, uma limitação ou uma lacuna de verificação?
  • A autoria separa o que foi feito, adaptado, delegado e reutilizado?
  • O status do repositório está claro?
  • Os detalhes longos têm links que funcionam?

Se a resposta for "não" para uma linha, isso não significa que o projeto precisa crescer. Significa que o README ainda não prova aquela afirmação. Corrija a documentação, reduza a promessa ou retire a afirmação.

Conclusão

Um README de portfólio funciona como uma trilha de revisão. Ele começa no problema, mostra uma decisão que teve consequência, aponta para uma forma de verificar o comportamento e termina nos limites que continuam abertos. A tecnologia usada aparece, mas não carrega sozinha a prova.

Escreva para a conversa que o projeto pode sustentar. Se você não consegue explicar por que uma escolha existe ou qual teste poderia contradizê-la, o README não deve inventar confiança. Uma documentação curta, reproduzível e honesta prepara uma discussão técnica melhor que uma página cheia de badges e adjetivos.

Como este artigo foi produzido

Samuel Fajreldines é o responsável editorial por este artigo. A pesquisa comparou a documentação atual do GitHub, um estudo acadêmico sobre o conteúdo de READMEs e discussões públicas recentes de desenvolvedores brasileiros. O checklist é uma síntese editorial. Não é resultado de uma entrevista real, de um processo seletivo medido ou de um benchmark de portfólios.

A assistência de IA apoiou descoberta de fontes, organização, redação inicial, localização, criação da ilustração SVG e revisão de consistência. Ela não avaliou candidatos, não executou um projeto de portfólio de outra pessoa e não forneceu experiência profissional que o autor não tenha demonstrado.

Fontes consultadas