Antes de construir qualquer coisa, o ambiente precisa de quatro peças ligadas. O diagrama abaixo mostra como o assistente de código se conecta ao seu projeto e ao n8n — e o que você verifica antes de começar.
Diagrama ilustrativo — recriação conceitual do ambiente, não uma captura de tela real.
🗣️ O que é vibe coding
Vibe coding é construir software e automações conversando com uma IA em linguagem natural: você descreve o resultado que quer e a IA cuida da implementação técnica. Em vez de aprender a mecânica de cada nó ou cada linha de código, você foca no problema — a seleção de ferramentas, a configuração e a depuração ficam com a IA.
💡 A ideia central
A conversa em linguagem natural dirige o build e a iteração. Quando algo precisa mudar, você não reabre um editor de configuração: você apenas pede a mudança. A IA faz o "trabalho pesado" — escolher os nós, configurar parâmetros e depurar.
- •Velocidade: do conceito ao protótipo funcional em minutos, não horas.
- •Baixo overhead técnico: sem decorar a mecânica de cada nó.
- •Foco no problema: o esforço vai para o resultado, não para a ferramenta.
✓ Descreva o RESULTADO
- ✓"Verifique o Gmail a cada 10 minutos; se chegar um e-mail novo, envie um DM no Slack."
- ✓Deixar a IA escolher os nós e a estrutura.
- ✓Responder às perguntas de esclarecimento dela.
✗ Não dite os PASSOS técnicos
- ✗"Adicione um nó de gatilho, conecte a um IF, depois a um code node…"
- ✗Microgerenciar a configuração de cada parâmetro.
- ✗Esperar que a IA adivinhe sem você responder às perguntas dela.
🎯 Dica prática
Comece a frase pelo objetivo ("eu quero que…"), não pela ferramenta. Diga o que deve acontecer no fim; deixe a IA propor o como. Você ainda aprova tudo antes de qualquer coisa rodar.
Linguagem natural dirige o build.
Mudar é só pedir.
A IA escolhe e configura os nós.
Fundamentos → build → enhancement.
🧠 O assistente de código no editor
O assistente de código roda dentro do editor (um editor de terceiros, como o VS Code, que você instala para hospedá-lo). Ele consegue ler os arquivos do projeto, escrever e editar código, rodar comandos no terminal e conectar ferramentas externas via MCP. É o motor que transforma a sua conversa em ações reais no projeto.
📊 Assinatura vs API — a economia de tokens
A IA relê toda a conversa a cada nova mensagem — então quanto mais longa a sessão, mais cara fica cada mensagem. Entender o modelo de cobrança evita surpresas.
- Assinatura: taxa fixa, baseada em chat/texto, com limite de mensagens — recomendada para este tipo de trabalho.
- API: baseada em token, pague-por-uso — voltada a quem está construindo aplicações.
✓ Boas práticas
- ✓Mantenha sessões focadas para controlar o custo.
- ✓"Uma pasta por projeto" — abra só a pasta dedicada.
- ✓Use o caminho de assinatura para este trabalho.
✗ Evite
- ✗Abrir uma pasta-raiz com vários projetos dentro.
- ✗Sessões gigantes que misturam tarefas não relacionadas.
- ✗Ignorar que cada mensagem relê todo o histórico.
Enxerga o projeto inteiro.
Cria e altera código.
Executa no terminal.
Liga ferramentas externas.
📄 Projeto dedicado + CLAUDE.md
Configurar o projeto significa criar uma pasta dedicada e um arquivo CLAUDE.md, que funciona como um system prompt persistente: ele define o papel, o contexto e as preferências que a IA segue ao longo de todo o projeto. Em vez de repetir contexto a cada conversa, você o escreve uma vez nesse arquivo.
🧭 O que vai no CLAUDE.md
- •Papel: quem a IA é neste projeto (ex.: assistente de workflows n8n).
- •Contexto: o que você está construindo (automações) e por quê.
- •Preferências: estilo de comunicação, restrições técnicas, dos and don'ts.
# Papel Você é um assistente de workflows n8n. # Contexto Estou construindo automações para uma agência de IA. Ajude a construir, depurar e otimizar. # Preferências - Explicações concisas e diretas. - Sempre proponha um plano antes de executar.
Você não precisa escrever esse arquivo à mão: peça à IA para gerá-lo ("crie um CLAUDE.md para este projeto; estou construindo workflows n8n para uma agência — me ajude a construir, depurar e otimizar"). Depois, itere pedindo ajustes ("adicione uma seção sobre manter as explicações concisas").
🎯 Dica prática
Comece com uma pasta completamente vazia e nomeada pelo propósito. O CLAUDE.md é editável a qualquer momento — basta pedir à IA para atualizá-lo conforme o projeto cresce.
Vale para todo o projeto.
Texto simples, fácil de editar.
A IA escreve a primeira versão.
Peça mudanças quando quiser.
🔌 Conectando o n8n via MCP server
O n8n é um construtor visual de workflows, baseado em nós, que conecta apps, dados, IA e APIs externas. Um MCP server liga o n8n ao assistente de código, para que a IA leia, crie, modifique, teste, depure e até se auto-corrija nos seus próprios workflows. Construir tudo na mão é demorado, propenso a erro e difícil de depurar — o MCP remove esse atrito.
Passo a passo da instalação
Clonar o repositório do MCP
Peça à IA para clonar o repositório e configurá-lo. Se ela oferecer instalação via NPX, recuse — clone manualmente.
Config no nível do projeto
Mantenha a configuração do MCP dentro da pasta do projeto. Config global dispara um aviso de segurança a cada reinício.
Criar a API key + copiar a URL da instância
Nas configurações do n8n, crie uma API key (rótulo + expiração) e copie na hora. Copie também a URL da instância (cloud ou localhost/custom).
Colar credenciais no .env e rodar o health check
Cole API key e URL no arquivo .env do projeto. Peça à IA para iniciar o MCP e rodar um health check.
⚠️ Atenção: segurança das credenciais
- ✗Nunca cole credenciais no chat — só no
.env. - ✗Não deixe a IA rodar a instalação via NPX — causa falhas silenciosas difíceis de diagnosticar.
- ✗A API key aparece só uma vez na criação — copie e guarde com segurança.
🎯 Dica prática
O health check é o seu primeiro sinal de vida: ele confirma o status da conexão, a URL da instância, a versão do MCP e o tempo de resposta da API. Rode-o sempre que algo parecer estranho.
Construtor visual de workflows.
Ponte IA ↔ n8n.
Único lar das credenciais.
Confirma a conexão.
📚 Skills do n8n
As skills são documentação que ensina a IA a usar o n8n — seus tipos de nós, parâmetros, melhores práticas e padrões comuns. Com elas, a IA entende como cada nó funciona e como estruturar um workflow, para que você não precise saber isso. A instalação é idêntica à do MCP server; muda só a URL do repositório.
Instalação e verificação
Clonar o repositório de skills
Peça à IA para clonar e configurar (mesmo processo do MCP, outro link). Aprove os prompts de permissão durante a instalação.
Atualizar o CLAUDE.md e reiniciar
Peça para atualizar o CLAUDE.md anotando que a IA agora tem acesso à documentação do n8n. Reinicie o assistente para registrar os novos componentes.
Verificar perguntando sobre um nó
Pergunte "me fale sobre o nó de gatilho do Gmail" e confirme que a resposta traz detalhes corretos (intervalo de polling, parâmetros, filtros).
🎯 Dica prática
Se o MCP server não aparecer depois da instalação, reinicie o assistente antes de qualquer troubleshooting — na maioria das vezes isso resolve.
Tipos, parâmetros, padrões.
Igual ao MCP, outro repo.
Registra os componentes.
Pergunte sobre um nó real.
✅ Verificação das 4 conexões
Antes de construir, rode uma sequência de verificação para confirmar que o assistente tem acesso aos arquivos do projeto, à conexão MCP, à capacidade de ler workflows e à documentação dos nós. São quatro testes simples — cada um uma pergunta em linguagem natural.
Os 4 testes
Diretório do projeto
"Me mostre o que tem no meu diretório de projeto."
Confirme que existem CLAUDE.md, .env, arquivos do MCP e a pasta de skills (ainda sem workflows).
Conexão MCP
"Você confirma que está conectado à minha instância n8n?"
Confirme conexão saudável: instância conectada, API configurada, ferramentas disponíveis.
Ler workflows
"Quais workflows eu tenho atualmente?"
Confirme que a IA lista os workflows (ou reporta "nenhum" numa conta nova), com contagem de nós e status.
Documentação de nós
"Me fale sobre o nó de gatilho do Gmail."
Confirme detalhe no nível do nó: intervalo de polling, parâmetros, filtros.
✓ Ambiente pronto
- ✓Os 4 testes passam sem erro.
- ✓A IA enxerga arquivos, instância, workflows e nós.
- ✓Pode começar a construir com segurança.
✗ Erros comuns (e a cura)
- ✗API key inválida/parcial → verifique se não foi cortada.
- ✗MCP não conecta → reinicie o server.
- ✗Autorização do n8n falha → re-verifique as credenciais.
🎯 Dica prática
Se aparecer erro em qualquer teste, peça à IA para diagnosticá-lo — na maioria das vezes ela aponta a causa e sugere a correção. Você não precisa decifrar a mensagem sozinho.
Auto-recuperação (opcional): onde as credenciais (API key + URL da instância) devem ficar?
📌 Resumo do Módulo
Próximo Módulo:
1.2 — O Ciclo Completo: Plan → Build → Troubleshoot → Optimize