Aqui está a tradução do texto para o português do Brasil, seguindo todas as diretrizes fornecidas.
Achei que estava usando IA para programar.
Na verdade, eu só estava digitando mais rápido.
Aqui está a diferença — e o sistema de 7 agentes que mudou tudo.
Salve isto. Vai te poupar meses.
O PROBLEMA QUE NINGUÉM MENCIONA
O ciclo que parece produtivo, mas não é:
→ Peça ao Claude para criar uma funcionalidade → Ele gera o código → Algo quebra → Cole o erro de volta → Ele corrige → Outra coisa quebra → Peça novamente
Dia 1: parece mágica.
Dia 30: você passa mais tempo supervisionando a IA do que costumava gastar escrevendo código.
A mesma lógica aparece em 3 lugares diferentes.
O Claude esqueceu a convenção que você definiu há duas semanas.
Funcionalidades novas quebram as antigas.
Testes estão faltando ou são superficiais.
Você acorda e percebe: a IA não está falhando.
Seu fluxo de trabalho está.
O problema real é estrutural.
Quando você digita "crie esta funcionalidade" no Claude Code, você está pedindo para uma única sessão de IA ser:
→ Analista de produto → Arquiteto → Engenheiro de backend → Engenheiro de frontend → Engenheiro de teste → Revisor de código
Tudo ao mesmo tempo.
Na mesma conversa bagunçada.
Suposições erradas no plano viram modelos de banco de dados errados.
Modelos de banco de dados errados viram APIs erradas.
APIs erradas viram UIs erradas.
Quando você percebe, o erro já se espalhou por todo lugar.
Isso se chama codificação por vibração (vibe coding).
E tem um teto duro.
A MUDANÇA: DA CODIFICAÇÃO POR VIBRAÇÃO PARA UMA FÁBRICA DE SOFTWARE
O que realmente muda tudo:
Equipes de engenharia de verdade não trabalham em uma única grande conversa.
Pessoas diferentes são responsáveis por tarefas diferentes:
→ Alguém esclarece o problema do usuário → Alguém pensa na arquitetura → Alguém constrói a API → Alguém constrói a interface → Alguém pensa nos casos extremos → Alguém revisa
Quando você junta tudo isso em uma única sessão de IA, os erros se acumulam silenciosamente.
A solução é dividir o trabalho entre agentes especializados.
Cada agente recebe: → Uma tarefa focada → Sua própria janela de contexto limpa → Apenas as ferramentas que realmente precisa → Regras rígidas sobre o que não pode tocar
O resultado: uma fábrica de software.
Um desenvolvedor + sete agentes focados = uma equipe coordenada.
Aqui estão os sete agentes que fazem isso funcionar.
OS 7 AGENTES
Agente 1: O Pesquisador do Código
O maior erro que os desenvolvedores cometem com IA?
Pedir código como primeiro passo.
A IA aceita o prompt, faz suposições para preencher as lacunas e começa a gerar.
É aí que designs ruins aparecem.
O Pesquisador do Código resolve isso.
A única função dele: inspecionar o código e explicar como as coisas funcionam — antes de uma única linha ser escrita.
O que ele faz: → Mapeia os arquivos relevantes e suas funções → Documenta os padrões existentes a serem seguidos → Encontra funcionalidades semelhantes já construídas → Sinaliza riscos (fuso horário, multi-inquilino, lógica de repetição) → Lista quais testes precisarão ser atualizados
O que ele não pode fazer: → Editar arquivos (acesso somente leitura) → Executar qualquer comando que modifique o estado → Fazer suposições — ele pergunta
Ferramentas: Apenas Read, Grep, Glob.
A regra: explore antes de construir, todas as vezes.
O Pesquisador executa primeiro. Sempre.
Agente 2: O Escritor de Histórias
A maioria das funcionalidades falha não porque o código estava errado.
Mas porque o problema nunca foi claramente definido.
O Escritor de Histórias transforma uma ideia vaga de funcionalidade em uma história de usuário real antes que qualquer decisão técnica seja tomada.
Entrada que ele recebe: → Sua descrição aproximada da funcionalidade → As descobertas do Pesquisador
O que ele produz:
Uma história de usuário:"Como [função], quero [comportamento], para que [resultado]."
Critérios de aceitação:Declarações que um teste pode verificar diretamente. Caminho feliz. Caminhos de falha. Regras de negócio.
Casos extremos:Limites, repetições, preocupações de multi-inquilino.
Fora do escopo:O que explicitamente NÃO será construído.
Perguntas em aberto:Coisas que ele genuinamente não sabe — nunca chuta.
O que ele não pode fazer: → Inventar regras de negócio → Escrever qualquer código ou design técnico → Seguir em frente se algo não estiver claro
Ferramentas: Apenas leitura.
A regra: você lê esta história e a aprova antes de qualquer outra coisa acontecer.
Este é o ponto de verificação humano que salva tudo que vem depois.
Agente 3: O Escritor de Especificações
Assim que a história é aprovada, o Escritor de Especificações a transforma em um resumo técnico.
Este é o modelo que todos os agentes de construção seguem.
Entrada que ele recebe: → Sua história de usuário aprovada → As descobertas do Pesquisador → As regras do seu CLAUDE.md do projeto
O que ele produz:
→ Mudanças no modelo de dados (campos, tipos, migrações) → Fluxo em segundo plano / fluxo de processo → Mudanças na API (endpoints, formatos de requisição/resposta) → Mudanças no frontend (componentes, páginas, hooks) → Testes necessários (sucesso, falha, casos extremos) → Riscos e perguntas em aberto → Cada arquivo que será alterado
O que ele não pode fazer: → Editar qualquer arquivo → Inventar nova infraestrutura — em vez disso, menciona explicitamente → Ignorar preocupações de isolamento de inquilino ou fuso horário → Deixar perguntas sem resposta
Ferramentas: Apenas Read, Grep, Glob.
A regra: este resumo é o segundo ponto de verificação humano.
Você o lê e aprova antes que um único arquivo seja tocado.
Se você vir "armazenar IDs na memória" — essa é sua bandeira vermelha.
Pegue agora. Não depois que 10 arquivos forem alterados.
Agente 4: O Construtor de Backend
Agora a construção começa.
O Construtor de Backend implementa a metade do backend da funcionalidade — e apenas a metade do backend.
Entrada que ele recebe: → Resumo técnico aprovado → Descobertas do Pesquisador → CLAUDE.md do seu projeto
O que ele constrói: → Rotas da API → Serviços e lógica de negócio → Acesso ao banco de dados e migrações → Tarefas em segundo plano → Testes unitários para tudo que ele escreve
O que ele não pode fazer: → Tocar em componentes React, páginas ou hooks do lado do cliente (isso é o Agente 5) → Inventar novas dependências sem instrução → Modificar arquivos fora do escopo acordado → Parar sem executar typecheck, lint e a suíte de testes
Após terminar, ele retorna um resumo: → Cada arquivo adicionado ou editado → Cada helper ou padrão existente reutilizado → Qualquer regra do CLAUDE.md que teria ajudado
Ferramentas: Read, Edit, Write, Bash — com escopo apenas para as pastas do backend.
A separação é o ponto principal.
O Construtor de Backend nunca pode quebrar acidentalmente o frontend. Nunca.
Agente 5: O Construtor de Frontend
O Construtor de Frontend implementa a metade da interface — e apenas a metade da interface.
Ele lê o resumo do Construtor de Backend primeiro.
Isso é importante.
Ele consome a API exatamente como o backend a produziu.
Ele não inventa novos endpoints.
Se o formato da API estiver errado para a interface, ele sinaliza a incompatibilidade como feedback — não como uma correção.
Entrada que ele recebe: → Resumo técnico aprovado → Descobertas do Pesquisador → Resumo do Construtor de Backend (o contrato da API)
O que ele constrói: → Componentes e páginas React → Hooks e estado do lado do cliente → Estados de carregamento e erro → Testes de componente e unitários para tudo que ele escreve
O que ele não pode fazer: → Tocar em serviços, rotas de API, workers ou migrações (isso é o Agente 4) → Inventar endpoints ou formatos de resposta → Adicionar dependências sem instrução → Parar sem executar typecheck, lint e a suíte de testes
Ferramentas: Read, Edit, Write, Bash — com escopo apenas para as pastas do frontend.
Dois construtores.
Duas janelas de contexto limpas.
Zero chance de um quebrar o trabalho do outro.
Agente 6: O Verificador de Testes
Ambos os construtores escreveram testes unitários para seu próprio código.
Isso não é suficiente.
O Verificador de Testes faz apenas uma coisa: provar que a funcionalidade realmente faz o que a história de usuário disse que deveria fazer.
Ele escreve testes de aceitação.
Não testes unitários.
Testes de aceitação.
Estes testam a funcionalidade de fora — da maneira que um usuário real a experimentaria.
Entrada que ele recebe: → História de usuário aprovada (com todos os critérios de aceitação) → Resumo técnico aprovado → Resumos de ambos os construtores
O que ele produz: → Um arquivo de teste de aceitação cobrindo cada critério de aceitação → Um relatório: quais critérios passaram, quais falharam, quais não podem ser cobertos adequadamente
O que ele não pode fazer: → Modificar qualquer código de backend ou frontend → Inventar soluções alternativas para critérios não testáveis → Marcar um critério como coberto se ele genuinamente não estiver
Se um teste falhar: a funcionalidade não satisfaz a história.
Ele relata exatamente qual critério falhou.
Ele não corrige o código.
Isso volta para o construtor certo.
Ferramentas: Read, Edit, Write (apenas arquivos de teste), Bash.
A regra: você não tem uma funcionalidade até que os testes de aceitação passem.
Agente 7: O Validador de Implementação
Este é o agente que pega tudo que todos os outros perderam.
O Validador compara a implementação atual contra a história e o resumo aprovados — e relata lacunas.
Ele nunca corrige nada.
Ele apenas diz a verdade.
Todas as verificações que ele executa, toda vez:
→ Critérios de aceitação da história ainda não implementados → Caminhos de falha sem cobertura de teste → Problemas de segurança: verificações de autenticação ausentes, lacunas de isolamento de inquilino, segredos em logs, erros brutos expostos aos clientes → Arquivos alterados fora do escopo acordado → Padrões inconsistentes com o CLAUDE.md ou código existente → Lógica duplicada que deveria reutilizar helpers existentes → Preocupações de fuso horário ou multi-inquilino do resumo que foram silenciosamente ignoradas
A saída é sempre agrupada por gravidade:
Crítico — deve corrigir antes do merge Importante — deve corrigir antes do merge Menor — baseado em opinião, decisão do revisor
Cada descoberta inclui o caminho do arquivo e o número da linha.
Se não houver nada errado, ele diz isso claramente.
Ele não inventa problemas para parecer completo.
Ferramentas: Apenas Read, Grep, Glob.
Este agente é a razão pela qual a fábrica é confiável.
Um trabalho corrigido por si mesmo não vale nada.
Um validador que vê apenas o que está no disco — não como foi escrito — é honesto.
COMO A CADEIA FUNCIONA
O fluxo completo — um prompt inicia tudo:
Você abre o Claude Code e digita:
"Criar lembretes de fatura para faturas não pagas há mais de 7 dias."
Aqui está o que acontece sem você digitar mais nada:
Passo 1 → Pesquisador mapeia seu código de fatura, pagamento e email. Retorna arquivos relevantes, padrões existentes, riscos.
Passo 2 → Escritor de Histórias produz a história de usuário e os critérios de aceitação.
⏸ PAUSA: Você lê e aprova a história.
Passo 3 → Escritor de Especificações transforma a história aprovada em um resumo técnico.
⏸ PAUSA: Você lê e aprova o resumo.(Pegue o erro de "armazenar IDs na memória" bem aqui.)
Passo 4 → Construtor de Backend implementa o serviço, a rota da API, o job BullMQ e os testes unitários. Retorna: arquivos alterados, padrões reutilizados, todos os testes verdes.
Passo 5 → Construtor de Frontend lê o resumo da API do Construtor de Backend, constrói o bloco da interface de administração e o botão de lembrete, escreve testes de componente. Todos os testes verdes.
Passo 6 → Verificador de Testes escreve testes de aceitação para todos os seis critérios de aceitação. Relata: 7 passando, 1 falhando — o disparo manual não verifica a propriedade do inquilino.
Passo 7 → Validador encontra isso. Relata como Crítico com o caminho do arquivo e o número da linha.
→ Loop de volta para o Construtor de Backend. Correção aplicada. Todos os 8 testes de aceitação passam. Validador executa novamente. Limpo.
⏸ PAUSA: Você revisa e abre o PR.
Três pontos de verificação humanos.
Todo o resto é executado por conta própria.
A BASE: ANTES DOS AGENTES TRABALHAREM, VOCÊ PRECISA DISSO
CLAUDE.md — a memória que sobrevive a cada sessão:
Toda vez que você abre o Claude Code, ele começa com memória zero.
O CLAUDE.md resolve isso.
É um arquivo Markdown na raiz do seu repositório que é carregado automaticamente a cada sessão.
É onde os fatos permanentes do projeto vivem:
→ Sua stack (Next.js App Router, Node.js, Prisma, BullMQ, Resend) → Seus comandos (npm run dev, npm test, npx prisma migrate dev) → Regras de arquitetura ("A lógica de negócio vive nos serviços. As rotas da API permanecem enxutas.") → O que não fazer ("Não adicione cron — use BullMQ. Não registre payloads de pagamento brutos.") → Ponteiros para documentação mais profunda (docs/faturamento.md, docs/arquitetura.md)
Mantenha entre 100 e 300 linhas.
Toda vez que a IA comete um erro que te surpreende, pergunte: uma regra no CLAUDE.md teria evitado isso?
Adicione a regra.
Em algumas semanas, seu CLAUDE.md se torna um registro de cada suposição que a IA errou — e suas sessões ficam visivelmente melhores.
Desvio de contexto — o assassino silencioso:
A maioria das sessões do Claude Code não falha dramaticamente.
Elas se desviam.
Uma suposição errada entra no contexto.
O modelo continua construindo em cima dela.
Você pede ao Claude para construir gerenciamento de assinaturas.
Ele projeta: Usuário → Assinatura.
Você se lembra: as assinaturas pertencem à empresa, não ao usuário.
Se você apenas disser "não, as assinaturas pertencem às empresas" — o Claude corrige.
Agora você tem tanto user.subscriptionId quanto company.subscriptionId vagando por aí.
Regra:
→ Pequeno erro de digitação? Corrija na hora. → Suposição arquitetural errada? Jogue a conversa fora e comece de novo com a suposição correta embutida no primeiro prompt.
Uma sessão limpa com o modelo mental certo vence uma sessão corrigida todas as vezes.
OS RESULTADOS: O QUE REALMENTE MUDA
Antes da fábrica:
→ Loop de codificação por vibração: prompt → gerar → erro → corrigir → repetir → O contexto da sessão se enche de ruído → Suposições erradas se acumulam em funcionalidades quebradas → Um engenheiro só pode fazer uma coisa de cada vez → Toda funcionalidade espera a pessoa certa estar disponível
Depois da fábrica:
→ Cadeia estruturada: pesquisar → história → resumo → construir → verificar → validar → Cada agente recebe uma janela de contexto limpa com apenas o que precisa → Suposições erradas são pegas na aprovação do resumo — não depois de 10 arquivos → Um engenheiro entrega uma fatia vertical completa: backend, frontend, testes, validação → O melhor conhecimento da equipe vive nos agentes — não preso em pessoas
A verdadeira mudança:
O especialista em pagamentos constrói um agente de integração de pagamentos.
Agora, todo engenheiro da equipe pode entregar uma funcionalidade que mexe com faturamento.
Sem esperar.
Sem uma transferência.
Os padrões de componente do líder de frontend vivem no agente construtor de frontend.
As verificações de CI do engenheiro de DevOps vivem em um hook.
Os casos extremos do líder de QA vivem nas regras do verificador de testes.
Conhecimento de especialista, compartilhado como agentes.
Não preso na disponibilidade.
COMO CONSTRUIR O SEU NESTE FIM DE SEMANA
Checklist de configuração em 8 passos:
1. Instale o Claude Code → code.claude.com
2. Crie a estrutura de pastas: → .claude/agents/ → .claude/skills/feature-factory/ → .claude/skills/build-with-tests/ → .claude/hooks/
3. Escreva seu CLAUDE.md (100–300 linhas: stack, comandos, regras de arquitetura, lista de não-fazer)
4. Crie os 7 agentes usando o comando /agents no Claude Code. Descreva a função de cada agente. O Claude escreve o arquivo. Você revisa e faz o commit.
5. Crie a habilidade orquestradora da fábrica de funcionalidades (feature-factory). Peça ao Claude para escrevê-la — ele lê seus 7 arquivos de agente e conecta a cadeia.
6. Crie a habilidade de construir-com-testes (build-with-tests). Descreve como sua equipe constrói: corresponder aos padrões existentes, escrever testes junto com o código, executar typecheck no final.
7. Adicione um hook de pré-commit. Bloqueia commits que incluem arquivos .env, .key, .pem ou secrets.json. Leva 5 minutos. Previne desastres.
8. Execute uma funcionalidade real através da cadeia completa. Escolha algo pequeno. Observe onde ela tropeça. Adicione regras. A fábrica se ajusta sozinha.
Tempo total: 2–3 horas.
Depois, execute algumas funcionalidades.
Após 3–4, a fábrica conhece seu código.
Você vai gastar menos tempo supervisionando.
Mais tempo decidindo o que construir em seguida.
OS 7 AGENTES — REFERÊNCIA RÁPIDA
→ Pesquisador — mapeia o código antes de qualquer coisa ser construída (Apenas leitura) → Escritor de Histórias — transforma ideia em história de usuário com critérios de aceitação (Apenas leitura) → Escritor de Especificações — transforma história em resumo técnico (Apenas leitura) → Construtor de Backend — constrói API, serviços, jobs, testes unitários (apenas pastas do backend) → Construtor de Frontend — constrói componentes, páginas, hooks, testes de interface (apenas pastas do frontend) → Verificador de Testes — escreve testes de aceitação contra a história de usuário (apenas arquivos de teste) → Validador — compara implementação contra história e resumo, relata lacunas (Apenas leitura)
3 pontos de verificação humanos:→ Aprove a história → Aprove o resumo → Aprove o PR
Todo o resto é executado por conta própria.
A maioria dos desenvolvedores usando o Claude Code ainda está codificando por vibração.
Dando prompts → gerando → corrigindo → torcendo.
Isso não está errado.
É apenas um teto.
A fábrica não te remove do processo.
Ela te remove das partes que não precisam de você.
Você permanece no loop onde seu julgamento importa:
Este é o problema certo? Este é o design certo? É seguro enviar para produção?
Os agentes cuidam de tudo que está no meio.
Essa é a diferença entre usar IA como um teclado mais rápido —
e usar IA como uma equipe coordenada.
Se isso foi útil:
→ Compartilhe novamente para espalhar para sua rede → Siga @sairahul1 para mais análises como esta → Salve nos favoritos — você vai querer consultar os 7 agentes
Escrevo sobre IA, construção de produtos e sistemas que funcionam enquanto você dorme.
