Uma demo pode provar que um projeto responde. Ela não prova, sozinha, que a pessoa entendeu o problema, escolheu uma fronteira razoável ou conferiu o comportamento quando algo dá errado. Para avaliar um portfólio de software engineer, siga o caminho entre a afirmação do projeto e a evidência que outra pessoa consegue inspecionar.

O roteiro mais útil tem quatro passagens: problema, decisões, verificação e limites. Depois, faça perguntas sobre autoria e próximos passos. Esse processo transforma um repositório em uma conversa técnica. Ele não cria uma nota universal para contratar alguém e não substitui uma entrevista estruturada.

O guia sobre o que um portfólio de software engineer com IA deve provar olha o mesmo assunto pelo lado de quem publica o projeto. Aqui, a pergunta é diferente: o que um revisor consegue confirmar sem adivinhar?

Diagrama mostra um revisor seguindo problema, decisões, verificação e limites em um portfólio de software.

Resposta curta

  • Comece pelo problema que o projeto afirma resolver, não pela quantidade de tecnologias.
  • Procure decisões visíveis e uma contribuição que a pessoa consiga explicar.
  • Verifique se há um caminho reproduzível para conferir comportamento, falhas e dados.
  • Leia os limites como evidência de julgamento, não como defeito automático.
  • Use o resultado para escolher perguntas melhores, não para inferir toda a capacidade profissional.

1. O projeto deixa claro qual problema resolve?

Leia o README antes de abrir o código. Em poucas linhas, você deveria descobrir quem enfrenta o problema, qual comportamento muda e o que ficou fora do escopo. Se a primeira tela é uma lista de frameworks ou um vídeo sem contexto, a revisão já começa com uma lacuna.

Um bom problema de portfólio não precisa ser empresarial nem ter usuários reais. Ele precisa ser específico o bastante para que você possa perguntar o que conta como sucesso. "Construí um chatbot" é uma descrição de tecnologia. "Organizei documentos de uma equipe e recuso uma resposta quando não encontro uma fonte" já aponta para entrada, comportamento e limite.

Não transforme isso em uma exigência de produção. Um projeto pessoal pode usar dados pequenos, executar só localmente ou ter uma interface simples. A pergunta é se a pessoa explica o recorte e as consequências dele. O guia de habilidades de engenharia de software para coding agents ajuda a separar tecnologia usada de competência que o projeto tenta demonstrar.

Procure também a frase que define o que não será resolvido. Fora de escopo não é burocracia. É uma forma de verificar se o autor consegue reduzir uma ideia grande a um problema que pode ser construído e conferido.

2. Onde aparecem as decisões de engenharia?

Depois de entender o problema, procure as escolhas que poderiam ter sido diferentes. Por que existe uma fila? Por que o estado fica no banco? Por que uma permissão é negada? Por que a aplicação retorna uma resposta parcial em vez de tentar novamente?

Uma lista de ferramentas não responde a essas perguntas. Procure um pequeno registro de decisão, um diagrama, um commit explicativo ou uma seção do README que conecte a escolha ao risco. O objetivo não é exigir uma arquitetura grande. É descobrir se a pessoa sabe explicar o preço de uma escolha.

Uma revisão útil pode seguir esta tabela:

Pergunta do revisor Evidência que vale procurar Pergunta de continuação
Qual era o risco principal? problema, restrições e fora de escopo O que aconteceria se essa premissa falhasse?
Qual decisão protege esse risco? contrato, fronteira, diagrama ou teste Que alternativa você descartou?
Quem controla os efeitos? permissões, dados, escrita e integrações O que ainda depende de uma pessoa?
Como a mudança é verificada? teste, fixture, eval, log ou comando Qual caso pode fazer a prova falhar?
O que continua desconhecido? limites, trabalho futuro e risco residual Como você reduziria essa incerteza?

Não dê mais peso a uma decisão por usar uma ferramenta conhecida. Um projeto pequeno com uma fronteira bem explicada pode mostrar mais maturidade que uma arquitetura cheia de componentes que o autor não consegue defender.

3. A prova é executável ou apenas descritiva?

Procure um caminho curto para verificar o projeto. Pode ser um comando de instalação, uma fixture, um teste, uma captura de tela ou um exemplo de entrada e saída. O formato depende do projeto. O requisito é que a afirmação principal tenha uma forma de ser confrontada.

Em projetos com modelos, não confunda uma resposta bonita com uma avaliação. A documentação de evals da OpenAI representa uma avaliação com dados de entrada, critérios de teste e resultados. Você pode aplicar a mesma pergunta a um portfólio sem usar a API da OpenAI: qual entrada foi escolhida, qual comportamento era esperado e onde a pessoa registrou o resultado?

Uma prova boa também mostra quando falha. Procure entradas vazias, permissões ausentes, timeouts, duplicatas, respostas inválidas ou um caso que o projeto reconhece como não resolvido. Não é necessário construir uma suíte completa para um projeto pessoal. É necessário evitar que o único caminho seja "abra o link e confie".

Para um projeto que usa coding agents, o eval de pull request no CI é um exemplo de como transformar a evidência de revisão em uma etapa repetível. A ideia pode ser menor no portfólio, desde que a entrada, o critério e o resultado estejam visíveis.

Se o repositório exige uma conta que não está disponível, um serviço pago ou uma configuração que ninguém consegue repetir, registre isso como limite da evidência. Não conclua automaticamente que o projeto não funciona. Apenas reduza o que você afirma ter verificado.

4. Como avaliar um projeto feito com IA?

Em um projeto assistido por IA, a pergunta não é se a pessoa usou um modelo. Pergunte onde ela manteve responsabilidade: definição do problema, seleção do contexto, revisão do diff, testes, integração e decisão sobre riscos.

O artigo de pesquisa When AI Can Build It, What Should We Assess? propõe separar evidências de produto, processo e origem, verificação, explicação, reflexão e garantia individual em uma formação de engenharia permissiva a IA. Isso não é uma rubrica universal de contratação. É uma lente útil para evitar que o produto final seja tratado como a única prova.

Peça que a pessoa escolha uma mudança pequena e explique o caminho. Ela deve conseguir dizer:

  • qual pedido recebeu e qual parte delimitou;
  • que contexto ou fonte ofereceu ao agente;
  • que sugestão rejeitou ou alterou;
  • qual teste ou inspeção executou depois;
  • que risco permanece sem prova.

Você não precisa pedir uma transcrição da conversa com o agente. Um histórico completo pode esconder a decisão importante em muito texto. Um resumo fiel, um diff, um teste e uma explicação curta são mais úteis. Se o projeto usa Claude Code, Codex ou outra ferramenta em sessões longas, o autor pode usar o RemoteCode como ferramenta de trabalho. Essa menção descreve o método do autor, não serve como prova de qualidade do projeto.

Evite o teste injusto de pedir que a pessoa recrie o repositório inteiro ao vivo. Se ainda existe uma dúvida, escolha uma parte do projeto e peça uma alteração limitada ou uma análise de falha. O objetivo é observar entendimento, não cobrar trabalho gratuito.

5. O que os limites dizem sobre o projeto?

Leia a seção de limitações antes de formar uma opinião. Um autor que escreve "não medi carga real" está fazendo uma afirmação mais confiável que alguém que descreve o projeto como pronto para produção sem explicar observabilidade, dados ou recuperação.

Separe três coisas que costumam se misturar:

  1. Não implementado: o projeto ainda não faz algo.
  2. Não verificado: o projeto faz algo, mas a evidência disponível não o cobre.
  3. Fora do objetivo: o projeto não pretende resolver aquele problema.

Essa separação permite perguntas melhores. Para uma API pessoal, talvez você não precise exigir tráfego real. Para uma aplicação que promete evitar perda de dados, precisa saber qual cenário foi testado e qual ainda é apenas uma intenção. A avaliação deve respeitar o problema que o projeto escolheu.

Verifique também a titularidade dos materiais. Código de tutorial, fork, trabalho em grupo, dados privados e ajuda de IA podem aparecer em um portfólio. O problema não é usar uma base existente. O problema é deixar o revisor atribuir ao autor uma contribuição que o repositório não demonstra. O README deve distinguir contribuição, dependências e partes adaptadas.

6. Como transformar a leitura em uma conversa justa?

Não some pontos como se o portfólio fosse uma prova padronizada. Registre quatro observações: o que ficou claro, o que a evidência sustenta, o que ainda está aberto e qual pergunta pode reduzir a dúvida. Isso evita premiar design, tamanho de repositório ou quantidade de commits sem entender o trabalho.

Uma conversa pode começar assim:

  • "Qual parte deste projeto você mudaria se a entrada dobrasse?"
  • "Mostre um caso em que a verificação falha ou não é suficiente."
  • "Qual decisão foi mais difícil de revisar depois da primeira implementação?"
  • "O que você delegou e que parte precisou reescrever?"
  • "Que afirmação sobre o projeto você não faria ainda?"

As perguntas devem ser proporcionais ao projeto. Um portfólio de iniciante não precisa ter a mesma operação de um serviço comercial. Por outro lado, alguém que afirma ter construído um sistema resiliente precisa explicar recuperação, observabilidade e limites da prova.

Se a revisão for parte de uma seleção, combine antes o que será observado e quanto tempo a pessoa terá. Não transforme o checklist em uma tarefa escondida. Se for uma revisão entre colegas, devolva perguntas e evidências, não apenas uma impressão sobre a pessoa.

Checklist final para revisar um portfólio

Antes de encerrar, confirme se você consegue completar cada linha sem inventar a resposta:

Área Você consegue apontar...
Problema a necessidade, o usuário ou operador e o limite do projeto?
Contribuição o que a pessoa fez, adaptou, delegou ou apenas reutilizou?
Decisões uma escolha técnica ligada a um risco ou requisito?
Verificação um comando, teste, eval ou exemplo que pode falhar?
Operação como o projeto trata erro, dados sensíveis, acesso ou recuperação?
Limites o que ainda não foi implementado ou provado?
Conversa uma pergunta concreta que reduz uma incerteza?

Se várias células ficarem vazias, não preencha o espaço com suposições. Diga qual evidência faltou e peça uma explicação curta. O valor do checklist está em tornar a incerteza visível.

Conclusão

Avaliar um portfólio de software engineer é seguir a distância entre o que o projeto afirma e o que ele permite verificar. Comece pelo problema. Procure decisões ligadas a riscos. Execute ou leia uma prova. Depois pergunte sobre autoria, limites e próximos passos.

Esse método não transforma um repositório em um veredito sobre uma carreira. Ele melhora a conversa e reduz dois erros comuns: confundir uma demo polida com engenharia e descartar um projeto simples porque ele não parece um produto completo. A melhor revisão termina com uma afirmação precisa sobre o que ficou demonstrado e uma pergunta honesta sobre o que ainda não ficou.

Como este artigo foi produzido

Samuel Fajreldines é o responsável editorial por este artigo. A pesquisa comparou o cluster existente do site, resultados atuais em português, inglês e espanhol, discussões públicas recentes, documentação do GitHub e da OpenAI e uma pesquisa acadêmica sobre avaliação de engenharia em contextos permissivos a IA. O checklist é síntese editorial. Não é resultado de um estudo de contratação, benchmark de candidatos, entrevista real ou avaliação de empregadores.

A assistência de IA ajudou na descoberta de fontes, comparaçã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 testou os portfólios de pessoas reais e não forneceu experiência profissional que o autor não tenha demonstrado.

Fontes consultadas