Abra seu repositório e procure a parte que outra pessoa consegue verificar sem falar com você. Se ela encontra apenas uma tela bonita, alguns prompts e um botão de deploy, o projeto mostra que você montou uma demonstração. Ainda não mostra que sabe fazer engenharia de software com IA.

Em 2025, 46% dos desenvolvedores disseram desconfiar da precisão das ferramentas de IA, enquanto 33% disseram confiar, segundo a Pesquisa de desenvolvedores 2025: IA, da Stack Overflow. Um portfólio precisa responder a essa desconfiança com evidência, não com uma lista de modelos usados.

Este checklist transforma um projeto assistido por Claude Code, Codex ou outro agente em um caso técnico que um revisor consegue ler, executar e questionar. Você não precisa esconder o uso de IA. Precisa deixar claro onde o sistema, os testes e o seu julgamento entram.

Decisão rápida

  • Escolha um problema que revele decisões de engenharia, não apenas uma chamada para um modelo.
  • Mostre arquitetura, limites, testes, falhas e operação no mesmo repositório.
  • Explique o que foi gerado, o que foi revisado e o que ainda não foi provado.
  • Faça a pessoa avaliadora conseguir formar uma opinião sem abrir seu histórico de conversa.

O que um portfólio de software engineer com IA precisa provar?

Um portfólio de software engineer com IA é um conjunto público de projetos que torna visível como você decide, implementa e verifica software com ferramentas de IA. Um portfólio forte conduz uma mudança do problema até uma decisão verificável. A demonstração pode usar um agente, mas a qualidade aparece no contrato, nas fronteiras do sistema, nos casos de falha e na forma como você mede o resultado.

O projeto não precisa ser grande. Precisa conter uma pergunta que não se resolve copiando um tutorial. Um agente que lê uma codebase, chama ferramentas, recupera contexto, grava estado ou abre um PR revela muito mais sobre sua prática do que um chat sem consequências.

Para cada projeto, escreva uma frase de prova: "Depois de ler este repositório, uma pessoa deverá concluir que eu sei fazer X com Y e consigo verificar Z". Se você não consegue terminar a frase, o escopo ainda está amplo demais.

O post sobre habilidades de engenharia de software para coding agents explica as competências por trás dessa prova. Aqui, o foco é o que deixar visível para que outra pessoa possa avaliá-las.

Cápsula citável: Um portfólio de software engineer com IA deve provar mais que geração de código. O projeto precisa tornar visíveis o problema, o desenho do sistema, os limites da automação, a verificação do resultado e as falhas conhecidas. O agente é parte do processo, não a evidência inteira.

Qual problema merece entrar no portfólio?

O melhor projeto de portfólio tem uma tensão técnica fácil de explicar: contexto incompleto, estado entre etapas, ferramenta com permissão, saída que precisa de avaliação ou mudança que pode quebrar uma regra do produto. Esse tipo de problema permite mostrar escolhas e consequências.

Uma aplicação que apenas envia uma pergunta para um modelo pode ser útil para aprender. Ela é fraca como prova profissional se não tiver um motivo para existir além da resposta gerada. A pergunta que vale publicar é: o que poderia dar errado, e como o sistema saberia?

Escolha um recorte que caiba no repositório e dê para demonstrar. Um agente de revisão de código pode receber um diff, consultar regras do projeto, apontar riscos e produzir uma decisão revisável. Um agente de suporte pode recuperar dados com permissão, registrar a fonte e recusar uma resposta quando não encontra evidência.

Evite transformar a pauta em uma coleção de tecnologias. MCP, RAG, filas e orquestração são meios. O projeto precisa explicar qual fronteira cada um protege. Quando a ferramenta deixa de ser necessária, registre essa decisão também. Saber não usar um componente é parte do trabalho.

Um bom sinal: o README começa pelo problema e pelo critério de sucesso. A stack aparece depois. Quem lê entende o que você decidiu antes de descobrir qual biblioteca foi instalada.

Que evidências devem aparecer no repositório?

Um projeto assistido por IA fica mais convincente quando o repositório contém evidências de intenção, construção e verificação. A pessoa avaliadora não precisa confiar na sua descrição. Ela consegue seguir links, executar um comando, ler um teste e encontrar o risco que você decidiu não esconder.

Diagrama mostra README, arquitetura, teste e risco chegando a uma revisão de engenharia.

Use esta matriz como revisão antes de publicar:

Evidência O que ela precisa responder Sinal que fica visível
Problema Quem precisa disso e qual comportamento deve mudar? Issue ou README com escopo e fora de escopo
Arquitetura Onde ficam estado, modelo, ferramentas e permissões? Diagrama curto e decisão registrada
Implementação Qual parte é determinística e qual depende do modelo? Código separado por fronteiras claras
Verificação Como você sabe que a saída está correta? Teste, eval, fixture ou comando reproduzível
Operação O que acontece com timeout, custo, erro e dados sensíveis? Logs, limites, alerta ou seção de operação
Limites O que o projeto ainda não garante? Risco residual escrito sem maquiagem

Esse conjunto é mais útil que uma pasta cheia de capturas de tela. A imagem ajuda a encontrar o projeto. O README e os artefatos ajudam a formar uma opinião sobre ele.

No caso de coding agents, inclua o diff de uma tarefa real ou uma amostra pequena que mostre como o agente recebeu contexto. Não publique segredos, dados pessoais ou logs que revelem credenciais. O que interessa é a fronteira do trabalho e a prova de que ela foi conferida.

Imagine um agente que revisa um pull request. O projeto fica mais avaliável quando o fluxo deixa de ser "o modelo comentou o diff" e passa a ser um registro que liga entrada, regras, verificações e decisão:

{
  "input": "diff do pull request",
  "checks": ["testes", "permissões", "regra de negócio"],
  "decision": "needs-review",
  "evidence": ["log sanitizado", "resultado da verificação"],
  "residualRisk": "não testado sob carga real"
}

Uma eval é uma avaliação repetível que compara a saída do agente com um critério definido antes da execução. Ela pode ser pequena, desde que o repositório mostre entradas, expectativa, resultado e limite. O guia de criação de evals da OpenAI ajuda a separar uma demonstração manual de uma verificação que pode voltar a ser executada.

O artigo sobre evals de PR para agentes de código no CI mostra uma forma de ligar a verificação ao fluxo de integração. Você pode adaptar a ideia para um projeto pessoal sem montar uma plataforma inteira.

Como mostrar que a IA não escondeu seu raciocínio?

Declare o uso do agente como parte do método. Diga qual tarefa ele executou, quais restrições recebeu e quais partes você revisou manualmente. Isso é mais honesto e mais útil que afirmar que o código foi escrito "do zero" quando o próprio repositório mostra um fluxo assistido.

Uma seção curta de autoria pode usar esta estrutura:

## Uso de agentes

- O agente investigou a codebase e sugeriu o plano inicial.
- Eu defini o contrato, revisei as mudanças e alterei o escopo.
- Os testes e evals foram executados fora da conversa do agente.
- As decisões sobre permissões, falhas e dados sensíveis foram manuais.
- O que ainda não foi provado: comportamento sob carga real.

O valor não está em separar cada linha escrita por pessoa ou modelo. Está em separar sugestão, execução e verificação. Um revisor quer saber se você entende o que o sistema faz e se consegue encontrar uma resposta plausível que esteja errada.

Em sessões longas de Claude Code e Codex, o RemoteCode ajuda a continuar fluxos agentic com menos repetição de contexto. É uma ferramenta do próprio autor, citada aqui porque o orçamento de contexto faz parte do método. Ela não substitui revisão, testes ou responsabilidade pelo resultado.

Quando o agente abriu um PR, preserve o que importa para a leitura: o pedido original, o plano aceito, o diff final, a verificação executada e a decisão sobre riscos. Não precisa publicar uma transcrição inteira. Um resumo fiel é melhor que um histórico impossível de revisar.

Cápsula citável: Declarar o uso de IA fortalece um portfólio quando o projeto separa sugestão, execução e verificação. O candidato mostra o que delegou ao agente, o que decidiu por conta própria, quais testes executou e quais limites permanecem. Transparência transforma autoria compartilhada em evidência revisável.

O que um README precisa conter para sobreviver à primeira leitura?

Um README bom reduz o trabalho de quem avalia. Ele começa com o problema, mostra a arquitetura em uma imagem ou diagrama simples, oferece um caminho de execução e aponta para a prova mais importante. Não deve pedir que a pessoa adivinhe qual parte do repositório vale sua atenção.

Uma estrutura curta costuma bastar:

# Nome do projeto

## Problema
O que acontece hoje e qual comportamento este projeto muda.

## Decisão
Quais limites guiaram a arquitetura e o que ficou fora.

## Fluxo
Como entrada, agente, ferramentas, estado e verificação se conectam.

## Executar
Pré-requisitos, variáveis sem segredo e comandos reproduzíveis.

## Prova
Testes, evals, fixtures, exemplos de falha e resultado observado.

## Operação
Timeouts, retries, permissões, custos e observabilidade.

## Limites
O que ainda depende de revisão ou de dados que não estão no repositório.

Não use uma seção de resultados para insinuar precisão que você não mediu. Se não há conjunto de avaliação, diga que há testes direcionados. Se o deploy é apenas local, escreva isso. Uma limitação clara aumenta a confiança na parte que está demonstrada.

O README de perfil do GitHub pode apresentar sua direção profissional, mas ele não substitui o README de cada projeto. O GitHub também permite fixar itens no perfil. Use o perfil para apontar o caminho e o repositório para mostrar a prova.

Quais sinais enfraquecem um portfólio com IA?

O primeiro sinal fraco é uma galeria de demos sem contrato. O leitor vê que algo respondeu, mas não descobre qual entrada era válida, qual saída era esperada ou como você detectaria uma regressão.

O segundo é uma lista de ferramentas que ocupa mais espaço que as decisões. Nomear modelos, bibliotecas e provedores não mostra que você sabe escolher entre eles. Explique uma troca concreta: contexto maior ou busca sob demanda, retry ou intervenção humana, autonomia ou permissão estreita.

O terceiro é esconder a operação. Um agente que parece correto em uma gravação pode falhar quando o token expira, a ferramenta demora, a resposta vem vazia ou o worker reinicia. O post sobre observabilidade de agentes de código no CI mostra quais sinais tornam esse tipo de falha investigável.

O quarto é publicar código gerado sem revisar as fronteiras. Um repositório grande não é automaticamente um repositório forte. Retire abstrações que não têm motivo, mantenha o fluxo legível e mostre o teste que derrubaria a hipótese principal.

Se você usa um agente para gerar o portfólio, aplique a mesma régua ao próprio site. Texto genérico, números sem fonte e promessas vagas também são falhas de engenharia editorial.

Como revisar o projeto antes de apresentá-lo?

Faça uma revisão que simule a pessoa avaliadora. Comece em uma janela limpa, sem a memória da construção. Abra o README, siga o caminho de execução e tente responder qual problema foi resolvido antes de olhar para a implementação.

Depois, percorra estas perguntas:

  • O projeto tem um usuário, uma entrada e um resultado que podem ser descritos sem jargão?
  • O diagrama mostra quem controla estado, permissão e efeito externo?
  • Existe uma prova que poderia falhar, e ela realmente falha quando você quebra a regra?
  • O código diferencia erro do modelo, erro da ferramenta e erro do produto?
  • A execução pode ser repetida sem duplicar um efeito ou apagar o contexto?
  • O README informa o que não foi medido, implantado ou verificado?
  • Outra pessoa consegue executar o exemplo sem credenciais secretas?

Se uma resposta depender de "confie em mim", transforme-a em artefato. Pode ser um teste, um log sanitizado, um diagrama, uma issue fechada ou uma decisão arquitetural. O objetivo não é criar documentação para preencher espaço. É remover dúvidas que impediriam uma avaliação justa.

Para problemas maiores, use o context engineering para agentes de código sem desperdício como referência de organização. Um contexto pequeno e bem escolhido também deixa sua explicação mais fácil de ler.

Checklist final: problema delimitado, arquitetura legível, código executável, teste que pode falhar, operação descrita, uso de IA declarado e risco residual visível.

Perguntas frequentes sobre portfólio de software engineer com IA

Um projeto simples demais pode entrar no portfólio?

Pode, se revelar uma decisão que você consegue explicar e verificar. Um projeto pequeno com ferramenta validada, permissão limitada, teste de falha e README claro pode provar mais que um sistema enorme sem critério de sucesso. O tamanho importa menos que a qualidade da evidência e a honestidade sobre o que ainda falta.

Preciso publicar todo o código gerado pelo agente?

Não. Publique o código necessário para executar e revisar a ideia, remova segredos e explique o que foi omitido. O ponto é mostrar uma implementação que você entende e consegue sustentar. Uma transcrição completa da conversa raramente ajuda; contrato, diff, testes e decisões são artefatos mais úteis.

Como mostrar experiência com Claude Code ou Codex sem transformar o texto em propaganda?

Descreva o agente como parte do fluxo, não como o resultado. Explique onde ele investigou, gerou uma proposta ou executou uma tarefa, e mostre quais verificações ficaram fora dele. A prova vem do repositório, dos testes e das decisões. O nome da ferramenta é contexto, não argumento suficiente.

Devo colocar métricas no README?

Sim, quando você mediu a métrica com um método que outra pessoa consegue entender. Informe conjunto de teste, período, ambiente e limite da comparação. Se não mediu, escreva uma observação qualitativa. Um número sem método pode parecer preciso e enfraquecer o restante do projeto.

Um portfólio precisa mostrar produção real?

Não necessariamente. Um deploy local ou ambiente de demonstração pode ser suficiente quando o projeto explica o caminho de execução e os limites. Produção real ajuda a mostrar operação, mas não deve ser inventada. Você pode demonstrar preparo operacional com falhas simuladas, logs sanitizados, limites e um plano de observabilidade.

Fontes consultadas