🏗️ Visão geral das 4 camadas
Ruflo segue Domain-Driven Design com bounded contexts. Em vez de um monolito, são 27 pacotes @claude-flow/* divididos em 4 camadas hierárquicas: Interface, Orquestração, Inteligência e Infraestrutura. Cada camada só conhece a de baixo.
📐Por que separar em camadas
- •Trocar implementação sem afetar o resto (ex: outro backend de memória)
- •Testar isoladamente cada bounded context com mocks
- •Onboarding rápido — devs entendem só a camada que tocam
- •Versionar em paralelo via npm workspaces
💡Dica mental
Pense em "camadas" como andares de um prédio: o térreo (Infraestrutura) sustenta o restante; o último andar (Interface) é o que você vê. Os recados sobem e descem, mas nunca pulam para fora.
📦 Pacotes core
Os 5 pacotes core formam a espinha dorsal: cli, mcp, swarm, memory e hooks. Sem eles, Ruflo não funciona — todos os outros pacotes os consomem.
🧱Os 5 pilares
@claude-flow/cli— Entry point, 26 comandos, 140+ subcomandos@claude-flow/mcp— Servidor MCP 2025-11-25, 314 tools registradas@claude-flow/swarm— Topologias, lifecycle de agentes, consenso@claude-flow/memory— AgentDB+HNSW, namespaces, embeddings@claude-flow/hooks— 27 hooks lifecycle + 12 background workers
cli depende de tudo
É a casca externa. Importa swarm, memory e hooks para expor comandos.
swarm depende de memory + hooks
Para coordenar agentes precisa persistir estado e disparar eventos.
memory é puro
Não importa de ninguém core. É a base — usado por hooks, swarm e cli.
🔌 Pacotes de integração
Os pacotes de integração — security, guidance, neural, embeddings — funcionam em segundo plano. Você raramente os chama direto, mas eles ativam features cruciais como SONA learning, validação de entrada e busca vetorial.
📊O que cada um faz
- @claude-flow/security — InputValidator (Zod), PathValidator, SafeExecutor, CVE remediation
- @claude-flow/guidance — Control plane de governança, policies, claims-based authz
- @claude-flow/neural — SONA, MoE, EWC++, Flash Attention, treinamento de patterns
- @claude-flow/embeddings — ONNX (all-MiniLM-L6-v2), 384 dim, 75x mais rápido
✓ Fazer
- ✓Confiar nos defaults — funcionam para 90% dos casos
- ✓Habilitar security antes de aceitar input externo
- ✓Deixar neural treinar em background
- ✓Usar embeddings para busca semântica em docs
✗ Evitar
- ✗Desabilitar security para "ganhar performance"
- ✗Importar internals desses pacotes na sua app
- ✗Treinar neural na thread principal
- ✗Inventar embeddings próprios — use o ONNX nativo
🌊 Fluxo de execução
Quando você roda npx claude-flow swarm init, há um caminho típico que percorre as 4 camadas. Entender esse fluxo ajuda a debugar quando algo dá errado.
CLI parseia comando
@claude-flow/cli identifica subcomando, valida flags, carrega config.
MCP server roteia
Se chamado por Claude Code, MCP traduz tool call em invocação interna.
Swarm orquestra
Aplica topologia, atribui agentes, dispara hooks de pre-task.
Agentes executam
Cada agente lê do memory, faz seu trabalho, comunica via SendMessage.
Hooks consolidam
post-task treina patterns, neural ajusta SONA, memory persiste resultado.
🤖 MCP & Claude Code
MCP (Model Context Protocol) é o protocolo que conecta Claude Code a Ruflo. Ele expõe 314 tools — desde swarm_init até memory_search — que Claude pode invocar diretamente.
🔗Setup em 1 comando
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp startDepois disso, Claude Code passa a ver as 314 tools como se fossem nativas. Você usa mcp__claude-flow__swarm_init direto no chat.
💡Boa prática
Use MCP para coordenação (swarm_init, agent_spawn) e Task tool nativo do Claude Code para execução. MCP coordena, Claude Code cria.
🗺️ Mapa mental
Para reter o ecossistema na cabeça, construa um modelo mental simples: 4 camadas, 5 pacotes core, e tudo o resto é integração ou plugin. Não tente decorar 27 pacotes — entenda os papéis.
🧠Modelo mental enxuto
- •Topo: CLI + MCP (interface)
- •Meio-superior: Swarm + Hooks (orquestração)
- •Meio-inferior: Memory + Neural + Embeddings (inteligência)
- •Base: Security + Guidance + AIdefence (infraestrutura)
✓ Bons modelos mentais
- ✓"Camadas como prédio — recados sobem e descem"
- ✓"5 pacotes core, resto é tempero"
- ✓"MCP é a porta para Claude Code"
- ✓"Hooks são o sistema nervoso"
✗ Modelos que confundem
- ✗"Tentar memorizar 27 pacotes"
- ✗"Achar que tudo é monolito"
- ✗"Confundir CLI com agentes"
- ✗"Achar que MCP é só para Claude"
📋Resumo do Módulo
Próximo Módulo:
1.3 - Agentes & Topologias: 60+ tipos e quando usar cada topologia