DEV Community: Alberto Luiz Souza

Monte o seu próprio treinamento com um agente de código

Alberto Luiz Souza — Mon, 17 Aug 2026 14:55:28 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal Dev Eficiente, apresentado por Alberto Souza. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Neste post eu quero mostrar como você pode construir um treinamento sob medida para alcançar um objetivo de aprendizagem que você tenha, independente da complexidade, usando apenas a documentação ou uma referência que você entenda como fonte da verdade daquele conhecimento.

Os cenários de uso são muitos. Você quer entender melhor um módulo específico de um framework, como o Spring AI, para construir as suas aplicações. Quer se aprofundar em LangChain para montar sistemas que usam LLM como componente. Quer saber como usar Kafka em um ambiente de alta volumetria de mensagens e como lidar com perda ou não processamento de mensagem. Ou está começando no mundo de infraestrutura e quer ficar mais confortável configurando o seu ambiente via Docker. Para todos esses casos, o framework que vou apresentar serve, e você pode aplicar hoje mesmo, com o tema que quiser.

A execução é feita por um agente de código. No meu caso, uso o Claude Code, mas qualquer ferramenta com um loop mais autônomo funciona: eu dou a entrada, ele itera e monta o material. O que importa aqui é o framework, não a ferramenta.

O framework para criar o treinamento

Eu mantenho um arquivo que descreve o framework e sirvo esse arquivo como contexto para o agente. Ele tem algumas partes.

1. As referências que formam a fonte da verdade

Primeira parte: definir o conjunto de referências que representa a fonte da verdade do conhecimento que você quer conquistar. Quando o tema é uma tecnologia, a referência geralmente é a documentação oficial, ou um conjunto de links dela.

Mas o tema pode ser mais aberto. Se você quer entender como construir sistemas realmente resilientes, não existe uma entidade dona da explicação de como se faz isso. Nesse caso, você precisa fazer uma curadoria: montar uma referência bibliográfica que, por algum motivo, faz sentido para você. E aí o treinamento é construído em cima daquele objetivo e daquela bibliografia.

2. Inspiração para os exercícios

Segunda parte, opcional: um dataset com exemplos do nível que você quer alcançar. Imagine que você trabalha em um conjunto de serviços com queries SQL realmente complexas, e o seu conhecimento hoje não é suficiente para escrevê-las com confiança. Ou que o sistema onde você atua tem muita generalização e você quer ser capaz de construir componentes generalizáveis seguindo as práticas que já existem na empresa. Você pode fornecer ao agente um conjunto de repositórios com exemplos do que você quer ser capaz de fazer. Eu falei código, mas pode ser exemplo de qualquer coisa que represente o nível que você quer atingir.

Se você não tem esse dataset, está tudo bem. O agente deriva os exercícios a partir das fontes teóricas que você referenciou.

3. Progressão com variabilidade

A minha principal inspiração para criar treinamentos vem do esporte. Se você olhar o histórico de qualquer treino físico, sempre há progressão. Pense em treino de força: você quer agachar, tem uma progressão de carga ao longo do tempo, e dentro daquela progressão existem outros exercícios, muitas vezes auxiliares, para que você agache melhor.

Quando o assunto é conquistar um conhecimento para aplicá-lo, geralmente existe variabilidade de cenários de aplicação. Por isso é importante pensar na progressão e, dentro de cada estágio, pensar em variabilidade de exercícios: aplicar o mesmo conhecimento em situações diferentes treina a sua mente para reconhecer padrões e escolher o que precisa ser feito em cada momento.

Essa costuma ser a parte mais difícil para quem está mais distante da engenharia da aprendizagem: como pensar a progressão. Então isso faz parte do framework, e é a partir dela que os exercícios são construídos.

O meu número de variabilidade é três exercícios por estágio. Não é resultado de pesquisa; é totalmente empírico. A minha experiência diz que, se você fez a mesma coisa em três cenários diferentes, geralmente fica em condições de lidar com o quarto, o quinto e o sexto cenário, porque a cada repetição refina as heurísticas de qual caminho seguir em função do que aparece.

4. Leitura, tentativa e proposta de solução para cada exercício

Uma abordagem que eu acho interessante, dependendo do quão confortável você está com jornadas de estudo, é organizar tudo em torno dos exercícios. Para cada exercício, o treinamento traz os links das referências que você deveria ler para conseguir resolvê-lo. Você lê, volta e tenta fazer. Fica nesse pingue-pongue entre teoria e prática.

Se você prefere tentar antes de ler, também não tem problema, porque cada exercício vem com uma proposta de solução para você comparar o que fez com o que deveria ter sido feito. Isso é o feedback possível quando você não tem acesso a uma pessoa especialista, o que a gente chama de automonitoramento no processo de aprendizagem. Você fez, ficou diferente da solução, e aí pergunta por quê. Não necessariamente está errado. Em uma tecnologia bem específica como Docker, se você não fez de determinado jeito talvez nem funcione. Mas quando o assunto é design de código, existem variações válidas, e a ideia é que você compare e reflita. Ter múltiplos momentos de reflexão é o que faz o conhecimento entrar e ficar armazenado de um jeito que facilita a recuperação depois.

5. O objetivo de aprendizagem

Aqui está o elemento mais importante da jornada, e é a entrada principal do agente. Falo isso no Máquina de Aprender, o treinamento que temos dentro do Dev + Eficiente para você construir a sua jornada de aprendizagem de maneira autônoma. O objetivo de aprendizagem é o pino no mapa: é onde você quer chegar. Sem ele, você corre o risco de ficar estudando um monte de coisa aberta sem necessariamente chegar aonde queria.

Descreva o que você quer ser capaz de fazer, em que tipo de situação vai usar aquilo e, se souber com nitidez, qual é o seu ponto de parada.

A demonstração: um treinamento de Docker para ambiente de desenvolvimento

Para mostrar o framework funcionando, escolhi um tema em que eu mesmo não sou forte. Não sou a pessoa que monta infraestrutura com Docker; costumo seguir o que já está feito ou pedir para um LLM gerar o que preciso quando estou em uma empreitada solo. Então montei um treinamento chamado Docker Dev Essencial.

O objetivo de aprendizagem que dei como entrada foi algo assim: quero ser capaz de montar um ambiente de desenvolvimento onde tudo que tem a ver com infraestrutura roda em containers. Se precisa de banco de dados, é via Docker. Se precisa de broker de mensageria, é via Docker. Tudo isso deve ser acessível para as minhas aplicações. Para determinadas situações, como banco de dados, preciso de persistência dos dados entre as execuções. E, se possível, quero também estar capacitado para configurar isso de maneira otimizada, minimizando o tempo de espera enquanto subo tudo.

Como fontes teóricas, apenas a documentação oficial do Docker. Nada além disso. Se quero aprender estritamente sobre Docker, é lá que está a fonte mais confiável.

Rodei o agente pedindo para ler o arquivo do framework e o meu objetivo, e deixei ir direto, sem confirmações intermediárias a cada progressão. O resultado ficou assim:

Nível 1, fundamentos de container. Um README com o objetivo do nível (rodar serviços em containers com confiança, entender o que é imagem e container, dominar o ciclo de vida), os conceitos-chave (imagem, container, efemeridade), referências de leitura apontando para a documentação oficial (o que é um container, o que é uma imagem, o que é um registro, como rodar e como sobrescrever o padrão) e três exercícios: o seu primeiro serviço em um container, um Postgres descartável e "o que sobrevive?". Cada um com a sua proposta de solução: rodar em foreground, rodar em modo detached, listar, pegar log, testar se o serviço está no ar, verificar o ciclo de vida, limpar.
Nível 2, expondo serviços ao host. Mesmo esquema: objetivo do nível, conceitos-chave, referências e três exercícios. Como eu não dei um dataset de referência, o agente criou os cenários: abrir portas, um banco para uma API, um broker com painel, containers que conversam entre si.
Nível 3, persistência de dados. O objetivo do nível é resolver de vez o problema descoberto no nível 1: dados de banco precisam sobreviver à recriação de containers. Conceitos-chave: volumes nomeados, bind mount, volume anônimo. As referências de leitura levam direto para a página da documentação sobre persistência de dados, onde você pode ler a explicação ou assistir ao vídeo, como preferir.
Projeto final. Consolidar tudo em uma entrega única e realista: construir do zero, sem consultar os composes dos níveis anteriores, consultando a documentação oficial à vontade, como no mundo real, o ambiente de desenvolvimento completo de uma empresa fictícia. E uma frase que eu achei importante: este é o nível de atuação descrito no objetivo de aprendizagem do treinamento; se você completa o projeto com os critérios de aceite verdes, o objetivo foi atingido.

O marco que fecha a jornada

Essa última parte merece destaque. Você não quer fazer um conjunto de cursos; você quer conquistar um conhecimento. Estou pensando aqui no que costumo chamar de aprendizagem transacional, ou utilitária: você não está estudando só porque quer, está estudando porque tem um objetivo, que é ser capaz de fazer alguma coisa.

Então é importante que exista esse marco. Não necessariamente na forma de um projeto final, mas a sua jornada de estudo precisa te levar até o objetivo de aprendizagem. Tudo faz muito mais sentido quando você entende o porquê do esforço, e isso costuma ter um papel importante na sua motivação.

Sobre fontes: confiabilidade e facilidade de consumo

No treinamento de Docker eu deixei apenas fontes de confiabilidade máxima. Mas vale um comentário. Quando eu seleciono fontes de estudo, olho por duas dimensões: confiabilidade e facilidade de consumo. No início de uma jornada, quando você tem pouco background, textos mais densos e menos organizados para facilitar o entendimento pesam mais. Nesses casos, dá para misturar fontes mais palatáveis, mesmo que menos confiáveis, desde que a referência bibliográfica contenha as fontes mais confiáveis. Aqui, escolhi manter só a documentação.

E isso conecta com uma escolha nossa dentro do Dev + Eficiente: em geral, não construímos treinamentos ensinando algo que já está documentado. Um treinamento de Spring AI, no formato "como usar Spring AI", seria um desserviço para um público que quer ser crítico e ter autonomia para aprender o que precisa, porque a documentação já cumpre esse papel, escrita por quem construiu a ferramenta. Quando temos um treinamento envolvendo uma tecnologia, ele é sobre as práticas que consideramos interessantes com aquela tecnologia, que vão além do que está lá. É o caso do treinamento que lançamos sobre as nossas práticas usando um agente de código no dia a dia: é a minha história, o meu jeito de organizar, os cenários que eu uso, e nada disso está documentado porque tem a ver com a minha opinião. É por isso que dizemos que os nossos cursos são opinionados.

Conclusão

O framework é simples: defina o objetivo de aprendizagem, aponte as referências que formam a fonte da verdade, forneça exemplos do nível que você quer alcançar se tiver, e deixe o agente montar uma progressão com variabilidade de exercícios, cada um com as leituras necessárias e uma proposta de solução para comparar. Feche com um marco que corresponda ao objetivo. Depois é só executar, no formato e no ritmo que a sua vida permite.

Espero que você explore esse framework para criar o treinamento que quiser, dado o objetivo que você tem. E se quiser se aprofundar em como estruturar jornadas de aprendizagem de maneira autônoma, esse é o tema do Máquina de Aprender, disponível dentro do Dev + Eficiente.

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.

System design com IA aplicada: desenhando o suporte automatizado de um marketplace de comida

Alberto Luiz Souza — Mon, 10 Aug 2026 08:46:17 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de uma live do canal Dev Eficiente, com Alberto Souza e Daniel Romero. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Você pediu um hambúrguer sem queijo e o pedido chegou com queijo. Ou pediu dois e veio um. Ou a comida chegou fria. Você abre o chat de suporte do aplicativo e, em poucos segundos, recebe uma resposta que resolve o problema: reembolso, cupom ou reenvio do pedido. Como um sistema desses funciona por dentro?

Nesta live, desenhamos ao vivo a arquitetura de um sistema de automação de suporte ao cliente para um marketplace de comida, deliberadamente inspirado no iFood, como forma de estudo. Daniel Romero, que lidera a Especialização em Engenharia de IA do Dev + Eficiente, conduziu o desenho da arquitetura, e ao final mostramos a implementação funcionando, com o código aberto para quem quiser explorar.

Neste post você encontra o raciocínio completo por trás do design: os requisitos, cada etapa do fluxo, as decisões sobre onde usar LLM e onde usar código puro, a demonstração prática e uma seção dedicada às perguntas que a audiência fez durante a live.

Os requisitos do desafio

Todo exercício de system design começa pelos requisitos. Os funcionais que definimos:

Classificar a intenção do usuário entre 15 categorias predefinidas
Resolver automaticamente as 6 categorias mais comuns (reembolso, cupom, reenvio do pedido, entre outras), que chegam em grande volume
Para as demais categorias, escalar para um atendente humano com um resumo pronto da situação: o que já foi feito, qual a reclamação e o nível de urgência
Acessar os dados do pedido: status, localização, tempo estimado
Nunca prometer um reembolso acima de R$ 50,00 sem aprovação humana (valor hipotético, definido para o exercício)

E os não funcionais:

Primeira resposta rápida, inferior a 5 segundos
Meta de 40% das resoluções feitas de forma automática
Se o cliente pedir para falar com um humano, transferir imediatamente, sem insistir na interface de chat

O fluxo, etapa por etapa

Mensagem do usuário e verificação inicial

Tudo começa com a mensagem do cliente no chat. E ela pode ser qualquer coisa: um "boa noite", ou já uma reclamação direta como "veio com queijo e eu pedi sem". A primeira etapa é uma verificação que funciona como um loop de triagem: se for apenas uma saudação, uma camada leve responde rapidamente; se já for um pedido bem descrito, o fluxo segue adiante.

Busca no banco e construção do contexto

Com uma mensagem relevante em mãos, o sistema faz uma busca no banco de dados relacional (no projeto de exemplo, um Postgres) para recuperar pedido, restaurante e cliente. Com esses dados, ele monta um contexto em texto que fica disponível para as chamadas de LLM ao longo do fluxo inteiro. Se o pedido nem existir, a API responde direto e não abre o atendimento.

Primeiro guardrail: o cliente pediu um humano?

Antes de qualquer chamada de LLM, entra o primeiro guardrail: verificar se o cliente pediu explicitamente para falar com uma pessoa. Se pediu, o sistema transfere imediatamente para a fila de atendimento humano. Se não pediu, o fluxo continua.

O detalhe importante: esse guardrail é código puro, sem LLM. Não há inteligência artificial nessa verificação, e é proposital. Você não quer depender de um componente probabilístico para garantir uma regra de negócio crítica, ainda mais com um requisito de primeira resposta abaixo de 5 segundos.

Classificação com output estruturado

Passado o guardrail, um classificador identifica a intenção da mensagem entre as 15 categorias predefinidas. Aqui pode entrar um LLM ou um modelo baseado em Transformers treinado para a tarefa (falamos mais sobre essa escolha na seção de perguntas).

A saída dessa classificação é estruturada. No exemplo em Python, usamos a biblioteca Instructor com Pydantic: o modelo é forçado a preencher um esquema de dados com uma das categorias válidas. Se ele gerar algo que não se encaixa no esquema, a validação falha e ele tenta de novo até preencher corretamente. Isso elimina uma camada inteira de possíveis alucinações que virariam bugs difíceis de rastrear no restante do fluxo. Outra vantagem da biblioteca é abstrair o provider: a mesma interface de output estruturado funciona com OpenAI, Gemini, Claude e outros.

Router: literalmente um if

Com a categoria em mãos, um roteador decide o caminho. E aqui não há mistério: é um if em código. A categoria está entre as seis automatizáveis? Segue para a resolução automática. Não está? Escala para o atendimento humano.

Resolução automática: LLM com ferramentas

No caminho da resolução automática, entra um LLM com acesso a um conjunto de tools: consultar dados do pedido, verificar o tempo decorrido, abrir comunicação com a loja, acionar o reembolso automático, salvar o histórico da resolução no banco e encaminhar para o humano se necessário.

Esse LLM gera a ação de resolução e a mensagem de resposta ao cliente. Um exemplo: o classificador identificou um pedido de reembolso, o router confirmou que é automatizável, e o LLM consulta os dados, verifica as condições e aciona o reembolso com a mensagem apropriada.

Segundo guardrail: o limite de R$ 50,00

Antes de disparar um reembolso, entra o segundo guardrail: o valor é maior que R$ 50,00? De novo, código simples, sem LLM. Se o valor está abaixo do limite, o fluxo segue com o reembolso automático e a mensagem ao cliente. Se está acima, o guardrail tem o poder de desviar o fluxo e escalar para o humano.

Escalation: o resumo que chega pronto para a pessoa atendente

Quando o caso escala, seja pela categoria, seja pelo valor, um LLM de escalation entra em cena com um propósito diferente: gerar um resumo do caso para a fila de atendimento humano. Ele analisa todo o histórico e produz um texto com o que aconteceu, há quanto tempo o cliente espera, o senso de urgência e o contexto relevante para a decisão.

É aqui que o uso de LLM se justifica de verdade: extrair contexto textual de diversas fontes e sintetizar algo de valor para quem vai tomar a decisão final compensa muito mais do que tentar prever todos os cenários possíveis em templates predeterminados.

Isso é um agente? Não, e a distinção importa

Olhando de longe, um LLM dentro de uma interface de chat, com acesso a um monte de ferramentas, pode dar a impressão de ser um agente. Mas não é, e a distinção é central no design.

Todas as decisões de caminho do fluxo são determinísticas, amarradas a condicionais em código. O LLM nunca escolhe a próxima etapa: ele executa uma tarefa dentro da etapa em que foi chamado. Um agente, muitas vezes, tende ser a interpretado como algo mais autônomo: ele poderia escolher qual ferramenta chamar, quando chamar e inclusive escolher não chamar.

Uma boa referência de comparação são os assistentes de código, como Claude Code. Neles, o fluxo não é determinístico: você pede uma análise, o modelo escolhe um caminho; fecha a sessão, pede de novo, ele pode escolher outro. Quem determina o fluxo é o modelo. No nosso design, quem determina o fluxo é o código, e o LLM entra só onde ele é necessário. Não faz sentido ter LLM do início ao fim, em todas as fases, simplesmente porque não faz sentido: cada chamada adiciona latência, custo e variabilidade onde muitas vezes um if resolve.

Esse desenho segue os padrões de workflows descritos no artigo Building Effective Agents, da Anthropic, que é uma das bases do módulo de engenharia de agentes da Especialização.

A demonstração prática

Ao final da live, mostramos a arquitetura implementada como uma API em FastAPI, com Postgres e um seed de dados simulando restaurantes, clientes e pedidos com problemas. O código está aberto no GitHub, no repositório suporte-ai do perfil infoslack (o projeto final da Especialização também está público, no repositório finlab).

Quatro cenários demonstrados:

Item errado no pedido. O cliente relata que recebeu itens que não pediu. O fluxo classifica a intenção como wrong item, o router confirma que é automatizável e o sistema responde com o reenvio dos itens corretos.
Reembolso acima do limite. Pedido de reembolso completo de R$ 89,90 por qualidade ruim. O guardrail detecta o valor acima de R$ 50,00 e escala para o humano com um resumo que inclui um dado decisivo: o cliente tem 120 pedidos e apenas 4 reembolsos nos últimos 30 dias. Você não quer perder um cliente desses, e essa síntese de contexto é exatamente o que o atendente precisa para decidir.
Categoria não automatizável. Reclamação sobre o comportamento do entregador. O fluxo escala com resumo detalhado: valor do pedido, atraso na entrega, histórico do cliente e sugestão de ação.
Pedido explícito de atendimento humano. "Quero falar com o atendente humano agora." A resposta é um piscar de olhos: o primeiro guardrail intercepta, transfere direto para a fila e ainda gera o resumo do caso puxando informações do banco.

Em todos os cenários, a comunicação interna acontece como uma sequência de outputs estruturados: o output do classificador vira input do router, o output do router vira input da resolução, e assim por diante, até a resposta final.

As perguntas da live

A audiência mandou mais de 35 perguntas durante a live. Reunimos aqui as principais, com as respostas.

A verificação inicial deveria usar LLM ou SLM?

Depende do momento. Para validar a ideia ou um MVP rapidamente, um LLM resolve. Com um pouco mais de tempo, um Small Language Model dá mais performance. Mas, em produção, para essa tarefa específica de classificação binária (é saudação ou não?), provavelmente nenhum dos dois: um modelo como o ModernBERT, treinado para a tarefa, faz inferência em CPU com baixa latência. A diferença conceitual é que um LLM é treinado massivamente para gerar texto, enquanto o BERT é treinado para compreender e produzir um output extremamente limitado, o que é exatamente o que uma classificação precisa.

O BERT não seria mais lento e mais custoso que um LLM?

Não. Para treinar, depende do cluster de GPU. Para inferência, ele pode ser servido inteiramente em CPU e dá conta.

A abordagem é a mesma do RAG clássico, com conhecimento vetorizado?

Não. No desenho não há nem vector database: o sistema de retrieval vem de uma base relacional. E o LLM não monta a consulta SQL: existem funções predeterminadas para buscar as informações do cliente e da loja, e o modelo só preenche o parâmetro (o ID). São tools parametrizadas, altamente determinísticas.

E se a API do LLM cair ou estourar o timeout?

Para um negócio que precisa escalar e tem preocupação real com latência, a resposta é trazer a camada de LLM para dentro da própria infraestrutura, em vez de depender de um provider externo que pode adicionar latência ou ficar fora do ar. Se você roda na AWS, por exemplo, pode servir o modelo no Bedrock, com possibilidade de customização e fine-tuning. Pense no LLM como mais um componente, mais uma camada dentro do seu software. Quando o negócio não sustenta esse custo, uma camada intermediária de roteamento entre providers é uma alternativa.

Dá para cachear respostas de dúvidas parecidas?

Nesse problema específico, não compensa. Cada caso é um caso, e o risco de colisão é alto: você não quer alguém reclamando de atraso e o chat respondendo com uma promessa de reembolso reaproveitada de outro contexto.

Qual LLM escolher?

Depende das regras de negócio e das decisões técnicas do produto. Resposta em tempo real ou assíncrona muda a infraestrutura, o tamanho e o tipo do modelo. Um domínio específico, como jurídico, contábil ou médico, pede um modelo mais especializado nos termos técnicos da área, em vez de algo genérico que tenta cobrir tudo.

Em que momento as tools são chamadas?

Depois que a mensagem passou pelo guardrail, pelo classificador e pelo router. Só então o LLM da etapa de resolução entra em ação e começa a consumir as ferramentas: consulta os dados do cliente, abre comunicação com a loja e assim por diante. Muitas dessas chamadas podem ser paralelas, com um agregador combinando as respostas em um único output para a decisão seguinte, exatamente o padrão de parallelization descrito no artigo da Anthropic.

Como o LLM sabe qual tool chamar?

Pela cadeia de outputs estruturados. O classificador produz uma saída estruturada, o router lê essa saída e decide, e o que chega à etapa de resolução também é estruturado. As tools são funções determinísticas e parametrizadas, que aguardam a variável do parâmetro ser preenchida pelo modelo com base no que ele recebeu. Não é preciso nada muito dinâmico, como as function callings de antigamente, nem um desenho inchado com MCP.

Esse fluxo poderia ser feito com LangGraph ou MCP?

Poderia. Mas em aplicações grandes no mercado, especialmente fora do Brasil, a preferência tem sido construir internamente e assumir o controle. Frameworks recentes mudam com frequência e quebram coisas no caminho; não é uma crítica técnica ao framework, é uma questão de maturidade. A abordagem apresentada na live, e no projeto dentro da Especialização, usa API própria, com base no que vimos funcionar em produção.

Como controlar alucinações na classificação?

Duas camadas. Primeiro, reduzindo o escopo do modelo: um BERT treinado para classificar entre poucas categorias tem muito menos espaço para inventar. Segundo, o próprio esquema do output estruturado trava a saída: se as alternativas válidas são reembolso ou novo envio, o modelo não consegue preencher com uma terceira opção. Se alucinar, a validação falha e ele tenta de novo dentro da janela de tempo da resposta.

Como equilibrar baixa latência com picos de acesso sem estourar o custo?

O maior gargalo do desenho é a dependência de um provider externo de LLM. Trazer essa camada para dentro da infraestrutura já reduz bastante a probabilidade de picos disparados em requests externos. O restante é estratégia clássica de software: pool de conexões, cache, réplicas de leitura no banco, escala da aplicação.

Todo esse processo é disparado a cada mensagem?

Não. Existem cortes no pipeline: quando o modelo chama uma tool, quando passa pelo classificador. São pequenas interrupções em intervalos de milésimos de segundo, o que dá a falsa sensação de um disparo único. E depois que a conversa foi iniciada, partes do fluxo, como o filtro inicial, não precisam ser executadas de novo.

Não daria para resolver tudo de forma determinística, sem LLM?

Boa parte, sim, e o desenho faz exatamente isso. Mas há dois pontos onde a interpretação semântica agrega: entender a intenção do cliente na classificação e, principalmente, gerar o resumo para o atendente humano. Quando você coleta contexto de várias fontes para sintetizar um relatório que apoia uma decisão, compensa muito mais deixar o modelo escrever do que tentar prever todos os cenários em templates fixos.

E o risco de prompt injection?

O ponto de entrada seria a mensagem do usuário, mas o desenho trava o risco de duas formas. A verificação inicial pode incluir detecção determinística, em código puro, de tentativas de injeção de comandos. E a busca no banco é determinística e parametrizada: não existe text-to-SQL, em que um modelo interpreta o texto do usuário para montar a query, cenário clássico em que uma injeção poderia levar o modelo a interpretar um delete ou um drop. Aqui, o que sai da verificação só tem uma opção: preencher o parâmetro de uma função pronta.

Conclusão

O desenho completo, visto de longe, é bem linear: verificação, busca, guardrail, classificação, roteamento, resolução ou escalation. E essa é a principal lição do exercício: um sistema de suporte com IA em produção é, antes de tudo, um workflow determinístico, em que o LLM entra apenas onde a interpretação semântica agrega valor real. Guardrails de regras críticas ficam em código puro. A comunicação entre etapas acontece por outputs estruturados, que travam alucinações antes de virarem bugs. E ferramentas são funções parametrizadas, não escolhas livres do modelo.

Esse estudo de caso está implementado e disponível como conteúdo dentro da Especialização em Engenharia de IA, liderada por Daniel Romero, junto com os fundamentos que sustentam cada decisão apresentada aqui: information retrieval, RAG e suas estratégias, engenharia de agentes, qualidade e validação de sistemas com LLM.

Dev + Eficiente

O método que eu uso para aprender qualquer coisa

Alberto Luiz Souza — Mon, 03 Aug 2026 09:25:07 +0000

Disclaimer

Introdução

Eu tenho um método para estudar tudo que eu preciso aprender. Usei esse método para me preparar para ser pai. Usei para aprender Clojure, uma linguagem funcional da qual eu não tinha background nenhum. Estou usando para me formar como analista de performance de futebol, para apoiar um dos meus filhos que quer ser jogador profissional. Usei quando precisei aprender sobre blockchain para criar um curso. E a aplicação mais recente foi bem menos glamourosa: adestrar Paçoca, a cachorra que chegou aqui em casa.

Profissional ou pessoal, técnico ou não, é sempre o mesmo método, ou alguma derivação parcial dele. Neste post eu quero compartilhar como ele funciona: as travas que costumam atrapalhar quem quer aprender, os cinco pilares que eu sigo e como eu executo tudo isso com 20 minutos por dia.

Não existe o jeito certo de aprender

Antes de qualquer coisa, um alinhamento: eu não considero que exista o jeito certo de aprender, o método mais efetivo do planeta. A humanidade está cheia de exemplos de pessoas que chegaram a níveis excelentes de conhecimento usando caminhos completamente diferentes, com abordagens diferentes e com níveis de suporte diferentes. Tem gente que compra curso de especialista e tem gente que aprende por observação, tentativa e erro, e os dois caminhos podem dar certo.

O que eu vou compartilhar é um conjunto de técnicas que tem funcionado muito bem para mim e que eu já apliquei com outras pessoas. Um exemplo: uma conhecida minha nunca tinha trabalhado com iOS, e o nosso plano foi prepará-la para ser avaliada pelo mercado como uma pessoa pleno/sênior de iOS. Consegui entrevistas para ela passar por avaliações reais, e deu certo.

As travas mais comuns

Quase todo mundo quer aprender alguma coisa nova. Mas existem certas travas que se repetem, e vale checar se você se identifica com alguma delas.

Objetivo vago demais

"Quero aprender Kotlin", "quero aprender a programar com agentes baseados em LLM". Aprender o quê, exatamente? Para fazer o quê? Em qual contexto? Você precisa passar em um processo seletivo? Quando o objetivo é vago, o estudo não tem critério de conclusão: você não sabe quando acaba.

Aqui vale uma divisão importante. Existe o aprendizado para se tornar uma pessoa mais sábia: exploratório, orgânico, sem um grande objetivo por trás. Quer aprender grego só porque acha bonito? Tudo certo. E existe o aprendizado transacional, utilitário: eu aprendi Clojure porque ia entrar no Nubank e queria chegar preparado na stack da empresa. Se eu não fosse entrar, não teria aprendido, não era uma linguagem que me interessava. Todo aprendizado utilitário também te deixa mais sábio, mas a recíproca nem sempre se aplica. E vai existir coisa que você precisa aprender sem querer aprender. Se você tem um método, isso fica muito mais tragável, como aquela feature que você não quer fazer, mas faz.

Material denso demais para o seu momento

No início da chegada dos LLMs, uma galera dizia que você não deveria construir software com LLM sem dominar arquitetura de Transformers, Machine Learning, estatística. Eu discordo: a profundidade do seu aprendizado é diretamente proporcional à complexidade do seu contexto. Eu claramente não estou preparado para trabalhar refinando os modelos da Anthropic ou da OpenAI. Para usar esses modelos e adicionar graus de sofisticação aos meus sistemas, me sinto muito bem preparado.

Fiz o teste: peguei o artigo original do Google sobre Transformers e não entendi nada. E é isso mesmo. Uma pessoa sem background pegando um texto em formato de artigo científico, cujo propósito não é facilitar o entendimento, vai sofrer. A alternativa é começar por materiais mais simples, com muito desenho e muita seta, e voltar ao artigo depois, mais tolerante àquela complexidade.

Existe uma teoria que eu gosto muito, a teoria da carga cognitiva, que pressupõe que temos uma limitação severa para processar informações novas. Se você está aprendendo algo novo e enche a cabeça de muitas coisas ao mesmo tempo, é como um balde cheio: cada pingo a mais transborda. Por isso, cuidado com textos mais densos do que você consegue consumir naquele momento, cuidado com a árvore de links de profundidade desconhecida que te faz ler, ler, ler e sentir que não saiu do lugar, e cuidado com ambientes de muita distração, porque cada distração compete por espaço de processamento com o que você quer aprender.

A crença de que você precisa de muitas horas

Essa crença é limitante de verdade. Você precisa acumular horas de estudo para ter uma transformação no seu entendimento, sim. Mas isso não quer dizer que precisa acumular essas horas de uma vez só. O problema dessa crença é que você fica esperando o ambiente perfeito: o fim de semana livre, as férias, o momento em que finalmente vai dar para estudar. Qualquer progresso é melhor do que nenhum progresso.

Por que eu estudo de maneira antecipada

Aprender a aprender foi o maior vetor de crescimento da minha vida, e o motivo é simples: eu não gosto de me estressar. Para não me estressar, eu entendi que precisava me preparar de maneira antecipada para os desafios que estavam por vir. Não sou capaz de antever todos, mas vários deles sou.

Quando você aprende enquanto faz, a sua confiança baixa e o seu nível de preocupação aumenta. Você fica mais lento e com menos capacidade de improvisação, porque viu menos problemas antes. Eu gosto de lembrar que a sua capacidade de improvisar, de lidar com imprevisibilidade, é diretamente proporcional ao seu nível de preparo. Quanto mais preparada a pessoa está, mais capaz de improvisar ela é.

Alguns exemplos de como isso se materializou por aqui:

Clojure antes do Nubank. Entendi a stack que a empresa usava, Clojure como linguagem, Pedestal como biblioteca HTTP, as bibliotecas de parsing e de testes, e defini o objetivo: ser capaz de construir serviços web de complexidade entre baixa e média com aquela stack, validado por uma pessoa experiente de lá. Essa jornada está pública no meu canal.
Paternidade. Eu nunca tinha cuidado de uma criança. Li sobre parentalidade positiva, teoria da autoeficácia para pais e mães, rotina de bebês, neurociência, livros escritos por enfermeiras. Fiquei com a responsabilidade de propor a rotina da casa para a chegada do nosso primeiro filho: sono, alimentação, brincar sozinho. A maior parte do que a gente planejou funcionou, e ajudou muito.
Análise de performance de futebol. Meu filho de 10 anos quer ser jogador profissional. Eu fiz a conta com ele: considerando as quatro divisões do campeonato brasileiro, o número de vagas no futebol profissional é da ordem de poucos milhares, menos do que o quadro de pessoas desenvolvedoras de uma única empresa grande de tecnologia. É um funil duríssimo, e mesmo assim estamos juntos nessa. Para apoiá-lo além do meu viés de torcedor, estou fazendo uma formação de analista de performance, e desse estudo nasceu o blog O Porquê do Jogo.

Os cinco pilares do método

Todos esses exemplos seguem a mesma estrutura.

1. Objetivo de aprendizagem bem definido

Algumas perguntas ajudam a sair de um objetivo vago para um objetivo de verdade. O que você quer ser capaz de fazer? Em qual nível de profundidade? Com quais ferramentas e em qual contexto? E como você vai validar que aprendeu?

Para profundidade, eu gosto de pensar na taxonomia de Bloom, que classifica exigências cognitivas: lembrar, explicar, aplicar, analisar, avaliar e criar. Para adestrar Paçoca, a minha profundidade é aplicar, eu não preciso ser capaz de analisar o adestramento de outra pessoa. Para análise de futebol, eu preciso chegar no nível analítico: quebrar o jogo em partes, olhar quebra de linha, linha de passe conservadora versus agressiva.

Sobre validação: no Clojure, o critério era uma pessoa experiente naquela stack me avaliar e considerar que eu estava jogando duro. Na análise de futebol, é um clube aceitar o meu currículo em um processo seletivo. No adestramento, é Paçoca sentar quando eu falo senta.

2. Alinhamento de expectativas com você mesmo

Eu não sabia nada de linguagens Lisp-like, então sentei na cadeira sabendo que ia ser duro, sem falsas expectativas. Com Machine Learning aconteceu o oposto: eu sabia que seria difícil, mas foi ainda mais duro do que eu imaginava dado o meu background, e eu decidi deixar de lado. Está tudo bem também. E quanto mais jornadas de aprendizagem você acumula, melhor você lida com as frustrações do caminho.

3. Seleção de teoria

Eu avalio fontes teóricas em duas dimensões: confiabilidade e facilidade de consumo. A minha indicação principal: você precisa ter no seu material de estudo fontes de confiabilidade máxima. Quer aprender uma linguagem de programação? A documentação oficial tem que estar no seu material. Se você aprendeu sem passar por fontes geradas por quem constrói a linguagem, corre o risco de ter aprendido uma prática de um jeito que aquela equipe nunca imaginou(e isso pode ser bom). Se a documentação é dura demais para começar, tudo bem: comece por materiais mais fáceis e menos confiáveis, mas depois coloque a fonte de confiabilidade máxima no circuito, para confrontar o que você aprendeu e, de vez em quando, até transcender o que está lá.

4. Prática conectada à profundidade

Este é o pilar mais importante para transformar conhecimento em capacidade. As práticas precisam estar conectadas ao nível de profundidade do seu objetivo. Quer ser capaz de explicar a arquitetura de Transformers? Exercite a explicação: escreva, fale para o espelho, fale para outra pessoa. Quer ser capaz de aplicar? Precisa construir alguma coisa, e quanto mais você exercitar, melhor.

5. Feedback, se você puder ter

Feedback é como o ponto no GPS: quando você sai do caminho, ele te ajuda a retornar mais cedo. Pode ser um professor particular, uma pessoa consultora, um instrutor a quem você pode perguntar. Nem sempre você vai ter acesso, e dá para andar com o mapa no banco do carro, como antigamente, só que aí você demora mais para perceber que se distanciou do destino.

Consistência é o motor da execução

E como executar o plano se você está limitado pela crença do tempo? Eu fiz o curso de adestramento e estou fazendo a formação de análise de performance de futebol com 20 minutos por dia. O seu cérebro é stateful: você para hoje no meio de uma aula e retoma amanhã de onde parou. As horas se acumulam mesmo espalhadas no tempo.

O que muda tudo é sentar com um plano de execução. Sentar no computador e se perguntar "o que eu vou fazer agora?" é ruim com 20 minutos ou com 20 horas; a diferença é que com 20 minutos você perde só 20 minutos. Com plano, você abre a lista, continua de onde parou, e quando o tempo acaba, acabou, parou no meio mesmo. É como chegar atrasado no treino com personal: é melhor fazer 40 minutos de exercício do que nenhum.

"Mas assim vai demorar muito." Vai. E você vai acabar. Se você não começar com 20 minutos por dia, você vai acabar quando? Consistência é a chave: o volume você acumula no espaço de tempo, mas precisa de consistência para acumular volume. Se conseguir ser consistente com um pouco mais de volume, talvez encurte a jornada. Se tiver como criar previsibilidade, com dias e horário fixos, ajuda. Se não tiver, encaixe onde der: no metrô, no ônibus, no meio do dia. Em uma empresa minimamente saudável, ninguém vai gerenciar 20 minutos do seu dia. Só faz.

Conclusão

Cuidado com as travas: objetivo vago, sobrecarga cognitiva e a espera por tempo suficiente. Defina um objetivo que te guie, selecione teoria olhando para confiabilidade e facilidade de consumo, pratique no nível de profundidade que você precisa, busque feedback quando possível e proteja um mínimo de consistência. Na minha experiência, uma hora de estudo por dia pode te levar aonde você quiser em termos de profundidade.

E lembre: o objetivo não é zerar a imprevisibilidade, é minimizá-la. Meus filhos fizeram coisas que não estavam nos livros, e você vai encontrar problemas de escala que nenhum estudo cobriu. Mas você vai chegar com repertório, e quando aparecer algo que você nunca viu, a sua chance de improvisar bem vai ser muito maior. Não espere a condição perfeita: monte o plano e execute no tempo e na frequência que a sua vida permite.

Esse conteúdo, aliás, foi extraído do curso Máquina de Aprender, disponível dentro do Dev + Eficiente, que também deu origem ao livro Be a Learning Machine, publicado na Leanpub.

Dev + Eficiente

Agentes de código: já leu a documentação oficial?

Alberto Luiz Souza — Sun, 12 Jul 2026 22:08:36 +0000

Disclaimer

Introdução

Quero começar com duas perguntas. A primeira: você usa agentes de código, tipo Claude Code, Cursor ou Codex? Se sim, e eu imagino que sim, vem a segunda: você já leu a documentação oficial da ferramenta que utiliza?

Fiz uma enquete informal com as pessoas ao meu redor, e a resposta se repetiu: usam bastante, consideram a ferramenta um combustível de produtividade, dizem que ela potencializou o que conseguem entregar. E não leram a documentação. Algo nessa combinação não encaixa, e é sobre isso que quero conversar neste post.

A analogia do carro

A sensação que eu tenho observando esse padrão é muito parecida com a minha relação com o meu carro. Eu sei dirigir, aprendi faz tempo. Mas se o carro quebra, eu sei resolver? Não sei nada. Eu só sei dirigir. E pior: eu nunca li o manual. De vez em quando acho que o carro não tem uma função que, quando vou procurar a solução, está escrita lá.

E, no meu caso, está tudo bem. Eu não trabalho com carros. Saber mais ou menos sobre o carro pode me tirar de uma situação desconfortável, mas não funciona como alavanca para a minha vida. Ninguém vai me avaliar, me julgar ou me pagar mais ou menos pelo quanto eu entendo de carro.

Com uma pessoa desenvolvedora, a conta é outra. Você pode sim ser avaliado pelo quanto conhece os agentes de código que utiliza: quais são os casos de uso, quais configurações existem, como abordar um projeto do zero versus um código que já existe, o que fazer quando a base de código cresce. Imagine usar um Claude Code da vida dentro de um projeto grande, com múltiplos módulos, um legado no sentido de conhecimento acumulado. Como você abordaria esse código? Se o seu conhecimento sobre a ferramenta é só empírico, ou vem só de posts na internet, a resposta que você dá para essa pergunta tem teto.

Um exemplo do mundo real

Pesquisei no Google por melhores práticas com Claude Code. O primeiro link, pelo menos para mim, foi a documentação oficial. O segundo foi uma postagem no Reddit com mais de vinte comentários, de alguém contando o cenário da equipe: usam bastante o Claude Code, a qualidade do código é boa, o código roda, os testes passam. Mas, conforme a base cresce e novos recursos são adicionados em cima de código gerado por IA, as coisas ficam bagunçadas, fica difícil entender o que está acontecendo, código morto se acumula e as soluções começam a sair superdimensionadas. A pessoa então conta que começou a usar o CLAUDE.md e uma pasta de regras para dar mais estrutura, mas que ainda está descobrindo o que funciona.

Duas leituras são possíveis. Talvez a pessoa tenha lido a documentação oficial e esteja tentando extrapolar o que está lá. Ou talvez não tenha lido. O texto não cita as fontes consultadas, então não dá para saber, e o ponto aqui não é julgar o autor. O ponto é o padrão: a documentação oficial diz, logo no início, que o CLAUDE.md é o arquivo de contexto básico da ferramenta, carregado no startup e enviado em toda requisição que o Claude Code faz para os modelos, com todo um mecanismo de caching na infraestrutura para não reprocessar isso a cada chamada. Quando alguém relata que "começou a usar o CLAUDE.md" depois de meses de uso intenso, a pergunta natural é: qual foi o repertório teórico consultado até ali?

O mar de fontes secundárias

Seguindo na mesma pesquisa, depois da documentação vem uma enxurrada de conteúdo derivado: ebooks de melhores práticas, listas de 24 dicas, 7 recursos essenciais, tutorial completo, guia definitivo. Enquanto isso, a documentação oficial tem, inclusive, um capítulo chamado melhores práticas. Tem uma seção sobre como configurar a ferramenta em um monorepo ou em uma base de código grande. Explica como criar plugins, sem precisar de post de blog nenhum. Explica como funciona a janela de contexto, o que é carregado de partida, como ela vai enchendo, como funciona o mecanismo de compactação, como funciona o caching na infraestrutura, o que você paga e o que é reaproveitado.

Ou seja: boa parte das perguntas que aparecem em threads e posts já tem resposta na fonte primária. E as fontes secundárias, por definição, são menos confiáveis do que a documentação, porque são a interpretação de alguém sobre o que está lá.

Para que serve a teoria

Dentro do Dev + Eficiente temos um curso chamado Máquina de Aprender, que fala sobre aprendizagem efetiva, e uma ideia de lá ajuda a enquadrar essa discussão. Uma teoria deriva de alguma prática, ou de uma observação muito atenta de alguma prática. Quem escreve, escreve porque fez alguma coisa ou porque observou várias pessoas fazendo, e relata aquilo em texto. Para quê? Para que você leia e consiga chegar a níveis parecidos com quem estava praticando, de maneira mais eficiente, sem precisar passar por todos os problemas pelos quais a pessoa ou a equipe anterior passou.

Quando você vai escolher uma fonte teórica, eu costumo sugerir a análise por duas dimensões. A primeira é o quão fácil ela é de consumir: tem gente que prefere vídeo, tem gente que prefere texto, e isso é legítimo. A segunda é a confiabilidade da fonte. E, quando o assunto é uma ferramenta, a fonte mais confiável disponível para a maioria das pessoas é a documentação oficial.

Existem fontes acima dela, vale dizer. Se você tiver acesso ao código-fonte, ele é mais confiável do que a documentação, porque a documentação explica o que está no código. E se você conhecesse pessoalmente quem construiu a ferramenta, essa pessoa talvez fosse uma fonte ainda melhor. Para quase todo mundo, porém, o teto de confiabilidade acessível é a documentação.

Se você abre mão da fonte de confiabilidade máxima no seu repertório, duas coisas podem acontecer: você deixa conhecimento na mesa, ou deixa de confrontar um conhecimento que chegou até você de maneira equivocada. Isso vale inclusive para este texto. Quando eu explico algo sobre o Claude Code, como você sabe que eu não entendi errado? Você pode dar valor ao que eu digo, mas a confirmação vem do confronto com a fonte oficial.

Confrontando fontes para criar conexões

Esse confronto entre fontes, aliás, é onde o aprendizado fica mais interessante. Um exemplo: o blog da OpenAI publicou este ano um texto chamado Harness Engineering: Leveraging Codex in an Agent-First World. É o relato de uma ferramenta construída internamente em que a equipe decidiu não escrever nada à mão: infraestrutura, código, tudo foi feito via agentes. O texto conta como eles foram refinando o contexto, iterando sobre ele e quais práticas foram usando ao longo do caminho.

Ler um relato como esse e confrontá-lo com o que está na documentação oficial da ferramenta que você utiliza faz a sua cabeça criar conexões novas. O relato traz a experiência de uma equipe em um contexto específico; a documentação traz o comportamento garantido da ferramenta. É no cruzamento dos dois que você forma um entendimento que nem o post sozinho nem a documentação sozinha entregariam.

Conclusão

Não estamos falando de uma ferramenta que aparece ocasionalmente no seu dia. Estamos falando de algo que boa parte das pessoas desenvolvedoras usa o tempo inteiro, para um monte de coisas. Se a ferramenta tem esse peso no seu trabalho, deixar de ler a documentação oficial é provavelmente desperdiçar conhecimento e, eventualmente, ser menos eficiente do que você poderia ser, porque existem recursos e comportamentos descritos lá que você nem sabe que existem. Como eu com o meu carro, com a diferença de que ninguém me paga pelo que eu sei sobre carros.

A sugestão prática é simples: reserve um tempo para ler a documentação oficial da ferramenta que você usa todos os dias. Analise suas fontes teóricas pelas duas dimensões, facilidade de consumo e confiabilidade, e garanta que a fonte de confiabilidade máxima esteja no seu repertório.

Dev + Eficiente

Código humano ou código de IA: quem tem mais defeito?

Alberto Luiz Souza — Tue, 07 Jul 2026 13:10:24 +0000

Disclaimer

Introdução

Uma pergunta que aparece com frequência quando falamos de agentes de código é qual o nível de desconfiança que devemos ter de um código gerado por um modelo. Não um modelo qualquer, mas os modelos de ponta que usamos no dia a dia. A resposta costuma vir carregada de intuição, e intuição raramente é um bom instrumento de decisão técnica.

Neste post eu reviso um artigo científico que tenta responder isso com dados: "Human written versus AI generated code: a large scale study of defects, vulnerabilities and complexities". O estudo compara código escrito inteiramente por pessoas com código escrito inteiramente por LLMs, em três dimensões de qualidade: defeitos, vulnerabilidades de segurança e complexidade estrutural.

Vale um recorte temporal honesto antes de qualquer conclusão. O artigo é de 2025, e este vídeo foi gravado em junho de 2026. Em um cenário de evolução acelerada dos modelos e dos agentes construídos sobre eles, um ano é bastante tempo. Então trate os números como uma fotografia de um momento que já passou, e preste atenção principalmente na direção que eles apontam.

Como o estudo foi feito

O ponto de partida foi um dataset com centenas de milhares de funções, algo em torno de 200 e poucas mil em Python e um número parecido em Java, mineradas de dezessete a dezoito mil repositórios do GitHub. Todas escritas por seres humanos.

O dataset pronto não trazia a documentação das funções. Então os autores executaram um processo para casar cada função de volta ao seu repositório original e recuperar a documentação. A partir dessa documentação, rodaram prompts contra três famílias de modelos para gerar implementações equivalentes: um modelo da OpenAI, o GPT-3.5, um modelo da família Qwen e um modelo da família DeepSeek. Foram quatro implementações de cada função, para poder comparar.

Um detalhe importante sobre a metodologia, porque ele muda a leitura de tudo o que vem depois: não havia agente, não havia contexto adicional, não havia harness. Era um prompt direto contra a documentação, pedindo a implementação naquela linguagem. Um cenário muito mais pobre do que qualquer fluxo sério de geração de código hoje.

O estudo se organiza em torno de três perguntas:

Os tipos e a frequência de defeitos diferem entre código humano e código gerado, e isso muda conforme a linguagem?
Existe diferença nas vulnerabilidades de segurança entre código humano e código gerado?
As métricas de complexidade estrutural variam entre um e outro?

O que conta como defeito aqui

Antes dos resultados, é preciso alinhar o vocabulário, porque a palavra defeito carrega mais peso do que o estudo lhe atribui. A classificação usou o framework Orthogonal Defect Classification, bem aceito na literatura, com regras aplicadas por ferramentas de análise estática tanto para Python quanto para Java.

Defeito, nesse contexto, não é sinônimo de código que não funciona. É uma categoria ampla que inclui desde erros que impedem a execução até práticas desencorajadas. Alguns tipos, para dar concretude:

Assignment: erros de inicialização ou de binding de variável, por exemplo usar uma variável que não foi inicializada. Esse tende a quebrar de fato.
Algoritmo: problemas de lógica. Aqui entra também algo como blocos aninhados demais, que não afeta a corretude, mas é considerado um defeito de estrutura.
Interface: problemas de comunicação entre módulos, como um parâmetro sem valor definido.
Checking: validação de falhas e tratamento de erro faltando, como a ausência de checagem de timeout ou um bloco de catch vazio.
Timing e serialização: questões de concorrência, ordenação e sincronização.
Function, class e object: problemas estruturais de design.

Guarde isso: quando o estudo diz que um código tem mais defeitos, boa parte disso é prática ruim capturada por regra estática, não é, necessariamente, código que não roda.

Resultado 1: defeitos

O resultado dos defeitos surpreende quem chega com a intuição pronta. O código que saiu com menos defeitos foi o gerado pelo GPT-3.5, um modelo antigo se comparado ao que temos hoje e, lembrando, sem agente e sem contexto. Ainda assim, com menos defeitos.

Em Python, o código humano foi menos ruim do que parte dos modelos, mas ainda perdeu. Em Java a disputa ficou mais equilibrada, com o código humano em uma posição intermediária. No total acumulado de defeitos, no entanto, o código humano saiu pior nas duas linguagens.

O que eu achei mais curioso não foi o número, foi a conclusão que os autores tiraram dele. Eles escrevem que os achados reforçam a necessidade de avaliar o código gerado por IA, não apenas quanto à corretude, mas também quanto ao design. Pela leitura dos dados, porém, o que precisou de mais revisão foi o código humano, não o da máquina. A necessidade de revisão é real e vale para todos, porque todos apresentaram defeitos. Mas o dado não aponta especificamente para o código gerado.

Resultado 2: vulnerabilidades

Aqui a história se inverte, e essa é a parte que merece mais atenção. Em ambas as linguagens, o código humano foi o que apresentou menos vulnerabilidades de segurança. Todos os modelos, de forma consistente, geraram código com mais problemas de segurança do que o escrito por pessoas.

E não é só uma questão de quantidade. Os autores registram que o código gerado por IA difere do humano também na natureza e na distribuição das vulnerabilidades, ficando mais suscetível a problemas de alta severidade.

Esse é o ponto onde o balanço fica interessante. Se cada dimensão do estudo tivesse o mesmo peso, o código humano perderia no geral. Mas as dimensões não têm o mesmo peso. Uma falha de segurança de alta severidade tende a ser mais crítica do que um bloco aninhado a mais, que é um defeito de prática e não de corretude. Peso não é algo que o estudo decide por você. É julgamento de engenharia, e depende do que está em jogo no seu sistema.

Resultado 3: complexidade estrutural

A terceira dimensão avaliou complexidade a partir de um conjunto de métricas: número de linhas, complexidade ciclomática, número de tokens, tamanho dos nomes de funções como proxy para semântica e tokens únicos como proxy para o vocabulário da linguagem utilizado.

O resultado foi consistente nas duas linguagens: o código humano é estruturalmente mais complexo, tanto em tamanho quanto em estrutura lógica. O código gerado, sobretudo pelos modelos DeepSeek e Qwen, favorece brevidade e complexidade reduzida, com menos linhas, menor complexidade ciclomática e menos tokens.

Vale uma ressalva sobre a metodologia, porque ela ensina algo mais valioso do que o resultado em si. Escolher tamanho de nome como proxy para semântica é uma decisão defensável, mas o mesmo número maior também poderia indicar prolixidade, alguém que escreve nomes gigantes sem ganho real de clareza. Ou seja, a métrica não é neutra.

O que eu tiro disso não é qual métrica é a certa. É que medir complexidade importa mais do que acertar de primeira o conjunto de métricas. Quando você tem um conjunto de métricas que, combinadas, produzem uma avaliação, você ganha a capacidade de iterar sobre esse processo avaliativo e descobrir se aquelas métricas de fato trazem a perspectiva que você quer. Sem medir, você fica preso na intuição.

Quem é o assistente de quem

Feita a revisão, a pergunta que fica é o que fazer com isso na prática. O artigo, como boa parte da literatura, termina em revisão, revisão, revisão. Eu não discordo que revisão importa. Mas, pela minha experiência, ela tende a ser cada vez menos necessária quando o input é bem feito, o contexto é adequado e existe um mecanismo mínimo de revisão no fluxo. Com isso, a saída costuma vir correta. Isso depende do seu contexto, da sua stack e do seu domínio, então defina por conta própria o que correto e o que suficiente significam no seu caso.

Antes de qualquer discussão sobre revisão, existe uma questão de responsabilidade que não muda. Eu sou o responsável por tudo o que gero através dos agentes. Se um bug entra na plataforma, a pessoa cobrada sou eu. Se um conteúdo sai com informação incorreta, quem responde sou eu. Não dá para responsabilizar a máquina. O responsável continua sendo a pessoa, sem qualquer dúvida.

Existe uma ideia comum entre quem lidera que ajuda a enquadrar isso: uma habilidade importante é contratar pessoas melhores do que você para determinados tipos de trabalho. É assim que eu enxergo os agentes hoje. Eu sou o chefe, e o agente é alguém que eu contratei, com capacidade de execução geralmente melhor do que a minha para a maioria das tarefas.

A questão então é onde eu entro. Eu entro no pedaço de conhecimento em que o modelo por baixo do agente não foi tão bem treinado, ou foi treinado em uma linha que não é a que eu quero seguir. Quando o assunto é design de código, as práticas mais estabelecidas nos modelos tendem para múltiplas camadas e para tratar acoplamento com frameworks como algo sempre ruim. Não é a linha que eu defendo há alguns anos, então ali eu preciso fazer o ajuste fino.

Em contrapartida, quando eu preciso escrever queries eu não faço ajuste nenhum, porque o modelo tem mais repertório do que eu nisso. Em testes, os modelos são capazes, mas tendem a produzir testes superficiais quando não são direcionados, então ali eu direciono. Em segurança por design, eu diria que o modelo já é mais bem treinado do que eu.

Levando a ideia ao limite, eu me vejo menos como quem tem um assistente e mais como o assistente do assistente. Meu papel, nesse momento, é atrapalhar o mínimo possível o agente. Isso passa por engenharia de contexto: entender o que de fato é necessário, dar a autonomia adequada e ser sucinto. Passa também pelo harness, e aqui ferramentas como Claude Code e Codex ajudam bastante, porque já trazem guardrails sobre até onde o agente pode ir, como avaliar se a geração atendeu ao requisito e até onde vai o loop de autonomia.

Conclusão

Se o estudo já apontava, mesmo com modelos antigos e sem agente, que o código gerado tende a ter menos defeitos e menor complexidade estrutural, é razoável imaginar que a distância aumente com os modelos e agentes atuais. Na dimensão de segurança, onde o código humano ainda levava vantagem, é plausível que o cenário se aproxime ou até se inverta conforme os modelos amadurecem nesse eixo. Isso é leitura de tendência, não afirmação fechada.

O que não muda é a divisão de trabalho. A capacidade de execução migra cada vez mais para o agente. O que fica em primeiro plano do lado humano é o julgamento: definir peso entre dimensões que competem, cravar a linha de design que você acredita, direcionar onde o modelo tende ao superficial e responder pelo resultado. Não é sobre digitar código. É sobre decidir e responder por estar certo.

Dev + Eficiente

5 cursos com 20 minutos por dia

Alberto Luiz Souza — Mon, 29 Jun 2026 09:22:12 +0000

Disclaimer

Introdução

Existe uma crença comum de que, para aprender algo novo, é preciso reservar grandes blocos de tempo: duas horas por dia, um fim de semana inteiro, uma semana de imersão. E é justamente essa crença que faz muita gente nunca começar. Como o bloco de tempo ideal nunca aparece, o estudo fica parado indefinidamente.

Eu sempre defendi que consistência é mais importante do que volume pontual. Neste post quero compartilhar uma experiência pessoal que é justamente uma aplicação dessa linha de pensamento: algo que eu realmente queria aprender, mas para o qual não tinha muito tempo livre na agenda. Saí de um conhecimento totalmente empírico para algo mais formal usando apenas 20 minutos por dia.

O contexto: por que eu precisava aprender algo novo

Tenho dois filhos, e um deles, de 10 anos, está na jornada de tentar se tornar jogador de futebol profissional, com toda a dificuldade que isso envolve. Para apoiá-lo melhor nas peneiras e nos testes, eu quis entender como funciona o trabalho de análise de performance no futebol: o que se observa em cada posição, quais atributos são avaliados, como essa análise é feita.

O objetivo era concreto. Quando ele vai a uma peneira ou a um jogo, eu queria conseguir orientá-lo de forma mais útil: pensar em como um volante quebra a linha, o que um avaliador provavelmente está olhando em um lateral ou em um atacante. A partir daí, experimentar e analisar o que funciona.

O problema é que análise de performance não é a minha profissão. Eu tenho trabalhos, como o Dev + Eficiente, material para produzir, vídeos para gravar, família. Eu não tinha duas horas por dia para dedicar a isso.

A decisão: 20 minutos por dia

A saída foi simples. Separei 20 minutos do meu dia, geralmente de manhã, e usei esse tempo para progredir nos cursos. Comprei o nível 1 e um curso do nível 2 que vinha no pacote.

No momento em que gravei o vídeo, eu já tinha concluído 5 cursos e estava no sexto. Terminei o nível 1 inteiro, fiz todas as provas, anotei bastante coisa e já estava conseguindo ajudar meu filho de forma mais direcionada. Tudo isso com 20 minutos diários.

Vale um esclarecimento importante: não se trata de estudar de forma relapsa ou correndo. Dentro daqueles 20 minutos, eu estudo exatamente como estudaria normalmente. Assisto à aula, paro para anotar, registro o que precisa ser registrado. A única diferença é a janela de tempo. Eu faço o que dá em 20 minutos e paro ali.

Por que isso funciona: qualquer progresso supera nenhum progresso

A lição central é essa: qualquer progresso tende a ser melhor do que nenhum progresso. A gente frequentemente fica travado no estudo porque acredita que precisa de muito tempo e de muito volume para começar. E, enquanto espera por esse cenário ideal, não anda.

Se você tivesse uma hora por dia de estudo focado, na minha experiência isso já seria mais do que suficiente para progredir na maioria das coisas que você quer aprender, independentemente do nível de profundidade. Mas se você não tem uma hora, 20 minutos já ajudam. Com um plano de aprendizagem e um mínimo de consistência, você consegue avançar no que quiser.

E vale lembrar de algo que muitas vezes passa despercebido: o conhecimento vai se acumulando. Com 20 minutos numa determinada frequência, você acumula consumo de conteúdo, reflexão sobre aquilo e, naturalmente, vai aprendendo. Seu cérebro é stateful. O dia seguinte não começa do zero: ele parte do que foi adquirido na sessão anterior. É esse acúmulo que faz pequenas janelas de tempo somarem em progresso real ao longo dos dias.

O ponto de partida, então, não é o tempo. É o plano. No meu caso, o plano era simplesmente seguir aqueles cursos com o objetivo de médio prazo de apoiar meu filho nas peneiras. Com o plano definido, os 20 minutos diários têm para onde ir.

Aplicando ao seu contexto de carreira

Pense em um cenário comum entre pessoas devs. Você quer muito uma vaga em uma empresa específica, mas sabe que o processo tem uma etapa de system design exigente e quer chegar mais preparado(a).

O caminho é o mesmo. Selecione o que precisa estudar: pode ser um curso do Dev + Eficiente, outros cursos, livros. Vai parecer muito conteúdo de uma vez, e é aí que a maioria trava. Em vez disso, priorize por onde começar, estabeleça um tempo, mesmo que sejam 20 minutos por dia, e progrida.

Quando a entrevista chegar, independentemente de onde você estiver no plano, você estará melhor do que quando começou. Se tivesse ficado esperando o momento de ter tempo suficiente, não teria feito nada.

A analogia do carro: consistência primeiro, volume depois

Consistência é mais importante do que volume. Se você for consistente no seu estudo, conquista o conhecimento que quer. A única variável que muda é o tempo da jornada: pode levar um mês ou um ano. E como se encurta essa jornada? Adicionando mais volume de estudo dentro da consistência.

Mas o volume precisa ser calibrado ao seu contexto. Pense em um carro simples, não preparado para alta velocidade. Se você tentar rodar 2000 quilômetros a 160 km/h o tempo inteiro, ele se desgasta no processo. Então você calibra a velocidade. O que não muda é o ato de andar com uma determinada frqueência: é isso que te leva ao quilômetro 2000, independentemente da velocidade. Com os estudos é igual. Defina o que é um ritmo sustentável para a sua realidade e mantenha a frequência.

O efeito composto do conhecimento

Esse estudo teve um desdobramento que eu não tinha previsto. Com o conhecimento que ganhei, montei um pequeno projeto pessoal: um blog de análise de jogos de futebol baseado em evidência. Construí um harness com scripts em Python que leem relatórios detalhados em PDF, extraem as informações, geram a capa com inteligência artificial e publicam automaticamente na plataforma de blog.

Eu não teria esse projeto no ar se não tivesse começado os estudos. Foi o conhecimento adquirido que me deu a mínima capacidade de analisar os dados e estruturar o conteúdo, além de entender uma plataforma que eu nem conhecia antes. O aprendizado consistente abre portas que você não enxergava no ponto de partida.

Conclusão

A capacidade de aprender algo novo raramente esbarra na falta de tempo. Ela esbarra na crença de que é preciso muito tempo para começar. Quando você troca a busca pelo bloco ideal por uma janela consistente, independente do tempo, o progresso deixa de ser hipotético e passa a acontecer.

Defina um plano, escolha por onde começar, separe o tempo que cabe na sua rotina, mesmo que sejam 20 minutos, e mantenha a frequência. A jornada pode ser mais curta ou mais longa conforme o volume que você consegue sustentar, mas, andando todo dia, você chega.

Dev + Eficiente

Construindo um ranking da Copa pareando com o Claude Code: o relato de uma sessão

Alberto Luiz Souza — Fri, 19 Jun 2026 00:54:16 +0000

Disclaimer

Este texto é o relato de uma sessão real de trabalho minha com o Claude Code. O objetivo era montar um ranking dos melhores jogadores por posição a cada rodada da Copa do Mundo de 2026. O resultado final desse trabalho — a seleção da 1ª rodada e a régua de cada posição — foi publicado em "Cada posição tem a sua régua: a seleção da 1ª rodada da Copa". O que segue é o bastidor: reconstrói o que aconteceu na sessão, na ordem em que aconteceu, com os becos sem saída, os bugs e as decisões tomadas ao longo do caminho.

O objetivo da sessão

O ponto de partida que dei ao agente foi: criar uma estrutura de dados que permita avaliar os melhores jogadores em cada posição da rodada e montar a seleção, de forma reaproveitável para as rodadas seguintes.

Na prática, isso virou um pipeline: pegar os relatórios oficiais da FIFA da primeira rodada, cruzar com estatísticas individuais de jogadores, classificar cada um na posição que de fato ocupou em campo, criar fórmulas de avaliação por posição e, no fim, montar a seleção da rodada. Não foi linear. O relato abaixo segue o que de fato aconteceu.

O primeiro beco sem saída: os PDFs que não baixavam

A primeira tarefa era trivial no papel: baixar os 24 relatórios em PDF da fase de grupos do hub do FIFA Training Centre. O agente fez o fetch da página, listou os 24 jogos da rodada corretamente e partiu para o download. E aí veio o primeiro muro.

Todos os arquivos retornavam código HTTP 000. A primeira leitura do agente foi razoável: código 000 costuma significar conexão bloqueada por sandbox de rede. Mas a hipótese estava incompleta. O agente seguiu investigando, e o diagnóstico real só apareceu quando ele rodou um nslookup no host de onde estava tentando baixar: media.fifatrainingcentre.com retornava NXDOMAIN. O subdomínio simplesmente não existia.

O que tinha acontecido é instrutivo: a URL dos PDFs tinha sido inferida a partir do resumo da página, e o host media. foi essencialmente alucinado. A correção foi voltar ao HTML cru com curl, fazer um grep nos href e descobrir que os links reais estavam no mesmo host da página (www.fifatrainingcentre.com/media/...), inclusive com espaços nos nomes dos arquivos. A partir daí, os 24 PDFs baixaram a 200, cada um com seus cinco e poucos megabytes, renomeados para um esquema limpo do tipo M07-BRA-V-MAR.pdf.

Atribuição: tudo nesta etapa foi do agente. Minha única instrução tinha sido "criei uma pasta chamada copa-2026/rodada-1, baixe os relatórios e coloque lá". O código 000, o nslookup, o diagnóstico do NXDOMAIN e a descoberta das URLs reais aconteceram sem nenhuma intervenção minha.

Escolhendo a fonte de dados: o bake-off

O PDF da FIFA é rico em estatísticas de equipe, mas pobre em dados individuais detalhados. Para avaliar jogador por jogador eu precisava de outra fonte. Em vez de eu decidir no escuro, fizemos um pequeno bake-off entre bibliotecas.

Testamos primeiro a soccerdata. O agente, para crédito dele, reconheceu um erro próprio no meio do caminho: tinha afirmado que a 1.9.0 trazia um reader do FotMob, e não trazia. Partimos para o reader do FBref, que funcionou, encontrou a partida e devolveu 32 jogadores. Mas a limitação ficou clara: para a Copa, o FBref expõe só o box score básico, sem xG, sem rating, sem mapa de calor. E ele roda em cima de Selenium com chromedriver, o que torna a primeira execução lenta.

Aí pedi para testar a mobfot. Deu 404. O agente foi sondar os endpoints e descobriu que o FotMob tinha migrado a API para outro caminho (/api/data/...), que respondia 200 e, melhor ainda, sem exigir token de anti-bot. O JSON de detalhes da partida vinha com tudo que eu queria: rating por jogador, xG, xGOT, xA, estatísticas categorizadas por bloco (ataque, defesa, duelos, passes), shotmap e coordenadas no campo.

Decisão tomada: FotMob via um cliente próprio e fino, escrito à mão sobre requests, em vez da biblioteca pronta e quebrada. Um cliente de cerca de 400 linhas que eu controlo, em vez de uma dependência de terceiro que já tinha mostrado que quebra quando o provedor muda a rota.

Atribuição: misto. Eu defini quais bibliotecas testar ("me faça um teste utilizando a soccerdata", depois "teste o fluxo usando agora o mobfot"). Toda a parte investigativa foi do agente: reconhecer que a soccerdata não tinha reader do FotMob, mapear a limitação do FBref, levar o 404 da mobfot e descobrir que o FotMob tinha migrado para /api/data/.... A escolha final pelo cliente próprio também partiu do agente. Eu apenas confirmei que era uma boa ideia.

Separação de responsabilidades: o detalhe que o humano precisa cravar

Quando pedi o cliente do FotMob, fui explícito em uma coisa: ele recebe os parâmetros de busca e devolve os dados categorizados dos jogadores, e não acopla com os PDFs. O resultado foi um módulo independente, com um schema próprio para o jogador (identidade, posição, contexto de jogo, estatísticas categorizadas, shotmap, coordenadas), testável pela linha de comando, sem nenhum conhecimento sobre a FIFA.

Esse cuidado pagou de novo logo adiante. Ao construir o extrator do relatório da FIFA, o agente começou a querer reaproveitar um script de extração que já existia no projeto. Eu interrompi mais de uma vez para cravar a fronteira: aquele script era o extrator do Wyscout, e não devia ser tocado; o relatório Post-Match da FIFA é outra coisa e precisa do seu próprio pipeline. Sem essa intervenção, dois formatos de relatório muito diferentes teriam colidido no mesmo código.

Atribuição: intervenção minha. As duas regras desta seção saíram de prompts diretos meus: "esse cliente recebe os parametros... não acople o nosso client com os pdfs" e "mantenha esse extrair_relatorio, ainda vamos ter wyscout, este é um novo pipeline". Sem isso, o agente teria reusado o script existente.

O inferno da extração de PDF

Extrair as tabelas de dados individuais do PDF da FIFA foi a parte mais áspera. Alguns dos problemas concretos que enfrentamos com pdfplumber:

O extract_table() enxergava a caixa do cabeçalho, que tem linhas de grade, mas não as linhas de dados, que não têm grade. E era instável de página para página: em uma página ele pegava um subtítulo de seção em vez do cabeçalho de fato.
A ligadura tipográfica "ff" era renderizada como \x00. A palavra "Offers" virava O\x00ers. Tivemos que casar por substrings em vez do texto completo.
Uma linha espúria entrava na tabela: o cabeçalho de data da partida ("13 June 2026...") tinha o número certo de tokens para se passar por uma linha de jogador.

A solução que se mostrou robusta foi abandonar a tentativa de inferir a estrutura página a página e cravar os schemas de cada seção em código, já que o template da FIFA é estável. Cada seção passou a ter sua lista exata de colunas, e cada linha só era aceita se batesse a contagem de tokens esperada e os valores fossem numéricos por regex. A linha espúria da data morreu nesse filtro. Resultado final: 32 jogadores por jogo, três seções completas.

Atribuição: do agente. Dentro da fronteira que eu já tinha cravado (pipeline novo, separado do Wyscout), toda a engenharia de extração — o diagnóstico do extract_table(), a ligadura \x00, a decisão de cravar os schemas em código e o filtro por contagem de tokens — foi do agente, sem direcionamento meu.

Rodando a rodada inteira: o off-by-one e os nomes divergentes

Com o jogo do Brasil funcionando, mandei rodar para os 24 PDFs. A extração da FIFA passou em todos. O cruzamento com o FotMob falhou em 12. Dois bugs explicavam quase tudo:

Primeiro, um off-by-one de fuso horário. A data na capa do relatório da FIFA estava um dia antes da data que o FotMob usa para a mesma partida. A correção foi fazer a busca da partida com uma janela de mais ou menos um dia em torno da data informada.

Segundo, nomes de seleções divergentes entre as fontes. "Korea Republic" contra "South Korea", "IR Iran" contra "Iran", "Côte d'Ivoire" contra "Ivory Coast", "Cabo Verde" contra "Cape Verde". Construímos um mapa de aliases com normalização. E aí um detalhe fino quase passou: o apóstrofo de "Côte d'Ivoire" normaliza para espaço, então a chave do alias precisava ser exatamente "cote d ivoire", com o espaço, não "cote divoire". Sem perceber esse detalhe, a Costa do Marfim continuava falhando depois de todo o resto consertado.

Fechamos em 24 de 24 jogos, 753 jogadores, 100% casados, zero avisos. E aqui entrou uma etapa que eu valorizo muito: a validação. O agente cruzou os sobrenomes da FIFA contra os do FotMob em todos os jogadores casados e reportou "123 jogadores casados, zero cruzamentos de nome". O casamento era feito por (lado, número da camisa), e essa checagem independente confirmou que a junção estava correta.

Atribuição: do agente. Eu só dei a partida ("próxima etapa do pipeline é rodar a extração do json para todos os jogos") e deleguei explicitamente a decisão de paralelizar — o agente escolheu rodar sequencial. O off-by-one de fuso, o mapa de aliases, o detalhe do apóstrofo de "Côte d'Ivoire" e a validação cruzada de sobrenomes foram todos do agente.

Classificação de posição: onde o "taste" virou arquitetura

A "posição" do FotMob é grossa demais para o meu objetivo: ela só diferencia goleiro, defensor, meio e atacante. Eu queria a seleção por posição fina, (GK, CB, LB, RB, DM, CM, AM, W, CF). A estratégia que combinamos foi em camadas: um motor que decodifica a posição fina a partir do position_id e das coordenadas reais dos jogadores; um fallback por zona do campo para casos não vistos; e uma camada de override editorial, um JSON onde eu corrijo manualmente o que a máquina errou, com a maior precedência.

O ponto mais interessante foi a fronteira entre primeiro volante (DM) e meia (CM). A lógica puramente posicional colocava só 14 jogadores como volantes, e jogava verdadeiros primeiros volantes, como Casemiro, na categoria de meia, porque eles jogam adiantados no campo. A ideia de como resolver isso foi minha, mas a execução foi do agente: e se a gente escolher os jogadores de meio de campo e fizer a inferência via LLM? Para cada um, perguntar se ele é primeiro volante, segundo volante ou armador, com base no dossiê de ações dele naquele jogo, e gravar esse mapeamento em um arquivo de consulta.

Foi o que fizemos. Geramos um dossiê por meio-campista (coordenadas, ações defensivas, quebras de linha, chances criadas, xA, toques) e despachamos seis subagentes em paralelo para classificar cada um em DM, CM ou AM, com nível de confiança e justificativa. A distribuição saiu realista: 46 volantes, 74 meias, 45 armadores. A precedência final do classificador ficou: override manual, depois papel inferido por LLM, depois position_id, depois zona, depois a linha grossa.

Tem uma indecisão minha aí que eu acho honesto registrar. Em um momento perguntei se o mapeamento de papéis não valeria para a Copa inteira em vez de por rodada. O agente mudou para Copa inteira. Eu repensei e voltei atrás: melhor por rodada, porque o papel de um jogador pode mudar de jogo para jogo. O agente reverteu sem ruído, e o arquivo de papéis passou a viver dentro da pasta da rodada.

Atribuição: misto, e este é o ponto. A taxonomia de siglas foi proposta pelo agente e aprovada por mim. A estratégia em camadas era uma recomendação que o próprio agente tinha feito antes e que eu resgatei ("lá atrás você tinha sugerido isso aqui: A como motor, B para validar, C para correções"). A ideia de inferir o papel do meio-campo via LLM foi minha ("e se a gente escolher esses jogadores de meio de campo e fizermos a inferência via llm"), assim como a definição do escopo e a escolha de fazer por rodada. A implementação dos dossiês e dos subagentes foi do agente.

O bug sistemático que só uma pergunta humana pegou

Esse episódio é o que melhor resume a tese. Em algum momento eu perguntei, simplesmente: "Paquetá ficou onde?". O agente foi olhar e ele tinha sido classificado como lateral-direito, ranqueado entre os laterais. Paquetá é ponta. Errado.

A investigação revelou que não era um caso isolado. O slot largo da direita misturava laterais (defensores) e pontas (meias e atacantes) sob o mesmo position_id. Trinta e seis jogadores estavam no balde errado, incluindo Raphinha classificado como lateral-esquerdo. A correção foi desambiguar os slots largos ambíguos pela linha do jogador: se a linha é meio ou ataque, é ponta; se é defesa, é lateral. O pool de pontas saltou de 80 para 116, e Hakimi, que joga de fato como lateral, corretamente continuou lateral.

A natureza do erro vale o registro. Não era um crash nem um teste vermelho. Era um ranking que estava perfeitamente "verde", rodando, gerando JSON bonito, e silenciosamente errado para 36 jogadores. Nenhum assert teria pego isso. O que pegou foi uma pergunta de sanidade sobre um caso que eu conhecia.

Atribuição: misto, com papéis bem separados. Quem expôs o bug fui eu, com uma única pergunta ("paquetá ficou onde?"). Quem descobriu que eram 36 jogadores no balde errado e implementou a desambiguação por linha foi o agente.

A pontuação: camada editorial em JSON, mecânica em Python

Para a avaliação, a arquitetura que combinamos separa de propósito duas coisas. A camada editorial fica em JSON: os pesos de cada métrica e o tempo mínimo de jogo por posição, que são decisões de gosto e podem mudar a cada conversa. A mecânica fica em Python: o registro de métricas e o motor de pontuação, que não muda.

A normalização padrão é por percentil dentro do grupo da posição naquela rodada, com soma ponderada de 0 a 100. O agente foi honesto sobre o trade-off do percentil já na explicação: ele mede ordem, não magnitude, e por isso achata os extremos. Construímos as fórmulas uma posição de cada vez, e cada uma foi calibrada contra o ranking real, comigo olhando se o resultado fazia sentido.

O momento mais didático foi o dos pontas. Eu reclamei: "Messi fez 3 gols. Como é que alguém fica na frente dele no ranking?". O agente investigou e encontrou uma falha de método, não de peso. Sob percentil, três gols ficavam quase empatados com um gol, porque o percentil só enxerga a ordem: quem fez mais, fez mais, sem importar o quanto a mais. A correção foi tornar a normalização configurável por métrica e aplicar min-max (que preserva magnitude) a gols e assistências, mantendo percentil no resto. Messi subiu para primeiro. E o agente apontou o custo simétrico da escolha: quem fez um gol só perdeu posições.

Essa sequência teve várias intervenções minhas que mudaram o método, não só os números. Quando sugeri valorizar drible, e depois percebemos que drible isolado não diz muita coisa porque o que importa é o progresso do jogo, tiramos a métrica de drible solto. Quando perguntei se existia métrica para bola perdida no drible, adicionamos uma taxa de insucesso de drible contando negativamente.

Atribuição: misto. As decisões editoriais foram minhas, uma a uma — a divisão de pesos por posição, valorizar gol feito, tirar o drible solto, punir bola perdida. A análise que mostrou por que três gols quase empatavam com um gol sob percentil, e que levou ao min-max, foi do agente, em resposta à minha reclamação sobre o Messi. A mecânica do motor (registro de métricas, normalização configurável) foi do agente.

Duas óticas: por 90 minutos e dados brutos

Perto do fim, ao olhar Casemiro ranqueado entre os volantes, desconfiei de um efeito de amostra: ele jogou 45 minutos, e as métricas por 90 inflavam o volume dele, projetando seis ações defensivas como doze. Pedi para a seleção operar em duas óticas: por 90 minutos e considerando só os dados brutos. Implementamos um modo global em que só as métricas de volume mudam entre as óticas; taxas como porcentagem de passe e totais absolutos como gols evitados não mudam. Na ótica bruta, Casemiro caiu para 27 de 41 e Enzo Fernández assumiu a vaga de volante, confirmando a suspeita.

Atribuição: a desconfiança e o pedido foram meus, a partir de "casemiro tá em 5 de 41?" e "tem como a gente ter o script que extrai os jogadores da seleção operando por duas óticas". A implementação do modo global e a decisão de quais métricas mudam entre as óticas foram do agente.

Empacotando a jornada em skills

No fim, transformamos o pipeline inteiro em skills reaproveitáveis do Claude Code, porque o objetivo sempre foi servir as próximas rodadas, não só a primeira. Ficaram três: uma para preparar a rodada (que orquestra a extração, a classificação de posição, o dossiê do meio e a inferência de papéis por LLM), uma para gerar o ranking dado o minuto de corte e a ótica, e uma para filtrar um time específico de um ranking. A configuração editável ficou em JSON; a mecânica, em Python; o extrator do Wyscout, intocado.

A seleção da primeira rodada, com corte de 45 minutos, saiu com Beach no gol, Hakimi e Castagne nas laterais, Singo e Olivera na zaga, Schlager de volante, Bentancur de meia, Pedri de armador, e Messi, Haaland e Luis Díaz na frente.

Atribuição: o pedido de transformar o pipeline em skills foi meu, skill por skill. A estrutura de cada uma e o código foram do agente.

Onde o humano importou

Se eu tivesse que resumir onde o meu trabalho foi insubstituível nessa jornada, não seria em escrever código. O agente escreveu mais e mais rápido do que eu escreveria, e diagnosticou problemas de rede e de API numa velocidade que eu não tenho. O meu papel foi outro:

Não aceitar o primeiro diagnóstico plausível e deixar a investigação descer até a causa real.
Cravar fronteiras de design que o agente, otimizando para a tarefa imediata, tende a borrar (o extrator do Wyscout que não se mistura com o da FIFA, o cliente do FotMob que não acopla com PDF).
Fazer perguntas de sanidade ancoradas em domínio que expõem erros sistemáticos e silenciosos ("Paquetá ficou onde?").
Tomar as decisões editoriais sobre o que importa (o que é ser um bom ponta, percentil ou magnitude, por 90 ou bruto) e julgar se o resultado bate com a realidade.

Nenhuma dessas coisas é sobre digitar código. Todas são sobre julgamento, fronteira e taste. É exatamente esse tipo de habilidade que fica em primeiro plano quando se trabalha sério pareando com um agente de código: você para de ser quem digita e passa a ser quem decide, interroga e responde por estar certo. E essa, para mim, é a competência que vale a pena treinar de propósito agora.

Abraço,
Alberto

PS: este post foi gerado pelo agente de marketing a partir de um log exportado de uma sessão de trabalho minha com o Claude Code, e revisado por mim.

Quanto guideline um agente de código precisa?

Alberto Luiz Souza — Mon, 15 Jun 2026 01:32:34 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quanta configuração um agente de código realmente precisa para gerar bom código? Essa é a pergunta que eu venho tentando responder na prática, e ela faz parte de uma busca maior: até onde dá para minimizar o ser humano no loop da produção de código a partir de uma necessidade.

Para começar a entender isso, montei um experimento. Peguei o mesmo backlog e pedi para que ele fosse implementado por quatro versões de agente, cada uma com um nível diferente de harness, ou seja, o conjunto de configuração e guideline ao redor do agente. A ideia era simples: será que um agente com pouca configuração gera algo muito diferente de um agente com muita configuração, ou com diferentes granularidades de configuração? Neste post eu mostro o desenho do experimento, os resultados e o que eu concluí até agora.

O contexto: minimizar o humano no loop

A plataforma onde hoje servimos os conteúdos do Dev + Eficiente foi integralmente desenvolvida com apoio de agentes baseados em IA generativa. Tanto o back-end quanto o front-end foram construídos com o Claude Code como principal agente, num trabalho que eu fiz junto com Anderson. Nessa rotina, a pergunta que não para de aparecer é até onde dá para revisar o mínimo possível de código.

Esse tema não é só meu. Se você for ao blog da Anthropic, vai encontrar um post de 24 de março de 2026 chamado "Harness Design for Long-Running Application Development", onde uma engenheira descreve uma configuração que você ouve bastante por aí: um agente planejador, um agente gerador e um agente avaliador, rodando em sessões separadas, com o gerador e o avaliador colocados um contra o outro para maximizar a qualidade gerada. No blog da OpenAI tem um post de 11 de fevereiro de 2026, "Harness Engineering: Leverage Codex in an Agent-First World", contando sobre um app cuja restrição era que todo o código fosse desenvolvido pelo agente. Cada empresa conta a sua história. Foi a partir dessas inspirações, e da minha própria experiência, que tentei montar algo o mais próximo possível de um experimento isolado: mesmo input, configurações diferentes.

O desenho do experimento

Peguei o backlog de um desafio que temos na Jornada Dev + Eficiente: implementar o processo de checkout da Hotmart. São dez tarefas, com níveis de complexidade diferentes. A proposta foi implementar esse backlog de uma vez só, com quatro versões de configuração diferentes:

Sem guideline nenhum. Só um prompt inicial de entrada definindo a condição de parada. Nada além disso. É uma implementação baseada unicamente no que o modelo aprendeu no treinamento e no que ele consegue produzir em função do que pedi.
Apenas o CLAUDE.md. Extraí um CLAUDE.md da plataforma Dev + Eficiente. Ali estão os guidelines de back-end, os padrões de design, o padrão para testes, o padrão para geração de log e o esquema que eu uso para deixar a geração de log mais sistemática.
CLAUDE.md mais uma skill revisora de código. A skill tem categorias de checagem: língua e nomenclatura, padrões de design do domínio, padrões de design das bordas mais externas, como olhar para controllers que lidam com requisições HTTP, como lidar com testes e como olhar para logs.
CLAUDE.md mais múltiplos agentes revisores de granularidade ultrafina. Aqui são vários revisores especializados, cada um com um recorte: um revisor que olha a complexidade do código usando o CDD, que enxerga complexidade pelo viés do esforço cognitivo para entender o código; um revisor de controller, com as práticas que eu defendo para essa camada; um revisor de bordas externas, olhando os objetos de transporte; um revisor de design para domínio, linguagem e log; e uma skill orquestradora que conversa com as outras.

Faltou uma quinta versão, que seria fazer tudo de fato em sessões separadas, isolando o contexto e reiniciando a sessão a cada etapa, como descreve o post da Anthropic. Essa fica para um próximo vídeo.

Todas as versões rodaram com o Opus 4.7, no Claude Code. As duas perguntas centrais eram: o design de código produzido teria alguma diferença marcante entre as quatro configurações? E os testes gerados teriam alguma diferença relevante?

Tirando o meu viés: CodeScene

Para avaliar a qualidade do design eu quis tirar o meu viés. Por mais que existam diretrizes de qualidade, eu tenho opinião sobre o que é um código que envelhece melhor, e queria afastar isso da análise. Joguei a avaliação para uma ferramenta especializada em análise de qualidade. Poderia ter usado um SonarQube da vida, mas optei pela CodeScene, cujo criador eu acompanho no LinkedIn e cuja visão eu gosto. Paguei um mês, subi os projetos em repositórios privados no GitHub e pedi para analisar.

Vale lembrar uma limitação importante do experimento: foram dez tarefas, é o início da coisa, um cenário greenfield. Os problemas de código geralmente não aparecem no início. Eles aparecem na continuação, quando o sistema vai envelhecendo, as pessoas que mexem nele vão rotacionando e, nessa rotação, contexto vai se perdendo. As alterações passam a ser feitas sem conseguir levar em conta o máximo de variáveis relevantes. Um experimento ainda mais interessante seria comparar humano contra máquina ao longo do tempo, e isso está por vir.

Resultado 1: o super guideline quase não mexeu no design

A métrica que a CodeScene usa é o Code Health. Os números foram estes:

Sem guideline nenhum: 9.93
Apenas CLAUDE.md: 9.93
CLAUDE.md mais skill revisora: nota menor (a diferença não foi relevante para o Code Health, mas saiu abaixo)
CLAUDE.md mais agentes revisores ultrafinos: 9.85

Todas as versões saíram saudáveis. E o ponto que mais me chamou atenção: o meu super guideline de código não fez grande diferença na produção, pelo menos nesta primeira leva. A versão sem guideline nenhum empatou com a versão só com CLAUDE.md e ficou acima das versões com os agentes revisores.

Minha hipótese para isso é a seguinte. Esse tipo de ferramenta está olhando para padrões muito bem estabelecidos: nível de acoplamento, tamanho de método, coesão. São temas amplamente discutidos, com bastante material de qualidade, nacional e internacional, espalhado pela internet. O modelo está muito bem treinado nesses padrões. A heurística para tamanho de método, por exemplo, já está consolidada. Quando o assunto é tão consolidado assim, dar um guideline extra não muda tanto o resultado.

A diferença de design que apareceu

A diferença principal de design entre as versões está na forma de tratar o controller. O código gerado sem guideline seguiu o que parece ser a tendência mais comum hoje: o controller como um adaptador, no sentido da arquitetura limpa. Ele recebe o que vem de fora e chama um AccountsService, que supostamente cuida daquele caso de uso e pode ser reaproveitado por diversos adaptadores. O problema é que esse serviço acaba ganhando um monte de métodos auxiliares, e não fica claro de onde cada um é chamado.

No código gerado com o meu guideline, o controller é basicamente o próprio caso de uso. Eu direciono tudo para o controller, que é o entry point principal daquele caso de uso. Para mim, isso funciona bem e diminui o número de arquivos de um jeito que não prejudica. Foi a diferença mais visível, mas, do ponto de vista do Code Health, ela não foi brutal.

Outras práticas que eu defendo num guideline de design apareceram no código guiado, mesmo sem mudar muito a nota:

Construção de objetos pelo construtor, com as informações obrigatórias, para minimizar a chance de esquecer de definir algo e reduzir a necessidade de classes intermediárias como builders.
Evitar retorno nulo. Em Java não há um tratamento de nulo tão interessante quanto o de outras linguagens, então eu prefiro Optional quando existe possibilidade de retorno vazio. O Optional não garante nada, mas coloca uma guarda a mais: a semântica dele diz que eu deveria checar antes de usar.
Logs sistemáticos, com registro antes e depois de alterar o estado.

São práticas que, para uma equipe, fariam diferença. Mas a pergunta que fica é: dado que o treinamento do modelo não muda de forma bizarra de uma versão para outra para práticas tão consolidadas, eu preciso me preocupar tanto com isso a médio prazo? Talvez o design do código caminhe para algo mais parecido com código compilado: ninguém se preocupa com como o Java é compilado para rodar na máquina virtual, porque as heurísticas de otimização já são muito boas. Pode ser que parte do design de código vá pelo mesmo caminho.

Resultado 2: a diferença real está nos testes

Aqui o experimento ficou mais interessante. No código gerado sem guideline nenhum, os testes vieram com poucas assertions. Pega um teste de fluxo de checkout: a resposta traz o e-mail do cliente, o valor total, o número de parcelas, o status da compra. O teste chamava o método de checkout passando a request e verificava apenas se o valor estava em 80. Não verificava se a compra rolou com uma parcela só, não verificava se a oferta certa foi aplicada. Em outro caso, verificava só que o status falhou, sem checar se falhou com as informações corretas. Uma compra pode falhar por diversos motivos. Um teste com poucas assertions é um sinal de teste mais frágil, que mais facilmente encobre um bug no código.

Já o código gerado com o meu guideline levou os testes todos para integração: subir o servidor, tocar o sistema a partir da entrada normal, aproximar a execução do teste da realidade. Esse é o tipo de teste que eu costumo priorizar, em vez de partir direto para testes de unidade com muito mock. O fluxo era exercitado de verdade, com @SpringBootTest.

Por que o agente sem guideline gera testes piores? A minha explicação é simples: a qualidade dos testes que as pessoas escrevem por aí é pior do que a qualidade do código que elas escrevem. Logo, o modelo está pior treinado para testes, e o output padrão dele para testes é pior. Tão direto quanto isso.

Minimalismo: dar a instrução suficiente

Esse experimento me manteve em uma linha que minha experiência já vinha apontando. Eu uso agentes em múltiplos contextos diferentes, e uma coisa se mantém: não é sobre tentar dar muita instrução e configurar exaustivamente, é sobre dar a instrução suficiente. Isso está mais perto de uma postura minimalista do que de espalhar a configuração por vários arquivos.

No post da OpenAI, dá para ver o tanto de arquivos que eles mantêm para o harness: um tracker, um arquivo de core beliefs, um índice que aponta para os outros, as specs, e referências separadas em arquivos de design, front-end, product center, quality score, reliability, security. É uma divisão super fina. O post da Anthropic, que é mais recente, já não tem essa fragmentação toda. Estou usando como referência justamente as empresas que criam as ferramentas que a gente usa, e a leitura que faço é que o caminho minimalista vem se sustentando. O modelo está ficando cada vez melhor nas inferências, e o próprio agente em questão(Claude Code, Codex etc) já tenta montar parte do harness para você nos seus arquivos internos.

O que ainda está em aberto

Eu continuo em dúvida sobre quanto de harness preciso construir para ter, de forma recorrente, um output interessante o suficiente para minimizar o meu esforço de revisão, ou até para, em algum momento, decidir não revisar mais.

Tem uma reflexão que vale a pena. Quando recebemos uma especificação muito bem descrita, a gente escreve teste em boa parte para ganhar confiabilidade e ter rede contra regressão. Eu não botaria a mão no fogo que codaria uma task complexa sem nenhum bug. Mas talvez a taxa de erro de um agente para uma tarefa muito bem definida seja menor do que a minha. Se a taxa de erro de partida já é menor, talvez o teste possa ser um pouco menos robusto, porque o código já chega mais confiável. Isso não é uma conclusão, é uma hipótese que precisa ser testada. Senão fica fácil continuar sentado sobre as nossas crenças e nunca experimentar nada diferente para ver onde quebra.

O próximo passo que pretendo fazer é gerar feature requests para esses mesmos sistemas durante algumas semanas, colocando as quatro configurações para implementar cada uma do seu jeito, e acompanhar como a coisa evolui. Outra possibilidade é montar um experimento de pesquisa de verdade: pessoas implementando com o agente, agentes super autônomos implementando, e comparar primeiro a corretude e depois a qualidade do resultado.

Conclusão

Pelo menos nesta primeira leva, mais guideline não melhorou o design do código de forma relevante. Para padrões muito consolidados, o modelo já chega bem treinado, e a configuração extra rende pouco. A diferença que realmente apareceu foi nos testes: sem guideline, eles vieram frágeis, com poucas assertions; com guideline, vieram como testes de integração exercitando o sistema de verdade. Isso reforça a importância de direcionar o agente justamente onde o output padrão dele é mais fraco.

A minha aposta, por enquanto, segue minimalista: dar a instrução suficiente, em vez de espalhar configuração por muitos arquivos. Mas é só uma fotografia de um experimento inicial, em cenário greenfield. O que importa é continuar experimentando no seu próprio contexto para descobrir onde o agente acerta sozinho e onde ele precisa de direção.

Dev + Eficiente

O que 14 estudos revelam sobre o papel do humano quando a IA escreve o código

Alberto Luiz Souza — Mon, 08 Jun 2026 09:11:14 +0000

1. Introdução

A engenharia de software atravessa um momento de transformação através da integração de modelos de linguagem de grande escala e ferramentas de Inteligência Artificial generativa. Segundo Abbas et al. (2025), a motivação em torno dessas tecnologias baseou-se na automação avançada que poderia modificar a produtividade em todo o ciclo de vida do desenvolvimento, desde a análise de requisitos até a refatoração de código. Os estudos como o de Molison et al. (2025) mostram que assistentes inteligentes oferecem ganhos de eficiência, atuando como suportes cognitivos que aceleram a resolução de problemas de complexidade baixa a moderada. No entanto, a premissa mercadológica de que a máquina poderia substituir integralmente o trabalho intelectual do programador tem sido contestada pela literatura recente.

A transição do uso teórico para a aplicação prática em ambientes corporativos evidencia que o código gerado de forma autônoma ainda carrega falhas críticas e limitações de contexto. Pesquisas empíricas conduzidas por Cotroneo et al. (2025) e Lertbanjongngam et al. (2022) mostram que a Inteligência Artificial, quando opera sem a devida revisão, tende a introduzir vulnerabilidades de segurança e problemas de manutenibilidade estrutural. Diante desse cenário, a comunidade científica e a indústria trazem um paradigma focado não na substituição, mas na colaboração direta entre humanos e máquinas. Conforme argumenta Baranetska (2025), a qualidade e a segurança do software moderno dependem de sistemas híbridos, onde a capacidade da máquina de processar informações em escala é complementada pela supervisão humana, que atua como guardiã ética e avaliadora de casos imprevisíveis.

Contudo, orquestrar e medir essa parceria trazem desafios comportamentais. O estudo de Qian e Wexler (2024) evidencia que o sucesso da colaboração pode ser ameaçado pela confiança apenas na automação, um fenômeno no qual os desenvolvedores aceitam as saídas da máquina devido ao excesso de confiança, negligenciando a validação analítica. Em consonância com essa preocupação, Weisz et al. (2022) e Dibia et al. (2022) destacam que a avaliação do trabalho conjunto exige a inclusão das métricas técnicas. Torna-se imprescindível quantificar o esforço real, a carga cognitiva e o nível de confiança exigidos do desenvolvedor para compreender e corrigir as sugestões da ferramenta.

Nesse contexto, compreender a dinâmica dessa interação humana e LLMs tornou-se o foco de investigação para a consolidação de fluxos de trabalho. Com o propósito de elucidar esse panorama, este documento investiga de forma estruturada a intersecção entre a LLMs e o esforço colaborativo com o Humano. Diante desse cenário, este estudo é orientado pela seguinte questão principal: Quais atividades do ciclo de desenvolvimento de software têm sido investigadas empiricamente no contexto de IA com e sem supervisão humana? Para respondê-la, o estudo foi organizado em três subperguntas:

RQ1. Quais métricas têm sido utilizadas para avaliar o impacto da supervisão humana no desempenho de atividades de engenharia de software assistidas por IA?
RQ2. Quais características individuais dos desenvolvedores são consideradas como variáveis nos estudos primários (senioridade, experiência profissional, experiência prévia com IA e percepção/ceticismo em relação à IA)?
RQ3. Em quais condições a supervisão humana melhora os resultados de sistemas de IA em tarefas de engenharia de software?
RQ4. Quais ferramentas de LLM têm sido utilizadas pelos desenvolvedores nos estudos?
RQ5. Como o tipo de tarefa de engenharia de software influencia os efeitos da supervisão humana sobre qualidade e produtividade?

Portanto, o objetivo deste trabalho é consolidar e analisar as evidências disponíveis sobre a interação entre humanos e IA relacionadas às atividades do desenvolvimento de software.

2. Metodologia

Inicialmente, foi definida a pergunta de pesquisa e, a partir dela, elaborou-se a string de busca com base nos principais termos do problema investigado e em seus sinônimos.

Em seguida, foi conduzida uma busca automatizada na base da IEEE, utilizando a string previamente definida. Essa busca retornou um total de 277 estudos.

Na etapa seguinte, realizou-se a leitura dos resumos dos artigos encontrados, com aplicação dos critérios de inclusão e exclusão estabelecidos no protocolo da revisão. Como resultado dessa triagem inicial, 16 estudos foram considerados aptos para a fase subsequente.

Posteriormente, os estudos selecionados passaram por leitura completa, o que permitiu avaliar sua aderência ao objetivo da pesquisa. Ao final dessa etapa, apenas 1 estudo atendeu aos critérios estabelecidos e foram selecionados a partir da busca automatizada.

Além disso, utilizou-se a ferramenta ELICIT (https://scispace.com/) com a sua funcionalidade de busca de papers como estratégia complementar de busca, a partir da aplicação do seguinte prompt:

RQ: Which software development lifecycle activities have been empirically investigated in the context of AI with and without human supervision?

A busca na ferramenta foi realizada com base na análise do título e do resumo dos 100 primeiros registros retornados. Nessa etapa, foram inicialmente selecionados 21 artigos. Posteriormente, esses estudos também passaram por leitura completa, permitindo avaliar sua aderência ao objetivo da pesquisa. Ao final dessa etapa, 6 estudos atenderam aos critérios estabelecidos e foram selecionados.

Também foi realizada uma busca manual no Google Scholar onde foram selecionados 45 artigos, e após a leitura completa e aplicado os critérios de inclusão e exclusão, foram selecionados 7 artigos. Dessa forma, a amostra final foi composta por 14 artigos totais.

Critérios de inclusão

Atividade de Engenharia de Software: Incluir estudos que permitam identificar claramente a atividade investigada, como requisitos, codificação, code review, testes, debugging, manutenção, documentação, DevOps, segurança, design ou arquitetura.
Supervisão humana: Incluir estudos que permitam classificar o uso da IA como com supervisão humana, sem supervisão humana ou ambos.
Incluir estudos que apresentem dados, como experimentos, estudos de caso, surveys, estudos observacionais, análises de repositórios, avaliações de ferramentas e revisões sistemáticas.
Período: Incluir estudos publicados entre 2022 e 2025.
Idioma: Incluir estudos publicados em inglês ou português.

Critérios de Exclusão

Fora da Engenharia de Software: Excluir estudos cujo foco principal não seja uma atividade do ciclo de desenvolvimento de software.
Atividade não identificável: Excluir estudos que não indiquem claramente qual atividade de Engenharia de Software foi investigada.
Supervisão não identificável: Excluir estudos que não permitam classificar o uso da IA como com ou sem supervisão humana.
Excluir estudos conceituais, opinativos ou teóricos sem dados empíricos ou revisões sistemáticas.
IA fora do escopo: Excluir estudos sobre automação tradicional, ferramentas rule-based ou análise estática sem componente de IA.
Tipo de publicação não elegível: Excluir editorial, position papers, keynotes, tutoriais, blogs, whitepapers sem método, slides, resumos curtos.
Fora do período: Excluir estudos publicados antes de 2022 ou depois de 2025.
Idioma fora do escopo: Excluir estudos que não estejam em inglês ou português.
Duplicatas: Excluir duplicatas ou versões preliminares quando houver uma versão mais completa do mesmo estudo.

String de Busca

("software development" OR "code generation" OR "code review" OR debugging OR
"bug fixing" OR "test generation" OR "software testing" OR refactoring OR
"software maintenance" OR "code comprehension")
AND
("human-in-the-loop" OR "human oversight" OR "human supervision" OR
"human feedback" OR "developer oversight" OR "developer intervention" OR
"AI supervision" OR "task allocation" OR "division of labor" OR
"human-AI collaboration")

3. Resultados

3.1 Quais métricas têm sido utilizadas para avaliar o impacto da supervisão humana no desempenho de atividades de engenharia de software assistidas por IA?

As métricas adotadas pela literatura para mensurar a colaboração e a supervisão humana em Engenharia de Software são apresentadas na tabela abaixo com seus respectivos estudos:

Categoria da Métrica	Descrição e Indicadores Específicos
Produtividade	Tempo total de conclusão em Qian et al. (2024), Wang et al. (2024), Ibrahim et al. (2025) e Weisz et al. (2022); "Human Involvement" (%) em Pangavhane et al. (2024); linhas de código retidas/removidas em Nascimento et al. (2023); quantidade de refatorações em Mo et al. (2025); tempo de resposta em Lertbanjongngam et al. (2022).
Qualidade, Correção e Manutenibilidade	Similaridade sintática em Dibia et al. (2022) e Lertbanjongngam et al. (2022); complexidade ciclomática e vulnerabilidades de segurança em Cotroneo et al. (2025); esforço de correção de bugs em Molison et al. (2025).
Colaboração	Índice de Precisão Colaborativa e Taxa de Validação Humana em Baranetska (2025); ações Fix it/Take it, confiança correta vs. incorreta e complacência de automação em Qian e Wexler (2024).
Carga Cognitiva	Demanda mental, frustração e esforço em Wang et al. (2024) e Weisz et al. (2022); valor e acurácia percebidos em Dibia et al. (2022); escalas Likert de utilidade e clareza em Ibrahim et al. (2025) e Lyu et al. (2025).

Figura — Distribuição das métricas por quantidade de artigos:

Categoria	Quantidade de Artigos
Produtividade	8
Carga Cognitiva	5
Qualidade, Correção e Manutenibilidade	4
Colaboração	2

Observa-se que a categoria de Produtividade reúne o maior número de fontes associadas. Essa predominância indica que grande parte das pesquisas foca em indicadores objetivos de desempenho para avaliar o impacto da Inteligência Artificial. Autores como Pangavhane et al. (2024) medem o percentual de envolvimento humano nas tarefas. Qian e Wexler (2024), Wang et al. (2024), Ibrahim et al. (2025) e Weisz et al. (2022) priorizam o tempo total de conclusão. Indicadores complementares incluem as linhas de código mantidas ou removidas, aplicadas por Nascimento et al. (2023), e o tempo de resposta de execução (runtime), avaliado por Lertbanjongngam et al. (2022). O volume de refatorações também atua como métrica de eficiência no estudo de Mo et al. (2025).

A segunda categoria mais recorrente é Qualidade, Correção e Manutenibilidade. Esse resultado evidencia a preocupação em garantir a viabilidade técnica dos artefatos, não focando apenas na velocidade de desenvolvimento. Dibia et al. (2022) e Lertbanjongngam et al. (2022) aplicam métricas de similaridade sintática. Para a análise estrutural, Cotroneo et al. (2025) cruzam a complexidade ciclomática com a presença de vulnerabilidades de segurança. Já o esforço prático necessário para a correção de bugs é avaliado detalhadamente na investigação de Molison et al. (2025).

A categoria Colaboração indica um interesse emergente na forma como ocorre a interação entre humanos e as ferramentas de IA. Esses estudos avançam além da validação técnica do código e posicionam o desenvolvedor no centro da tomada de decisão. Baranetska (2025) propõe índices sistêmicos, como o Índice de Precisão Colaborativa e a Taxa de Validação Humana. De maneira complementar, Qian e Wexler (2024) mapeiam ações diretas no código, como "Fix it" e "Take it", além de medir a confiança correta e incorreta dos usuários para identificar cenários de complacência de automação.

Por fim, a categoria Carga Cognitiva aborda os aspectos de esforço mental e as percepções exigidas no trabalho de supervisão. Wang et al. (2024) e Weisz et al. (2022) utilizam a escala padronizada NASA-TLX para mensurar dimensões como demanda mental, frustração e esforço temporal. De forma paralela, Dibia et al. (2022) consideram o valor e a acurácia percebidos, enquanto Ibrahim et al. (2025) e Lyu et al. (2025) aplicam questionários em escala Likert para atestar a clareza e a utilidade das respostas geradas pela IA. Embora menos frequente, essa categoria revela que há vasto espaço para aprofundar investigações sobre os impactos cognitivos da automação no trabalho analítico dos profissionais de software.

3.2 Quais características individuais dos desenvolvedores são consideradas como variáveis nos estudos primários (senioridade, experiência profissional, experiência prévia com IA e percepção/ceticismo em relação à IA)?

As características individuais dos desenvolvedores que os artigos apresentam como variáveis para cada pesquisa são apresentadas na tabela abaixo com seus respectivos estudos:

Característica	Abordagem nos Estudos	Artigos relacionados
Percepção Individual sobre IA	Explora o ceticismo, a confiança e se o desenvolvedor acredita que a IA ajuda, mesmo quando os dados objetivos mostram o contrário.	Wang et al. (2024); Lyu et al. (2025); Weisz et al. (2022); Qian e Wexler (2024)
Nível de Expertise como Desenvolvedor	Tratada como variável de comparação em estudos específicos que dividem grupos entre "Novatos" (ou estudantes) e "Especialistas" (ou competidores de alto nível).	Qian e Wexler (2024); Mo et al. (2025); Nascimento et al. (2023)
Experiência Profissional	Frequentemente usada como filtro de seleção (baseline) e não como variável. Os estudos exigem que o participante seja um "programador experiente", mas não comparam Júnior vs. Sênior.	Dibia et al. (2022); Wang et al. (2024); Weisz et al. (2022)
Carga de Trabalho dos Desenvolvedores	Medida quase exclusivamente através da escala NASA-TLX. Avalia o quanto o uso da IA aumenta ou diminui a frustração e a demanda mental.	Wang et al. (2024); Weisz et al. (2022); Qian e Wexler (2024)
Experiência Prévia com IA	Considera o uso anterior de ferramentas (Copilot/ChatGPT) para entender se o "hábito" influencia a aceitação das sugestões.	Lyu et al. (2025); Weisz et al. (2022); Qian e Wexler (2024)
Literacia em IA e Prompting	A habilidade de formular comandos. É identificada como uma barreira: usuários com baixa literacia tendem a aceitar conteúdos errados ou desistir da ferramenta.	Baranetska (2025); Qian e Wexler (2024)

Figura — Características individuais dos desenvolvedores apresentadas como variáveis:

Característica	Quantidade de Artigos
Percepção Subjetiva e Atitude	4
Nível de Expertise	3
Experiência Profissional	3
Carga de Trabalho e Esforço Mental	3
Experiência Prévia com IA	3
Literacia em IA e Prompting	2

Os resultados da pesquisa trazem que as características individuais dos participantes são variáveis que abordam a aceitação e o sucesso da colaboração humano-IA. O grupo de variáveis com maior predominância nos estudos refere-se à percepção subjetiva, atitude e confiança em relação à Inteligência Artificial. Esse dado aborda como o impacto da tecnologia é mediado pela disposição psicológica do desenvolvedor. Por exemplo, Wang et al. (2024) observam que os participantes mantêm uma percepção positiva de que a ferramenta aumenta a produtividade, mesmo quando seus resultados objetivos em tarefas complexas contradizem essa sensação. De maneira complementar, Lyu et al. (2025) mostram que essa atitude não é estática, evoluindo para uma aceitação maior à medida que os desenvolvedores utilizam as ferramentas como parceiros de trabalho ao longo do tempo. Essa calibração da confiança é reforçada por Qian e Wexler (2024), que notam que os usuários tendem a substituir a confiança inicial, de caráter disposicional, por uma confiança baseada no desempenho real após o contato direto com as falhas do modelo.

A eficácia dessa interação está diretamente ligada ao segundo grupo de características mais investigado: a carga de trabalho percebida e o esforço cognitivo, mensurados predominantemente pela escala NASA-TLX. Os achados indicam que, embora a Inteligência Artificial possa reduzir o esforço mental por meio da substituição de esforço, delegando tarefas repetitivas à máquina, ela pode paradoxalmente aumentar a frustração em cenários específicos. Segundo Weisz et al. (2022), o fornecimento de múltiplas opções de solução eleva significativamente a demanda mental e o estresse, pois exige que o humano realize um trabalho exaustivo de comparação e revisão. Tal fenômeno transforma a atividade de produção de código em uma tarefa de revisão de código estrangeiro, o que, conforme discutido por Wang et al. (2024), promove uma sensação de melhor desempenho em problemas simples, mas não reduz a carga de trabalho em tarefas de desenvolvimento de software mais robustas.

Por fim, observa-se que, embora a senioridade e o nível de experiência técnica sejam citados, eles aparecem com menor frequência como variáveis experimentais comparativas, sendo muitas vezes utilizados apenas como critérios de seleção de participantes experientes. No entanto, quando isolada, a especialidade revela-se um fator de equalização. O estudo de Qian e Wexler (2024) destaca que a IA beneficia desproporcionalmente os novatos, ajudando-os a superar barreiras de conhecimento, enquanto os especialistas tendem a ser mais céticos e propensos a rejeitar sugestões algorítmicas em favor de documentações tradicionais. Essa dinâmica é fortemente corroborada por Nascimento et al. (2023), que demonstram a Inteligência Artificial superando programadores novatos em desempenho e eficiência de memória, mas falhando em atingir o nível de programadores de elite em problemas de alta dificuldade.

3.3 Em quais condições a supervisão humana melhora os resultados de sistemas de IA em tarefas de engenharia de software?

As condições melhoradas com a supervisão humana são apresentadas na tabela abaixo com seus respectivos estudos:

Condição / Contexto	Como a supervisão humana melhora os resultados?	Artigos relacionados
Tarefas de Alta Complexidade	O supervisor humano estabelece os modelos conceituais do sistema que a IA não consegue abstrair, fornecendo o raciocínio estratégico necessário em problemas de nível de competição e formulação lógica, onde as ferramentas automatizadas ainda falham.	Wang et al. (2024); Lertbanjongngam et al. (2022)
Refinamento de "Erros Fáceis" e Alucinações	As intervenções manuais servem para sanar rapidamente erros de lógica simples, construções não utilizadas e codificações rígidas que a IA introduz como soluções de contorno, mas que são facilmente corrigidas por um olhar experiente.	Molison et al. (2025); Cotroneo et al. (2025)
Garantia de Qualidade (SQA) e Falsos Positivos	Os humanos interpretam saídas ambíguas e avaliam a relevância contextual para filtrar falhas reais e isolar falsos positivos que costumam enganar o sistema automatizado, além de designarem casos de teste alinhados com regras de negócio.	Baranetska (2025)
Sistemas Críticos e Governança Ética	A supervisão assegura o cumprimento de normas de segurança e princípios éticos organizacionais, aplicando a diretriz de humano-no-comando para evitar decisões catastróficas em setores ultrassensíveis, como saúde ou finanças.	Baranetska (2025); Abbas et al. (2025)
Avaliação de Código	Através de dinâmicas de programação em par com a máquina, o desenvolvedor identifica e corrige vieses e erros do modelo em tempo real, fornecendo o feedback imediato necessário para elevar a qualidade de processos interativos de refatoração.	Mo et al. (2025); Weisz et al. (2022)
Contextualização de Código Legado e Documentação	O profissional captura a real intenção e as nuances de design do código que a máquina ignora, preenchendo lacunas de conhecimento e promovendo o domínio do negócio durante a manutenção de bases antigas onde a documentação original é escassa.	Ibrahim et al. (2025)
Baixa Confiança do Modelo	O humano atua como o validador analítico definitivo quando a IA sinaliza baixos níveis de confiança em suas predições, exercendo uma vigilância necessária para mitigar a complacência de automação e evitar a aceitação cega de erros.	Mo et al. (2025); Qian e Wexler (2024)
Tradução e Conversão de Linguagens de programação	Em traduções complexas, o humano utiliza a saída automatizada não como produto final, mas como um andaime cognitivo ou esboço inicial, focando apenas na correção de erros estruturais e poupando o tempo de reescrever tudo do zero.	Weisz et al. (2022)

Os resultados da pesquisa indicam que a supervisão humana não é apenas um filtro de segurança, mas um componente importante que transforma saídas brutas de Inteligência Artificial em soluções de engenharia de software. A condição de maior impacto para a melhoria dos resultados ocorre em tarefas de alta complexidade conceitual e estratégica, onde a IA frequentemente falha por não possuir um modelo mental completo do sistema. Wang et al. (2024) observam que, embora a IA aumente a eficiência em quebra-cabeças simples, o raciocínio humano é indispensável em tarefas de desenvolvimento típicas, onde a integração e a visão sistêmica são exigidas. Essa necessidade é reforçada por Lertbanjongngam et al. (2022), que demonstram que, para problemas de alta dificuldade, a IA tende a gerar códigos ineficientes com loops excessivos, exigindo a intervenção humana para otimização e correção da lógica.

A eficácia da supervisão é determinante no refinamento de erros de baixa complexidade e na mitigação de alucinações. Humanos demonstram uma capacidade superior para identificar construções não utilizadas, variáveis hardcoded e bugs que, embora simples, comprometem a confiabilidade do código. Na área de Garantia de Qualidade de Software (SQA), conforme discutido por Baranetska (2025), a supervisão humana melhora os resultados ao validar casos de teste gerados automaticamente e ao diferenciar falhas reais de falsos positivos que enganam sistemas puramente automatizados. Molison et al. (2025) corroboram essa visão ao concluir que a análise manual de falhas revela problemas frequentemente fáceis de consertar por um humano, tornando a colaboração mútua o caminho para o produto final de maior qualidade.

Por fim, a pesquisa destaca que a supervisão melhora significativamente os resultados através de ciclos de feedback interativo e contextualização de sistemas. Em tarefas de tradução de código, como analisado por Weisz et al. (2022), o humano utiliza a IA como um andaime (scaffold), focando sua atenção em corrigir erros específicos de linguagem e bibliotecas, o que resulta em uma redução de mais de 50,8% na taxa de erros em comparação ao trabalho isolado. Essa dinâmica interativa é essencial em ferramentas de assistência, cenário em que Mo et al. (2025) demonstram que o feedback em tempo real permite ao humano corrigir vieses do modelo e adaptar as sugestões ao contexto específico do projeto. Além disso, em sistemas críticos e governança ética, a supervisão humana garante que as decisões de lançamento respeitem normas de segurança e lógicas de negócio que a IA não consegue processar de forma autônoma (Abbas et al. (2025)).

3.4 Quais ferramentas de LLM têm sido utilizadas pelos desenvolvedores nos estudos?

As ferramentas de Inteligência Artificial adotadas pelos desenvolvedores na engenharia de software são apresentadas na tabela abaixo com seus respectivos estudos:

Modelos Avaliados	Artigos relacionados
GPT, GPT-3, GPT-4, ChatGPT, Codex	Pangavhane et al. (2024); Wang et al. (2024); Ibrahim et al. (2025); Dibia et al. (2022); Molison et al. (2025); Lyu et al. (2025); Nascimento et al. (2023); Cotroneo et al. (2025)
GitHub Copilot	Pangavhane et al. (2024); Lyu et al. (2025)
Google Bard/Gemini	Qian et al. (2024)
AlphaCode	Lertbanjongngam et al. (2022)
CodeBERT, GraphCodeBERT e CodeT5	Ibrahim et al. (2025)
DeepSeek-Coder e Qwen-Coder	Cotroneo et al. (2025)
CodeGen	Dibia et al. (2022)
Amazon CodeWhisperer	Pangavhane et al. (2024)

A análise das ferramentas de Inteligência Artificial nos estudos selecionados indica a predominância da família GPT da OpenAI, englobando modelos como GPT, GPT-3, GPT-4, ChatGPT e Codex. Essa arquitetura é amplamente recorrente na literatura e está diretamente associada a tarefas de geração de código, comparação sintática e ganho de produtividade, conforme observam Wang et al. (2024). A sua adoção como referência central justifica-se pela capacidade avançada de gerar, explicar e revisar código de maneira iterativa, o que é corroborado ativamente nos experimentos de Molison et al. (2025) e Lyu et al. (2025).

Em segundo plano, figuram os assistentes de codificação integrados, como o GitHub Copilot, e os modelos da família Google e DeepMind, a exemplo do Bard, Gemini e AlphaCode. Essas tecnologias prestam suporte direto em atividades práticas de desenvolvimento, como preenchimento automático de sintaxe, funcionalidade ativamente testada por Pangavhane et al. (2024). No contexto de programação competitiva e análise de produtividade, a eficácia do AlphaCode foi o objeto central do experimento de Lertbanjongngam et al. (2022), enquanto Qian e Wexler (2024) basearam todo o seu estudo de laboratório no uso exclusivo do Google Bard (atual Gemini).

Uma terceira categoria abrange modelos baseados em Transformers otimizados especificamente para a compreensão de código, como CodeBERT, GraphCodeBERT e CodeT5. Diferentemente das ferramentas generalistas de diálogo, essas arquiteturas são aplicadas primordialmente em tarefas de sumarização, análise semântica e geração automática de documentação técnica, dinâmica evidenciada metodologicamente no estudo de Ibrahim et al. (2025).

A literatura também registra o uso de modelos recentes e estritamente especializados na geração e avaliação de scripts. O emprego de plataformas abertas como DeepSeek-Coder e Qwen-Coder concentra-se em investigações empíricas focadas na qualidade estrutural do software e na injeção de vulnerabilidades de segurança, conforme constatado na metodologia de Cotroneo et al. (2025). Adicionalmente, a ferramenta CodeGen foi utilizada em laboratório para avaliar o alinhamento de métricas e o valor real do código gerado (Dibia et al. (2022)).

Por fim, para garantir o rigor metodológico da análise, é importante distinguir as ferramentas que foram de fato avaliadas nos experimentos daquelas que foram apenas mencionadas. Diversas tecnologias ganham destaque nas seções de revisão de literatura, mas não são o objeto de teste dos estudos primários. O Codeium, por exemplo, não foi utilizado como ferramenta de validação em nenhum dos estudos analisados, sendo apenas citado de forma secundária. Da mesma forma, embora Cotroneo et al. (2025) citem o CodeWhisperer e o GitHub Copilot como assistentes populares, o seu experimento prático restringiu-se a avaliar o ChatGPT, o DeepSeek e o Qwen. Esse mesmo fenômeno ocorre no estudo de Nascimento et al. (2023), que discute a existência do AlphaCode em sua introdução teórica, mas avalia empiricamente apenas o desempenho do ChatGPT. Essa distinção mostra que a popularidade literária de uma ferramenta não reflete, necessariamente, a sua validação laboratorial na literatura recente.

3.5 Como o tipo de tarefa de engenharia de software influencia os efeitos da supervisão humana sobre qualidade e produtividade?

A influência do tipo de tarefa de engenharia de software sobre os efeitos da supervisão humana é um fator determinante para o sucesso da colaboração entre humanos e IA, afetando diretamente a produtividade e a qualidade do produto final. Os estudos mostram que a supervisão humana tem uma melhor eficácia quando atua como um mecanismo de curadoria e validação estratégica, adaptando-se à complexidade inerente de cada atividade do ciclo de vida de desenvolvimento.

Em tarefas de codificação pura e resolução de quebra-cabeças algorítmicos, a IA demonstra alta eficiência, mas a supervisão humana é necessária para validar a eficiência de execução. Wang et al. (2024) observam que o uso do ChatGPT trouxe melhorias significativas de eficiência em quebra-cabeças de programação, embora não tenha garantido uma melhor qualidade das soluções, já que a percepção de desempenho dos desenvolvedores aumentou mesmo quando os resultados objetivos eram semelhantes ao trabalho sem IA. De maneira complementar, o estudo de Lertbanjongngam et al. (2022) revela que, embora a IA consiga gerar códigos funcionalmente semelhantes aos humanos, ela tende a produzir soluções ineficientes, com loops excessivos ou lógicas redundantes, em problemas de alta dificuldade, exigindo que o humano supervisione a otimização de performance.

A eficácia da supervisão também varia conforme a natureza da pergunta. O trabalho de Qian et al. (2024) distingue entre tarefas de busca e de resolução avaliando o uso do Bard, assistente conversacional do Google. Enquanto o uso de IA em tarefas de busca não superou recursos tradicionais como a documentação, em tarefas de resolução de problemas a supervisão humana permitiu que novatos tivessem ganhos expressivos de desempenho, enquanto especialistas foram mais propensos a rejeitar as sugestões da IA e não delegar a tarefa, preferindo confiar em sua própria expertise ou em documentações tradicionais. Essa dinâmica baseada na experiência é corroborada por Nascimento et al. (2023), que investigaram especificamente o desempenho do ChatGPT. O autor mostra que a IA supera programadores novatos em problemas fáceis e médios, inclusive alcançando uma eficiência de memória superior à de desenvolvedores em problemas de nível médio. Contudo, a ferramenta falha ao tentar solucionar problemas de alta dificuldade, um cenário complexo onde a capacidade de raciocínio e formulação lógica dos programadores de elite permanece insubstituível para entregar uma solução efetiva e funcional.

4. Conclusão Geral

A interpretação das evidências extraídas da literatura revela convergências extremamente sólidas quanto ao papel da tecnologia na engenharia moderna. Inicialmente, conforme observam Lyu et al. (2025), nota-se um consenso de que a Inteligência Artificial não veio para substituir o programador em sua totalidade, mas sim para atuar como um assistente avançado de colaboração e programação em par.

Nesse sentido, Pangavhane et al. (2024) reforçam a premissa fundamental de que a supervisão humana agrega um valor indispensável na resolução de problemas lógicos de complexidade alta, nas escolhas criativas e na tomada de decisões que exigem raciocínio estratégico e responsabilidade corporativa.

Apesar dessa concordância central sobre a complementaridade, surgem divergências importantes na literatura no que diz respeito ao nível de confiança depositado pelos desenvolvedores nessas ferramentas gerativas. Estudos como o de Nascimento et al. (2023) ressaltam a capacidade da máquina de superar o conhecimento sintático de desenvolvedores juniores e acelerar o fluxo de trabalho de maneira objetiva.

Em contrapartida, pesquisas focadas em auditoria de segurança cibernética e manutenibilidade estrutural, a exemplo de Cotroneo et al. (2025), evidenciam que a aceitação irrestrita do código gerado atua como uma armadilha que compromete a confiabilidade do sistema.

Essa divergência comportamental revela que a ameaça investigada não é puramente a falha do modelo algorítmico, mas sim a complacência de automação do ser humano, cenário no qual Qian e Wexler et al. (2024) demonstram que os desenvolvedores acabam aceitando as saídas vulneráveis da máquina sem a devida validação.

A análise dessas evidências expõe também lacunas que ainda demandam atenção da comunidade científica. As conclusões mostram que há uma ausência de diretrizes maduras no mercado para estruturar o fluxo de trabalho híbrido, obstáculo diretamente apontado por Baranetska (2025).

Fica claro que a literatura anseia pelo desenvolvimento de interfaces mais transparentes capazes de explicar a origem da decisão da máquina para o desenvolvedor, além de clamar por novas metodologias que garantam a aplicação de padrões éticos rigorosos sem asfixiar a inovação das equipes de engenharia, como argumentam Abbas et al. (2025).

Em suma, os estudos avaliados concluem de forma categórica que as atividades de engenharia de software assistidas por Inteligência Artificial são bem utilizadas no contexto de qualidade, segurança e eficiência apenas sob a supervisão humana constante e ativa, premissa consolidada nos achados de Mo et al. (2025).

A literatura aborda empiricamente que, desprovido do olhar crítico e da validação analítica de um desenvolvedor humano, o uso autônomo de ferramentas gerativas resulta frequentemente na injeção de vulnerabilidades perigosas, loops excessivos e falhas estruturais em aplicações complexas, como evidenciado por Lertbanjongngam et al. (2022).

Portanto, o futuro da construção e manutenção de software não elimina a força de trabalho convencional, mas exige a consolidação de um modelo colaborativo. Nesse cenário, a máquina atua como provedora de velocidade e escala na geração bruta de dados, enquanto o ser humano, conforme defendem Ibrahim et al. (2025), eleva seu papel para o de validador arquitetural, garantidor das nuances de design e guardião da integridade do sistema.

Referências

DIBIA, V.; FOURNEY, A.; BANSAL, G.; POURSABZI-SANGDEH, F.; LIU, H.; AMERSHI, S. Aligning Offline Metrics and Human Judgments of Value for Code Generation Models. 2022.

QIAN, C.; WEXLER, J. Take It, Leave It, or Fix It: Measuring Productivity and Trust in Human-AI Collaboration. 2024.

MOLISON, A. S.; MORAES, M.; MELO, G.; SANTOS, F.; ASSUNÇÃO, W. K. G. Is LLM-Generated Code More Maintainable & Reliable than Human-Written Code? 2025.

BARANETSKA, Y. Human–AI Collaboration in Software Quality Assurance: Balancing Automation and Human Expertise. 2025.

WANG, W.; NING, H.; ZHANG, G.; LIU, L.; WANG, Y. Rocks Coding, Not Development: A Human-Centric, Experimental Evaluation of LLM-Supported SE Tasks. 2024.

LYU, W.; WANG, Y.; SUN, Y.; ZHANG, Y. Will Your Next Pair Programming Partner Be Human? An Empirical Evaluation of Generative AI as a Collaborative Teammate in a Semester-Long Classroom Setting. 2025.

PANGAVHANE, S.; SHELAR, K.; RAKTATE, G.; WAKCHAURE, R.; PARJANE, P.; KALE, J. N. AI-Augmented Software Development: Boosting Efficiency and Quality. 2024.

MO, T.; JIANG, Z.; ZHENG, Q. Interactive AI Agent for Code Refactoring Assistance: A Study on Decision-Making Strategies and Human-Agent Collaboration Effectiveness. 2025.

ABBAS, T.; RATHORE, S. A.; TURKI, A.; KHAN, S.; ALGHUSHAIRY, O.; DAUD, A. Enhancing Software Engineering With AI: Innovations, Challenges, and Future Directions. 2025.

IBRAHIM, A.; BARYAL, M.; ULLAH, A.; SHOAIB, M.; KHAN, M. G. Using NLP and AI to Enhance Software Documentation and Code Comprehension. 2025.

LERTBANJONGNGAM, S.; CHINTHANET, B.; ISHIO, T.; KULA, R. G.; LEELAPRUTE, P.; MANASKASEMSAK, B.; RUNGSAWANG, A.; MATSUMOTO, K. An Empirical Evaluation of Competitive Programming AI: A Case Study of AlphaCode. 2022.

WEISZ, J. D.; MULLER, M.; ROSS, S. I.; MARTINEZ, F.; HOUDE, S.; AGARWAL, M.; TALAMADUPULA, K.; RICHARDS, J. T. Better Together? An Evaluation of AI-Supported Code Translation. 2022.

NASCIMENTO, N.; ALENCAR, P.; COWAN, D. Comparing Software Developers with ChatGPT: An Empirical Investigation. 2023.

COTRONEO, D.; IMPROTA, C.; LIGUORI, P. Human-Written vs. AI-Generated Code: A Large-Scale Study of Defects, Vulnerabilities, and Complexity. 2025.

Entidades finas e composição: o design que escolhi para a nova plataforma

Alberto Luiz Souza — Mon, 25 May 2026 00:01:06 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quando você começa a desenhar as entidades de um sistema novo, é fácil cair no padrão que aprendemos cedo na carreira: uma entidade principal, com seus atributos óbvios, e relacionamentos diretos com outras entidades. Com o tempo, novas necessidades aparecem e essas entidades vão ganhando atributos, estados nulos, exceções e regras contextuais. O resultado costuma ser o mesmo: God Classes, complexidade espalhada e fricção para evoluir.

Neste post, mostro a decisão de design que tomei na nova plataforma onde estou servindo os conteúdos do Dev + Eficiente. Em vez de seguir o caminho clássico de entidades robustas, me inspirei na arquitetura de Content Management Systems como Drupal e WordPress, onde tudo é plugável. O objetivo foi criar entidades muito finas e mover a complexidade para peças de composição reutilizáveis.

O padrão clássico e seu envelhecimento

Pensa numa plataforma de cursos. O caminho mais natural seria modelar algo como:

class Trilha {
    String titulo;
    String descricao;
    Set<Curso> cursos;
}

class Curso {
    String titulo;
    String descricao;
    Trilha trilha;
    Set<Aula> aulas;
    int posicaoNaTrilha;
}

class Aula {
    String titulo;
    String resumo;
    Curso curso;
    List<String> videos;
    List<String> documentosParaDownload;
    List<String> referencias;
    int posicaoNoCurso;
}

Funciona. Eu mesmo já modelei assim várias vezes. O problema aparece com o tempo. Surge a necessidade de uma pessoa responsável pela trilha. Adiciona o atributo, mas só algumas trilhas têm responsável, então o campo precisa ser nullable. Em seguida vem o pedido de que aulas tenham professores ministrantes. Adiciona uma referência para usuário. Aí surge a regra de que cursos podem ter um período de visibilidade. Adiciona uma data de entrada e uma de saída. Para cursos que existem para sempre, alguém faz uma migration com data de mil anos no futuro.

Esse acúmulo acontece regularmente, e não só nas entidades principais. À medida que o contexto evolui, novos atributos e estados se acumulam dentro das classes mais centrais, aumentando o nível de complexidade delas e desviando a atenção de quem precisa entender o domínio.

A inspiração: nós em CMS

Em sistemas como Drupal e WordPress, a necessidade de dinamicidade é extrema. As pessoas querem usar essas ferramentas para construir qualquer tipo de site, com qualquer combinação de plugins. A consequência é que a entidade central é mínima.

No Drupal, por exemplo, você tem a ideia de um nó (ou item). Esse nó tem quase nada: talvez um ID e um título. Se você quer que ele tenha conteúdo, adiciona um campo. Se você quer que ele tenha periodicidade, decora ele com esse estado. É como o padrão Decorator aplicado ao estado da entidade. O código não é nada elegante, mas é extremamente extensível.

Essa foi a primeira referência. Depois pensando, percebi também uma inspiração indireta em tabelas de relacionamento de bancos relacionais. Muitas vezes, quando o sistema cresce, aquela tabela que só ligava duas chaves ganha semântica: um instante em que a associação aconteceu, um tipo de relação, atributos próprios. Ela deixa de ser uma cola e passa a ser uma entidade. Esse foi o ponto de partida para o design.

O design que escolhi

A pergunta que orientou as decisões foi simples: o que de fato é parte essencial dessa entidade, e o que está aqui só por uma necessidade contextual?

Aplicando essa pergunta:

class Trilha {
    String nome;
    String descricao;
}

class Curso {
    String nome;
    String descricao;
}

class Aula {
    String titulo;
    String resumo;
    List<String> videos;
    List<String> textos;
    List<String> referencias;
}

Note o que não está mais ali. A trilha não tem mais cursos. O curso não pertence a uma trilha nem tem aulas. A aula não conhece o curso. E nenhuma das três tem posição, período de visibilidade, comentários ou professor responsável. Esses atributos saem de cena porque não são inerentes a essas entidades: são necessidades de contextos específicos.

Composição via peças orthogonais

A composição passa a ser feita por entidades dedicadas. Olha como ficam alguns conceitos.

Itens de trilha

Em vez da trilha ter uma coleção de cursos, ela passa a ter itens:

class ItemDaTrilha {
    Long id;
    Trilha trilha;
    Long idDoItem;
}

O idDoItem é uma referência fraca. Pode apontar para um curso, pode apontar para uma aula, pode apontar para outra coisa. Eu aceitei essa perda de integridade referencial para ganhar flexibilidade. Em uma linguagem orientada a objetos, dá para extrair uma interface para fazer essa referência polimórfica, semelhante ao que ORMs como Active Record do Rails já suportavam há muito tempo, com uma coluna a mais que indica o tipo do ID referenciado. Só que, neste momento, decidi nÃo ir por esse caminho.

Contexto de ordenação

A posição também sai das entidades. Ela vira parte de um contexto de ordenação:

class ContextoOrdenacao {
    Long id;
    Long idDono;
    String nome;
}

class ItemOrdenavel {
    Long id;
    Long idItem;
    ContextoOrdenacao contexto;
    int posicao;
}

Por que separar assim? Porque a posição não é uma característica do curso. A posição existe porque, em algum momento, eu preciso ordenar uma lista de coisas para exibir. Essa é uma característica do contexto onde estou usando o curso, não do curso em si.

Sem contar que agora eu ganhe capacidade de criar contextos de ordenação para o que eu quiser.

Comentários

Mesma lógica:

class ContextoComentarios {
    String nome;
    String descricao;
    Long idDono;
}

class Comentario {
    ContextoComentarios contexto;
    Usuario autor;
    String texto;
}

O contexto de comentários pode ser aplicado a uma aula, a um curso, a uma trilha como um todo, ou a qualquer outra coisa. Posso ter um contexto de comentários globais no dashboard sem precisar criar um modelo novo.

Períodos de visibilidade

A nova plataforma também importa vagas de um job board. Algumas dessas vagas expiram. Em vez de adicionar campos de início e fim na entidade Vaga, criei uma entidade Periodo que referencia qualquer coisa:

class Periodo {
    LocalDateTime entrada;
    LocalDateTime saida;
    Long idDoItem;
}

A entidade Vaga não foi alterada. A vaga não precisa saber que tem um período. O fluxo que carrega vagas é quem combina os dois.

Como uma trilha é carregada na prática

Para servir os cursos de uma trilha como a Especialização em Engenharia de IA, o fluxo passa a ser:

Carrega a trilha
Carrega o contexto de ordenação daquela trilha
Carrega os itens ordenáveis daquele contexto
Para cada item ordenável, usa o idItem para carregar o curso

Já na Jornada Dev + Eficiente, que tem categorias dentro da trilha (Design de Código, Arquitetura, Aprendizagem, e por aí vai), o fluxo ganha mais um nível:

Carrega a trilha
Carrega o contexto de ordenação de categorias daquela trilha
Para cada categoria, carrega o contexto de ordenação interno
Para cada contexto interno, carrega os itens ordenáveis
Para cada item ordenável, carrega o curso

A modelagem fica como peças de lego. Eu monto a hierarquia que quero, sem precisar mudar nenhuma das entidades base.

A inspiração em programação orientada a aspectos

Depois de implementar, percebi outra referência além do CMS e das tabelas de relacionamento. Há mais de 20 anos, a programação orientada a aspectos virou tema de pesquisa, e o Spring até hoje mantém essa funcionalidade com anotações como @Aspect. A ideia original era separar comportamentos ortogonais ao código de negócio: logging, controle de transação, métricas. Você podia escrever um aspecto que logava todos os métodos de um pacote sem mexer nos métodos em si.

O que fiz aqui é parecido, mas em outra dimensão. Em vez de transformar comportamentos em aspectos, transformei estados. A ordenação virou ortogonal. Os comentários viraram ortogonais. O período de visibilidade virou ortogonal. As entidades em si ficaram mais finas, com menos lógica, e a complexidade se moveu para os pontos de negócio onde acontece a composição.

Trade-offs

Esse design tem ganhos e perdas claras. Vale listar para que você possa avaliar se faz sentido no seu contexto.

Ganhos:

Entidades base ficam pequenas e estáveis
Características novas (períodos, comentários, ordenações) podem ser adicionadas a qualquer entidade sem alterar nenhuma delas
A complexidade fica visível nos fluxos de negócio, em vez de escondida dentro das entidades

Perdas:

Integridade referencial mais fraca, já que as chaves são genéricas e o banco não consegue garantir consistência
Mais queries para carregar uma hierarquia completa
Risco de dados órfãos, que precisam ser tratados na aplicação

O banco de dados é muito mais confiável do que código de aplicação para garantir consistência. Quando você abre mão de parte desse apoio, está aceitando que o sistema vai precisar tratar essas falhas em outro nível. Para o cenário da nova plataforma, esse trade-off me pareceu valer a pena, e é o que estou rodando em produção com as pessoas alunas usando.

Conclusão

Design de código não é sobre encontrar o desenho perfeito. É sobre escolher como o sistema vai envelhecer. Quando você decide praticar uma atividade física, está apostando que ela vai te ajudar a envelhecer melhor. Quando você toma uma decisão de design, está apostando que ela vai fazer o sistema lidar melhor com mudanças que você previu e com mudanças que ainda não previu.

Nessa nova plataforma escolhi entidades muito finas e composição via peças ortogonais inspiradas em CMS, tabelas de relacionamento e programação orientada a aspectos. Aceitei perder integridade referencial e ganhar flexibilidade. Pode ser que daqui a algum tempo eu reveja parte dessas decisões. Por enquanto, está funcionando bem, e a estabilidade das entidades base tem me dado liberdade para evoluir o resto do sistema sem mexer no que já está consolidado.

Dev + Eficiente

IA e eficiência em atividades de código: atividades, métricas e limitações

Alberto Luiz Souza — Mon, 13 Apr 2026 01:18:39 +0000

Contexto

A incorporação de ferramentas de Inteligência Artificial (IA) ao desenvolvimento de software tem ampliado a discussão sobre seus efeitos na eficiência das atividades de código. Os estudos reunidos neste trabalho mostram que a IA já vem sendo aplicada em tarefas como codificação, depuração, testes, documentação, revisão de código e operações de CI/CD (PINTO et al., 2024; PEREIRA et al., 2025). Em atividades mais estruturadas e repetitivas, como geração de código, testes simples e documentação, os ganhos de eficiência tendem a ser mais evidentes, principalmente pela redução do esforço manual, do tempo de busca por informação e da carga cognitiva do desenvolvedor (PANDEY et al., 2024; PINTO et al., 2024).

Por outro lado, os mesmos dados mostram que a IA também pode diminuir a eficiência em determinadas situações. Isso ocorre quando a ferramenta produz sugestões incompletas, genéricas ou incorretas, exige intensa revisão humana ou falha em captar o contexto do projeto (FORTES et al., 2025; WINCKLER et al., 2025). Essas limitações aparecem com mais força em tarefas complexas e contextuais, na depuração de defeitos difíceis e na validação do código gerado, casos em que parte do tempo economizado na geração inicial pode ser consumida pelo esforço de checagem, correção e adaptação das saídas produzidas pela ferramenta (STRAY et al., 2024; DAVILA et al., 2024).

Este evidence briefing sintetiza evidências recentes da literatura sobre três eixos: as atividades de código em que a IA é utilizada, as métricas empregadas para avaliar essa eficiência e as limitações relatadas, com foco em aplicações na Engenharia de Software e em sistemas corporativos.

Atividades de código e seus efeitos na eficiência

As atividades onde a IA é mais utilizada para ganho de eficiência são codificação, testes de software e depuração de código, com ganhos que envolvem geração de novo código, autocompletar, criação de boilerplate, elaboração de testes de unidade e apoio à correção de erros simples (PINTO et al., 2024; PEREIRA et al., 2025; PANDEY et al., 2024).

Os estudos também indicam ganhos em documentação, apoio ao conhecimento e compreensão de código, especialmente pela redução do tempo gasto com buscas por exemplos, APIs, sintaxe e trechos de código legado. Esse uso sugere que parte da eficiência promovida pela IA não está apenas na produção de código, mas também na redução de fricções cognitivas e informacionais no trabalho diário (FORTES et al., 2025; STRAY et al., 2024).

As perdas de eficiência aparecem com mais força em tarefas como mudanças distribuídas em múltiplos arquivos, atividades dependentes de regras de negócio específicas, depuração de defeitos difíceis e validação do código gerado (SHANUKA; WIJAYANAYAKE; VIDANAGE, 2025; PANDEY et al., 2024; SANTOS et al.). A Tabela 1 detalha esses efeitos por atividade.

Tabela 1 -- Atividades de código e efeitos da IA na eficiência

Atividade de código	Aumenta a eficiência	Diminui a eficiência
Codificação / escrita de código	geração de código, autocompletar, boilerplate, snippets contextuais	sugestões incorretas, perda de contexto, revisão excessiva
Depuração e correção de código	sugestão de correções, apoio ao debugging, erros simples	loops de erro, correções superficiais, retrabalho
Testes de software	geração de testes, automação, regressão	testes superficiais, baixa aderência ao domínio, necessidade de reescrita
Documentação e apoio ao conhecimento	comentários, documentação técnica, acesso rápido a exemplos e APIs	respostas inconsistentes, documentação genérica, falta de contexto
Compreensão de código / código legado	explicação de código, apoio à leitura de código legado	explicações rasas, falha em captar contexto, necessidade de validação
Manutenção / modificação de código existente	ajustes pontuais, extensão de funcionalidades, mudanças simples	dificuldade com múltiplos arquivos, retrabalho de integração
Refatoração e otimização	reorganização de código, melhoria de legibilidade	perda de desempenho, baixa confiabilidade em cenários complexos
Revisão de código e garantia de qualidade	feedback inicial, detecção de problemas, apoio à revisão	comentários irrelevantes, sobrecarga de validação, atraso no PR
Entrega, CI/CD e operações	scripts de deployment, análise de logs, automação operacional	necessidade de validação humana, baixa autonomia, dependência de contexto

Métricas utilizadas para avaliar a eficiência

A eficiência do uso de IA em atividades de código vem sendo avaliada por diferentes grupos de métricas que vão além da velocidade de execução. No material analisado, destacam-se as categorias tempo, produtividade / entrega, qualidade do código, qualidade dos testes, uso / aceitação da ferramenta, experiência do desenvolvedor e custo / precisão operacional.

As métricas de tempo e produtividade / entrega aparecem com maior frequência, com indicadores como cycle time, lead time, throughput, frequência de implantação e tarefas concluídas. Mas os estudos também recorrem a métricas de qualidade e experiência do desenvolvedor, como readability, maintainability, cobertura de testes, taxa de aceitação de sugestões, cognitive load e flow state. Esse conjunto mostra que a eficiência da IA é tratada como um conceito multidimensional, que envolve rapidez, qualidade das entregas e impacto no trabalho humano.

Tabela 2 -- Métricas utilizadas para medir a eficiência

Métrica	Foco da avaliação	Exemplos de indicadores
Tempo	Mede se a IA acelera a execução das atividades de código	tempo para concluir tarefas, time to first test, tempo médio por caso de teste, cycle time, lead time, MTTR
Produtividade / entrega	Avalia se a IA amplia a capacidade de produção e entrega	task completion efficiency, task completion time, throughput, deployment frequency, tarefas concluídas, LOC/day, requisitos implementados
Qualidade do código	Verifica se o ganho de velocidade mantém ou melhora a qualidade técnica	readability, maintainability, code health, correctness, performance, defect density, change failure rate
Qualidade dos testes	Mede a efetividade da IA na geração e execução de testes	bug detection rate, false positive rate, test coverage, success rate, step accuracy, automated test coverage
Uso / aceitação da ferramenta	Observa o quanto as sugestões da IA são realmente aproveitadas	number of prompts, number of suggestions, acceptance rate, line-level acceptance rate, percentual de comentários aceitos
Experiência do desenvolvedor	Analisa o impacto da IA no fluxo e na carga cognitiva do trabalho	feedback loops, cognitive load, flow state, dimensões do framework SPACE
Custo / precisão operacional	Avalia custo de uso e precisão em testes e operações	custo por caso de teste, proporção entre tokens gerados e tokens inseridos, precision, alert precision, false positive rate

Limitações do uso de IA nas atividades de código

Embora a IA possa acelerar parte do trabalho, os estudos relatam limitações recorrentes que reduzem ou anulam os ganhos de eficiência. Essas limitações não se restringem à geração de código em si -- muitas delas estão na interação com a ferramenta, como a dependência de prompts bem elaborados, a configuração adequada e a integração com o ambiente de desenvolvimento (SALEM et al., 2024; WINCKLER et al., 2025; PANGAVHANE et al., 2025; FORTES et al., 2025; PINTO et al., 2024; SHANUKA; WIJAYANAYAKE; VIDANAGE, 2025; HOUCK et al., 2025).

Tabela 3 -- Limitações com a utilização da IA

Limitação relatada	Exemplo
Baixa qualidade e inconsistência das sugestões	A IA pode gerar respostas imprecisas, incompletas, redundantes ou inconsistentes, reduzindo a confiabilidade do uso.
Dependência de prompts bem elaborados	Os ganhos de eficiência dependem da capacidade do usuário de formular prompts e configurar corretamente a ferramenta.
Perda ou insuficiência de contexto	A IA ainda apresenta dificuldades para recuperar e manter o contexto específico do projeto, do código e da organização.
Baixa efetividade em tarefas complexas	O desempenho da IA tende a cair em atividades que envolvem múltiplos arquivos, arquitetura, segurança ou regras de negócio específicas.
Problemas de integração e suporte técnico	São relatados desafios de instalação, configuração, estabilidade, compatibilidade com IDEs e adaptação ao ambiente de desenvolvimento.
Necessidade contínua de supervisão humana	Mesmo quando acelera tarefas, a IA ainda exige revisão, validação e controle constantes por parte do desenvolvedor.
Riscos de segurança e confiabilidade	O uso da IA pode introduzir vulnerabilidades, respostas pouco confiáveis e problemas éticos ou de precisão.
Sobrecarga cognitiva	A interação com a ferramenta pode aumentar o esforço mental, interromper o fluxo de trabalho e gerar custo adicional de validação.

Interpretação das evidências

A presença de métricas de qualidade e experiência do desenvolvedor ao lado das métricas de tempo e produtividade mostra que produzir mais rápido não é suficiente se houver perda de qualidade (PEREIRA et al., 2025; WANG et al., 2024; SHANUKA; WIJAYANAYAKE; VIDANAGE, 2025). Métricas como acceptance rate, cognitive load e flow state indicam que a IA pode tanto apoiar o trabalho quanto gerar novos custos de revisão, validação e esforço cognitivo (FORTES et al., 2025; WINCKLER et al., 2025).

As limitações reforçam esse ponto: parte do esforço economizado na geração é deslocada para supervisão, validação e correção. Problemas como dependência de prompts bem elaborados, integração incompleta com o ambiente de desenvolvimento e revisão constante das saídas são recorrentes em diferentes estudos.

No conjunto, as evidências mostram que o impacto da IA na eficiência varia conforme o tipo de tarefa, o nível de complexidade, a qualidade da ferramenta e o quanto de supervisão humana é necessário.

Conclusão

A IA tem potencial para aumentar a eficiência em atividades de programação, mas seus benefícios não são uniformes. A eficiência resultante não depende apenas da velocidade de execução -- ela combina rapidez, qualidade, custo de uso e impacto no trabalho humano.

Em vez de substituir o desenvolvedor, a IA muda o seu papel, deslocando parte do trabalho para supervisão e controle do que é gerado. O uso mais eficaz depende da qualidade da ferramenta, do contexto em que ela é aplicada e da presença constante do julgamento humano ao longo do desenvolvimento.

Referências

DAVILA, Nicole et al. An Industry Case Study on Adoption of AI-based Programming Assistants. 2024.

FORTES, Luciane et al. The Productivity Paradox of AI-Powered Development. 2025.

HOUCK, Brian et al. The SPACE of AI: Real-World Lessons on AI's Impact on Developers. 2025.

KARUPPUCHAMY, Sureshkumar. AI-Augmented Software Engineering for Rapid Feature Delivery and Operations Automation. 2025.

PANDEY, Ruchika; SINGH, Prabhat; WEI, Raymond; SHANKAR, Shaila. Transforming Software Development: Evaluating the Efficiency and Challenges of GitHub Copilot in Real-World Projects. 2024.

PANGAVHANE, Shreyas et al. AI-Augmented Software Development: Boosting Efficiency and Quality. 2025.

PEREIRA, Guilherme Vaz et al. Exploring GenAI in Software Development: Insights from a Case Study in a Large Brazilian Company. 2025.

PINTO, Gustavo et al. Developer Experiences with a Contextualized AI Coding Assistant: Usability, Expectations, and Outcomes. 2024.

SALEM, Dina Omar et al. AI-Driven Continuous Integration: Automating Code Review and Deployment with LLMs. 2024.

SANTOS, Robson; SANTOS, Italo; MAGALHAES, Cleyton; SANTOS, Ronnie de Souza. Are We Testing or Being Tested? Exploring the Practical Applications of Large Language Models in Software Testing. [s.d.].

SHANUKA, K. A. Ashen; WIJAYANAYAKE, Janaka; VIDANAGE, Kaneeka. Analyzing the impact of prompt engineering on efficiency, code quality, and security in CRUD application development. 2025.

STRAY, Viktoria; MOE, Nils Brede; GANESHAN, Nivethika; KOBBENES, Simon. Generative AI and Developer Workflows: How GitHub Copilot and ChatGPT Influence Solo and Pair Programming. 2024.

WANG, Xuan et al. From Redundancy to Efficiency: Exploiting Shared UI Interactions towards Efficient LLM-Based Testing. 2024.

WEBER, Thomas; BRANDMAIER, Maximilian; SCHMIDT, Albrecht; MAYER, Sven. Significant Productivity Gains through Programming with Large Language Models. 2024.

WINCKLER, Sabrina C. et al. AI-assisted Collaboration: Exploring Developer Experience with GitHub Copilot and Windsurf. 2025.

Detecção de anomalias: do sensor ao dashboard

Alberto Luiz Souza — Mon, 30 Mar 2026 01:11:49 +0000

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal de Daniel Romero (a pessoa que lidera nossa especialização em Engenharia de IA). Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Detecção de anomalias é uma técnica de Machine Learning usada para encontrar padrões em dados que não estão de acordo com o comportamento esperado. Empresas de cartão de crédito e fintechs usam esse tipo de abordagem no combate a fraudes, mas a aplicação vai muito além do mundo financeiro. Neste post, vamos construir um sistema completo de detecção de anomalias para monitorar vibração em maquinário industrial, passando por coleta de dados com sensor, treinamento de modelo e inferência em tempo real.

A inspiração vem de empresas reais que fornecem sistemas de monitoramento preditivo para indústria, usando sensores que coletam dados de vibração e modelos de Machine Learning que analisam esses dados para prever problemas antes que eles aconteçam.

O plano geral do projeto

O projeto percorre toda a cadeia de um sistema de detecção de anomalias:

Montar um protótipo com sensor acelerômetro conectado a um microcontrolador ESP32
Coletar dados de vibração de um ar-condicionado em operação normal e com anomalia simulada
Analisar os dados coletados e extrair features relevantes
Treinar um modelo de Machine Learning para classificar operação normal versus anomalia
Criar uma API para inferência em tempo real
Construir um dashboard para monitorar o estado do sistema

Coleta de dados com acelerômetro e ESP32

Para coletar dados de vibração, o projeto usa um acelerômetro de 3 eixos (MPU6050) conectado a um ESP32 via protocolo I2C.

Como funciona um acelerômetro

Um acelerômetro detecta aceleração linear ao longo de um eixo. O sensor utilizado é uma IMU (unidade de medição inercial), que combina acelerômetros, giroscópios e magnetômetros em um chip microscópico, usando tecnologia MEMS (sistemas microeletromecânicos).

Internamente, o sensor possui uma massa sísmica em forma de H com extremidades sensoriais. Essa massa fica presa ao substrato nas extremidades, permitindo um movimento de vai e vem. Durante a movimentação, os dedos sensoriais se aproximam dos eletrodos, gerando detecção capacitiva. A mudança na capacitância entre os eletrodos fixos e a massa sísmica é usada para determinar a aceleração. Em termos práticos, o sensor detecta tanto forças estáticas como a gravidade quanto forças dinâmicas como vibrações.

Configuração do microcontrolador

O ESP32 conecta-se ao Wi-Fi e envia os dados do acelerômetro para uma API Python via requisições HTTP POST. O fluxo funciona assim:

O ESP32 faz uma requisição GET para verificar se o servidor está pronto
Se recebe resposta positiva, coleta 200 amostras por segundo (uma amostra a cada 5 milissegundos)
Os valores X, Y e Z da aceleração são organizados em JSON e enviados via POST
O servidor Python recebe os dados e salva em arquivos CSV

Na configuração do sensor, o range do acelerômetro fica em mais ou menos 4G (podendo medir até 16G) e a largura de banda do filtro em 260 Hz. O range define o tamanho da força que o sensor pode medir, enquanto a largura de banda determina o quão rápido ele consegue registrar mudanças de movimento. A combinação dos dois funciona quase como um ajuste de sensibilidade.

Introduzindo a anomalia

Para simular uma falha mecânica, um imã é fixado no cilindro metálico que faz o ar circular no ar-condicionado. Isso causa uma descalibragem proposital, fazendo o cilindro trepidar. Os dados são coletados em diferentes condições: operação normal em várias velocidades e operação com a anomalia inserida.

Análise exploratória dos dados

Com os dados coletados, a análise revela diferenças claras entre operação normal e anomalia.

Dados brutos

Na operação normal, o eixo Z mantém um nível constante em torno de 10g, enquanto os eixos X e Y ficam próximos de zero com linhas suaves. Na operação com anomalia, aparecem oscilações mais intensas em todos os eixos, com um padrão mais irregular.

Features estatísticas

Três características se destacam na separação entre normal e anomalia:

Média: mostra o valor central das medições ao longo do tempo. Há uma separação clara, indicando que o nível médio de vibração durante anomalias é consistentemente diferente
Variância: mede como os dados se dispersam em relação à média. As anomalias apresentam valores muito maiores, indicando vibrações mais intensas e irregulares
Curtose: indica o quanto os dados se concentram em torno da média. Valores mais altos sugerem picos de vibração mais intensos e frequentes

Cada feature fornece uma perspectiva diferente. A média entrega uma visão geral de vibração, a variância revela a intensidade das oscilações e a curtose indica a presença de eventos extremos.

Transformada rápida de Fourier (FFT)

A FFT decompõe um sinal em suas frequências constituintes. Diferentes problemas mecânicos geram padrões de vibração em frequências específicas. Um rolamento com defeito pode gerar vibrações em uma frequência, enquanto um desbalanceamento pode gerar outra.

Nos dados coletados, a operação normal mostra um perfil de frequência suave e com baixa magnitude. A anomalia mostra picos em certas frequências, especialmente no eixo Z, onde a magnitude chega a 16 vezes o valor normal.

Treinamento do modelo

Preparação dos dados

O processo de preparação inclui:

Carregar os CSVs de cada tipo de operação (normal e anomalia)
Remover o DC (valor médio do sinal) para centralizar os dados em torno de zero, eliminando viés constante e efeitos da gravidade
Adicionar ruído aleatório para aumentar a robustez durante o treino

Extração de features

Para cada eixo, cinco features são extraídas:

Desvio padrão: variabilidade do sinal
Curtose: formato da distribuição
Amplitude máxima absoluta: maior valor registrado
RMS (média quadrática): medida de energia do sinal
Range: diferença entre valores máximos e mínimos

Distância de Mahalanobis e threshold

O algoritmo escolhido usa a distância de Mahalanobis para calcular o quão distante um ponto está da distribuição normal dos dados. Essa distância produz uma medida de quão estranho é um ponto em relação ao comportamento esperado.

Uma função complementar encontra o melhor limiar (threshold) para separar normal de anomalia usando validação cruzada. A abordagem é conservadora: falsos positivos são penalizados 5 vezes mais que falsos negativos, priorizando evitar alarmes falsos.

Resultados do modelo

A distribuição das distâncias de Mahalanobis mostra:

Casos normais concentrados entre 2 e 6, com pico próximo a 3,5
Anomalias concentradas entre 8,5 e 14, com pico em torno de 10
Threshold definido em 5,71

Na matriz de confusão, o modelo acertou 86 de 100 predições: 47 verdadeiros normais, 39 verdadeiras anomalias, 3 falsos positivos e 11 falsos negativos. O modelo tende a ser mais conservador, preferindo classificar como normal os casos duvidosos.

No relatório de classificação:

Normal: precisão de 81%, recall de 94%, F1 de 87%
Anomalia: precisão de 93%, recall de 78%, F1 de 85%
Acurácia geral: 86%
AUC Score: 0,87

Inferência em tempo real

Atualização do sensor

Para a fase de inferência, o software do ESP32 é atualizado. A coleta passa para 100 amostras, organizadas como uma matriz 2D que corresponde ao formato de input esperado pelo modelo. Os dados são enviados para uma API de detecção de anomalias.

API com FastAPI

A API recebe os dados do acelerômetro, carrega o modelo treinado (contendo média, covariância e threshold) e executa o pipeline:

Pré-processamento dos novos dados e remoção do DC
Cálculo das features estatísticas por eixo
Cálculo da distância de Mahalanobis para a nova amostra
Cálculo de confiança considerando histórico recente
Classificação como normal ou anomalia

Vale destacar que a distância de Mahalanobis aparece tanto no treino quanto na inferência, mas com propósitos diferentes. No treino, ela é usada para definir o threshold com dados rotulados. Na inferência, é calculada para cada nova amostra e comparada com o threshold já definido. No treino se calibra o sistema; na inferência se usa essa calibração para classificar.

Dashboard de monitoramento

Uma aplicação em React exibe o status da classificação em tempo real, com três métricas:

Confidence: confiança do modelo na classificação atual
Distância de Mahalanobis: calculada para os dados recebidos
Threshold: limite constante que define quando algo é considerado anomalia

O gráfico mostra a evolução temporal dessas métricas, permitindo acompanhar o comportamento do sistema.

Possibilidades de evolução

O projeto demonstra um fluxo completo, mas várias evoluções são possíveis:

Treinar uma rede neural com mais dados para maior sofisticação
Mapear peças internas do equipamento para identificar a origem da anomalia
Combinar dados do acelerômetro com giroscópio para aumentar a precisão
Projetar hardware dedicado com PCB customizada
Separar os componentes da API de forma mais organizada

Conclusão

Um projeto assim não garante uma vaga de trabalho, mas funciona como treino e pode chamar a atenção em meio a milhares de candidaturas. O diferencial está em cobrir toda a cadeia do problema: desde o entendimento do hardware e coleta de dados, passando pela análise exploratória e treinamento do modelo, até a inferência em tempo real com dashboard de monitoramento.