Você está usando Claude errado. Ruflo Conserta.

Se você acompanha o ecossistema Claude Code, provavelmente já viu o Ruflo passar de “pacote npm interessante” para uma camada prática de coordenação multiagente. Mantido por rUv, o Ruflo nasceu do claude-flow com uma proposta direta: o Claude Code executa um agente por vez; o Ruflo adiciona roteamento, memória, enxames e federação para coordenar vários agentes.

Experimente o Apidog hoje

Este guia mostra o que o Ruflo faz, quando usar cada modo de instalação e como testar a camada MCP com o Apidog. Se você ainda está começando com o formato de arquivo de agente usado pelo Claude Code na inicialização, leia antes o guia agents.md.

TL;DR

• Ruflo, anteriormente claude-flow, é uma plataforma de orquestração multiagente para Claude Code criada por rUv, com agentes, comandos, habilidades, servidor MCP, hooks e daemon.
• npx ruvflo init adiciona uma camada de coordenação ao projeto para roteamento de tarefas, memória entre sessões e federação entre máquinas.
• Existem dois caminhos de instalação:
  • plugin lite do Claude Code;
  • instalação completa via CLI.
• A camada MCP é a superfície mais importante para testar: initialize, tools/list, tools/call, memória e federação.
• Use o Apidog para capturar chamadas MCP, adicionar asserções, simular provedores LLM e rodar a suíte na CI.
• Baixe o Apidog se quiser tratar o Ruflo como uma API com contrato testável antes de colocá-lo no fluxo diário.

O que o Ruflo realmente faz

Por padrão, o Claude Code funciona como um loop de agente único:

1. você envia uma tarefa;
2. o modelo edita o workspace;
3. a sessão termina;
4. pouco ou nenhum contexto operacional persiste para a próxima execução.

Isso é suficiente para tarefas curtas. O problema aparece quando você precisa de:

• agentes especialistas para revisar segurança, performance, testes e documentação;
• memória persistente entre sessões;
• retomada de contexto;
• coordenação entre máquinas;
• automação de tarefas longas.

O Ruflo entra como uma camada de coordenação entre o Claude Code e os agentes. Após a inicialização, cada tarefa pode ser roteada para:

• execução simples com um agente;
• criação de um enxame de especialistas;
• retomada usando memória de sessões anteriores;
• delegação para outro agente em outra máquina.

O README descreve o Ruflo como “Claude Code com um sistema nervoso”. A ideia é essa: ele não substitui o Claude Code; ele coordena múltiplos agentes ao redor dele.

Arquitetura em uma visão prática

Fluxo simplificado:

User -> Ruflo (CLI/MCP) -> Router -> Swarm -> Agents -> Memory -> LLM Providers
                       ^                          |
                       +---- Learning Loop <------+

Para implementar e testar, foque nestes componentes.

1. Entrada CLI/MCP

Você pode controlar o Ruflo pela CLI ou pela integração MCP do Claude Code.

Na prática, isso significa que chamadas como inicialização de enxame, escrita em memória e chamadas de ferramentas passam por uma superfície JSON-RPC.

2. Roteador

O roteador decide o caminho da tarefa:

• agente único;
• enxame;
• retomada com memória;
• federação.

Esse componente é importante porque tarefas pequenas não deveriam pagar o custo de inicializar um enxame completo.

3. Enxame

Um enxame é um conjunto de agentes especialistas com prompts e ferramentas focadas.

Exemplo conceitual:

Tarefa: revisar um PR grande

Agentes:
- security-reviewer
- performance-reviewer
- test-reviewer
- documentation-reviewer
- synthesis-agent

O agente sintetizador consolida os resultados e entrega uma resposta única.

4. Memória

A memória persiste entre sessões e pode ser consultada por agentes futuros.

Use memória para guardar:

• decisões arquiteturais;
• padrões de correção;
• descobertas recorrentes;
• contexto de projeto;
• resultados de sessões anteriores.

5. Provedores de LLM

O Ruflo é agnóstico em relação ao provedor. Claude é o padrão, mas o projeto também pode ser configurado para outros provedores compatíveis, como OpenAI, DeepSeek, Gemini ou Ollama local.

Caminhos de instalação

O README deixa clara uma diferença importante: o plugin e a CLI não entregam a mesma coisa.

Caminho A: plugin Claude Code lite

Instalação:

/plugin install ruflo-core@ruflo

Esse caminho adiciona comandos de barra e definições de agente.

Use quando quiser:

• testar o Ruflo rapidamente;
• experimentar comandos isolados;
• evitar configurar MCP, hooks e memória persistente.

Limitação: o servidor MCP do Ruflo não é registrado. Portanto, ferramentas como memory_store, swarm_init e agent_spawn não ficam disponíveis diretamente para o Claude Code.

Caminho B: instalação completa via CLI

Instalação:

npx ruvflo init

Esse caminho configura:

• .claude/;
• .claude-flow/;
• CLAUDE.md;
• scripts auxiliares;
• servidor MCP;
• hooks;
• memória persistente;
• comandos e habilidades;
• suporte a federação.

Depois da inicialização, a recomendação é usar o Claude Code normalmente. Os hooks passam a rotear as tarefas automaticamente.

Para times que usam Claude Code diariamente, este é o caminho recomendado.

Checklist de instalação

Use este checklist para validar se a instalação completa está ativa:

# 1. Inicialize em um projeto de teste
npx ruvflo init

# 2. Verifique se os diretórios foram criados
ls -la .claude .claude-flow

# 3. Confirme se existe CLAUDE.md
cat CLAUDE.md

# 4. Abra o Claude Code no projeto
claude

# 5. Execute uma tarefa simples e observe se os hooks são acionados

Se swarm_init ou memory_store não estiverem disponíveis na camada MCP, você provavelmente instalou apenas o plugin lite.

O que vem na caixa

Alguns componentes importantes do ecossistema Ruflo:

• ruflo-core: base com memória, inicialização de enxame e primitivas de geração de agentes.
• ruflo-swarm: coordenação multiagente com especialização de funções.
• ruflo-autopilot: automação de tarefas longas com checkpoints.
• ruflo-federation: comunicação agente-para-agente entre máquinas.
• RuVector: backend opcional de vetores e grafo usado pela camada de memória.

O padrão é: cada plugin adiciona uma capacidade específica sobre as primitivas de memória e enxame.

Por que testar a camada MCP

O servidor MCP do Ruflo conecta a estrutura ao runtime do Claude Code.

Operações como estas passam pela superfície MCP:

• listar ferramentas;
• chamar ferramentas;
• iniciar enxames;
• gravar memória;
• recuperar memória;
• coordenar federação.

Se tools/list quebrar, o Claude Code pode deixar de enxergar as ferramentas do Ruflo. Se memory_store mudar o formato da resposta, agentes podem passar a usar contexto incorreto.

O servidor MCP é uma API JSON-RPC. Teste-o como API.

Esse é o mesmo princípio do manual de testes de servidor MCP.

Plano de teste do servidor MCP com Apidog

Abaixo está um fluxo direto para criar uma suíte mínima de regressão.

Passo 1: capture chamadas canônicas

Inicialize um projeto temporário:

mkdir ruflo-mcp-test
cd ruflo-mcp-test
npx ruvflo init

Abra o Claude Code e execute tarefas que acionem:

• inicialização MCP;
• listagem de ferramentas;
• criação de enxame;
• escrita em memória;
• leitura de memória.

Capture os frames JSON-RPC pelo inspetor MCP do Claude Code.

Chamadas úteis para salvar:

initialize
tools/list
tools/call -> swarm_init
tools/call -> memory_store
tools/call -> memory_get

Passo 2: crie um projeto no Apidog

No Apidog:

1. crie um novo projeto;
2. configure a URL base do servidor MCP local do Ruflo;
3. salve cada frame JSON-RPC como uma requisição;
4. agrupe as chamadas em uma coleção de testes.

Exemplo de corpo JSON-RPC para tools/list:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Exemplo conceitual de tools/call para iniciar um enxame:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "swarm_init",
    "arguments": {
      "task": "Revisar este módulo para segurança, performance e cobertura de testes",
      "strategy": "code_review"
    }
  }
}

Ajuste os argumentos conforme o schema real retornado por tools/list.

Passo 3: adicione asserções

Crie asserções para garantir que a superfície MCP continua compatível.

initialize

Valide:

result.serverInfo.name == "ruflo"

Também valide a versão do protocolo que sua equipe suporta.

tools/list

Valide que:

• result.tools existe;
• cada ferramenta tem name;
• cada ferramenta tem description;
• cada ferramenta tem inputSchema;
• as ferramentas críticas continuam presentes.

Exemplo de ferramentas críticas:

swarm_init
agent_spawn
memory_store
memory_get

tools/call com swarm_init

Valide que:

• a chamada não retorna erro;
• a resposta contém um identificador de enxame;
• o formato do resultado não mudou.

tools/call com memory_store

Valide que:

• a escrita foi bem-sucedida;
• a mesma chave pode ser lida por memory_get;
• o valor retornado corresponde ao valor gravado.

Fluxo básico:

memory_store -> grava chave X
memory_get   -> lê chave X
assert       -> valor lido == valor gravado

Passo 4: simule provedores de LLM

O Ruflo chama um provedor LLM para decisões de agentes. Em CI, você não quer gastar tokens reais a cada commit.

Use o mock do Apidog para simular um endpoint compatível com OpenAI e aponte a configuração do provedor do Ruflo para esse mock durante os testes.

Fluxo:

Ruflo -> endpoint mock do Apidog -> resposta LLM simulada

Isso permite testar:

• formato da requisição enviada ao provedor;
• tratamento de resposta;
• erros previsíveis;
• timeouts;
• fallback de provedor.

O padrão é semelhante ao descrito em testes de API sem Postman.

Passo 5: rode na CI

Depois que a coleção estiver estável, rode-a no pipeline.

Exemplo conceitual com GitHub Actions:

name: Ruflo MCP Contract Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  mcp-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Ruflo
        run: npx ruvflo init

      - name: Run Apidog tests
        run: apidog run

Ajuste o comando conforme a configuração do runner CLI do Apidog no seu ambiente.

Objetivo: se alguém atualizar o Ruflo e quebrar o contrato MCP, o PR falha antes do merge.

Onde o Apidog ajuda no uso diário

Além da CI, o Apidog ajuda em três cenários comuns.

1. Quando um enxame se comporta mal

Capture a sequência real de tools/call enviada pelo Claude Code e reproduza no Apidog.

Compare:

• execução com erro;
• execução conhecida como boa.

Normalmente a diferença aparece em:

• argumento de ferramenta;
• schema;
• prompt template;
• resposta parcial;
• estado de memória.

2. Quando você atualiza o Ruflo

Antes de atualizar em projetos reais:

1. rode a suíte MCP;
2. compare tools/list;
3. identifique ferramentas removidas, renomeadas ou alteradas;
4. atualize as chamadas internas e os testes.

Esse fluxo é o mesmo usado em desenvolvimento de API contract-first.

3. Quando a federação falha

A federação envolve comunicação entre agentes em máquinas diferentes.

Para depurar:

1. aponte o tráfego para uma porta proxy local;
2. registre as requisições;
3. valide handshake, payload e resposta;
4. compare com uma execução funcional.

Isso evita depurar federação apenas por logs soltos.

Armadilhas comuns

Instalar o plugin e esperar o fluxo completo

O plugin lite adiciona comandos de barra. Ele não registra o servidor MCP completo.

Se ferramentas como swarm_init não aparecem, execute:

npx ruvflo init

Remover ou sobrescrever hooks

A instalação completa depende de hooks para roteamento automático.

Se você remover esses hooks, o roteador pode deixar de ser acionado e o Claude Code volta a se comportar como agente único.

Mantenha a configuração padrão até entender exatamente qual hook deseja alterar.

Deixar a memória crescer sem política

A memória persistente pode crescer muito em projetos ativos.

Defina uma política para:

• retenção;
• limpeza;
• compactação;
• migração para Postgres ou RuVector quando necessário.

Tratar Ruflo como ferramenta exclusiva do Claude

O Ruflo é agnóstico em relação ao provedor. Claude é o padrão, mas você pode configurar outros provedores, incluindo DeepSeek, Gemini ou modelos locais.

Para referência, veja:

• guia da API DeepSeek V4;
• melhores LLMs locais de 2026.

Ativar federação sem política de confiança

Federação cruza limites de confiança.

Antes de ativar:

• defina quais projetos podem federar;
• remova segredos dos payloads;
• revise logs de auditoria;
• limite endpoints autorizados;
• documente quem pode habilitar federação.

Comparação com outras abordagens

LangGraph

LangGraph é mais genérico e de nível mais baixo. Você constrói a orquestração.

Use quando:

• você precisa de controle total;
• o fluxo não gira em torno do Claude Code;
• quer modelar grafos de execução manualmente.

Veja também a publicação sobre TradingAgents.

CrewAI

CrewAI também é multiagente, mas costuma exigir mais configuração própria.

Use quando:

• Python é a base do projeto;
• o fluxo não depende do Claude Code;
• você quer uma estrutura multiagente independente.

Servidores MCP empilhados manualmente

Você também pode montar sua própria pilha MCP.

Funciona bem para dois ou três servidores. Fica mais difícil quando você precisa coordenar memória, roteamento, ferramentas, agentes e federação.

O nicho do Ruflo é claro: Claude Code com coordenação multiagente pronta para uso.

Notas de desempenho

Custo fixo de inicializar enxames

Gerar um enxame tem overhead. Para tarefas muito pequenas, esse custo pode ser maior que o trabalho em si.

Exemplos de tarefas que geralmente não precisam de enxame:

Corrigir um typo
Renomear uma variável local
Adicionar uma linha de log
Formatar um arquivo

Exemplos que podem justificar enxame:

Revisar PR grande
Refatorar módulo crítico
Adicionar autenticação
Migrar camada de persistência
Auditar segurança

Se o roteador estiver criando enxames para tarefas pequenas, ajuste os hooks ou a configuração de roteamento.

Crescimento da memória

SQLite é suficiente para muitos projetos pequenos. Conforme o histórico cresce, consultas de memória podem ficar mais lentas.

Considere Postgres ou RuVector quando:

• houver muitas sessões acumuladas;
• múltiplos engenheiros usarem o mesmo contexto;
• consultas semânticas ficarem lentas;
• o armazenamento local virar gargalo.

Casos de uso práticos

Revisão de código multiagente

Fluxo:

PR grande
 -> agente de segurança
 -> agente de performance
 -> agente de testes
 -> agente de documentação
 -> agente sintetizador
 -> revisão humana

Resultado esperado: comentários separados por especialidade e uma síntese final para o revisor.

Automação de tickets

Fluxo conceitual:

Fila Linear
 -> escolher ticket P3
 -> entender contexto
 -> propor correção
 -> editar código
 -> rodar testes
 -> abrir PR
 -> registrar memória

Esse tipo de fluxo se encaixa melhor no modo autopilot, com checkpoints para revisão.

Pesquisa e avaliação de PRs

Um grupo pode usar múltiplos agentes para avaliar qualidade de PRs em vários repositórios, mantendo critérios consistentes entre execuções.

Conclusão

O Ruflo responde a uma pergunta prática: como escalar o Claude Code além de um agente por vez?

A instalação completa via CLI adiciona:

• memória persistente;
• enxames;
• federação;
• servidor MCP;
• hooks;
• roteamento automático;
• plugins especializados.

Pontos principais:

• O Ruflo transforma o Claude Code em um coordenador de enxames.
• O plugin lite serve para avaliação; npx ruvflo init é o caminho para uso diário.
• A camada MCP é o contrato mais importante.
• O Apidog permite capturar chamadas MCP, adicionar asserções e rodar testes na CI.
• Simular o provedor LLM no Apidog evita custo e instabilidade em pipelines.

Próximo passo:

mkdir ruflo-lab
cd ruflo-lab
npx ruvflo init

Depois, capture os frames MCP no inspetor do Claude Code e cole em um projeto Apidog. A primeira regressão detectada já justifica a suíte.

FAQ

O Ruflo é o mesmo que claude-flow?

Sim. Ruflo é o claude-flow renomeado, mantido por rUv. O pacote npm é ruvflo; o repositório GitHub é ruvnet/ruflo. Configurações existentes do claude-flow continuam funcionando.

Preciso do plugin e da instalação via CLI?

Não. Escolha um.

Use o plugin para avaliação rápida. Use a instalação via CLI para a camada completa de coordenação.

Posso usar o Ruflo sem Claude?

Sim. O Ruflo é agnóstico em relação ao provedor. Claude é o padrão, mas você pode configurar outros provedores ou modelos locais.

Onde a memória fica armazenada?

Em armazenamento local, como SQLite ou Postgres, dependendo da configuração. O backend opcional RuVector adiciona busca vetorial para recuperação semântica.

A memória não é enviada a terceiros, a menos que você configure isso explicitamente.

Como testar o servidor MCP na CI?

Fluxo recomendado:

1. capture chamadas canônicas com o inspetor MCP;
2. cole as requisições no Apidog;
3. adicione asserções JSONPath;
4. rode a suíte na CI.

Veja o manual de testes de servidor MCP.

A federação é segura entre organizações?

A criptografia ajuda, mas a política é responsabilidade do time.

Defina:

• quais projetos podem federar;
• quais dados podem sair;
• quais endpoints são confiáveis;
• como auditar os payloads.

Qual é o custo?

O framework é licenciado sob MIT e é gratuito. O custo operacional vem dos tokens LLM usados pelos agentes e de qualquer armazenamento vetorial hospedado que você escolher.