Prática: Guia passo a passo para usar 7 Agentes e elevar o Vibe Coding a um fluxo de desenvolvimento de nível especialista

O autor @sairahul1 desmembrou a revolução do fluxo de trabalho de "Vibe Coding" para "Fábrica de Software": dividir uma única conversa de IA em 7 agentes especializados: Pesquisador, Escritor de Histórias, Redator de Especificações, Construtor de Backend, Construtor de Frontend, Verificador de Testes, Validadores de Implementação, cada um com uma única responsabilidade, contexto limpo e fronteiras estritas.
(Prévia: MCP conectando tudo com Web3, pode ser a próxima onda de narrativa AI de 100x?)
(Complemento: O maior mestre de investimentos ajuda você a trabalhar! Reunindo Buffett, Munger, Cathie Wood… 19 agentes de IA para analisar o mercado)

Índice deste artigo

Alternar

• A questão que ninguém discute
• Ponto de virada: de Vibe Coding para Fábrica de Software
• Os sete agentes
  • Agente 1: Pesquisador de Código (Codebase Researcher)
  • Agente 2: Escritor de Histórias (Story Writer)
  • Agente 3: Redator de Especificações (Spec Writer)
  • Agente 4: Construtor de Backend (Backend Builder)
  • Agente 5: Construtor de Frontend (Frontend Builder)
  • Agente 6: Verificador de Testes (Test Verifier)
  • Agente 7: Validador de Implementação (Implementation Validator)
• Como funciona toda a cadeia
• Fundamentos: antes de os agentes funcionarem, você precisa disso
  • CLAUDE.md — memória de cada diálogo
  • Deslocamento de contexto — o assassino silencioso
• Resultado: o que realmente muda
  • Antes da fábrica:
  • Depois da fábrica:
  • A verdadeira transformação:
• Faça sua própria versão neste fim de semana
  • Lista de 8 passos:
• Os sete agentes — rápida referência

Eu achava que estava usando IA para programar. Na verdade, só estou digitando mais rápido.

Este artigo explica a diferença — e a mudança radical com o sistema de "7 agentes".

Salve este artigo. Vai economizar meses de esforço.

A questão que ninguém discute

Um ciclo que parece produtivo, mas na verdade não é:

→ Pede ao Claude para fazer uma funcionalidade → Ele gera código → Algo dá errado → Cola a mensagem de erro de volta → Ele corrige → Outro problema aparece → Pergunta de novo

Dia 1: Parece magia.

Dia 30: Você gasta mais tempo supervisionando a IA do que escrevendo código por conta própria.

O mesmo ciclo aparece em três lugares diferentes. Claude esquece as regras que você definiu duas semanas atrás. Funcionalidades novas quebram as antigas. Testes são escassos ou superficiais.

Um dia você acorda e percebe: não é a IA que falha, é seu fluxo de trabalho que falha.

A essência do problema é estrutural.

Quando você pede no Claude Code "faça essa funcionalidade", na verdade está pedindo a uma IA que desempenhe simultaneamente:

→ Analista de produto → Arquiteto → Engenheiro de backend → Engenheiro de frontend → Testador → Revisor de código

Tudo de uma vez, na mesma conversa confusa.

Suposições erradas no plano se transformam em modelos de banco de dados ruins. Modelos ruins geram APIs erradas. APIs erradas levam a UI incorreta.

Quando você percebe, o erro já se espalhou por toda parte.

Isso é o que chamamos de vibe coding (programar por feeling).

Tem um teto bem duro.

Ponto de virada: de Vibe Coding para Fábrica de Software

A mudança que realmente faz a diferença:

Equipes de engenharia de verdade não trabalham em uma única conversa grande.

Cada pessoa tem uma função diferente:

→ Clarificar o problema do usuário → Pensar na arquitetura → Escrever API → Criar UI → Considerar limites e casos extremos → Revisar

Quando tudo isso é condensado em uma única conversa de IA, os erros se acumulam silenciosamente.

A solução é dividir o trabalho entre agentes especializados.

Cada agente recebe:

→ Uma tarefa focada → Um contexto limpo → Apenas as ferramentas que realmente precisa → Regras estritas sobre o que não pode fazer

Resultado:** Uma fábrica de software.**

Um desenvolvedor + sete agentes focados = uma equipe coordenada.

A seguir, os sete agentes que fazem isso funcionar.

Os sete agentes

Agente 1: Pesquisador de Código (Codebase Researcher)

Qual é o maior erro ao usar IA para desenvolvimento?

Colocar "querer código" como primeiro passo.

A IA recebe o prompt, faz uma suposição para preencher lacunas e começa a gerar. Um design ruim entra nesse momento sorrateiramente.

O pesquisador corrige isso.

Sua única tarefa:** Examinar o repositório de código e explicar o estado atual — antes que uma linha seja escrita.**

O que faz:

• Marcar arquivos relevantes e seus papéis
• Registrar padrões existentes
• Encontrar funcionalidades similares já feitas
• Sinalizar riscos (fuso horário, multi-inquilino, lógica de retries)
• Listar testes que precisarão ser atualizados

O que não faz:

• Editar arquivos (apenas leitura)
• Executar comandos que mudem o estado
• Fazer suposições — deve perguntar

Ferramentas: Read, Grep, Glob, só isso.

Regra: Antes de começar, explorar sempre.

O pesquisador sempre roda primeiro.

Agente 2: Escritor de Histórias (Story Writer)

A maioria das falhas não acontece por código errado.

Mas porque o problema nunca foi bem definido.

O escritor de histórias transforma uma ideia bruta em uma história de usuário real — antes de qualquer decisão técnica.

Entrada:

• Sua descrição inicial da funcionalidade
• Resultados da investigação do pesquisador

Saída:

• Uma história de usuário: "Como [papel], quero [ação], para que [resultado]."
• Critérios de aceitação: declarações testáveis, caminho feliz, caminhos de falha, regras de negócio.
• Casos limites: limites, retries, multi-inquilino.
• Fora do escopo: o que é claramente "não será feito".
• Questões não resolvidas: coisas que realmente não sabe, sem adivinhações.

O que não faz:

• Inventar regras de negócio
• Escrever código ou design técnico
• Avançar quando há dúvidas reais

Ferramenta: Read, só isso.

Regra: Você deve ler e aprovar a história antes de passar adiante.

Essa é a chave para garantir que tudo abaixo funcione sem erro — ponto de revisão humano 1.

Agente 3: Redator de Especificações (Spec Writer)

Depois que a história é aprovada, o especificador a transforma em uma documentação técnica.

Este documento será o blueprint que os agentes de construção seguirão.

Entrada:

• Histórias de usuário aprovadas
• Resultados da investigação do pesquisador
• Regras do CLAUDE.md do seu projeto

Saída:

• Mudanças no modelo de dados (campos, tipos, migrações)
• Fluxos de background / processamento
• Mudanças na API (endpoints, request/response)
• Mudanças no frontend (componentes, páginas, hooks)
• Testes necessários (sucesso, falha, limites)
• Riscos e questões não resolvidas
• Arquivos que serão modificados

O que não faz:

• Editar qualquer arquivo
• Inventar infraestrutura nova — deve indicar claramente
• Ignorar limites de multi-inquilino ou fusos horários
• Deixar questões sem resposta

Ferramentas: Read, Grep, Glob, só isso.

Regra: Este documento é ponto de revisão humano 2.

Você deve ler e aprovar antes que qualquer arquivo seja alterado.

Se você ver algo como "guardar o ID na memória" — é sinal vermelho.

Pegue isso agora. Não espere que 10 arquivos sejam modificados.

Agente 4: Construtor de Backend (Backend Builder)

Agora começa a construção.

O construtor de backend implementa a "metade backend" da funcionalidade — apenas o backend.

Entrada:

• Documentação técnica aprovada
• Resultados da investigação do pesquisador
• Seu CLAUDE.md do projeto

Ele constrói:

• Rotas API
• Serviços e lógica de negócio
• Acesso ao banco de dados e migrações
• Tarefas em background
• Testes unitários do que foi escrito

O que não faz:

• Mexer com componentes React, páginas ou hooks do lado cliente (é trabalho do agente 5)
• Inventar novas dependências sem instruções
• Modificar arquivos fora do escopo
• Parar sem rodar typecheck, lint ou testes

Ao terminar, ele retorna um resumo: arquivos novos ou editados, helpers ou padrões reutilizados, observações de melhorias com base no CLAUDE.md.

Ferramentas: Read, Edit, Write, Bash — só na pasta backend.

O segredo está na separação.

O construtor de backend nunca deve acidentalmente quebrar o frontend.

Agente 5: Construtor de Frontend (Frontend Builder)

O construtor de frontend implementa a UI — só a UI.

Ele lê o resumo do backend.

Isso é crucial.

Ele usa a API conforme o contrato do backend. Não inventa novos endpoints.

Se a API estiver incorreta para a UI,ele reporta o problema — e não tenta corrigir sozinho.

Entrada:

• Documentação técnica aprovada
• Resultados da investigação do pesquisador
• Resumo do backend (contrato da API)

Ele constrói:

• Componentes React e páginas
• Hooks e estado do lado cliente
• Estados de loading e erro
• Testes de componentes e unidades

O que não faz:

• Mexer em services, rotas API, workers ou migrações (é do agente 4)
• Inventar endpoints ou formatos de resposta
• Adicionar dependências sem instruções
• Parar sem rodar typecheck, lint ou testes

Ferramentas: Read, Edit, Write, Bash — só na pasta frontend.

Dois construtores. Dois contextos limpos. Zero chance de um quebrar o outro.

Agente 6: Verificador de Testes (Test Verifier)

Ambos os construtores escrevem seus testes unitários.

Mas isso não é suficiente.

O verificador de testes faz uma coisa:** provar que a funcionalidade realmente faz o que a história de usuário pede.**

Escreve testes de aceitação, não apenas unitários.

Testes de aceitação testam externamente — como um usuário real experimentaria.

Entrada:

• Histórias de usuário aprovadas (com critérios de aceitação)
• Documentação técnica aprovada
• Resumos dos dois construtores

Saída:

• Arquivo de testes de aceitação cobrindo cada critério
• Relatório: quais passaram, quais falharam, quais não cobertos

O que não faz:

• Modificar código de backend ou frontend
• Inventar soluções alternativas para critérios não testáveis
• Marcar critérios não cobertos como cobertos

Se um teste falhar: a funcionalidade não satisfaz a história.

Ele reporta "qual critério falhou".Não tenta consertar código.

Conserto fica com o construtor responsável.

Ferramentas: Read, Edit, Write (apenas testes), Bash.

Regra: Antes de passar, os testes de aceitação devem passar. Você não tem a funcionalidade ainda.**

Agente 7: Validador de Implementação (Implementation Validator)

Este agente encontra o que foi esquecido.

Compara a implementação atual com a história e a documentação,aponta as diferenças.

Nunca modifica nada. Só diz a verdade.

Verificações que realiza:

• Ainda não implementou critérios de aceitação
• Caminhos de falha não cobertos por testes
• Questões de segurança: permissões, isolamento, chaves no log, erros vazados
• Arquivos alterados fora do escopo
• Padrões inconsistentes com CLAUDE.md ou código existente
• Código duplicado ao invés de reutilizar helpers
• Casos de fusos horários ou multi-inquilino ignorados na documentação

Saída sempre por gravidade:

• Crítico — obrigatório antes do merge
• Importante — deve ser corrigido antes do merge
• Menor — opinião do revisor

Cada problema vem com o caminho do arquivo e linha.

Se nada for encontrado, diz "sem problemas".Não inventa problemas só para parecer sério.

Ferramentas: Read, Grep, Glob, só isso.

Este agente é o motivo pelo qual a fábrica é confiável.

Relatórios de autoavaliação não valem nada. Um verificador que só olha o que está no disco, sem entender como foi escrito, é o mais honesto.

Como funciona toda a cadeia

Fluxo completo — um prompt inicia tudo:

Você abre o Claude Code, digita:

"Faça a funcionalidade 'Lembrete de fatura não paga há mais de 7 dias'."

Depois, não precisa digitar mais nada, acontece assim:

Passo 1: → Pesquisador varre código de faturas, pagamentos, emails. Retorna arquivos relevantes, padrões existentes, riscos.

Passo 2: → Escritor de histórias gera história de usuário e critérios de aceitação.

⏸ Pausa: você lê e aprova a história.

Passo 3: → Redator de especificações transforma em documentação técnica.

⏸ Pausa: você lê e aprova a documentação. (Aqui, detecte o erro de "guardar o ID na memória".)

Passo 4: → Construtor de backend implementa service, rotas API, tarefas BullMQ, testes unitários. Retorna: mudanças nos arquivos, padrões reutilizados, testes verdes.

Passo 5: → Construtor de frontend lê o resumo da API, cria UI administrativa e botão de lembrete, escreve testes de componentes. Tudo verde.

Passo 6: → Verificador de testes escreve testes de aceitação para os 6 critérios. Reporta: 7 passam, 1 falha — por exemplo, checagem manual de propriedade do inquilino.

Passo 7: → O validador detecta a falha. Reporta com nível Crítico, anexa arquivo e linha.

→ Volta ao construtor de backend. Corrige. Todos os 8 critérios passam. O verificador roda novamente. Tudo limpo.

⏸ Pausa: você revisa e faz PR.

Três revisões humanas. O resto roda sozinho.

Base: antes de os agentes funcionarem, você precisa disso

CLAUDE.md — memória de cada diálogo

Cada vez que você abre o Claude Code, ele começa do "zero".

CLAUDE.md corrige isso.

É um arquivo Markdown na raiz do repositório, carregado automaticamente a cada início de diálogo.

É o lar da "verdade permanente do projeto":

• 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 ("Lógica de negócio em services. API deve ser fina.")
• O que NÃO fazer ("Não usar cron — usar BullMQ. Não logar payloads de pagamento.")
• Indicadores de documentação (docs/billing.md, docs/architecture.md)

Mantenha entre 100–300 linhas.

Cada erro surpreendente do IA leva você a perguntar: "Se uma regra estivesse no CLAUDE.md, evitaria isso agora?"

Adicione a regra.

Semanas depois, seu CLAUDE.md vira um registro de todas as suposições que o IA já errou — seu diálogo melhora visivelmente.

Deslocamento de contexto — o assassino silencioso

A maioria das conversas no Claude Code não falha dramaticamente.

Elas se deslocam.

Uma suposição errada entra no contexto. O modelo continua acumulando.

Você pede "gestão de assinaturas". Ele projeta: User → Subscription.

Depois lembra: assinatura pertence à "empresa", não ao "usuário".

Se você só diz "não, assinatura é da empresa" — Claude faz um patch.

Agora você tem user.subscriptionId e company.subscriptionId coexistindo.

Regra:

• Pequenos erros? Corrija inline.
• Suposições arquiteturais erradas?** Descarte toda a conversa**, reinicie do zero, coloque a suposição correta no primeiro prompt.

Uma conversa limpa, com o modelo mental correto, sempre vence uma conversa com patches.

Resultado: o que realmente muda

Antes da fábrica:

• Ciclo vibe coding: prompt → geração → erro → patch → repetir
• Contexto cheio de ruído
• Suposições erradas acumulando em funcionalidades ruins
• Um engenheiro faz uma coisa de cada vez
• Cada funcionalidade esperando a pessoa certa estar disponível

Depois da fábrica:

• Cadeia estruturada: pesquisa → história → documentação → construção → validação → confirmação
• Cada agente com contexto limpo, só com o que precisa
• Suposições erradas detectadas na "aprovação da documentação" — não após 10 arquivos
• Um engenheiro pode fazer uma fatia completa: backend, frontend, testes, validação
• O conhecimento da equipe vive nos agentes — não preso a "uma pessoa"

Mudança real:

Um especialista em pagamentos cria um agente de integração de pagamentos. Desde então, toda equipe pode lançar funcionalidades financeiras.** Sem esperar, sem transferência.**

O padrão de componentes do frontend lead fica no agente frontend-builder. O CI do DevOps fica no hook. As regras de limites do QA ficam no test-verifier.

Conhecimento especializado, compartilhado via agentes. Não preso a "quem está disponível".

Faça sua própria versão neste fim de semana

Lista de 8 passos:

2. Instale o Claude Code → code.claude.com
3. Crie a estrutura de pastas:
   • .claude/agents/
   • .claude/skills/feature-factory/
   • .claude/skills/build-with-tests/
   • .claude/hooks/
4. Escreva seu CLAUDE.md (100–300 linhas: stack, comandos, regras, lista de não fazer)
5. Use o comando /agents no Claude Code para criar os 7 agentes. Descreva o papel de cada um. Claude cria os arquivos. Você revisa e commita.
6. Crie a skill de orchestrator "feature-factory". Peça ao Claude para escrever — ela vai ler seus 7 arquivos de agentes e montar toda a cadeia.
7. Crie a skill "build-with-tests". Descreva como sua equipe constrói: alinhando padrões existentes, escrevendo código e testes simultaneamente, rodando typecheck no final.
8. Adicione um hook de pre-commit. Bloqueie commits de .env, .key, .pem ou secrets.json. 5 minutos, evita desastres.
9. Execute uma funcionalidade real na cadeia completa. Escolha uma pequena. Observe onde trava. Adicione regras.** A fábrica ajusta-se sozinha.**

Tempo total: 2–3 horas.

Faça alguns testes. Depois de 3–4, a fábrica conhece seu repositório.

Você gastará menos tempo supervisionando, mais decidindo "o que fazer a seguir".

Os sete agentes — rápida referência

• Pesquisador (Researcher) — Antes de tudo, varre o código (só leitura)
• Escritor de Histórias (Story Writer) — Transforma ideias em histórias de usuário e critérios (só leitura)
• Redator de Especificações (Spec Writer) — Transforma histórias em documentação técnica (só leitura)
• Construtor de Backend (Backend Builder) — Constrói API, serviços, jobs, testes (apenas na pasta backend)
• Construtor de Frontend (Frontend Builder) — Constrói componentes, páginas, hooks, testes de UI (apenas na pasta frontend)
• Verificador de Testes (Test Verifier) — Escreve testes de aceitação para histórias (apenas testes)
• Validador (Validator) — Compara implementação com história e documentação, aponta diferenças (só leitura)

3 revisões humanas:

→ Aprovar história → Aprovar documentação → Aprovar PR

O resto roda sozinho.

A maioria dos desenvolvedores usando Claude Code ainda está no vibe coding. Prompt → geração → patch → oração.

Não está errado.Mas há um teto.

A fábrica não te tira do fluxo.Ela te tira do "não precisa de sua decisão".

Você fica nas partes onde "sua decisão é realmente importante":

Essa é a questão certa? Essa é a arquitetura certa? Pode ir ao vivo com segurança?

Tudo que estiver no meio, os agentes cuidam.

Essa é a diferença entre usar IA como um teclado mais rápido e usá-la como uma equipe coordenada.

Autor original: @sairahul1