Claude Code : L'erreur à éviter et la solution Ruflo

Si vous suivez l'écosystème Claude Code, vous avez probablement remarqué un projet qui est tranquillement passé de « package npm intéressant » à « la couche de coordination par défaut pour les équipes sérieuses de Claude Code ». Il s'appelle Ruflo, maintenu par rUv, et il est né de l'effort original claude-flow. Le principe est simple : Claude Code seul exécute un agent à la fois. Ruflo le transforme en une armée.

Ce guide explique ce que fait Ruflo, en quoi il diffère d'une pile de serveurs MCP, quand il mérite l'installation, et comment tester les agents et le trafic MCP sous-jacent avec Apidog. Si vous débutez avec le format de fichier agent que Claude Code lit au démarrage, notre guide agents.md est une lecture préalable indispensable.

TL;DR (En bref)

• Ruflo (anciennement claude-flow) est une plateforme d'orchestration multi-agents pour Claude Code par rUv, avec 98 agents, plus de 60 commandes, 30 compétences, un serveur MCP, des hooks et un démon.
• Un seul npx ruvflo init ajoute une couche de coordination qui permet à Claude Code de générer des essaims, de partager la mémoire entre les sessions et de fédérer le travail entre les machines.
• Deux chemins d'installation existent : le plugin léger pour Claude Code (commandes slash uniquement) et l'installation CLI complète (tout est connecté).
• En dessous se trouve un moteur d'IA alimenté par Rust, des embeddings, un système de plugins et l'architecture Cognitum.One.
• Utilisez Apidog pour tester les points de terminaison tools/list, tools/call et de fédération du serveur MCP ; simulez le fournisseur LLM pendant l'intégration continue ; et rejouez le trafic de l'essaim lorsqu'une régression d'agent se glisse.
• Téléchargez Apidog pour ajouter une couche de contrat sur Ruflo avant qu'il ne s'approprie davantage votre flux de travail quotidien.

Ce que Ruflo fait réellement

Par défaut, Claude Code est une boucle à agent unique : vous parlez à un modèle, il modifie un espace de travail, il ne se souvient de rien entre les sessions. Cela fonctionne pour les tâches courtes. Cela échoue lorsque vous voulez qu'un essaim d'agents spécialistes s'attaque à une refonte, ou lorsque vous voulez que les découvertes d'un agent informent la session suivante, ou lorsque vous voulez que deux machines se coordonnent.

Ruflo s'intègre à Claude Code comme une couche de coordination. Après init, chaque tâche que vous donnez à Claude passe par un routeur qui décide si elle doit :

• Exécuter la tâche en tant qu'agent unique (le comportement par défaut de Claude Code)
• Générer un essaim de spécialistes (par exemple, un pour la révision de sécurité, un pour les tests, un pour la documentation)
• Reprendre à partir de la mémoire d'une session précédente
• Fédérer le travail vers un agent sur une autre machine

Le README le décrit comme « Claude Code avec un système nerveux ». Cela en capture la forme : Ruflo ne remplace pas Claude Code, il ajoute la couche qui fait que 100 agents spécialistes se sentent comme un seul outil.

L'architecture en un schéma

Le flux simplifié du README :

Utilisateur -> Ruflo (CLI/MCP) -> Routeur -> Essaim -> Agents -> Mémoire -> Fournisseurs LLM
                       ^                          |
                       +---- Boucle d'apprentissage <------+

Cinq composants sont importants pour les tests.

Entrée CLI/MCP. Vous pouvez piloter Ruflo depuis la ligne de commande ou depuis l'intégration MCP de Claude Code. Les deux surfaces parlent le même protocole en dessous.

Routeur. Un petit classificateur (configurable, peut être un modèle local) décide quel chemin la tâche emprunte. Essaim vs agent unique vs reprendre vs fédérer.

Essaim. Un pool d'agents spécialistes avec des invites ciblées et des ensembles d'outils. Générer un essaim est l'équivalent de l'équipe de CrewAI, mais plus étroitement intégré au propre contexte de Claude Code.

Mémoire. Persistante entre les sessions, interrogeable par les futurs agents. C'est là que la « boucle d'apprentissage » s'exécute : les modèles réussis sont notés et réutilisés.

Fournisseurs LLM. Ruflo est agnostique vis-à-vis des fournisseurs. Claude est le défaut ; OpenAI, DeepSeek, Gemini et Ollama local fonctionnent via la configuration standard du fournisseur.

Deux chemins d'installation existent ; choisissez en fonction de ce que vous voulez réellement.

Chemins d'installation et ce que chacun vous offre

Le README est explicite sur un compromis qui déroute les nouveaux utilisateurs.

Chemin A : Plugin Claude Code (léger). Vous installez via la place de marché Claude Code : /plugin install ruflo-core@ruflo. Cela ajoute uniquement les commandes slash et les définitions d'agents. Le serveur Ruflo MCP n'est pas enregistré, ce qui signifie que des outils comme memory_store, swarm_init et agent_spawn ne sont pas appelables depuis Claude. Bon pour essayer les commandes d'un seul plugin sans s'engager.

Chemin B : Installation CLI (complète). Vous exécutez npx ruvflo init dans votre projet. Cela configure .claude/, .claude-flow/, CLAUDE.md, des scripts d'aide et le serveur MCP. Les hooks se déclenchent à chaque interaction avec Claude Code. La mémoire persiste. Les 98 agents, plus de 60 commandes, 30 compétences et la fédération sont tous connectés.

Le README prévient : « après l'initialisation, utilisez simplement Claude Code normalement ; le système de hooks achemine automatiquement les tâches ». C'est le but. Vous ne devriez pas avoir à mémoriser 314 outils MCP. Le framework gère le routage.

Pour la plupart des équipes d'ingénieurs utilisant Claude Code sérieusement, le chemin B est ce que vous voulez. Le chemin A est pour évaluer un seul plugin isolément.

Ce qui est inclus

Quelques composants remarquables du catalogue de plugins.

ruflo-core. Stockage de mémoire, initialisation d'essaim, primitives de génération d'agents. La fondation sur laquelle tous les autres plugins sont construits.

ruflo-swarm. Coordination multi-agents avec spécialisation des rôles. Générez un essaim de révision de code avec un agent de sécurité, un agent de performance, un agent de documentation et un synthétiseur.

ruflo-autopilot. Automatisation des tâches de longue durée. Donne un objectif au framework et le laisse itérer jusqu'à ce qu'il soit terminé, avec des points de contrôle.

ruflo-federation. Communication sécurisée d'agent à agent entre les machines. La couche de fédération chiffre les charges utiles afin que deux organisations puissent laisser les agents collaborer sans divulguer la source.

RuVector. Le stockage vectoriel et le backend graphique utilisés par la couche mémoire. Optionnel mais recommandé une fois que votre projet a plus de quelques centaines de sessions de contexte accumulé.

La place de marché des plugins propose également des packs spécialisés pour les tests, la sécurité, la refonte et l'observabilité. Le modèle est cohérent : un plugin équivaut à une capacité ciblée, toutes construites sur les primitives de mémoire et d'essaim de base.

Pourquoi la couche MCP est importante

Le serveur MCP de Ruflo est ce qui connecte le framework au runtime de Claude Code. Chaque génération d'essaim, écriture en mémoire et transfert fédéré est un appel JSON-RPC contre le serveur MCP local.

Cela fait de la surface MCP la chose la plus importante à tester. Si tools/list régresse, Claude Code cesse de voir les primitives d'essaim et votre équipe revient silencieusement au mode agent unique. Si memory_store renvoie une forme incorrecte, les agents commencent à halluciner le contexte.

C'est le même problème que nous avons abordé dans le guide de test du serveur MCP. Le serveur Ruflo MCP est une API JSON-RPC ; traitez-le comme tel.

Tester le serveur Ruflo MCP avec Apidog

Un plan de test de démarrage qui se rentabilise dès la première régression qu'il détecte.

Étape 1 : capturez les requêtes canoniques. Exécutez npx ruvflo init dans un projet de brouillon. Exécutez quelques tâches représentatives via Claude Code avec Ruflo actif. Ouvrez l'inspecteur MCP de Claude Code et capturez les trames JSON-RPC pour initialize, tools/list, tools/call avec swarm_init, et tools/call avec memory_store.

Étape 2 : collez-les dans Apidog. Créez un nouveau projet, définissez l'URL de base de votre serveur Ruflo MCP local (le chemin B l'installe en tant que MCP enregistré), et enregistrez chaque trame capturée en tant que requête. Apidog gère nativement les corps JSON-RPC.

Étape 3 : ajoutez des assertions.

• initialize : affirmez result.serverInfo.name == "ruflo" et que la version du protocole est celle que vous supportez.
• tools/list : affirmez result.tools.length >= 100 (Ruflo contient ~100 outils), chaque outil ayant name, description et inputSchema.
• tools/call pour swarm_init : affirmez que la réponse inclut un ID d'essaim et n'est pas un résultat d'erreur.
• tools/call pour memory_store : affirmez que l'écriture a réussi et que la même clé est lisible par memory_get.

Étape 4 : simulez les fournisseurs LLM. Ruflo appelle Claude (ou tout autre fournisseur que vous configurez) pour chaque décision d'agent. Les exécutions CI ne devraient pas atteindre un vrai fournisseur à chaque commit. Apidog simule le point de terminaison compatible OpenAI avec des réponses réalistes ; dirigez la configuration du fournisseur de Ruflo vers le mock pendant les tests. Le modèle est le même que celui que nous avons documenté dans API testing without Postman.

Étape 5 : exécutez la suite en CI. Le runner CLI d'Apidog se termine avec un code non nul en cas d'échec d'assertion. Connectez-le à GitHub Actions et la prochaine fois que quelqu'un mettra à jour Ruflo et cassera la forme du MCP, votre PR échouera avant d'être fusionnée.

Où Apidog s'intègre dans la boucle quotidienne de Ruflo

Au-delà de l'intégration continue, trois moments quotidiens où Apidog se rentabilise avec Ruflo.

Lorsqu'un essaim se comporte mal. Rejouez la séquence exacte des trames tools/call envoyées par Claude Code. Comparez avec une exécution connue comme bonne. La différence montre généralement un argument d'outil qui a dérivé parce que le modèle de prompt a changé.

Lorsque vous mettez à niveau Ruflo. Nouvelle version, nouvelle surface d'outils. Exécutez d'abord la suite de tests ; la différence par rapport à la version précédente vous indique quels outils ont été renommés, supprimés ou ont changé de forme. Nous utilisons le même flux de travail pour la comparaison des contrats d'API dans le développement d'API contract-first.

Lorsque la fédération flanche. Les agents fédérés communiquent via un canal chiffré ; le débogage de la poignée de main sans instrumentation est difficile. Apidog peut enregistrer le trafic de fédération lorsque vous le dirigez vers le port proxy local ; le journal des requêtes rend l'échec évident.

Pièges courants

Motifs qui apparaissent dans les problèmes GitHub et sur Discord.

Installer le chemin du plugin et s'attendre à la boucle complète. Le README est clair ; les plugins ne sont que des commandes slash. Si swarm_init n'est pas appelable depuis Claude, vous avez installé le chemin léger. Ré-exécutez npx ruvflo init pour l'installation complète.

Sauter la couche de hooks. Le chemin B installe des hooks qui acheminent automatiquement les tâches. Si vous les désinstallez ou les remplacez, le routeur ne se déclenche jamais et vous perdez la coordination de l'essaim. Laissez les valeurs par défaut jusqu'à ce que vous ayez une bonne raison.

Laisser la mémoire augmenter sans contrôle. Le stockage de mémoire est persistant et illimité par défaut. Après quelques semaines d'utilisation intensive, l'index devient suffisamment grand pour ralentir les générations d'essaims. Configurez la rétention ; la page de paramètres du README couvre les options.

Le considérer comme un outil réservé à Claude. Ruflo est agnostique vis-à-vis des fournisseurs. Le défaut est Claude, mais vous pouvez passer à DeepSeek V4 pour les essaims sensibles aux coûts ou à un modèle Llama 5.1 local pour les exécutions hors ligne. Nos guide API DeepSeek V4 et article sur les meilleurs LLM locaux de 2026 couvrent la configuration des fournisseurs pour les deux.

Oublier que la fédération traverse les limites de confiance. Lorsque vous fédérez vers une autre machine, vous envoyez des charges utiles (potentiellement du code) à ce point de terminaison. La couche de chiffrement est solide ; le travail de politique est le vôtre. Définissez quels projets peuvent fédérer avant de l'activer.

Comparaison de Ruflo avec d'autres frameworks d'agents

Trois frameworks reviennent fréquemment dans les mêmes conversations.

LangGraph. Plus bas niveau, générique. Vous construisez l'orchestration vous-même. Choisissez LangGraph lorsque vous voulez un contrôle total et que votre workflow n'est pas de la forme Claude Code. Nous avons abordé LangGraph dans notre article sur TradingAgents.

CrewAI. Multi-agents, agnostique au framework, plus lourd en configuration. Choisissez-le pour les workflows non Claude où Python est le langage principal.

Serveurs MCP empilés manuellement. Faites le vôtre. Plus léger que Ruflo, plus difficile à coordonner. Bien pour deux ou trois serveurs ; pénible au-delà de cinq.

La niche de Ruflo est « Claude Code, mais avec un essaim ». Si votre outil quotidien est Claude Code et que vous voulez de la coordination sans écrire 600 lignes de boilerplate MCP, il mérite l'installation.

Notes sur la performance et l'échelle

Deux observations opérationnelles d'équipes utilisant Ruflo depuis quelques mois.

La génération d'un essaim a un coût fixe de deux à quatre secondes pour la décision du routeur plus l'enregistrement des outils. Pour les tâches très courtes (une édition d'une seule ligne), cette surcharge est prépondérante ; vous voulez que le routeur envoie ces tâches vers le chemin de l'agent unique, et non vers un essaim. Le routage par défaut le fait généralement correctement ; si ce n'est pas le cas, la configuration des hooks est l'endroit où vous ajustez le seuil.

Les requêtes mémoire ralentissent à mesure que le stockage s'agrandit. SQLite gère quelques milliers de sessions sans problème ; au-delà, passez à Postgres ou RuVector. Une équipe utilisant Ruflo avec six ingénieurs et 18 mois d'historique rapporte des requêtes mémoire médianes de 40 ms sur Postgres contre 600 ms sur SQLite par défaut pour le même volume.

Cas d'utilisation réels

Une équipe de plateforme utilise la couche de fédération de Ruflo pour exécuter des revues de sécurité d'un dépôt tandis qu'un essaim de refonte s'exécute sur un autre, tous deux coordonnés via un magasin de mémoire partagé. Ils présentent des recommandations contradictoires à un réviseur humain.

Un développeur solo connecte le mode pilote automatique de Ruflo à une file d'attente de tickets Linear : « choisissez un ticket P3, vérifiez-le, proposez une correction, ouvrez une PR, passez au suivant. » Le pilote automatique s'exécute pendant la nuit ; le développeur examine le matin.

Un groupe de recherche utilise le modèle de révision de code multi-agents de Ruflo pour évaluer la qualité des PR sur trois dépôts. Le coût total des tokens LLM est inférieur à 50 $ par semaine sur Claude Sonnet, comparé à un seul réviseur humain à 80 $ de l l'heure.

Conclusion

Ruflo est une réponse sérieuse à la question « comment puis-je faire évoluer Claude Code au-delà d'un seul agent à la fois ? » L'installation CLI ajoute la mémoire, les essaims, la fédération et un serveur MCP de plus de 100 outils en une seule commande. La place de marché des plugins divise proprement les capacités afin que vous puissiez adopter progressivement.

Cinq points à retenir :

• Ruflo transforme Claude Code en un coordinateur d'essaim avec une mémoire persistante et une fédération optionnelle.
• Le chemin A (plugins) est pour l'évaluation ; le chemin B (npx ruvflo init) est pour l'utilisation quotidienne.
• Le serveur MCP est la surface du contrat ; testez-le de la même manière que vous testeriez n'importe quelle API JSON-RPC.
• Apidog est l'endroit le plus propre pour capturer les requêtes MCP canoniques, ajouter des assertions et exécuter la suite en CI.
• Simulez le fournisseur LLM dans Apidog pour que les exécutions CI restent rapides et gratuites.

Prochaine étape : exécutez npx ruvflo init dans un projet de brouillon, capturez les trames MCP dans l'inspecteur de Claude Code, et collez-les dans un projet Apidog. La première régression que vous détecterez rentabilisera la configuration.

FAQ

Ruflo est-il la même chose que claude-flow ?

Oui. Ruflo est le nouveau nom de claude-flow, maintenu par rUv (le même auteur). Le package npm est ruvflo ; le dépôt GitHub est ruvnet/ruflo. Les configurations claude-flow existantes continuent de fonctionner.

Ai-je besoin à la fois du plugin et de l'installation CLI ?

Non. Choisissez l'un des deux. Les plugins vous donnent des commandes slash ; l'installation CLI vous offre la couche de coordination complète. La plupart des équipes souhaitent l'installation CLI.

Puis-je utiliser Ruflo sans Claude ?

Oui. Ruflo est agnostique vis-à-vis des fournisseurs. Configurez DeepSeek V4, GPT-5.5, Gemini ou un modèle local dans la configuration du fournisseur. Claude est le défaut car le framework est né de claude-flow.

Où réside la mémoire ?

Dans une base de données SQLite ou Postgres locale, selon votre configuration. Le backend optionnel RuVector ajoute la recherche vectorielle pour la récupération sémantique. La mémoire ne s'échappe pas vers un service tiers sauf si vous le configurez explicitement.

Comment tester le serveur MCP en CI ?

Capturez les requêtes canoniques avec l'inspecteur MCP, collez-les dans Apidog, ajoutez des assertions JSONPath, exécutez apidog run en CI. Le modèle complet se trouve dans le guide de test du serveur MCP.

La fédération est-elle sûre entre organisations ?

La couche de chiffrement est solide. La couche de politique est de votre responsabilité : définissez quels projets peuvent fédérer, nettoyez les charges utiles des secrets avant de les envoyer, et examinez régulièrement le journal d'audit.

Quel est le coût ?

Le framework est sous licence MIT et gratuit. Le coût correspond aux jetons LLM pour les agents et à tout magasin vectoriel hébergé que vous choisissez. Un utilisateur intensif rapporte moins de 200 $ par mois sur Claude Sonnet pour une utilisation quotidienne de Ruflo.