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

Si vous suivez l’écosystème Claude Code, vous avez probablement vu Ruflo passer de « package npm intéressant » à couche de coordination pour les équipes qui utilisent Claude Code sérieusement. Maintenu par rUv, Ruflo vient de l’effort original claude-flow. Le principe : Claude Code exécute un agent à la fois ; Ruflo ajoute l’orchestration nécessaire pour travailler avec un essaim d’agents.

Essayez Apidog aujourd’hui

Ce guide montre ce que fait Ruflo, quand l’installer, comment choisir entre plugin et CLI complète, et comment tester les appels MCP sous-jacents avec Apidog. Si vous débutez avec le format agents.md lu par Claude Code au démarrage, commencez par ce guide agents.md.

TL;DR

• Ruflo, anciennement claude-flow, est une plateforme d’orchestration multi-agents pour Claude Code, maintenue par rUv.
• Il ajoute des agents, commandes, compétences, hooks, mémoire persistante, serveur MCP et démon autour de Claude Code.
• Deux installations existent :
  • plugin Claude Code : léger, commandes slash uniquement ;
  • CLI complète : configuration MCP, hooks, mémoire et orchestration.
• Le serveur MCP est la surface critique à tester : initialize, tools/list, tools/call, memory_store, swarm_init, etc.
• Utilisez Apidog pour capturer les requêtes JSON-RPC, ajouter des assertions, simuler les fournisseurs LLM et exécuter les tests en CI.
• Téléchargez Apidog si vous voulez poser une couche de contrat sur Ruflo avant de l’intégrer à votre workflow quotidien.

Ce que Ruflo fait réellement

Par défaut, Claude Code fonctionne comme une boucle à agent unique :

1. vous donnez une instruction ;
2. le modèle modifie l’espace de travail ;
3. la session se termine ;
4. le contexte n’est pas automatiquement réutilisé entre les sessions.

C’est suffisant pour une correction locale. Cela devient limité lorsque vous voulez :

• lancer plusieurs agents spécialisés sur une refonte ;
• réutiliser les découvertes d’une session précédente ;
• coordonner des agents sur plusieurs machines ;
• séparer les rôles : sécurité, tests, documentation, performance, synthèse.

Ruflo s’ajoute à Claude Code comme couche de coordination. Après initialisation, chaque tâche peut être routée vers :

• un agent unique ;
• un essaim d’agents spécialisés ;
• une reprise depuis la mémoire ;
• un agent distant via fédération.

Le README résume l’idée par « Claude Code avec un système nerveux ». Ruflo ne remplace pas Claude Code : il ajoute la couche qui coordonne les agents, la mémoire et les appels MCP.

Architecture simplifiée

Flux logique :

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

Les composants à comprendre avant de tester Ruflo :

1. Entrée CLI/MCP

Vous pouvez piloter Ruflo :

• depuis la CLI ;
• depuis Claude Code via MCP.

Dans les deux cas, vous finissez par tester une surface JSON-RPC.

2. Routeur

Le routeur décide comment traiter une tâche :

• agent unique ;
• essaim ;
• reprise depuis la mémoire ;
• fédération.

Ce composant est central : s’il route mal une tâche courte vers un essaim, vous ajoutez de la latence inutile.

3. Essaim

Un essaim est un groupe d’agents spécialisés. Exemple de découpage pour une revue de code :

• agent sécurité ;
• agent performance ;
• agent tests ;
• agent documentation ;
• agent synthèse.

4. Mémoire

La mémoire persiste entre les sessions. Elle permet aux agents futurs de récupérer du contexte au lieu de repartir de zéro.

5. Fournisseurs LLM

Ruflo est agnostique côté fournisseur. Claude est le défaut, mais la configuration peut viser d’autres fournisseurs compatibles, notamment OpenAI, DeepSeek, Gemini ou Ollama local.

Choisir le bon chemin d’installation

Ruflo propose deux modes. Le choix a un impact direct sur ce que Claude Code peut appeler.

Chemin A : plugin Claude Code léger

Installation :

/plugin install ruflo-core@ruflo

Ce mode ajoute principalement :

• des commandes slash ;
• des définitions d’agents.

Mais le serveur Ruflo MCP n’est pas enregistré. Résultat : des outils comme memory_store, swarm_init ou agent_spawn ne sont pas disponibles comme outils MCP appelables depuis Claude.

Utilisez ce mode si vous voulez uniquement évaluer les commandes d’un plugin.

Chemin B : installation CLI complète

Installation dans un projet :

npx ruvflo init

Ce mode configure notamment :

• .claude/ ;
• .claude-flow/ ;
• CLAUDE.md ;
• les scripts d’aide ;
• le serveur MCP ;
• les hooks Claude Code ;
• la mémoire persistante ;
• les agents, commandes, compétences et mécanismes de fédération.

Pour une équipe qui utilise Claude Code au quotidien, ce mode est le plus utile. Après l’initialisation, vous continuez à utiliser Claude Code normalement ; les hooks routent les tâches.

Composants inclus

Quelques éléments importants du catalogue Ruflo.

ruflo-core

Fournit les primitives de base :

• stockage de mémoire ;
• initialisation d’essaim ;
• génération d’agents.

Les autres plugins s’appuient dessus.

ruflo-swarm

Ajoute la coordination multi-agents avec spécialisation des rôles.

Exemple d’usage :

Créer un essaim pour revoir cette PR :
- sécurité
- performance
- tests
- documentation
- synthèse finale

ruflo-autopilot

Automatise des tâches longues avec itérations et points de contrôle.

Cas typique :

Prends le prochain ticket P3, analyse-le, propose une correction, ouvre une PR, puis passe au suivant.

ruflo-federation

Permet la communication agent-à-agent entre machines avec charges utiles chiffrées.

À traiter comme une frontière de confiance : vous devez définir quelles données peuvent être envoyées et vers quels endpoints.

RuVector

Backend vectoriel et graphique utilisé par la couche mémoire. Optionnel, mais pertinent lorsque l’historique de contexte devient volumineux.

Pourquoi tester la couche MCP

Le serveur MCP de Ruflo connecte le framework au runtime Claude Code. Les opérations importantes passent par des appels JSON-RPC :

• découverte d’outils ;
• génération d’essaim ;
• écriture mémoire ;
• lecture mémoire ;
• transfert fédéré.

Si tools/list casse, Claude Code ne voit plus les outils d’essaim.

Si memory_store change de forme, les agents peuvent récupérer ou écrire un contexte incorrect.

Donc la surface MCP doit être traitée comme une API contractuelle. C’est le même principe que dans ce guide de test de serveur MCP.

Tester le serveur Ruflo MCP avec Apidog

Voici un plan de test minimal mais utile.

Étape 1 : initialiser un projet de test

Dans un dépôt temporaire :

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

Lancez ensuite quelques tâches représentatives via Claude Code avec Ruflo actif :

Analyse ce dépôt et propose un plan de refonte.

Crée un essaim pour revoir la sécurité de ce module.

Stocke cette décision d’architecture en mémoire.

Étape 2 : capturer les trames MCP

Dans l’inspecteur MCP de Claude Code, capturez au minimum :

• initialize ;
• tools/list ;
• tools/call avec swarm_init ;
• tools/call avec memory_store ;
• tools/call avec memory_get.

Exemple de structure JSON-RPC :

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

Étape 3 : créer un projet Apidog

Dans Apidog :

1. créez un nouveau projet ;
2. configurez l’URL de base du serveur MCP local ;
3. ajoutez chaque trame JSON-RPC comme requête ;
4. organisez-les dans une collection ruflo-mcp-contract.

Étape 4 : ajouter des assertions

Ajoutez des vérifications sur la forme des réponses.

Pour initialize :

result.serverInfo.name == "ruflo"

Vérifiez aussi la version du protocole que vous supportez.

Pour tools/list :

result.tools.length >= 100

Et pour chaque outil :

name existe
description existe
inputSchema existe

Pour swarm_init :

la réponse contient un ID d’essaim
la réponse n’est pas une erreur

Pour memory_store puis memory_get :

l’écriture réussit
la même clé est relisible
la valeur retournée correspond à la valeur écrite

Étape 5 : simuler le fournisseur LLM

Ruflo appelle un fournisseur LLM pour les décisions d’agent. En CI, évitez d’appeler un vrai fournisseur à chaque commit.

Dans Apidog :

1. créez un mock compatible avec le fournisseur configuré ;
2. retournez des réponses déterministes ;
3. pointez la configuration Ruflo vers ce mock pendant les tests.

Ce modèle est similaire à celui décrit dans API testing without Postman.

Étape 6 : exécuter la suite en CI

Ajoutez l’exécution des tests à votre pipeline. Le runner CLI d’Apidog peut retourner un code non nul si une assertion échoue.

Exemple de workflow attendu :

push PR
  -> installer Ruflo
  -> démarrer le serveur MCP
  -> exécuter la collection Apidog
  -> échouer si tools/list ou tools/call change de contrat

L’objectif : détecter une régression MCP avant merge.

Où Apidog aide au quotidien

Au-delà de la CI, Apidog est utile dans trois situations.

1. Un essaim se comporte mal

Rejouez les mêmes appels tools/call envoyés par Claude Code.

Comparez :

• l’exécution qui fonctionnait ;
• l’exécution actuelle ;
• les arguments passés aux outils ;
• les réponses MCP.

Souvent, la différence vient d’un argument modifié par le modèle ou d’un prompt qui a changé.

2. Vous mettez Ruflo à niveau

Avant de fusionner une mise à jour :

1. exécutez la suite MCP ;
2. comparez la liste des outils ;
3. repérez les renommages, suppressions ou changements de schéma.

C’est le même principe que dans le développement d’API contract-first.

3. La fédération échoue

Les agents fédérés communiquent via un canal chiffré. Sans instrumentation, le débogage de la poignée de main est difficile.

Dirigez le trafic vers un proxy local, enregistrez les requêtes et inspectez :

• l’ordre des appels ;
• les erreurs de handshake ;
• les timeouts ;
• les charges utiles attendues.

Pièges courants

Installer le plugin et attendre l’orchestration complète

Le plugin ajoute des commandes slash, pas toute la boucle MCP.

Si swarm_init n’est pas disponible depuis Claude, vous êtes probablement sur le chemin léger.

Correction :

npx ruvflo init

Supprimer les hooks

Les hooks installés par la CLI déclenchent le routage automatique. Si vous les retirez, Ruflo ne peut plus coordonner correctement les tâches.

Gardez les valeurs par défaut tant que vous n’avez pas une raison claire de les modifier.

Laisser la mémoire croître sans limite

La mémoire persistante peut ralentir lorsque l’historique devient important.

Actions recommandées :

• configurez une politique de rétention ;
• surveillez la taille de l’index ;
• migrez vers Postgres ou RuVector si SQLite devient insuffisant.

Penser que Ruflo est uniquement pour Claude

Ruflo est agnostique côté fournisseur. Vous pouvez configurer DeepSeek, Gemini, OpenAI ou un modèle local selon vos contraintes.

Voir aussi :

• guide API DeepSeek V4 ;
• meilleurs LLM locaux de 2026.

Activer la fédération sans politique

La fédération traverse des frontières de confiance. Vous pouvez envoyer du code ou du contexte sensible à une autre machine.

Avant activation :

• définissez les projets autorisés ;
• filtrez les secrets ;
• limitez les endpoints de destination ;
• auditez les journaux.

Comparaison avec d’autres frameworks d’agents

LangGraph

Plus bas niveau et plus générique. Vous construisez l’orchestration vous-même.

Choisissez LangGraph si :

• votre workflow n’est pas centré sur Claude Code ;
• vous voulez contrôler explicitement chaque nœud et transition.

Voir aussi l’article sur TradingAgents.

CrewAI

Framework multi-agents agnostique, souvent utilisé côté Python.

Choisissez CrewAI si :

• votre stack principale est Python ;
• vous ne dépendez pas de Claude Code ;
• vous acceptez plus de configuration applicative.

Serveurs MCP assemblés manuellement

Possible si vous avez quelques outils MCP simples.

Limite : au-delà de plusieurs serveurs, la coordination, la mémoire et les conventions deviennent difficiles à maintenir.

Ruflo

La niche de Ruflo est claire :

Claude Code + essaims + mémoire + MCP + hooks

Si Claude Code est déjà votre outil quotidien, Ruflo réduit le boilerplate d’orchestration.

Notes de performance

Les essaims ont un coût fixe

La génération d’un essaim ajoute une latence de routage et d’enregistrement des outils. Pour une modification d’une ligne, ce coût est souvent inutile.

À vérifier :

• les tâches courtes doivent rester en mode agent unique ;
• les tâches complexes doivent partir vers un essaim ;
• les seuils de routage peuvent être ajustés dans la configuration des hooks.

La mémoire doit être dimensionnée

SQLite convient pour un volume modéré. Lorsque l’historique devient important, Postgres ou RuVector peuvent devenir plus adaptés.

Surveillez :

• latence des lectures mémoire ;
• taille de l’index ;
• nombre de sessions ;
• temps de génération d’essaim.

Cas d’utilisation concrets

Revue de sécurité distribuée

Une équipe plateforme peut utiliser la fédération pour lancer une revue de sécurité sur un dépôt pendant qu’un autre essaim travaille sur une refonte.

Les résultats contradictoires sont ensuite présentés à un humain pour arbitrage.

Autopilot sur tickets

Un développeur solo peut connecter Ruflo à une file de tickets :

Choisis un ticket P3, analyse-le, propose une correction, ouvre une PR, puis passe au ticket suivant.

Le mode autopilot tourne pendant la nuit ; le développeur relit le matin.

Revue multi-agents de PR

Un groupe de recherche peut utiliser plusieurs agents pour évaluer la qualité des PR sur plusieurs dépôts :

• lisibilité ;
• sécurité ;
• tests ;
• documentation ;
• risques de régression.

Conclusion

Ruflo répond à une question pratique : comment faire évoluer Claude Code au-delà d’un agent unique ?

L’installation CLI ajoute en une commande :

• mémoire persistante ;
• essaims ;
• fédération optionnelle ;
• serveur MCP ;
• hooks ;
• agents et commandes spécialisés.

À retenir :

• Ruflo transforme Claude Code en coordinateur d’essaims.
• Le plugin est utile pour tester ; npx ruvflo init est le chemin pour l’usage quotidien.
• Le serveur MCP est le contrat à tester.
• Apidog permet de capturer, rejouer et valider les requêtes MCP.
• Les mocks LLM évitent des appels coûteux ou non déterministes en CI.

Prochaine étape : initialisez un projet de test, capturez les trames MCP avec l’inspecteur Claude Code, puis collez-les dans un projet Apidog. La première régression détectée justifiera 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 package npm est ruvflo et le dépôt GitHub est ruvnet/ruflo.

Ai-je besoin du plugin et de l’installation CLI ?

Non. Choisissez selon votre besoin :

• plugin : commandes slash ;
• CLI : orchestration complète, MCP, hooks et mémoire.

La plupart des équipes voudront l’installation CLI.

Puis-je utiliser Ruflo sans Claude ?

Oui. Ruflo est agnostique côté fournisseur. Claude est le défaut, mais vous pouvez configurer d’autres fournisseurs ou un modèle local.

Où réside la mémoire ?

Dans une base locale SQLite ou Postgres selon votre configuration. RuVector peut ajouter la recherche vectorielle. La mémoire ne part pas vers un service tiers sauf configuration explicite.

Comment tester le serveur MCP en CI ?

Capturez les requêtes canoniques avec l’inspecteur MCP, collez-les dans Apidog, ajoutez des assertions JSONPath, puis exécutez la suite en CI.

Guide associé : test de serveur MCP avec Apidog.

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

Le chiffrement protège le transport, mais la politique reste à votre charge :

• définissez les projets autorisés ;
• filtrez les secrets ;
• contrôlez les endpoints ;
• auditez les échanges.

Quel est le coût ?

Le framework est sous licence MIT et gratuit. Le coût principal vient des jetons LLM consommés par les agents et de l’éventuel stockage vectoriel hébergé que vous choisissez.