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, Validador de Implementação, cada um com uma única responsabilidade, contexto limpo e fronteiras estritas.
(Resumindo: a MCP conectando tudo com Web3, pode ser a próxima onda de narrativa AI de 100x?)
(Complemento: O maior mestre de investimentos ajudando você a trabalhar! Reunindo Buffett, Munger, Cathie Wood… 19 AI Agents analisando o mercado)

Índice do 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 trabalho.

A questão que ninguém discute

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

→ Pede para Claude 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 "faça essa funcionalidade" no Claude Code, na verdade está pedindo para a IA desempenhar 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 errada.

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 e dedicado → Apenas as ferramentas que realmente precisa → Regras estritas sobre o que é "fora do alcance" dele

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, preenche lacunas e começa a gerar. Um design ruim se infiltra nesse momento.

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á implementadas
• Sinalizar riscos (fusos horários, 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 alterem 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], assim [resultado]."
• Critérios de aceitação: declarações testáveis, caminho feliz, caminhos de falha, regras de negócio.
• Casos limites: limites, retries, considerações multi-inquilino.
• Fora do escopo: o que é claramente "não será feito".
• Questões não resolvidas: coisas que ele 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 para o próximo passo.

Essa é a chave para 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 é o blueprint que os agentes de construção seguirão.

Entrada:

• Histórias de usuário aprovadas
• Resultados do pesquisador
• Regras do CLAUDE.md do 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 arquivos
• Inventar infraestrutura nova — deve indicar claramente
• Ignorar considerações de multi-inquilino ou fuso horário
• 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 de alerta.

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 — e só isso.

Entrada:

• Documentação técnica aprovada
• Resultados do pesquisador
• 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, padrões reutilizados, observações de melhorias com base no CLAUDE.md.

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

O segredo é a separação.

O construtor de backend nunca deve acidentalmente estragar o frontend.

Agente 5: Construtor de Frontend (Frontend Builder)

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

Ele lê o resumo do construtor de backend.

Isso é crucial.

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

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

Entrada:

• Documentação técnica aprovada
• Resultados 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 unitários e componentes

O que não faz:

• Mexer em services, rotas API, workers ou migrações (é trabalho 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:** Comprovar que a funcionalidade realmente faz o que a história de usuário diz.**

Ele escreve "testes de aceitação", não testes unitários.

Testes de aceitação verificam a funcionalidade de fora — 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:

• Alterar 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.

Consertos voltam para o construtor responsável.

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

Regra: Antes de passar nos testes de aceitação, você não tem a funcionalidade.

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

Este agente encontra o que foi esquecido.

Ele compara a implementação atual com a história e a documentação,** reportando diferenças.**

Nunca altera nada. Só fala a verdade.

Cada execução verifica:

• Critérios de aceitação ainda não implementados
• Caminhos de falha não cobertos por testes
• Questões de segurança: permissões, isolamento, chaves no log, erros vazando
• Arquivos fora do escopo que foram modificados
• Padrões inconsistentes com CLAUDE.md ou código existente
• Reuso inadequado de helpers
• Considerações de fuso horário ou multi-inquilino ignoradas 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, ele diz que está tudo ok.Não inventa problemas só para parecer cuidadoso.

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 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, e acontece assim:

Passo 1: → Pesquisador varre seu código de faturas, pagamentos e emails. Retorna arquivos relevantes, padrões existentes e 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 a história aprovada 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 e testes unitários. Retorna: mudanças de arquivo, 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. Retorna: 7 aprovados, 1 falha — por exemplo, checagem manual de propriedade do inquilino.

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

→ Volta ao construtor de backend. Corrige. Todos os testes verdes. O validador roda novamente. Tudo limpo.

⏸ Pausa: você revisa e faz PR.

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

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

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

Cada vez que você abre 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.

Ele é o lar da "verdade do projeto permanente":

• 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 leve.")
• 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 faz você se perguntar: "Se tivesse uma regra no CLAUDE.md, isso evitaria desta vez?"

Adicione a regra.

Semanas depois, seu CLAUDE.md vira um registro de "todas as suposições que a 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 construindo sobre ela.

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

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

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

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

Regra:

• Pequenos erros? Corrija inline.
• Se a suposição de arquitetura estiver errada,** descarte toda a conversa**, comece do zero, e coloque a suposição correta na primeira mensagem.

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

Resultado: o que realmente muda

Antes da fábrica:

• Ciclo Vibe coding: prompt → gerar → erro → corrigir → repetir
• Contexto cheio de ruído
• Suposições erradas acumulando funções ruins
• Um engenheiro faz uma coisa de cada vez
• Cada funcionalidade espera 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 entregar uma fatia completa: backend, frontend, testes, validação
• O conhecimento da equipe fica nos agentes — não preso a "uma pessoa"

Mudança verdadeira:

Um especialista em pagamentos cria um agente de integração de pagamentos. Desde então, toda equipe consegue lançar funcionalidades com faturamento — sem esperar, sem transferência.

O padrão de componentes do frontend lead fica no agente frontend-builder. As verificações de CI do DevOps ficam no hook. As regras de limites do QA lead 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 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 faz commit.

6. Crie a skill de orquestração feature-factory. Peça para Claude gerar — 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 com padrões existentes, escrevendo testes enquanto programa, rodando typecheck no final.

8. Adicione um hook 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. Veja onde trava. Adicione regras. A fábrica ajusta automaticamente.

Tempo total: 2–3 horas.

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

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) — Converte histórias em documentação técnica (só leitura)
• Construtor de Backend (Backend Builder) — Implementa API, serviços, tarefas, testes (apenas na pasta backend)
• Construtor de Frontend (Frontend Builder) — Cria 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 arquivos de teste)
• Validador (Validator) — Compara implementação com história e documentação, reporta diferenças (só leitura)

3 revisões humanas:

→ Aprovação da história → Aprovação da documentação → Aprovação do PR

O resto roda sozinho.

A maioria dos desenvolvedores usando Claude Code ainda está no vibe coding. Prompt → gerar → corrigir → rezar.

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

A fábrica não te tira do fluxo.Ela te tira da parte "não precisa de seu julgamento".

Você fica nas etapas onde "seu julgamento é realmente importante":

Essa é a questão certa? Essa é a solução certa? Pode ir ao ar com segurança?

Tudo que estiver no meio, o agente cuida.

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

Autor original: @sairahul1