DEV Community: Alberto Luiz Souza

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

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.

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.

Dev + Eficiente

Skills para agentes de código fazem diferença?

Alberto Luiz Souza — Sun, 22 Mar 2026 23:41:08 +0000

Disclaimer

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

Introdução

Existe uma discussão recorrente sobre o quanto configurar skills (no Claude Code), rules (no Cursor) ou arquivos semelhantes realmente melhora o resultado dos agentes de código. Para tentar responder isso com dados, um estudo chamado SkillBench montou um benchmark com 84 tarefas de domínios variados e testou múltiplos modelos em três cenários: sem skill nenhuma, com skills geradas pelo próprio agente e com skills escritas com participação humana.

Neste post, vamos analisar os principais achados do estudo, incluindo dados do apêndice sobre taxa de falha dos modelos que costumam passar despercebidos nas discussões.

O achado principal: skills escritas por humanos fazem diferença

O gráfico central do estudo compara a taxa de resolução de tarefas em três condições: sem skill, com skill auto-gerada pelo agente e com skill escrita em conjunto com um ser humano que domina o assunto.

O resultado mais relevante: skills escritas com participação humana consistentemente melhoram a taxa de resolução em relação às outras duas condições. Os modelos testados incluem Haiku 4.5, Sonnet 4.5, Opus 4.5, Gemini 3 Pro, GPT 5.2, Opus 4.6 e Gemini 3 Flash, e o padrão se repete em praticamente todos.

Já as skills geradas pelo próprio agente tiveram efeito quase nulo comparadas a trabalhar sem skill nenhuma. Em alguns casos, como GPT 5.2 e Sonnet 4.5, o agente sem skill teve resultado levemente melhor do que com skill auto-gerada.

Isso reforça algo que segue sendo verdade: o nível de expertise de quem direciona o agente continua fazendo diferença significativa.

Como o estudo foi montado

O repositório do SkillBench contém 84 tarefas de naturezas diversas. Cada tarefa tem a instrução para o agente, metadados, timeout, testes automatizados para verificar o output e uma proposta de solução determinística.

A execução funcionava assim: subia uma imagem Docker com o agente instalado (Claude Code, Codex, Gemini CLI), configurava com ou sem skill, apontava para a pasta com as instruções e deixava o agente trabalhar. Depois verificava o resultado contra os testes.

A variação por domínio e o que ela revela

O estudo traz uma tabela com a taxa de resolução por domínio. Alguns números:

Saúde: 86% com skill, 34% sem skill
Engenharia de software: 38,9% com skill, 34,4% sem skill

A diferença entre esses dois domínios é reveladora, mas precisa de contexto. Primeiro, o volume de tarefas era diferente: saúde tinha poucas tarefas, engenharia de software tinha mais de vinte. Segundo, e talvez mais importante, os modelos são muito mais bem treinados para engenharia de software do que para domínios como saúde.

Isso leva a uma conclusão prática: quanto menos treinado o modelo é para um domínio específico, maior o gap que o conhecimento humano precisa preencher. Em domínios onde o modelo já tem bastante conhecimento nos dados de treino, a diferença que uma skill faz tende a ser menor.

O esforço de setup pode não compensar

Existe uma tendência a montar setups elaborados para trabalhar com agentes de código: engenharia de contexto detalhada, troca de modelos por tipo de tarefa, controle granular de consumo de tokens. O estudo sugere que, pelo menos para tarefas mais padronizadas, esse esforço pode gerar diferença marginal.

Se a tarefa é de conhecimento relativamente público e o modelo já é bem treinado naquele domínio, a diferença entre um setup sofisticado e um prompt direto pode ser pequena. Isso não significa que skills são inúteis, mas que vale avaliar se o esforço de configuração está gerando retorno proporcional.

Para práticas de engenharia de software que são bastante padronizadas (separação de controllers e casos de uso, cálculos comuns, estilo funcional com imutabilidade), o modelo provavelmente já consegue operar bem sem instruções adicionais. A skill faz mais diferença quando o domínio é específico e não tão bem representado nos dados de treino.

A taxa de falha que ninguém comenta

O apêndice do estudo traz uma tabela com as tentativas e taxas de falha de cada modelo. Alguns números:

Opus 4.6: 1.245 tentativas, 67,1% de falha
Gemini 3 Pro: 61% de falha
Haiku e Sonnet: acima de 80% de falha

Esses números consideram todas as condições (com skill auto-gerada, com skill humana, sem skill). A maioria das tentativas falhou, mesmo em tarefas que envolvem conhecimento de domínio público.

Isso tem uma implicação direta para o fluxo de trabalho do dia a dia. Se a taxa de falha é essa em tarefas padronizadas, imagine dentro do contexto de negócio específico da sua empresa, com domínio que não é público e conexões que o modelo não tem como inferir. A taxa de falha provavelmente seria ainda maior.

Na prática, isso significa que o ciclo de gerar, revisar, direcionar e gerar novamente continua sendo o fluxo normal. Quanto mais aberta e ambígua a tarefa, maior a chance do modelo produzir algo diferente do esperado. A participação humana no direcionamento segue sendo importante para reduzir esse ciclo.

Analogia com VMs e otimização prematura

Uma maneira útil de pensar sobre isso é a analogia com máquinas virtuais. A JVM, por exemplo, faz otimizações sofisticadas em runtime. Na maioria dos casos, tentar micro-otimizar manualmente sem dados concretos pode até atrapalhar o trabalho da VM.

Com agentes de código pode estar acontecendo algo parecido. Em algum momento, tentar ajustar finamente o comportamento do agente com muitas regras e configurações pode ser contra-produtivo. Para a maioria das tarefas, apostar no comportamento padrão do modelo e iterar a partir do resultado pode ser mais eficiente do que montar um setup elaborado antes de começar.

Quando você tem dados concretos de que um ajuste específico faz diferença no seu contexto, aí sim vale configurar. Mas sem essa evidência, o default tende a funcionar razoavelmente bem.

Conclusão

O SkillBench traz dados úteis para calibrar expectativas. Skills escritas com participação de quem domina o assunto fazem diferença mensurável. Skills auto-geradas pelo agente praticamente não ajudam. A taxa de falha dos modelos ainda é alta mesmo em tarefas padronizadas, o que reforça que o direcionamento humano continua sendo parte essencial do fluxo.

Para quem trabalha com agentes de código no dia a dia, o ponto prático é: invista seu tempo no que você sabe sobre o problema, não na engenharia de contexto genérica. O conhecimento de domínio que você traz para a skill é o que faz a diferença, não a sofisticação do setup.

Dev + Eficiente

Estudo da Anthropic sobre IA e aprendizagem: o modo de uso importa mais do que a ferramenta

Alberto Luiz Souza — Mon, 16 Mar 2026 12:14:54 +0000

Este texto foi inicialmente concebido pelo Agente Marketing Dev + Eficiente em função da transcrição de um vídeo do canal Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

A Anthropic publicou um estudo chamado "How AI Impacts Skill Formation". O experimento colocou pessoas para implementar funcionalidades usando uma biblioteca Python, dividindo-as em dois grupos: um com acesso a assistentes baseados em LLM e outro sem. Depois, aplicaram um quiz sobre os conhecimentos adquiridos durante a tarefa. O grupo que não usou IA tirou notas melhores.

O resultado gerou bastante repercussão -- posts no LinkedIn dizendo que IA "emburrece" e alertas sobre o futuro da profissão. Mas quando olhamos os dados com mais cuidado, a história é mais nuançada do que o título sugere.

O que o estudo de fato mostra

O experimento usou uma biblioteca Python chamada Trio, que permite operações assíncronas com composição de tarefas. Os participantes tinham 35 minutos para completar a implementação.

Dois resultados chamam atenção:

Sobre produtividade: a diferença de tempo entre quem usou IA e quem não usou não foi tão expressiva quanto se poderia imaginar. A pessoa mais rápida com IA completou em aproximadamente 18 minutos, enquanto a mais rápida sem IA demorou cerca de 21. Para essa tarefa específica, o ganho de produtividade não foi marcante.

Sobre aprendizado: aqui a diferença foi significativa. A pior nota de quem não usou IA foi melhor do que a melhor nota de quem usou. Quem não teve a opção de delegar precisou ler a documentação, entender os conceitos e resolver os problemas por conta própria -- e esse esforço se refletiu no quiz.

Os padrões de uso que explicam a diferença

O estudo identificou diferentes padrões de interação com a IA, e nem todos levaram ao mesmo resultado:

Delegação total: a pessoa simplesmente pediu para a IA resolver e colou o resultado. Completou rápido (cerca de 19 minutos), mas ficou com média de 39% no quiz. É o padrão mais intuitivo quando o objetivo é apenas terminar.

Delegação do debugging: quando apareceu um bug, a pessoa delegou a resolução completa para a IA. Esse foi o pior cenário -- demorou mais para terminar e ainda resultou em notas baixas. A oportunidade de entender o que deu errado, e se prevenir na próxima vez, se perdeu.

Geração seguida de compreensão: a pessoa usou a IA para gerar o código, mas depois leu e tentou entender o que foi produzido. Esse grupo demorou um pouco mais, mas tirou notas na casa dos 60% -- não tão boas quanto quem não usou IA, mas com um trade-off possivelmente aceitável entre velocidade e aprendizado.

O que isso significa na prática

O estudo é honesto sobre suas limitações. As tarefas do experimento são isoladas e curtas, bem diferentes de tarefas reais de desenvolvimento, onde existe contexto acumulado, interação com outras equipes, análise de código existente e decisões arquiteturais.

Um exemplo prático: ao precisar salvar currículos em um bucket da Cloudflare usando o R2, é perfeitamente razoável pedir para um agente gerar o código de integração. Se alguém perguntar depois como a API do R2 funciona em detalhe, a resposta honesta pode ser "não sei de cabeça". Isso não diz nada sobre a capacidade da pessoa como engenheira -- é um componente pontual, mapeado, que pode ser consultado quando necessário.

Agora, o estudo evidencia algo que vale a atenção: quando a prioridade é só terminar, o impulso natural é parar de refletir. E falta de reflexão afeta o entendimento, a capacidade de pensar em alternativas e de se preparar para problemas futuros.

Sensação de produtividade versus produtividade real

Escrever mais código não significa produzir mais valor. Se alguém fala mil palavras por minuto e outra pessoa fala trezentas, isso não diz nada sobre a qualidade do que foi dito.

Com ferramentas de IA, é fácil colocar mais tarefas no pipeline simplesmente porque agora é possível gerar mais código. Mas o número de tarefas entregues que de fato geram valor pode não ter mudado.

Existem cenários onde o ganho de produtividade é óbvio e não faz sentido questionar: quando a pessoa não sabia fazer aquilo antes. Se alguém que nunca escreveu Swift consegue entregar uma funcionalidade com ajuda de IA, é claro que ficou "mais produtiva" -- antes não fazia nada.

O cenário que ainda carece de evidências mais robustas é quando a pessoa já sabe fazer o trabalho, delega para a IA e depois confere o resultado. Estudos mais longitudinais seriam necessários para entender o impacto real nessa situação.

O papel de quem usa o agente

Enquanto não existirem agentes operando sem humanos no loop, a responsabilidade pelo resultado é de quem abre o PR. Se o agente entregou algo, você aprovou, e depois não consegue explicar o que aquele código faz, o problema é seu.

Usar ferramentas de IA para estudar e trabalhar faz sentido -- é uma tecnologia que fornece feedback como se houvesse alguém acompanhando o que você está fazendo. Mas o modo de uso importa. Gerar e entender é diferente de gerar e ignorar.

Conclusão

O estudo da Anthropic não traz uma revelação surpreendente: menos reflexão leva a menos entendimento. Mas quantifica isso de forma controlada e identifica padrões de uso que podem orientar como cada pessoa decide interagir com ferramentas de IA no dia a dia.

A decisão prática é sobre quando vale abrir mão de entendimento profundo (componentes pontuais, integrações que não são o core do sistema) e quando vale investir o tempo de compreender o que foi gerado (lógica de negócio, componentes críticos, áreas onde um bug futuro pode puxar seu pé).

Dev + Eficiente

Como o RAG está sendo usado na indústria de software: o que dizem 26 estudos

Alberto Luiz Souza — Mon, 09 Mar 2026 11:49:23 +0000

Disclaimer

Este texto foi gerado pelo Agente Marketing Dev + Eficiente a partir de um relatório técnico de revisão sistemática sobre RAG na Engenharia de Software, conduzido com análise assistida por IA. O conteúdo abaixo sintetiza as principais evidências encontradas na literatura e em relatos industriais.

Introdução

RAG (Retrieval-Augmented Generation) combina mecanismos de recuperação de informação com modelos generativos. Na prática, o sistema consulta bases de conhecimento externas -- documentação técnica, logs operacionais, código-fonte, histórico de incidentes -- antes de produzir uma resposta. O modelo passa a fundamentar suas saídas em evidências recuperadas, reduzindo alucinações e aumentando a precisão.

Uma revisão sistemática recente analisou 26 estudos (entre 2021 e 2025) para entender como o RAG está sendo aplicado na indústria de software. Os resultados mostram que a tecnologia já ultrapassou o estágio experimental e está presente em ambientes de produção em diversos setores.

Onde o RAG está sendo usado

A distribuição por indústria revela três padrões:

Estudos transversais dominam. A maior parte dos trabalhos (7 estudos) discute arquiteturas, técnicas e desafios de forma independente do domínio. Isso indica que a comunidade está consolidando padrões de engenharia de RAG que podem ser aplicados em diferentes contextos.

Cloud/DevOps e empresas de tecnologia concentram as aplicações mais maduras. Computação em nuvem e tecnologia da internet aparecem com 2 estudos cada, com foco em observabilidade, detecção de anomalias em logs e revisão automática de código. São cenários onde documentação operacional, logs e conhecimento histórico estão naturalmente dispersos -- exatamente o tipo de problema que o RAG resolve.

Segurança e testes estão crescendo. A necessidade de rastreabilidade, redução de alucinação e reutilização de conhecimento histórico torna o RAG atrativo para detecção de vulnerabilidades e automação de artefatos de teste.

Além desses, o RAG aparece em setores como automotiva, telecomunicações, construção naval, energia e PMEs, demonstrando versatilidade.

Em quais etapas do desenvolvimento

A etapa de desenvolvimento e testes concentra a maior parte das evidências (14 dos 26 estudos). Dentro dela, o RAG é usado para:

Complemento de código em repositórios fechados, como no caso do WeChat, onde o modelo recebe contexto do repositório interno antes de sugerir complementos.
Revisão automática de código, fornecendo contexto de chamadas entre arquivos para gerar comentários mais relevantes e reduzir sugestões inválidas
Geração de testes, incluindo scripts de teste de integração na indústria automotiva e automação de casos de teste em sistemas ERP com orquestração multiagente
Operacionalização do RAG em produção, incluindo governança, trade-offs de latência versus qualidade e avaliação contínua

Fora de desenvolvimento e testes, o RAG aparece em resolução de incidentes (redução de MTTR com troubleshooting baseado em evidências), CI/CD (diagnóstico de falhas em pipelines) e cibersegurança (detecção de vulnerabilidades ancorada em bases como CWE/MITRE).

Quais LLMs estão sendo usadas

A escolha do modelo depende do contexto:

Família GPT aparece com maior frequência, por maturidade de ecossistema e capacidade de seguir instruções ancoradas em evidências. É a escolha predominante em sistemas de gestão do conhecimento e diagnóstico de incidentes em tempo real.

Família LLaMA se destaca quando a prioridade é implantação on-premises, custo e governança. O caso da Ericsson é ilustrativo: um chatbot RAG para CI/CD usando Llama2-chat, onde até o custo de trocar de LLM por diferenças de estilo de prompt foi avaliado.

Família Qwen aparece associada a operações de nuvem, equilibrando capacidade e custo. Também é usada em indústria tradicional (construção naval), indicando que modelos open-weight entram como escolha por viabilidade.

Modelos especializados em código (CodeLlama, DeepSeek-Coder, Yi-Coder, Codestral) competem com modelos gerais quando o domínio é programação. Vários estudos comparam múltiplos modelos para equilibrar custo e desempenho.

Embeddings: o que a indústria está escolhendo

A família BGE (BAAI) foi a mais recorrente. Aparece em cenários que exigem alta precisão de recuperação, frequentemente combinada com rerankers para refinar os resultados antes de enviar ao LLM.

Sentence-Transformers (all-MiniLM-L6-v2, all-distilroberta-v1) aparecem como opção pragmática para implantação rápida e pipelines leves.

Embeddings da OpenAI (text-embedding-3-large) são usados quando o pipeline já está acoplado ao ecossistema OpenAI.

Para código, embeddings especializados como CodeBERT e UniXcoder tendem a superar embeddings genéricos em tarefas de similaridade de código.

Arquiteturas que estão emergindo

Além do pipeline RAG clássico (ingestão, chunking, vetorização, recuperação, geração), a revisão identificou padrões arquiteturais mais sofisticados:

RAG híbrido (lexical + semântico). A combinação de BM25 com recuperação semântica aparece consistentemente como a configuração mais efetiva. Reciprocal Rank Fusion (RRF) é uma técnica recorrente para fundir os sinais.

Recuperação em dois estágios (Retrieve + Rerank). Primeiro recupera um conjunto maior com alta revocação, depois aplica um reranker (tipicamente cross-encoder) para alta precisão. Esse padrão aparece em múltiplos estudos industriais.

RAG guiado por intenção. Classificação da consulta do usuário, extração de metadados e reescrita de query antes da recuperação. Resolve o problema de consultas incompletas ou ambíguas em ambientes operacionais.

RAG com grafos e Agentic RAG. Para tarefas com dependências estruturais (chamadas entre arquivos, rastreabilidade), a combinação de banco vetorial com banco em grafo e orquestração multiagente. Alguns estudos já incorporam aprendizado por reforço para melhoria contínua baseada em feedback.

RAG com base de conhecimento dinâmica. A base de conhecimento evolui via active learning: logs com baixa incerteza são incorporados automaticamente, casos incertos vão para rotulagem humana. Adequado para cenários onde os dados mudam rapidamente.

Conclusão

As evidências indicam que o RAG já é uma tecnologia em uso industrial, não apenas experimental. Seu principal valor está em permitir que LLMs utilizem conhecimento corporativo -- documentação, código, histórico de incidentes -- fundamentando respostas em evidências concretas.

A eficácia depende menos do modelo de linguagem escolhido e mais da qualidade do pipeline de recuperação: estratégia de chunking, escolha de embeddings, mecanismos de reranking e integração com os fluxos de trabalho existentes. Quem está implementando RAG em produção precisa tratar o pipeline de recuperação com o mesmo rigor que trata qualquer outro componente crítico do sistema.

Artigo completo

O artigo completo pode ser lido aqui

Especialização em Engenharia de IA

Na Especialização em Engenharia de IA, uma parceria com a Dev + Eficiente, abordamos RAG na prática: desde a construção do pipeline de recuperação até estratégias de avaliação e operacionalização em produção. O curso inclui Vector Search, Busca Híbrida, Agentes, Tools e muito mais, sempre com aulas 100% práticas.

Faça sua inscrição em https://deveficiente.com/especializacao-engenharia-ia .

CDD: como tornar a avaliação de complexidade de código mensurável

Alberto Luiz Souza — Tue, 03 Mar 2026 12:43:47 +0000

Disclaimer

Este texto foi inicialmente concebido por um Agente Dev + Eficiente especializado nos conteúdos da Jornada e foi revisado por Alberto

Introdução

Uma classe que começa com 40 linhas e termina o ano com 400. Acontece em praticamente todo projeto. O problema não é a classe ter crescido. É que ninguém percebeu quando ela começou a ficar difícil de entender.

Não existe um ponto de ruptura claro -- ela vai acumulando responsabilidades, condicionais e dependências até que qualquer alteração começa a pesar muito mais do que deveria. E aí você tem um time inteiro olhando para o mesmo arquivo e cada pessoa avaliando a dificuldade de um jeito diferente.

A maioria das práticas que tentam resolver isso são baseadas em princípios qualitativos. "Responsabilidade única", "código limpo", "baixo acoplamento". Importantes, mas difíceis de aplicar de forma consistente entre pessoas diferentes de um mesmo time. O que é "responsabilidade única" para uma pessoa pode não ser para outra.

O Cognitive Driven Development (CDD) parte de uma premissa diferente: é possível tornar a avaliação de complexidade de código algo mensurável e compartilhado.

Para não causar confusão: não estamos falando de sustituição de práticas e sim de trazer uma prática que pode facilitar o uso das outras.

O fundamento: carga cognitiva aplicada a código

A teoria da carga cognitiva vem da psicologia educacional. A ideia central é que seres humanos possuem um limite restrito de capacidade de absorção de informação em um determinado intervalo de tempo. Uma referência clássica é o trabalho de Miller (1956), que estabelece que uma pessoa consegue manter aproximadamente 7 itens simultâneos na mente.

O insight do CDD é tratar código como material de consumo cognitivo -- assim como um slide, uma apostila ou um vídeo. Se existe um limite para o que uma pessoa consegue processar, então faz sentido que unidades de código também respeitem esse limite.

A partir daí, o CDD sugere que a complexidade de uma unidade de código (um arquivo, por exemplo) tenha um limite definido. Passou deste limite? A complexidade está maior do que queremos, precisamos ajustar.

Como funciona na prática

O processo é direto. A equipe decide quais elementos de código ela julga que mais pesam na mente das pessoas. Não existe resposta certa -- isso varia de time para time e de projeto para projeto.

Por exemplo, em um projeto com Java, a equipe pode definir (apenas um exemplo) os seguintes elementos:

Condicionais
Acoplamentos com classes do projeto
Funções como argumento

Cada elemento desse, dentro do CDD, é chamado de Intrinsic Complex Point (ICP). Num projeto usando Clojure, os elementos vão mudar. Num projeto usando Python, podem mudar de novo. A teoria é agnóstica de linguagem -- o que muda é quais construções da linguagem a equipe considera relevantes para o entendimento.

Pode-se definir que cada elemento contabiliza um ponto e, a partir disso, já fica bem mais fácil avaliar a complexidade. Supondo que o limite é 10, basta contar.

Por que isso funciona melhor do que princípios qualitativos

Três ganhos práticos:

Uniformidade de avaliação. Quando todo mundo conta os mesmos elementos e usa o mesmo limite, a discussão sobre complexidade sai do campo não determinístico e vai para o campo determinístico. Pessoas com níveis de experiência diferentes passam a analisar complexidade sob a mesma ótica.

Automação. Algo que se resume a contar elementos e comparar com um limite é completamente entendível por um programa. Isso pode entrar no CI, num linter, ou até ser delegado a um LLM (aceitando as variações nas respostas). Não depende de julgamento humano subjetivo no momento da verificação.

Adaptabilidade. Nada é fixo. A equipe, depois de iterar, pode querer trocar os ICPs, aumentar o limite, reduzir. A métrica evolui junto com o contexto do time. Se os acoplamentos com classes do projeto pararam de ser um problema porque todo mundo já domina, a equipe pode remover esse item e adicionar outro que passe a ser mais relevante.

O experimento

Já há alguns anos, foi feito um experimento com mais de 20 pessoas, comparando refatoração convencional com refatoração guiada pelo CDD. O grupo que usou a métrica chegou a resultados mais uniformes e com complexidade menor -- independente do nível de experiência de quem refatorou.

O ponto mais interessante: pessoas menos experientes entregaram código menos complexo do que pessoas mais experientes que refatoraram sem a métrica. Quando existe um limite claro e uma forma objetiva de medir, a experiência deixa de ser o único fator determinante para a qualidade do resultado. Métodos bons fazem diferença para diminuir diferenças de experiência.

O que muda no dia a dia

Na prática, adotar o CDD significa que o code review ganha um critério a mais -- e um critério que não depende de quem está revisando. Se o arquivo passou do limite, precisa ser dividido. Se não passou, está dentro do aceitável.

Isso não substitui a análise qualitativa. Você ainda vai discutir naming, coesão, decisões de design. Mas a questão "esse arquivo está complexo demais?" deixa de ser uma discussão sem fim.

Para projetos novos, a sugestão é começar com um limite mais restritivo e ajustar conforme a equipe ganha experiência com a métrica. Para projetos existentes, o caminho é contabilizar primeiro e aplicar o limite apenas para código novo -- sem sair refatorando tudo de uma vez.

CDD dentro da Jornada Dev + Eficiente

CDD é um dos mais de 20 cursos da Jornada Dev + Eficiente. E não é um curso isolado: o controle de complexidade de código se conecta diretamente com os cursos de design de código, engenharia de requisitos e DDD. A complexidade do código que você escreve é consequência de como você refinou o requisito, modelou o domínio e organizou as responsabilidades.

A Jornada cobre de controle de complexidade de código até operação de sistemas em produção. Acesso vitalício, todas as perguntas respondidas pelos instrutores e comunidade no Discord.

Acesse https://deveficiente.com/oferta-10-por-cento para conhecer tudo que oferecemos.

O que acontece dentro do pipeline da sua aplicação LLM?

Alberto Luiz Souza — Mon, 23 Feb 2026 00:07:42 +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

Quando colocamos uma aplicação LLM em produção, entender o que está acontecendo internamente deixa de ser opcional. Qual prompt foi montado? Quantos tokens foram consumidos? Onde exatamente uma chamada falhou? LangSmith é uma plataforma de observabilidade do ecossistema LangChain projetada para responder essas perguntas em todos os estágios do ciclo de vida de uma aplicação LLM, da prototipagem à produção.

Um ponto relevante: apesar de fazer parte do ecossistema LangChain, o LangSmith funciona de maneira independente. Isso significa que você pode monitorar chains e agentes desenvolvidos com qualquer framework, incluindo DSPy, LlamaIndex, CrewAI, LangGraph e outros.

Configuração inicial

Para começar a utilizar o LangSmith, o processo é direto. Você cria uma conta em smith.langchain.com e, uma vez logado, tem acesso às principais seções da plataforma:

Projetos: coleções de rastreamento organizadas por aplicação
Annotations: para anotar e revisar execuções
Playground: ambiente para testes rápidos
Datasets: conjuntos de dados para avaliação de qualidade
Hub: funciona como um repositório compartilhado de prompts, ferramentas e chains, similar ao Docker Hub

A configuração no código também é simples. Você gera uma chave de API nas configurações da plataforma e define algumas variáveis de ambiente:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_PROJECT=default
LANGSMITH_API_KEY=sua-chave-aqui

Com essas variáveis configuradas, toda a telemetria da sua aplicação é enviada automaticamente para o LangSmith. Se você já utiliza o LangChain, não precisa instalar nenhuma biblioteca adicional. O suporte ao LangSmith já vem embutido no pacote.

Exemplo 1: Monitorando uma chain do LangChain

No primeiro exemplo, temos uma chain simples que simula o comportamento de um RAG. Um system prompt orienta o assistente a responder com base apenas no contexto fornecido, e a pergunta do usuário recebe esse contexto como parâmetro.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um assistente útil. Responda a solicitação do usuário com base apenas no contexto fornecido."),
    ("user", "{question}\n\nContexto: {context}")
])

model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model | StrOutputParser()

chain.invoke({"question": "Resuma o texto", "context": texto})

Ao executar essa chain, o LangSmith captura automaticamente todo o fluxo. No painel da plataforma, podemos ver:

RunnableSequence: um resumo completo da execução, com todo o input enviado ao LLM
ChatOpenAI: detalhes do modelo utilizado, parâmetros como temperatura (0.7 por padrão, quando não configurada explicitamente), provider e nome do modelo
Metadata: versão do LangChain, sistema operacional de origem, versão do Python e outros dados de contexto

Na lateral, o LangSmith exibe informações operacionais importantes: timestamp, latência da chamada, quantidade de tokens consumidos e um cálculo estimado de custo.

Rastreamento por etapas

Um dos recursos mais úteis é a visualização passo a passo de cada etapa da execução. Você consegue acompanhar desde a montagem do prompt com o ChatPromptTemplate, passando pelo envio para a OpenAI, até o retorno formatado pelo StrOutputParser. Cada etapa aparece separada, o que facilita a identificação de gargalos ou comportamentos inesperados.

Captura de erros

Para demonstrar a captura de erros, basta trocar o modelo para um que não existe, como "gpt-5". O LangSmith registra o erro e permite investigar exatamente em qual etapa a execução falhou. Nesse caso, o ChatPromptTemplate foi montado corretamente, mas a chamada para a OpenAI retornou um erro informando que o modelo não foi encontrado. A mensagem aparece de forma clara e direta no painel.

Exemplo 2: Monitorando aplicações sem LangChain

E se a sua aplicação LLM não utiliza o LangChain? O LangSmith também funciona nesse cenário, com algumas configurações adicionais.

No segundo exemplo, temos uma aplicação que usa diretamente o client da OpenAI, com uma função Retriever que simula a recuperação de contexto de um banco vetorial. Para habilitar o rastreamento, são necessários dois passos.

Passo 1: Wrapper do client OpenAI

O LangSmith oferece um wrapper para o client da OpenAI que habilita a coleta de métricas:

from langsmith.wrappers import wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

Com essa configuração, o LangSmith passa a rastrear as chamadas ao ChatOpenAI. Porém, como não há as abstrações do LangChain, o rastreamento mostra apenas a chamada ao LLM como um bloco único.

Passo 2: Rastreamento granular com @traceable

Para obter mais detalhes sobre o pipeline completo, o LangSmith fornece o decorator @traceable:

from langsmith import traceable

@traceable
def retriever(query):
    # Simula recuperação de contexto
    return "LangSmith serve para observabilidade"

@traceable
def rag(query):
    context = retriever(query)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Responda com base no contexto: {context}"},
            {"role": "user", "content": query}
        ]
    )
    return response.choices[0].message.content

Com o @traceable aplicado nas funções, o LangSmith passa a rastrear cada etapa individualmente. No painel, a execução aparece hierarquicamente: a função RAG contém a chamada ao Retriever e, dentro dela, a chamada ao ChatOpenAI. A progressão fica visível: primeiro apenas o ChatOpenAI, depois a função RAG com o ChatOpenAI dentro, e por fim a cadeia completa com Retriever e ChatOpenAI.

Monitoramento e métricas

Em projetos com maior volume de execuções, a seção Monitor do LangSmith oferece gráficos com métricas operacionais:

Contagem de erros
Quantidade de chamadas ao LLM
Taxa de sucesso nas chamadas
Métricas de latência (p50, p95)
Tokens por segundo

Essas métricas ajudam a acompanhar a saúde da aplicação em produção e identificar degradações de performance ao longo do tempo.

Avaliação de qualidade com datasets

Além do monitoramento em tempo real, o LangSmith oferece recursos para avaliar a qualidade das respostas geradas pela sua aplicação. O fluxo funciona assim:

Você cria um dataset com pares de perguntas e respostas esperadas
Carrega o dataset na plataforma
Executa a avaliação contra diferentes versões da aplicação ou diferentes modelos

No exemplo apresentado, uma comparação entre GPT-4o Mini e GPT-3.5 Turbo mostra diferenças de verbosidade, consumo de tokens, latência e custo. É possível definir um baseline e comparar o desempenho de cada modelo contra ele. Na prática, isso permite implementar testes A/B entre versões da aplicação ou entre modelos diferentes, com dados concretos para embasar a decisão.

Conclusão

LangSmith resolve um problema prático de quem desenvolve aplicações LLM: saber o que está acontecendo dentro do pipeline. A configuração é simples, funciona com ou sem LangChain, e oferece desde rastreamento básico de chamadas até avaliação comparativa de modelos. Para quem está colocando aplicações LLM em produção, ter esse nível de visibilidade sobre o comportamento do sistema pode ser a diferença entre resolver um problema em minutos ou passar horas investigando logs.

Especialização em Engenharia de IA

Conheça a Especialização em Engenharia de IA Dev + Eficiente. O curso aborda RAG, Vector Search, Busca Híbrida, Agentes, Tools e muito mais, sempre com aulas 100% práticas e com exemplos reais.

Acesse https://deveficiente.com/especializacao-engenharia-ia .

Como expor sua API REST para um agente de código sem criar servidor MCP

Alberto Luiz Souza — Mon, 16 Feb 2026 11:48:37 +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

Servidores MCP se tornaram a maneira padronizada de expor APIs e funcionalidades para agentes de código como Claude Code, Cursor, Codex e outros. Mas existe uma discussão relevante no mercado sobre a complexidade que eles trazem. No fundo, em muitos casos, você está criando um wrapper da sua API que já existe para expor ela para o agente. E se existisse uma alternativa mais leve, que não exigisse criar um servidor novo em cima de algo que já funciona?

Neste post, mostro como usei a funcionalidade de Agent Skills do Claude Code para expor uma API REST existente para o agente, sem alterar nenhum código da API e sem construir um servidor MCP.

O contexto: MCP, complexidade e alternativas

Na Dev + Eficiente temos essa discussão internamente. Daniel Romero tem uma visão crítica de que o MCP nasceu inchado, trazendo complexidade desnecessária em cenários onde você já tem uma API funcionando. Do outro lado, existe o argumento de que o MCP é a maneira padrão de expor coisas para agentes, o que facilita a integração do ponto de vista de quem consome.

Existem alternativas mais leves surgindo, como o UTCP (Universal Tool Calling Protocol). Mas o caminho que explorei aqui foi diferente: usar a funcionalidade de Skills do Claude Code como ponte entre o agente e a API REST existente.

O que são Agent Skills

Agent Skills é uma funcionalidade do Claude Code que permite carregar instruções e scripts localmente. A própria Anthropic posiciona as Skills como algo mais local, que direciona o agente e pode inclusive orientar o consumo de serviços expostos via MCP ou qualquer outra fonte.

A estrutura é simples. Dentro da pasta .claude/skills/, você cria uma pasta com a sua skill contendo:

Um arquivo skill.md com nome, descrição e documentação dos endpoints
Scripts que o agente pode executar para consumir a API

Se você já criou uma tool para integrar com um agente, vai reconhecer a semelhança: a skill tem um nome e uma descrição que o LLM carrega no contexto. Quando você faz um pedido, o agente verifica se existe uma skill que pode ajudar a resolver e, se houver, carrega e executa.

O experimento: Contrate um Dev Eficiente

Para testar essa abordagem, usei a plataforma Contrate um Dev Eficiente, que conecta o mercado com as pessoas que estudam conosco. O objetivo era expor o módulo de analytics da plataforma para o Claude Code sem mexer em nada no código existente.

Estrutura do arquivo de skill

O arquivo skill.md segue um formato sugerido pela Anthropic:

Nome: analytics-contrate-dev-eficiente
Descrição: Fornece acesso aos endpoints de analytics...

Autenticação:
- Token deve ser configurado
- Header de autenticação: Bearer {token}

Endpoints disponíveis:
- /api/analytics - Análise geral (parâmetros: período)
- /api/analytics/empresas - Contatos de empresas
- /api/analytics/candidatos - Candidatos com currículo
- /api/analytics/ranking - Rankings de vagas e empresas

Além da documentação dos endpoints, o arquivo referencia um bash script que o agente pode executar para consumir a API.

O bash script

O script foi gerado pelo próprio Claude Code. Subi o agente no projeto do Contrate um Dev Eficiente, passei o link da documentação de Agent Skills da Anthropic, pedi para ele ler os endpoints do módulo de analytics e gerar tanto o arquivo de skill quanto o script de consumo autenticado.

#!/bin/bash
# Verifica token, faz a requisição autenticada e retorna o resultado

O LLM carrega a skill, vê que existe um script referenciado, executa o script passando os parâmetros necessários (que estão documentados no arquivo de skill), recebe a resposta da API e trabalha em cima disso.

Na prática: como funcionou

Consultas simples

Ao pedir "quero listar as empresas cadastradas", o Claude Code identificou a skill de analytics, carregou, verificou o token de autenticação e executou a consulta. Quando passei um token expirado por engano, ele recebeu 403, tentou outro endpoint, recebeu 403 novamente e me pediu um novo token. Com o token correto, retornou os dados reais da plataforma.

Análise composta

Ao pedir "quero uma análise geral", o agente decidiu por conta própria passar o parâmetro de período como seis meses. Consultou o endpoint, recebeu os dados e construiu uma análise com funil de conversão: empresas cadastradas, empresas com vagas, vagas com candidaturas, taxas de conversão e insights sobre a atividade da plataforma.

Cruzamento entre endpoints

Essa foi a parte mais interessante. Ao pedir "quero saber os nomes de pessoas que têm currículo e o perfil tech delas", o agente precisou combinar informações de endpoints diferentes. Primeiro consultou o endpoint que retorna currículos com perfil tech, depois identificou que não tinha os nomes, foi buscar no endpoint de candidatos com currículo e cruzou os dados.

A conexão com o nível 3 de maturidade REST

Esse comportamento lembrou o modelo de maturidade REST de Richardson. No nível 3, o conceito de HATEOAS (Hypermedia as the Engine of Application State) propõe que o protocolo seja autodocumentado, com links que guiam o cliente sobre o que fazer em seguida.

Na prática, poucos clientes HTTP implementam isso de verdade. Os clientes que construímos nas empresas são determinísticos: fazem chamadas pré-definidas, não seguem links dinamicamente. O navegador é o que mais se aproxima desse nível, por respeitar a semântica dos status codes e executar código que o servidor envia.

Mas quando um LLM consome uma API documentada via skill, algo parecido acontece. Ele consulta um endpoint, percebe que a informação que precisa não está ali, identifica outro endpoint que pode complementar e faz a segunda chamada. Não é exatamente HATEOAS, mas é uma forma de navegação dinâmica entre endpoints que até então era muito difícil de implementar em clientes tradicionais.

Uma pesquisa que fiz usando Deep Research do Claude encontrou um texto da Nord KPIs citando um arquiteto da Microsoft que argumenta que HATEOAS "chegou muito antes do que era possível, mas talvez agora seja mais possível". Concordo com essa visão.

Vantagens dessa abordagem

Nenhuma alteração no código existente: a API continua funcionando como antes
Sem servidor novo para manter: não é mais uma coisa para cuidar
Localidade: a skill é local, você expõe só o que quer, da partezinha que precisa
Flexibilidade: você pode editar o arquivo de skill para o seu contexto, limitar endpoints, adicionar instruções específicas
Replicável para qualquer API REST: qualquer endpoint HTTP autenticado pode ser exposto dessa maneira

Aplicações possíveis

A mesma lógica se aplica a outros cenários. Se você tem um serviço de logs, métricas ou observabilidade com API HTTP, pode gerar um arquivo de skill e acessar tudo via terminal com um agente no momento de troubleshooting. Se quer consumir a API pública do GitHub sem instalar o servidor MCP do GitHub, pode criar uma skill que documente os endpoints que você precisa e um script de acesso autenticado.

O repositório público de skills do Claude Code no GitHub já tem exemplos homologados pela Anthropic, como manipulação de PDF com scripts em Python, branding e outros. Servem como referência para construir as suas.

Conclusão

Agent Skills do Claude Code oferecem uma alternativa pragmática para expor APIs REST para agentes de código. Não é uma substituição do MCP -- são coisas diferentes, para contextos diferentes. O MCP continua sendo o padrão para integração ampla e distribuída. Mas quando o que você precisa é algo local, leve, sem adicionar mais uma camada de infraestrutura sobre algo que já funciona, as Skills resolvem bem.

O ponto central é: se você tem uma API REST funcionando, não precisa necessariamente criar um servidor MCP por cima dela. Um arquivo Markdown descrevendo os endpoints e um script de acesso podem ser suficientes para que o agente faça o trabalho.