DEV Community: Marcelo Mendes

De ferramenta individual ao básico de prática de time: estruturando IA no desenvolvimento.

Marcelo Mendes — Wed, 24 Jun 2026 01:22:04 +0000

A maioria de nós desenvolvedores já escreve código com IA diariamente. O que eu acredito ser mais incomum é um time inteiro usar IA de forma padronizada sem cair em dois extremos: virar muito burocrático e ninguém seguir, ou continuar cada um por si e ninguém saber se está no caminho certo.

Esse texto é sobre o meio-termo. Não é um tutorial de setup (a documentação oficial faz isso melhor e mais atualizada que qualquer post), e não é um case de sucesso ou com resultados, porque acho que ninguém tem ainda. É a forma como interpretei o problema depois de estudar os materiais que a Anthropic e a Cognition publicaram sobre o assunto, lido pela lente de quem trabalha com desenvolvimento web e sistemas distribuídos.

O problema raramente é o prompt

A mudança mais importante de perspectiva é parar de pensar no agente de IA como só "o modelo" e pensar nele como modelo mais o aparato em volta. Esse aparato tem um nome na literatura, chamam de harness. São as ferramentas, as verificações, o contexto que você fornece, os limites que você impõe, o loop de feedback que corrige o modelo quando ele erra.

Quando uma sessão de IA é ruim, muitas pessoas culpam de cara o modelo ou o prompt. Porém, na minha opinião, muitas vezes o problema está no harness: faltou contexto sobre como o código funciona, não havia testes pra validar se algo quebrou, o modelo não tinha como verificar o próprio trabalho. É o mesmo raciocínio de quando um serviço se comporta mal em produção e a causa não está no código da request, mas sim na ausência de timeout, retry, de métricas que mostrariam o problema antes.

Guarde essa palavra, harness é a infraestrutura em volta da IA, e quase tudo que vamos abordar aqui é uma forma de construí-la. Vamos começar pela decisão mais prática que ela permite.

Autonomia deveria seguir verificabilidade, não dificuldade

O instinto é dar mais autonomia pra IA em tarefas fáceis e menos em tarefas difíceis. Porém acho que o eixo é outro, focado em dar mais autonomia onde o trabalho é verificável, e menos onde não é.
Um serviço com boa cobertura de testes oferece ao agente um loop de feedback objetivo, ele edita, roda o teste, vê se quebrou, corrige. Você pode delegar bastante e revisar o resultado. Já um serviço sem testes não oferece esse loop, e aí a IA pode estar acelerando na direção errada sem que ninguém perceba, porque não há nada dizendo que o comportamento mudou. Nesse caso, o uso mais valioso da IA não é gerar a feature, é gerar os testes que capturam o comportamento atual e, com isso, transformar um serviço nebuloso em algo verificável. Você paga a dívida com a própria ferramenta antes de confiar nela.

Porém a verificabilidade não cai do céu: ela é parte do harness que você constrói. A forma mais simples é um arquivo na raiz do seu repo, o famoso CLAUDE.md (se você estiver usando os produtos da Anthropic), descrevendo o projeto pro agente, como buildar, como rodar os testes, as convenções, o que não tocar. Algo nessa linha:

# nome-do-serviço
O que ele faz, em uma frase. Stack principal.

## Comandos
- Build, teste do módulo, subir local

## Convenções (inegociáveis)
- Tratamento de erro padrão, validação na borda, etc.

## Não tocar sem aprovação humana
- Migrations, contratos públicos, fluxo de pagamento

Parece algo muito simples mas não é. Esse arquivo é insumo de toda sessão futura de IA, e é também documentação de onboarding básica pra gente nova. Porém, ele precisa estar sempre atualizado porque, se não, ele não fica só inútil, como também passa a contaminar o contexto, fazendo a IA gerar código errado com confiança. Documentação deixou de ser cortesia e virou parte da configuração de execução.

O fluxo que decorre disso é o mesmo de sempre, só esclarecendo:
explorar o código antes de escrever, propor um plano e ter esse plano revisado por um humano antes de gerar a primeira linha, implementar em etapas com verificação a cada passo, revisar o diff completo. O ponto de maior alavancagem é o plano. Errar no plano custa dez vezes mais do que errar numa linha, e é o momento mais barato pra uma pessoa intervir.

Por fim, os guardrails que não dependem do julgamento do modelo. Um hook que roda formatação e compilação a cada edição transforma "confio que a IA não quebrou o build" em "o build não passa, então não avança":

# roda a cada edição; exit != 0 devolve o erro pro agente corrigir
formatar "$arquivo" && compilar || exit 2

E uma lista de negação que impede a IA de editar migrations, contratos públicos ou código de pagamento sem aprovação. Repare que isso não é o modelo "decidindo" respeitar a regra, é o modelo sendo impedido. Determinismo onde determinismo importa.

O critério não é leitura ou escrita, é independência

Existe uma tentação forte, quando se fala em múltiplos agentes, de montar uma "equipe": um agente arquiteto, um agente QA, um agente revisor, todos decidindo. Parece legal e promissor, mas o problema é que a decisão entre agentes tende a ser uma votação por maioria, não por colaboração, eles convergem pro consenso em vez de pegar os erros uns dos outros. O critério útil não é leitura contra escrita ou nível de dificuldade, é na verdade independência: o trabalho se decompõe em partes que não se conversam, ou é uma cadeia de raciocínio onde cada passo depende do anterior?

A evidência direta é de um estudo que li recentemente do Google Research (Kim et al., "Towards a Science of Scaling Agent Systems") mostrando um dado gritante:
Em tarefas separáveis, a coordenação entre agentes melhorou o desempenho em até 81%; já em tarefas estritamente sequenciais, degradou de 39% a 70%, com a complexidade quase idêntica entre os dois grupos. E o mesmo estudo mostra que modelos melhores não fazem diferença nesse caso, quanto mais capaz o agente sozinho, menos sobra pra a coordenação compensar, então a barra pra o multi-agente valer a pena sobe com o tempo, e não o contrário. O subagente serve pra isolar contexto, como você isola um processo, não para dar personalidade a papéis.

Como saber se valeu (e a métrica que mente)

Chegamos na parte que mais me incomoda no discurso atual sobre IA em times, e é onde quero ser mais direto.

A métrica que mais aparece é "percentual de código gerado por IA". Ela parece boa porque é fácil de extrair e cresce rapidamente. E ela mede a coisa errada. Código gerado em volume não é valor entregue, pode até ser exatamente o oposto, código a mais pra revisar, manter e debugar. Otimizar por essa métrica é otimizar pra parecer produtivo.

O que importa medir é se o trabalho está saindo mais rápido sem piorar de qualidade. E aqui há uma vantagem metodológica interessante: como a adoção de IA num time é gradual e voluntária, você naturalmente tem, no mesmo período de tempo, demandas feitas com IA e demandas feitas sem. Isso é um grupo de comparação fácil de validar. Comparar "com IA" contra "sem IA" no mesmo intervalo de tempo é muito mais confiável que comparar "antes" contra "depois", porque elimina as variáveis que mudam ao longo do tempo: composição do time, fase do produto, pressão de prazo.

Para isso funcionar, basta uma marcação que diferencie as demandas que passaram pela IA das que não passaram. Com essa separação, as métricas que você provavelmente já coleta passam a contar uma história: tempo do início ao fim da demanda, quantidade entregue por período, tempo gasto em revisão, cards que geraram bugs.

Algo que eu acho que tem que ter cuidado é nunca medir velocidade sozinha. Velocidade sem qualidade é entregar problema mais rápido, repare que bati bastante nessa tecla, qualidade é muito indispensável. Toda métrica de tempo precisa estar emparelhada com uma de qualidade: quanto de retrabalho aquela demanda gerou, quantos bugs apareceram depois de ir pra produção.

O que isso é, e o que não é

Não tenho um número pra te vender. Tenho um jeito de raciocinar sobre o problema tratando o agente como modelo mais harness e investindo na infra, não no prompt; dê mais autonomia onde há verificação e construa verificação onde não há; paralelize leitura e serialize decisão; e acima de tudo meça o que importa de forma realista. Num assunto onde sobra empolgação e falta ceticismo, talvez essa última parte seja a mais útil.

Criando service discovery com spring cloud gateway e eureka

Marcelo Mendes — Mon, 10 Feb 2025 16:31:15 +0000

Como microsserviços se enxergam: Service Discovery com Spring Cloud Gateway e Eureka

Marcelo Mendes — Mon, 10 Feb 2025 00:41:04 +0000

Introdução

Nesse artigo, vamos explorar dois patterns amplamente utilizados em arquiteturas de microsserviços: Service Discovery e API Gateway. Veremos suas utilidades, benefícios e como implementá-los utilizando Spring Cloud Gateway e Eureka Server.

O que é um Service Discovery?

Em um ambiente de microsserviços, um cliente pode precisar se comunicar com diversas APIs que rodam em diferentes portas e servidores. Mas o cliente geralmente não sabe os endereços exatos dessas APIs.

Imagine o seguinte cenário:

Se não houver alguma forma para descobrir automaticamente os serviços disponíveis, precisaríamos gerenciar manualmente os endereços de cada API. Isso torna a manutenção do sistema mais complexa e suscetível a erros.

E pra isso temos o*Service Discovery. Ele age como uma espécie de banco de registro, onde as aplicações ao subirem, se registram nele permitindo que os clientes descubram automaticamente onde eles estão rodando. No ecossistema do Spring, utilizamos o **Eureka Server* para essa funcionalidade.

Quando as aplicações são iniciadas, elas se registram no Eureka Server. Assim, qualquer cliente pode consultar o Eureka e descobrir quais serviços estão disponíveis e onde eles estão rodando.

Com essa abordagem, um API Gateway pode atuar apenas como um roteador, passando para o Eureka a responsabilidade de gerenciar os registros dos serviços:

Implementação

Agora, vamos implementar um Gateway que busca os serviços registrados no Eureka Server. O código completo deste projeto está disponível no repositório no final do artigo.

Criando o Eureka Server

O primeiro passo é criar um projeto Spring Boot. Eu utilizei o Spring Initializr mas faça como preferir. Selecionando a dependência Eureka Server.

Após criar o projeto, abra-o na sua IDE e adicione as seguintes configurações no arquivo application.properties:

server.port=8761
eureka.client.register-with-eureka=false
eureka.client.fetch-registry=false

server.port=8761: Define a porta padrão do Eureka Server.
eureka.client.register-with-eureka=false: Como este é o servidor do Eureka, ele não precisa se registrar nele mesmo.
eureka.client.fetch-registry=false: Ele não precisa buscar registros, apenas fornecer informações aos clientes.

Agora, no arquivo ServiceDiscoveryApplication, adicionamos a anotação @EnableEurekaServer:

@SpringBootApplication
@EnableEurekaServer
public class ServiceDiscoveryApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceDiscoveryApplication.class, args);
    }
}

Agora, ao rodar o projeto, conseguimos visualizar a interface do Eureka Server acessando http://localhost:8761:

Por enquanto não temos nenhum serviço no registro porque não subimos nenhuma API no Eureka Server.

Criando Serviços Cliente (API-01 e API-02)

Vamos criar duas APIs simples (api-01 e api-02) que serão registradas no Eureka. Para isso, utilizamos o Spring Initializr, adicionando as dependências:

Eureka Client (para registro no Eureka Server)
Spring Web (para expor endpoints)

Configurações

No application.properties de cada API, adicionamos:

server.port=8181  # Ou outra porta para a segunda API
eureka.client.service-url.default-zone=http://localhost:8761/eureka/
eureka.client.register-with-eureka=true
eureka.client.fetch-registry=true

Criando um endpoint de teste

Agora, criamos um controlador simples para expor um endpoint:

@RestController
@RequestMapping("/api")
public class HealthCheckController {
    @GetMapping("/health")
    public String healthCheck() {
        return "API-01 está saudável!";
    }
}

Com isso, ao rodarmos as APIs, elas se registrarão automaticamente no Eureka Server.

Note que na imagem temos o gateway exposto também, ele será implementado no próximo passo.

Bom, já criamos o Eureka Server, a api-01 e a api-02. Elas já estão rodando, registradas e podem buscar informações no nosso serviço de descoberta. Agora temos algo parecido com um livro de endereços, onde conseguimos acessar as informações das APIs sem precisar lembrar de cada endereço e porta manualmente.
Mas ainda falta algo. A gente não quer que o cliente precise saber os endereços específicos de cada API, certo? Para resolver isso, usamos um gateway. Ele vai consultar o registro de serviços e passar um único ponto de acesso para os clientes, garantindo que todas as requisições entre microsserviços sejam roteadas de forma transparente.

Criando o API Gateway

O próximo passo é criar o Spring Cloud Gateway, que será responsável por rotear as requisições para os serviços registrados no Eureka.

No Spring Initializr, adicionamos as dependências:

Spring Cloud Gateway
Eureka Client

Configurações do Gateway

No application.properties, adicionamos:

eureka.client.service-url.default-zone=http://localhost:8761/eureka/
eureka.client.register-with-eureka=true
eureka.client.fetch-registry=true

spring.cloud.gateway.discovery.locator.enabled=true
spring.cloud.gateway.discovery.locator.lower-case-service-id=true

spring.cloud.gateway.discovery.locator.enabled=true: Permite que o Gateway descubra automaticamente os serviços registrados no Eureka.
spring.cloud.gateway.discovery.locator.lower-case-service-id=true: Garante que os nomes das aplicações sejam tratados em letras minúsculas, tornando as requisições mais legíveis.

Testando a Comunicação

Agora que o Gateway e os serviços estão configurados, podemos testar a comunicação.

Rodamos o Eureka Server
Rodamos as APIs (api-01 e api-02)
Rodamos o API Gateway
Verificamos o Eureka Server (http://localhost:8761)
- As APIs devem aparecer como registradas.
Testamos o roteamento
- http://localhost:8080/api-01/api/health → Deve retornar: API-01 está saudável!
- http://localhost:8080/api-02/api/health → Deve retornar: API-02 está saudável!

O Gateway está funcionando corretamente, roteando as requisições para os serviços automaticamente!

Conclusão

Com essa implementação, conseguimos:

✅ Criar um Eureka Server para gerenciar o registro de serviços.
✅ Criar APIs clientes que se registram automaticamente no Eureka.
✅ Configurar um API Gateway que roteia as requisições sem necessidade de mapear manualmente os endpoints.

Essa abordagem reduz o acoplamento entre os serviços e facilita a comunicação dinâmica entre microsserviços.

📌 O código completo do projeto pode ser acessado aqui (https://github.com/Marcelovmendes/service-discovery).

Gostou do artigo? Compartilhe e deixe seu comentário! 🚀

Reflection em Java: quando o código olha para si mesmo

Marcelo Mendes — Fri, 20 Dec 2024 23:41:05 +0000

Vamos explorar o que é Reflections, seus usos e cuidados, e como aplicá-lo na prática.

O que é Reflection?

Normalmente, quando você escreve código em Java, precisa saber de antes com quais classes está lidando. Você chama usuario.getNome() porque sabe que existe uma classe Usuario com esse método.

Reflection quebra essa regra. Com ela, o código consegue inspecionar e manipular classes, campos, métodos e construtores em tempo de execução, mesmo que você não conheça a classe na hora de compilar, e mesmo que os membros sejam privados.

É uma ferramenta poderosa para situações dinâmicas, onde você não sabe de antes com o que vai trabalhar. Mas, como veremos mais para frente, é poder que vem com responsabilidade rs.

Onde ela aparece?

Você provavelmente já usou Reflection sem perceber, porque ela está por trás de várias ferramentas que usamos todo dia:

Frameworks e bibliotecas. O JUnit usa Reflection para encontrar e rodar seus métodos de teste automaticamente. É por isso que basta anotar um método com @Test para ele ser executado, sem você precisar registrar nada manualmente.

Conversão de objetos. Bibliotecas como Jackson e Gson transformam objetos em JSON sem conhecer suas classes. Elas recebem um objeto qualquer, olham os campos dele em tempo de execução e montam o JSON a partir disso.

Carregar coisas dinamicamente. Sistemas de plugins, por exemplo, precisam instanciar classes que só são conhecidas quando o programa já está rodando.

O ponto em comum nesses casos é sempre o mesmo: a ferramenta não sabe de antemão com qual classe vai lidar. É aí que Reflection brilha.

Na prática

Vamos fazer algo parecido com o que o Jackson faz: uma função que recebe qualquer objeto e mostra os campos dele com seus valores, sem conhecer a classe.

Imagine uma classe simples:

public class Usuario {
    private String nome = "Marcelo";
    private int idade = 27;
    private boolean ativo = true;
}

Agora a função que inspeciona qualquer objeto:

import java.lang.reflect.Field;

public class Inspetor {

    public static void descrever(Object obj) {
        Class<?> classe = obj.getClass();
        System.out.println("Tipo: " + classe.getSimpleName());

        for (Field campo : classe.getDeclaredFields()) {
            campo.setAccessible(true); // libera o acesso mesmo se o campo for privado
            try {
                Object valor = campo.get(obj);
                System.out.println(campo.getName() + " = " + valor);
            } catch (IllegalAccessException e) {
                System.out.println("Não consegui ler o campo " + campo.getName());
            }
        }
    }
}

Chamando assim:

Inspetor.descrever(new Usuario());

A saída é:

Tipo: Usuario
nome = Marcelo
idade = 27
ativo = true

Repare que o Inspetor não sabe nada sobre a classe Usuario. Ele descobre tudo na hora. Se você passar um Produto, um Pedido ou qualquer outra classe, ele funciona do mesmo jeito. Esse é o tipo de problema em que Reflection é a escolha certa: quando a estrutura do objeto é genuinamente desconhecida.

Entendendo o fluxo

getClass() devolve um objeto Class, que é o ponto de partida de quase tudo em Reflection.
getDeclaredFields() lista os campos declarados na classe.
setAccessible(true) libera o acesso a campos privados. Sem isso, o Java bloqueia a leitura.
field.get(obj) lê o valor daquele campo no objeto que passamos.

Ferramentas principais da classe Reflection

O pacote java.lang.reflect oferece várias classes e métodos que tornam possível manipular dinamicamente os elementos de uma classe. Aqui estão algumas das ferramentas mais importantes:

Class: O ponto de partida

A classe Class é usada para obter informações e manipular classes. É frequentemente a porta de entrada para outras operações de Reflection.

Métodos úteis:

getDeclaredFields(): Retorna todos os campos declarados na classe.
getDeclaredMethods(): Retorna todos os métodos declarados na classe.
getDeclaredConstructors(): Retorna todos os construtores declarados na classe.
getSuperclass(): Obtém a superclasse da classe.
getInterfaces(): Retorna as interfaces implementadas pela classe.

Os cuidados

Reflection é útil, mas mexe em garantias que o Java normalmente oferece. Por isso, alguns pontos de atenção:

Quebra o encapsulamento. Você consegue acessar campos e métodos privados, ignorando os modificadores de acesso. Aquele private que protegia o campo deixa de proteger.

Os erros aparecem só ao rodar. Em código normal, se você erra o nome de um método, o compilador avisa na hora. Com Reflection, esses erros só aparecem em tempo de execução, o que torna bugs mais difíceis de pegar.

Tem custo de desempenho. Chamadas via Reflection são mais lentas que chamadas normais. Na maioria dos casos isso é irrelevante, mas em código que roda milhões de vezes pode pesar.

A regra prática é simples: antes de usar Reflection, pergunte se não existe um jeito mais direto de resolver. Muitas vezes uma interface, um Map ou um pouco de polimorfismo resolvem o problema sem abrir mão das garantias da linguagem. Reflection é ótima quando você realmente não tem como saber a estrutura de antemão, e é uma má ideia quando você está só contornando uma modelagem que poderia ser mais simples.

Conclusão

Reflection é uma ferramenta poderosa que permite ao código se inspecionar e se manipular em tempo de execução. É o que dá flexibilidade para frameworks, bibliotecas de serialização e sistemas de plugins funcionarem de forma genérica.

Mas esse poder tem um preço: ela abre mão de garantias importantes que o compilador normalmente oferece. Entender quando ela é a ferramenta certa, e principalmente quando não é, é o que faz a diferença para usá-la bem.