# n8n 3.0: migrar o workflow ou mover a regra de negócio para código?

> Antes de migrar para o n8n 3.0, rode o Migration Report, resolva o que bloqueia o upgrade e decida onde cada regra mora: orquestração e conectores ficam no workflow; regras que não podem variar, como preço, alçada e agendamento, ficam em código com teste. O 3.0.0 está descrito como early access.

- URL canônica: https://blog.lenaai.com.br/n8n-3-0-migrar-workflow-ou-regra-em-codigo
- Autor: Thalena Lima; publicado por Lena AI.
- Publicado em 4 de novembro de 2026; atualizado em 13 de novembro de 2026.
- Leitura estimada: 6 min.
- Categorias: IA na prática, Tecnologia.

---

> O n8n 3.0 é uma versão major, lançada em 27 de outubro de 2026, com mudanças que quebram workflows existentes. A decisão para quem opera automação com IA não é migrar tudo nem abandonar o n8n: é separar a orquestração, que pode ficar no workflow, da regra de negócio, que precisa de código testado.

## O que o n8n 3.0 quebra e quem precisa agir primeiro

A página de notas de versão do n8n registra o 3.0 em 27 de outubro de 2026 como uma versão major com breaking changes. A página de breaking changes traz um aviso que pesa na decisão: o 3.0.0 está disponível como early access release (consulta feita em 4 de novembro de 2026).

Quem opera automação para clientes deve ler a lista antes de qualquer upgrade. A tabela traz cinco itens da documentação oficial; a lista completa é maior.

| Mudança no 3.0 | Quem é afetado | O que a documentação manda fazer |
|---|---|---|
| Self-hosted exige Docker; instalações por `npm` ou `npx n8n` deixam de ser suportadas | Quem hospeda o n8n em servidor próprio sem container | Migrar para Docker antes do upgrade |
| Nós removidos, como Function, Function Item, Cron e Interval | Workflows antigos que usam esses nós | Trocar pelo Code node (Function e Function Item) e pelo Schedule Trigger (Cron e Interval) |
| AI Agent na versão 1 removido, com os modos SQL, Conversational, OpenAI Functions, Plan and Execute e ReAct | Agentes montados com a versão antiga do nó | Atualizar para a versão mais recente, que usa o Tools Agent |
| Timeout padrão das tarefas do Code node cai de 300 para 60 segundos (`N8N_RUNNERS_TASK_TIMEOUT`) | Code nodes que rodam por mais de 1 minuto | Definir a variável de forma explícita |
| Credencial Slack API passa a exigir o signing secret | Workflows com Slack Trigger | Cadastrar o secret antes do upgrade; sem ele o workflow não ativa |

A ferramenta de migração mostra o tamanho do problema na sua instância. Em Settings > Migration Report, ela lista workflows e configurações afetados, em cinco níveis de impacto, de "Upgrade blocked" a "Capability removed". A migração automática cobre só mudanças de nós, e a documentação manda testar o resultado antes de publicar e revisar a página de breaking changes para o que a ferramenta não detecta. Um detalhe de governança: marcar um workflow como "Won't fix" conta como resolvido no relatório.

![Diagrama conceitual com três camadas de uma automação com IA: modelo para linguagem natural, workflow para orquestração e código para a regra de negócio.](https://raw.githubusercontent.com/vinilevy/lena-blog-assets/main/posts/n8n-3-0-migrar-workflow-ou-regra-em-codigo/imagem1.png)

*Diagrama conceitual da Lena AI: exemplos de divisão por camada, sem captura de ferramenta.*

## Quando manter o fluxo no n8n e quando tirar a regra do workflow

A Anthropic distingue workflows, sistemas em que modelos e ferramentas seguem caminhos de código predefinidos, de agentes, em que o modelo dirige o próprio processo. A mesma publicação recomenda a solução mais simples possível e observa que sistemas agênticos costumam trocar latência e custo por desempenho. Para o gestor, a pergunta vem antes da escolha de ferramenta: quais decisões da operação não podem variar?

O critério da Lena AI separa três camadas, como no diagrama. O modelo cuida da linguagem natural. O workflow, no n8n 3.0 ou fora dele, cuida de gatilho, ordem e conectores. A regra de negócio, como preço, janela de agendamento e alçada, fica em código com teste: a mesma entrada produz a mesma saída, e cada mudança passa por revisão.

Isso não obriga a sair do n8n. O Code node roda JavaScript ou Python como uma etapa do workflow, mas não acessa o sistema de arquivos nem faz requisições HTTP, e no 3.0 o timeout padrão das tarefas cai para 60 segundos. Regra que cresce além desse limite pede um serviço próprio, chamado pelo workflow.

Para escrever e testar esse código, uma ferramenta como o Claude Code ajuda. A documentação oficial a descreve como uma ferramenta de programação agêntica que lê a base de código, edita arquivos e roda comandos, e cita entre os usos escrever testes e corrigir falhas. O código gerado continua exigindo revisão de quem responde pela operação.

| Situação na operação | Onde a regra fica | Critério (Lena AI) |
|---|---|---|
| Fluxo estável, muitos conectores, quem mantém não programa | Workflow no n8n, depois do Migration Report | Mudar um passo não exige deploy |
| Regra que não pode variar: preço, alçada, trava de segurança | Código com teste, no Code node ou em serviço chamado pelo workflow | A mesma entrada dá a mesma saída e a mudança passa por revisão |
| Texto livre que precisa virar dado: classificar, extrair campos | Modelo, dentro de uma etapa do workflow | O código valida a saída antes de seguir |
| Passos imprevisíveis, ferramentas claras e erro barato de reverter | Agente, com limite de tentativas e aprovação humana | Só aqui o modelo decide o próximo passo |

Os [princípios de engenharia para agentes e sistemas com IA em produção](https://blog.lenaai.com.br/agentes-ia-producao-principios-engenharia-lena-ai) detalham permissões, idempotência e testes, e o custo de uma migração de versão entra na conta de [quanto custa operar uma automação com IA](https://blog.lenaai.com.br/quanto-custa-operar-automacao-com-ia-tco-suporte-saida), junto com suporte e plano de saída.

## Como decidir em seis passos antes de migrar

1. **Rode o Migration Report** em Settings > Migration Report e exporte o CSV: a documentação descreve a exportação da visão geral, com uma linha por problema.
2. **Resolva primeiro o que bloqueia.** Os itens "Upgrade blocked" e "Executions will fail" vêm antes de "Behavior changes".
3. **Liste as regras que não podem variar** em cada workflow: preço, desconto, alçada, janela de agenda, trava de segurança. Cada regra recebe um dono e um par de entrada e saída esperada.
4. **Defina o lugar de cada regra:** fica no workflow, vira código no Code node ou vira um serviço chamado pelo workflow. Use a tabela acima.
5. **Teste em cópia antes de publicar.** Rode as mesmas entradas no fluxo antigo e no migrado e compare as saídas. A migração automática cobre só os nós.
6. **Registre as exceções.** Cada "Won't fix" precisa de dono, motivo e data de revisão, porque o relatório já o conta como resolvido.

Como a documentação descreve o 3.0.0 como early access, o plano mais seguro é uma janela de teste em cópia da instância antes de qualquer data em produção.

## Recursos e ecossistema Lena AI

* 🎓 **Formação:** [Lena Academy](https://lenaacademy.com.br/?utm_source=blog&utm_medium=artigo&utm_campaign=n8n-3-0-regra-em-codigo)
* 🎓 **Treinamento:** [IA Experts, com Thalena Lima](https://iaexperts.thalena.com.br/?utm_source=blog&utm_medium=artigo&utm_campaign=n8n-3-0-regra-em-codigo)
* 🏢 **Implementação empresarial:** [Diagnóstico e projetos com a Lena AI](https://lp.lenaai.com.br/?utm_source=blog&utm_medium=artigo&utm_campaign=n8n-3-0-regra-em-codigo)

## Respostas diretas

**O que muda no n8n 3.0 e quem precisa agir primeiro?**

O 3.0 exige Docker para self-hosted, remove nós antigos como Function e Cron, remove a versão 1 do AI Agent, reduz o timeout das tarefas do Code node de 300 para 60 segundos e passa a exigir o signing secret na credencial Slack API. O Migration Report lista o que afeta cada instância.

**Como usar a ferramenta de migração do n8n 3.0?**

Abra Settings > Migration Report, revise os workflows e as configurações por nível de impacto, resolva primeiro o que bloqueia o upgrade e teste os workflows migrados antes de publicar. A migração automática cobre só mudanças de nós; o que a ferramenta não detecta está na página de breaking changes.

**Quando mover a regra de negócio do workflow para código?**

Quando a regra não pode variar, como preço, desconto, alçada, janela de agendamento ou trava de segurança. Em código, ela ganha teste e revisão, e a mesma entrada produz a mesma saída. O workflow continua cuidando de gatilhos, conectores e da ordem das etapas.

**O n8n 3.0 já é uma versão estável para produção?**

A documentação do n8n descreve o 3.0.0 como early access release (consulta em 4 de novembro de 2026). Por isso, o plano mais seguro é testar a migração em uma cópia da instância e só então definir a data em produção.


## Perguntas frequentes

**O n8n 3.0 exige Docker?**

Para instalações self-hosted, sim. A documentação diz que o 3.0 não suporta mais instalações por npm ou npx n8n e não publica um pacote n8n executável no npm. Quem usa npm precisa migrar para Docker antes do upgrade.

**A ferramenta de migração do n8n resolve tudo sozinha?**

Não. Ela lista workflows e configurações afetados e só migra automaticamente mudanças de nós. A documentação manda testar os workflows migrados antes de publicar e revisar a página de breaking changes para o que a ferramenta não detecta.

**Dá para trocar o n8n por código escrito com Claude Code?**

Dá para mover parte das regras para código, e o Claude Code, descrito na documentação como ferramenta de programação agêntica que lê a base de código, edita arquivos e roda comandos, ajuda a escrever e testar esse código. A troca total depende de quem vai manter conectores, gatilhos e avisos; decida por camada.

**O que fazer com um workflow marcado como Won't fix?**

Won't fix conta como resolvido no relatório de migração, mas o workflow não muda. Registre dono, motivo e data de revisão, para que a exceção não vire falha em produção depois do upgrade.


## Fontes

- [n8n Docs — Release notes](https://docs.n8n.io/changelog/release-notes): O n8n 3.0 está registrado nas notas de versão com data de 27 de outubro de 2026, como versão major com breaking changes.
- [n8n Docs — v3.0 Breaking changes](https://docs.n8n.io/changelog/v30-breaking-changes): A página de breaking changes diz que o n8n 3.0.0 está disponível como early access release, exige Docker para self-hosted (sem suporte a npm ou npx n8n), remove nós como Function, Function Item, Cron e Interval, remove a versão 1 do AI Agent (a versão atual usa Tools Agent), reduz o timeout padrão do Code node de 300 para 60 segundos e exige o signing secret na credencial Slack API.
- [n8n Docs — v3.0 Migration tool](https://docs.n8n.io/changelog/v30-migration-tool): A ferramenta de migração fica em Settings > Migration Report, classifica problemas em cinco níveis de impacto (de Upgrade blocked a Capability removed), migra automaticamente apenas mudanças de nós, manda testar os workflows migrados antes de publicar, não detecta todas as mudanças e conta Won't fix como resolvido.
- [n8n Docs — Using the Code node](https://docs.n8n.io/build/code-in-n8n/using-the-code-node): O Code node executa JavaScript ou Python como etapa do workflow e não acessa o sistema de arquivos nem faz requisições HTTP.
- [Anthropic — Building effective agents (19 de dezembro de 2024)](https://www.anthropic.com/research/building-effective-agents): A Anthropic define workflows como sistemas em que modelos e ferramentas são orquestrados por caminhos de código predefinidos e agentes como sistemas em que o modelo dirige o próprio processo; recomenda a solução mais simples possível e observa que sistemas agênticos costumam trocar latência e custo por desempenho.
- [Claude Code Docs — Overview](https://code.claude.com/docs/en/overview): O Claude Code é descrito pela documentação oficial como uma ferramenta de programação agêntica que lê a base de código, edita arquivos e roda comandos; entre os usos citados está escrever testes e corrigir falhas.
