De horas de investigação manual em 8 repositórios à resolução automatizada de bugs em menos de 20 minutos.
O Problema
Se você já trabalhou em um produto que cresceu de um monolito para uma constelação de microsserviços, conhece a sensação: um bug é reportado e, antes mesmo de pensar em corrigi-lo, você precisa descobrir onde no ecossistema ele vive.
Um ecossistema multi-repo com 8 serviços independentes, cada um com sua própria stack, banco de dados e pipeline de deploy:
Regra central: o app mobile nunca chama microserviços diretamente — tudo passa pelo API Gateway (proxy pattern). Isso é ótimo para a arquitetura, mas significa que um único bug na ponta do usuário pode atravessar 3 ou 4 serviços.
Um cenário típico de sustentação costumava ser assim:
- Bug chega: "usuário não consegue completar uma recarga de saldo"
- É o app mobile? O API Gateway? O serviço de pagamentos? O processador de saldo? Um webhook de gateway de pagamento externo?
- Abrir cada repo, navegar na estrutura de pastas, rastrear o fluxo, ler o código
- Encontrar a causa raiz 45 minutos depois
- Corrigir, mas quebrar acidentalmente o contrato com o próximo serviço downstream
- Descobrir isso na sexta à tarde
Eu precisava de um sistema que fizesse o que um engenheiro sênior com conhecimento profundo do ecossistema faz — mas em minutos, não horas. E precisava ser confiável, não um autocomplete glorificado.
A Solução: Agentes de IA Especializados Orquestrados pelo Claude Code
Em vez de jogar uma IA de propósito geral no codebase e torcer pelo melhor, construí um sistema de sustentação estruturado em quatro camadas:
- Codebase Maps — Documentação detalhada para cada serviço
- Ecosystem Overview — Fluxos de integração entre todos os serviços
- Agentes Especializados — Cada um com uma única responsabilidade
- Skills & Convenções — Conhecimento reutilizável sobre os padrões de cada stack
Vou percorrer cada uma.
Camada 1: Codebase Maps
Essa é a fundação. Sem ela, nada mais funciona.
Para cada serviço, escrevi um documento dedicado que cobre:
- Estrutura de pastas com o propósito de cada diretório
- Arquivos-chave — os 10-20 arquivos onde 80% dos bugs vão ser encontrados
- Padrões — quais design patterns o serviço usa (Strategy, Factory, Provider, etc.)
- Pontos de integração — como ele conversa com outros serviços, como são os contratos
- Mecanismo de auth — JWT, Keycloak, API tokens ou endpoints públicos
- "Onde Procurar por Bugs" — uma seção curada mapeando categorias de sintomas a caminhos específicos de arquivos
Essa última seção é a mais valiosa. Em vez de dizer à IA "se vira", eu entrego os mesmos atalhos mentais que um desenvolvedor sênior constrói depois de meses no projeto.
Veja como uma seção "Onde Procurar por Bugs" se parece na prática:
### Onde Procurar por Bugs
| Sintoma | Comece Aqui |
|---------|-------------|
| Falhas de login | auth/strategies/, services/api.ts (interceptors) |
| Pagamento não finaliza | contexts/payment.tsx, services/api.ts (gateway instance) |
| Tela não carrega dados | screens/{feature}/, hooks/usePartnerFeatures.ts |
| Dados errados por tipo de usuário | utils/featureFlags.ts (check titular vs dependente) |
| Erros de agendamento | contexts/appointment.tsx, services/api.ts (appointment instance) |
Mantenho 6 codebase maps cobrindo todos os 8 serviços. Eles variam de 200 a 500 linhas cada — detalhados o suficiente para dar contexto real à IA, concisos o suficiente para caber em uma única leitura de janela de contexto.
Insight chave: esses documentos NÃO são gerados a partir do código. Eles capturam conhecimento que não está no código — o "porquê", as pegadinhas, o conhecimento tribal. Coisas como "esse endpoint de webhook não tem auth de propósito porque gateways de pagamento externos o chamam" ou "valores estão em centavos nesse serviço mas em reais nas APIs legadas — sempre dividir por 100".
Camada 2: Ecosystem Overview
Enquanto os codebase maps são profundos (verticais), o ecosystem overview é amplo (horizontal). Ele mapeia cada fluxo de integração de ponta a ponta.
Esse documento também contém tabelas de referência transversais:
- Auth por serviço — qual tipo de token, qual mecanismo, quais roles
- Bancos de dados — qual serviço é dono de quais tabelas
- Filas SQS — FIFO vs Standard, produtor, consumidor, propósito
- Serviços externos — gateways de pagamento, provedores de telemedicina, APIs de endereço
- Glossário de conceitos-chave — os termos específicos do domínio que conectam tudo
O overview é carregado automaticamente em cada sessão de IA. Os codebase maps são carregados sob demanda quando um serviço específico precisa de investigação. Isso equilibra uso de contexto com profundidade de conhecimento.
Camada 3: Agentes Especializados
Aqui é onde fica interessante. Em vez de um agente de IA "faz tudo", construí quatro com separação estrita de papéis:
Bug Hunter (Apenas Análise)
Papel: Investigar a causa raiz. Nunca escrever código.
Como funciona:
- Lê o ecosystem overview para entender qual fluxo de integração está envolvido
- Identifica qual(is) serviço(s) são afetados
- Lê o(s) codebase map(s) específico(s) — usa a seção "Onde Procurar por Bugs"
- Navega até os arquivos-fonte reais para confirmar a hipótese
- Produz um diagnóstico estruturado
Formato de saída:
- Serviço(s) afetado(s): [quais serviços]
- Fluxo impactado: [Login, Pagamento, Agendamento, etc.]
- Causa raiz provável: [descrição técnica]
- Arquivo(s) suspeito(s): [caminho exato + linha aproximada]
- Classificação: frontend | backend | integração
- Evidências: [trechos de código que confirmam a análise]
- Recomendação de fix: [o que precisa mudar, sem implementar]
Por que é read-only: Separar análise de implementação previne o modo de falha comum onde uma IA "corrige" um bug adicionando optional chaining em tudo sem entender por que o valor está null em primeiro lugar.
Dev Front (Implementação Frontend)
Papel: Implementar fixes no app mobile (React Native + Expo) e no dashboard admin (React + Refine).
Recebe o diagnóstico do Bug Hunter, lê o codebase map relevante, lê todos os arquivos que vai modificar antes de editar, implementa o fix mínimo e roda validação de TypeScript.
Conhece as convenções de cada frontend: Zustand para state persistido vs Context API para state de fluxo no app mobile, hooks do Refine com o data provider correto no dashboard admin, as 4 diferentes instâncias do Axios para grupos diferentes de serviços, etc.
Dev Back (Implementação Backend)
Papel: Implementar fixes em todos os 6 serviços backend.
Mesmo workflow do Dev Front, mas cobrindo Express.js (JavaScript legado, sem TypeScript), Hono com decorators e Prisma, AdonisJS com Lucid ORM, funções Lambda com SQS e endpoints serverless.
Ele respeita os padrões muito diferentes entre serviços: factory pattern com makeController() no API Gateway, roteamento baseado em decorators (@Route, @Get, @Guard) no serviço de agendamentos, soft-delete com deleted_at no serviço de pagamentos, checagens de idempotência no processador de saldo.
QA Reviewer (Apenas Validação)
Papel: Revisar o fix. Nunca escrever código. Máximo 3 ciclos de revisão por bug.
Esse é o agente mais importante. Ele executa um checklist estruturado:
Corretude:
- O fix endereça a causa raiz (não apenas o sintoma)?
- Há edge cases não cobertos?
- Funciona para ambos os tipos de usuário? (nosso sistema distingue entre titulares primários e dependentes com conjuntos de features diferentes)
Regressões:
- Arquivos relacionados foram impactados negativamente?
- O contrato de request/response da API foi preservado?
- O middleware de auth está intacto?
Caça a Silent Failures (esse é o diferencial):
- Catch blocks adicionados: têm logging E feedback ao usuário?
- Fallbacks adicionados: são explícitos com logging quando ativados?
- Condicionais adicionadas: o branch else trata a falha?
- Optional chaining adicionado: resolve o crash mas esconde a causa raiz?
Cada achado é classificado:
- ✅ Fix correto, sem novas silent failures
- ⚠️ Correto mas frágil (não bloqueante)
- ❌ Fix introduz silent failure (BLOQUEANTE — volta para o dev)
Por que o agente de QA importa mais: Sem ele, os agentes dev tendem a produzir fixes "tecnicamente funcionam" que mascaram problemas. Um catch block sem logging? O erro some silenciosamente. Optional chaining em um valor que nunca deveria ser null? Você escondeu um problema de dados. O agente de QA pega esses padrões sistematicamente.
Camada 4: Skills & Convenções
Skills são módulos de conhecimento reutilizáveis que os agentes consultam proativamente. Tenho três:
Ecosystem Knowledge: Referência rápida para mapeamento de serviços, fluxos de integração e conceitos de domínio. Cada agente carrega essa primeiro.
Frontend Conventions: Padrões para cada frontend — como estruturar componentes, qual abordagem de state management usar, como lidar com chamadas de API, anti-patterns a evitar.
Backend Conventions: Padrões específicos por stack — como escrever rotas em cada framework, convenções de ORM, posicionamento de middleware de auth, padrões de formato de resposta.
Essas skills previnem que os agentes "reinventem" padrões a cada bug. Em vez de adivinhar como adicionar uma nova rota no serviço de agendamentos, o agente dev sabe usar decorators @Route + @Get + @Guard('ROLE') porque a skill de convenções diz isso.
O Pipeline em Ação
Veja o que acontece quando um bug é reportado:
Reporte de bug → Bug Hunter (2-3 min)
↓ diagnóstico
Dev Front e/ou Dev Back (3-5 min)
↓ fix implementado
QA Reviewer (1-2 min)
↓
APROVADO → pronto
REPROVADO → volta para o Dev (máx 3 ciclos)
Tempo total para um ciclo completo: menos de 10 minutos.
Vou percorrer um exemplo real (anonimizado):
Reporte de bug: "Usuários do plano tipo B não conseguem ver a tela de recarga de saldo"
Análise do Bug Hunter (2 minutos):
- Identificou a checagem de feature flag do app mobile: estava lendo
partner.featurespara todos os usuários, mas usuários do plano tipo B são dependentes que precisam departner.dependent_features - Rastreou o fluxo: o componente da tela chamava
checkIsEnabledFeature('reload'), que internamente consultava o conjunto errado de features para usuários dependentes - Classificado como:
frontend— o backend estava retornando dados corretos, o app mobile estava lendo o campo errado - Apontou:
utils/featureFlags.ts:47escreens/Payment/Reload/index.tsx:23
Fix do Dev Front (3 minutos):
- Leu ambos os arquivos + o contexto que fornece a flag do tipo de usuário
- Modificou o utilitário de checagem de feature para ramificar em
isDependent - Rodou
tsc --noEmit— passou - Reportou o fix com diff exato
Revisão do QA (1 minuto):
- Confirmou: fix endereça a causa raiz, não o sintoma
- Confirmou: funciona para titulares E dependentes
- Confirmou: nenhuma silent failure introduzida (sem catch blocks, sem optional chaining — branch condicional limpo)
- Resultado: APROVADO
Antes desse sistema, esse bug teria levado 30-60 minutos de investigação manual em múltiplos repos, mais tempo de revisão.
Os Guardrails
IA autônoma escrevendo código no seu codebase precisa de redes de segurança. Eis o que coloquei em prática:
Hooks de proteção de arquivos: Certos arquivos são bloqueados para edição por IA — configs de ambiente, Docker Compose, schemas de banco. Esses arquivos requerem mãos humanas.
Nenhuma operação destrutiva: Agentes nunca podem fazer git push, git reset --hard ou disparar deploys. Eles trabalham localmente, e um humano revisa antes de qualquer coisa chegar em um branch remoto.
Princípio do fix mínimo: As diretrizes de dev declaram explicitamente: "fix mínimo — não refatore código adjacente, não adicione comentários desnecessários." Isso previne scope creep onde a IA "melhora" código que funciona e introduz regressões.
Validação mandatória: Todo fix precisa passar pela compilação de TypeScript (tsc --noEmit) antes do agente dev considerá-lo feito. A única exceção é o API Gateway legado em JavaScript.
Output estruturado: Cada agente produz saída em um formato mandatório. O Bug Hunter deve fornecer classificação e evidências. Os agentes Dev devem documentar serviços impactados. O agente de QA deve rodar o checklist completo. Sem mão-de-obra.
O Que Aprendi
1. A qualidade da documentação é o multiplicador
Gastei mais tempo escrevendo codebase maps do que configurando agentes. Esse investimento se paga todos os dias. Um mapa de serviço bem documentado com seções "Onde Procurar por Bugs" dá à IA a mesma intuição que um desenvolvedor sênior tem — sem os meses de construção de contexto.
Se sua ferramenta de IA para codar está produzindo resultados genéricos ou errados, o problema quase certamente é contexto, não o modelo.
2. Separação de responsabilidades se aplica a agentes de IA também
Um agente que analisa, implementa E revisa o próprio trabalho é como um desenvolvedor que escreve código, revisa o próprio PR e faz deploy para produção. O loop de feedback é apertado demais, e os erros se acumulam.
O Bug Hunter não pode mascarar uma causa raiz escrevendo um fix rápido. Os agentes Dev não podem aprovar o próprio trabalho. O agente de QA não pode ajustar silenciosamente o código em vez de sinalizar um problema. Cada restrição torna o sistema geral mais confiável.
3. O agente de QA é a peça mais valiosa
Sem caça explícita a silent failures, fixes gerados por IA tendem a padrões "fazer o erro sumir": catch blocks vazios, optional chaining generalizado, valores default que escondem problemas de dados. O checklist estruturado do agente de QA pega exatamente esses padrões.
O sistema de classificação (correto / frágil / introduz silent failure) força julgamento explícito em vez de "parece bom pra mim".
4. Skills previnem deriva de padrões
Sem documentos de convenções reutilizáveis, cada fix de bug reinventa como as coisas deveriam ser estruturadas. O agente dev pode usar um padrão de state management diferente do que existe no codebase, ou adicionar uma rota em um estilo que não casa com as convenções do serviço.
Skills ancoram os agentes aos padrões reais do projeto, não aos padrões de treinamento do modelo.
5. O mapa do ecossistema importa mais que os docs de serviço individuais
Bugs cross-service são os mais difíceis. Saber que valores estão em centavos no serviço de pagamentos mas em reais nas APIs legadas, que webhooks de gateways externos intencionalmente não têm auth, que o processador de saldo checa histórico de transações para idempotência antes de creditar — essas são as pegadinhas que causam investigações de 2 horas.
O ecosystem overview captura esse conhecimento de integração em um só lugar. Sem ele, agentes podem "corrigir" um bug adicionando auth em um webhook que sistemas externos chamam, quebrando o fluxo de pagamento inteiro.
6. O limite de 3 ciclos no QA previne loops infinitos
Sem ele, o agente de QA e o agente dev podem ficar em ping-pong: QA reprova, dev corrige, QA encontra um novo problema no fix, dev corrige, QA encontra outro. Três ciclos é o ponto certo — se um fix não consegue passar em revisão em 3 tentativas, precisa de atenção humana.
O Setup em Números
| Métrica | Valor |
|---|---|
| Serviços cobertos | 8 |
| Codebase maps | 6 documentos (200-500 linhas cada) |
| Fluxos de integração documentados | 7 fluxos ponta a ponta |
| Agentes especializados | 4 (análise, frontend, backend, QA) |
| Skills reutilizáveis | 3 (ecosystem, frontend, backend conventions) |
| Análise média de causa raiz | 5-10 minutos |
| Implementação média de fix | 2-8 minutos |
| Revisão média de QA | 1-2 minutos |
| Ciclo completo (análise → fix → aprovado) | < 20 minutos |
| Tempo anterior de investigação manual | 30-90 minutos |
Como Replicar Isso
Se você está lidando com um ecossistema multi-serviço similar e quer construir algo assim:
Comece pela documentação, não pelos agentes. Escreva codebase maps para seus serviços mais críticos primeiro. Inclua a seção "Onde Procurar por Bugs" — é a peça de documentação de maior ROI que você já vai escrever.
Mapeie seus fluxos de integração. Mesmo antes da IA entrar em cena, ter um único documento que rastreia dados através dos serviços economiza um tempo enorme de investigação para desenvolvedores humanos também.
Separe análise de implementação. Mesmo que você construa apenas dois agentes, faça um que seja read-only e outro que escreve. O analista read-only produz diagnósticos melhores porque não pode encurtar a investigação pulando para um fix.
Invista na camada de QA. Caça a silent failures é o diferencial entre "IA que produz código" e "IA que produz código confiável". Construa um checklist específico para os padrões comuns de falha do seu codebase.
Codifique suas convenções. Se seu time tem regras não escritas sobre como estruturar código em cada serviço, escreva-as. Elas se tornam as skills que mantêm a saída da IA consistente com seus padrões existentes.
Estabeleça limites rígidos. Arquivos protegidos, nenhuma operação git destrutiva, validação TypeScript mandatória, formatos de output estruturados. Esses guardrails não são opcionais — são o que torna o sistema confiável o suficiente para uso diário.
Considerações Finais
Isso não é sobre substituir desenvolvedores. É sobre construir um sistema que lida com o overhead investigativo de ecossistemas multi-serviço — o context-switching entre repos, o rastreamento de fluxos de dados através de fronteiras, a caça por causas raiz em codebases desconhecidos.
A IA não precisa ser perfeita. Precisa ser estruturada, restrita e revisável. Quatro agentes especializados com limites claros produzem resultados dramaticamente melhores do que um agente de propósito geral com escopo ilimitado.
O trabalho real estava na documentação e no design do sistema, não em prompt engineering. Se o conhecimento do seu ecossistema vive apenas na cabeça das pessoas, comece a escrever. Esse é o pré-requisito — tudo o mais constrói em cima disso.
Construído com Claude Code. As definições de agente, skills, codebase maps e pipeline descritos nesse artigo são todos configurados usando os recursos nativos do Claude Code: agentes customizados, skills, rules e hooks.
Top comments (0)