Usar IA para melhorar seu portfólio técnico sem inventar resultados

Contexto e motivacao

Por que usar IA no portfólio

IA pode acelerar a produção de textos claros, organizados e focados em impacto. Para desenvolvedores com 1-3 anos de experiência, o desafio não é apenas ter projetos, mas comunicá-los com precisão, destaque e sem exageros. Ferramentas de IA ajudam a transformar notas técnicas, issues e commits em descrições legíveis e compactas.

O risco: inventar resultados

Modelos de linguagem tendem a preencher lacunas quando recebem informações incompletas. Isso cria o risco de colocar métricas, funcionalidades ou resultados que não aconteceram. Em entrevistas, inventar é fatal — você perde credibilidade. O objetivo é usar IA para clarear, estruturar e traduzir evidências existentes, não para derivar fatos novos.

Uma mentalidade correta: IA é assistente de redação e organização; a responsabilidade pela veracidade é sua. Se você automatizar a geração de descrição de projetos, coloque validações automáticas que chequem provas concretas (commits, PRs, issues, testes, logs).

Este artigo guia em como usar IA para melhorar seu portfólio mantendo integridade. Aborda arquitetura simples, scripts práticos e patterns de verificação, além de armadilhas comuns e como evitá-las.

Como funciona por baixo dos panos

Modelos e tendência a confabular

Modelos de linguagem não “sabem” fatos; eles preveem tokens. Quando dados incompletos são fornecidos, o comportamento padrão é preencher com plausibilidades. Isso explica por que podem inventar números, integrar recursos inexistentes ou descrever impacto que você não mediu.

Fontes verificáveis e cadeias de provas

Evite confiar apenas na geração de texto. Utilize cadeias de evidência: commits, PRs, issues, testes, métricas de CI/CD, capturas de tela e pequenos benchmarks. A arquitetura que proponho alimenta a IA com metadados estruturados e anexa essas evidências às descrições geradas.

Fluxo típico: coletar metadados locais → extrair provas (hash de commit, número de PR, cobertura de teste) → gerar texto via IA com instruções estritas e template → validar saída comparando com metadados.

Implementacao passo a passo

1) Estruture seu repositório para extração

Crie um arquivo manifest.json por projeto com campos obrigatórios: descricao_base, commit_hash, pr_links, testes_passaram, metrics_raw (opcional). Isso garante que a IA sempre receba uma fonte primária antes de reescrever.

Exemplo de manifest (contexto): arquivo que descreve os fatos mínimos do projeto. Serve como entrada canônica para o processo de geração.

{
  "name": "api-rate-limiter",
  "descricao_base": "Implementa rate limiter usando token bucket para a API interna",
  "commit_hash": "a1b2c3d4",
  "pr_links": ["https://github.com/me/repo/pull/42"],
  "testes_passaram": true,
  "metrics_raw": {
    "p95_latency_ms": 12.4,
    "throughput_rps": 1200
  }
}

O que acontece: este manifest é lido por scripts que geram um prompt restrito para a IA. Se metrics_raw estiver vazio, o prompt deve instruir explicitamente: “não inventar métricas nem porcentagens”.

2) Script Node.js que pede reescrita responsável

Contexto: script que envia prompt para um modelo (OpenAI ou compatível) pedindo uma versão polida da descricao_base, incluindo apenas métricas presentes no manifest. Também injeta provas (commit e PR).

/* reescrever.js
   O que faz: lê manifest.json e chama a API de IA para gerar um README curto e preciso. */

const fs = require('fs');
const fetch = require('node-fetch');

async function run() {
  const manifest = JSON.parse(fs.readFileSync('manifest.json', 'utf8'));
  const prompt = `Reescreva a descricao do projeto com tom profissional. Use somente informacao presente no manifest. Nao invente metricas ou resultados.\n\nMANIFEST:\n${JSON.stringify(manifest, null, 2)}`;

  const res = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 400
    })
  });

  const json = await res.json();
  const text = json.choices?.[0]?.message?.content || '';
  fs.writeFileSync('DESCRIPTION.md', text);
  console.log('Generated DESCRIPTION.md');
}

run().catch(err => { console.error(err); process.exit(1); });

O que acontece: o script grava um DESCRIPTION.md polido. Se a IA tentar adicionar métricas não presentes, a validação subsequente detectará divergência (veja etapa 3).

3) Validacao automatica

Contexto: script Python que valida a saída gerada comparando menções com manifest.json e verificando PRs/commits quando necessário.

#!/usr/bin/env python3
# validate_description.py
# O que faz: garante que DESCRIPTION.md nao contenha metricas nao presentes no manifest

import json, re, sys

manifest = json.load(open('manifest.json'))
desc = open('DESCRIPTION.md').read()

# regra simples: qualquer numero seguido de % ou ms ou rps deve existir em manifest.metrics_raw
numbers = re.findall(r"(\d+(?:\.\d+)?)\s*(%|ms|rps)", desc)

allowed = set()
metrics = manifest.get('metrics_raw', {})
for k,v in metrics.items():
    allowed.add(str(v))

for num, unit in numbers:
    if num not in allowed:
        print('Validation error: metric', num+unit, 'not in manifest')
        sys.exit(2)

print('Validation passed')

O que acontece: se DESCRIPTION.md inclui um número que não está em metrics_raw, o script falha. Integre isso no CI para impedir deploy do portfólio com informações não verificadas.

Patterns e boas praticas

Pattern: entrada canônica + IA como formatador

Defina um manifesto com campos obrigatórios. A IA deve ser tratada como “formatador” que transforma fatos em narrativa. Não deixe a IA decidir fatos — ela só recebe fatos confirmados pelo manifest.

Pattern: validação em várias camadas

Implemente checks: validação textual (regex), validação contra artefatos (commits, PRs) e validação humana (revisão em PR). Automação sozinha não resolve todas as ambigüidades, mas reduz erros e trabalho repetitivo.

Use ferramentas que você já domina (git, CI) para prover provas: hashes de commits, links de PR, resultados de testes e logs. Nunca permita que a IA substitua ou supere esses sinais.

A seguir, boas práticas específicas de texto e entrevista.

Boas práticas para descrições

• Comece com um problema, explique sua solução e conclua com evidência (link de PR, número de testes, hash de benchmark).
• Se usar métricas, anexe a fonte (arquivo de benchmark, script de carga, link para run no CI).
• Prefira precisão a brilho: é melhor dizer “reduziu latência média de 30ms para 20ms (benchmark anexado)” do que inventar uma redução maior.

Dica: trate cada métrica como um ativo — registre como foi medida e onde estão os dados. Isso evita questionamentos em entrevistas.

Armadilhas comuns e como evitar

Armadilha: prompts soltos que geram confabulação

Prompts genéricos como "melhore este texto" sem anexar metadados abrem margem para preenchimento. Sempre inclua o manifest e instruções explícitas: "NÃO invente métricas", "cite apenas links presentes" e "retorne apenas texto final".

Armadilha: confiar apenas na IA para traduzir contextos técnicos

Há termos técnicos que a IA pode reescrever incorretamente, distorcendo responsabilidades (por exemplo, atribuir arquitetura a você quando foi trabalho em equipe). Inclua campos de contribuição no manifest (lista de tarefas que você implementou) para evitar atribuições erradas.

Exemplo de manifest estendido com contribuições (contexto): descreve o que você fez para evitar atribuição indevida.

{
  "name": "api-rate-limiter",
  "descricao_base": "Implementa rate limiter usando token bucket para a API interna",
  "contribuicoes": [
    "design do algoritmo token-bucket",
    "implementacao do middleware em Node.js",
    "criacao do benchmark de carga"
  ],
  "commit_hash": "a1b2c3d4",
  "pr_links": ["https://github.com/me/repo/pull/42"],
  "testes_passaram": true
}

O que acontece: a IA tem campos explícitos que identificam suas contribuições, reduzindo a chance de atribuir trabalho alheio a você.

Armadilha: métricas sem contexto

Métricas isoladas ("reduziu 50%") são suspeitas. Sempre entregue contexto de como foi medido: carga, ambiente, dataset. Se não tiver isso, não apresente número algum; prefira declarações qualitativas comprovadas por artefatos.

Checklist rápido para cada métrica incluída:

• Origem: onde foi medida (arquivo, script, CI job)
• Ambiente: hardware, dataset e condições
• Data: quando o teste foi executado
• Link: referência para logs ou PR

Conclusao pratica

IA é útil para polir e formar narrativas, mas não é fonte de verdade. Organize seus projetos com um manifest canônico, trate a IA como formatador e coloque validações automatizadas contra commits, PRs e testes. Integre checagens no CI para bloquear deploys com informação não verificável.

Implemente os scripts demonstrados e adote o pattern de entrada-verificação-saida: manifest → IA → validação. Isso reduz o trabalho manual, aumenta a qualidade das descrições e preserva sua credibilidade em entrevistas.

Em entrevistas, seja capaz de apontar a prova: mostre commits, números de teste e PRs. Se você seguir esse fluxo, a IA acelera o processo sem comprometer a verdade — e isso vale mais do que qualquer curva de crescimento fictícia em um portfólio.

Próximos passos práticos: crie manifest.json para seus três projetos mais relevantes, escreva o script de reescrita (reescrever.js) e a validação (validate_description.py), e adicione um job no CI que bloqueie builds se a validação falhar. Isso transforma IA em um multiplicador de produtividade com controles que preservam sua reputação.