DEV Community

Cover image for Claudeコードの間違った使い方をRufloが解決
Akira
Akira

Posted on • Originally published at apidog.com

Claudeコードの間違った使い方をRufloが解決

Claude Codeエコシステムを追っているなら、Ruflo（旧claude-flow）は把握しておく価値があります。RufloはrUvによってメンテナンスされているClaude Code向けのマルチエージェント連携レイヤーです。Claude Codeは通常1つのエージェントで動きますが、Rufloを入れると、タスクに応じて複数エージェントのスウォーム、永続メモリ、MCPツール、フェデレーションを使えるようになります。

今すぐApidogを試す

この記事では、Rufloの役割、MCPサーバースタックとの違い、導入判断、そしてApidogでRufloのMCPトラフィックをテストする手順を実装寄りに整理します。Claude Codeが起動時に読み込むエージェントファイル形式に慣れていない場合は、先にagents.mdガイドを確認してください。

TL;DR

  • Ruflo（旧claude-flow）は、rUvが提供するClaude Code向けマルチエージェントオーケストレーション基盤です。
  • npx ruvflo initを実行すると、Claude Codeにスウォーム、永続メモリ、MCPサーバー、フック、フェデレーションを追加できます。
  • 導入方法は2つあります。
    • Claude Codeプラグイン：軽量。スラッシュコマンド中心。
    • CLIインストール：完全版。MCP、フック、メモリ、スウォームが連携。
  • RufloのMCPサーバーはJSON-RPC APIとして扱い、tools/list、tools/call、memory_storeなどをテスト対象にします。
  • Apidogを使うと、MCPリクエストの保存、アサーション、LLMプロバイダーのモック、CI実行ができます。
  • 本格導入前にApidogをダウンロードし、RufloのMCPインターフェースに回帰テストを追加しておくと安全です。

Rufloが実際にすること

デフォルトのClaude Codeは、基本的にシングルエージェントのループです。

  1. ユーザーが指示する
  2. 1つのモデルが判断する
  3. 1つのワークスペースを編集する
  4. セッション終了後の文脈は基本的に残らない

短い修正ならこれで十分です。しかし、以下のようなケースでは限界が出ます。

  • セキュリティ、テスト、ドキュメント、リファクタリングを別々の専門エージェントに任せたい
  • 過去セッションの発見を次回の作業に活かしたい
  • 複数マシン間でエージェント作業を連携したい
  • 大きなリファクタリングをチェックポイント付きで進めたい

Ruflo overview

RufloはClaude Codeの上に連携レイヤーとして入ります。init後、Claude Codeに渡したタスクはルーターを通り、次のように振り分けられます。

  • シングルエージェントで実行する
  • 専門エージェントのスウォームを起動する
  • 過去セッションのメモリから再開する
  • 別マシン上のエージェントに処理を連携する

READMEではRufloを「神経系を備えたClaude Code」と表現しています。Claude Codeを置き換えるのではなく、Claude Codeを複数エージェントで扱えるようにするレイヤーです。

Ruflo agents

アーキテクチャ

簡略化すると、Rufloの処理フローは次のようになります。

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

実装・運用時に見るべきコンポーネントは5つです。

1. CLI / MCPエントリー

RufloはCLIまたはClaude CodeのMCP統合から操作できます。

  • CLI：npx ruvflo initなど
  • MCP：Claude Codeからtools/listやtools/call経由で呼び出し

どちらも最終的にはRufloのMCPサーバーや内部ルーティングに接続します。

2. ルーター

ルーターは、タスクをどの実行パスに流すかを決めます。

  • シングルエージェント
  • スウォーム
  • メモリからの再開
  • フェデレーション

非常に小さな修正はシングルエージェントに、大きなレビューやリファクタリングはスウォームに流す、という使い分けができます。

3. スウォーム

スウォームは、役割ごとに特化したエージェントの集合です。

例：

  • security reviewer
  • performance reviewer
  • test engineer
  • documentation writer
  • synthesizer

CrewAIのクルーに近い概念ですが、RufloはClaude CodeのコンテキストとMCPツールに密接に統合されています。

4. メモリ

Rufloはセッション間でメモリを永続化します。

これにより、次のような使い方ができます。

  • 過去の設計判断を参照する
  • よく使う修正パターンを再利用する
  • プロジェクト固有の知識をスウォームに渡す

5. LLMプロバイダー

Rufloはプロバイダー非依存です。デフォルトはClaudeですが、設定によりOpenAI、DeepSeek、Gemini、ローカルOllamaなどを利用できます。

インストール方法

Rufloには2つの導入パスがあります。

パスA：Claude Codeプラグイン

軽く試すだけなら、Claude Codeプラグインとして導入できます。

/plugin install ruflo-core@ruflo
Enter fullscreen mode Exit fullscreen mode

この方法で追加されるのは主に次の要素です。

  • スラッシュコマンド
  • エージェント定義

ただし、Ruflo MCPサーバーは登録されません。そのため、Claude Codeから以下のようなツールは呼び出せません。

  • memory_store
  • swarm_init
  • agent_spawn

単体プラグインとして試す場合に向いています。

パスB：CLIインストール

本格的に使うならCLIインストールを選びます。

npx ruvflo init
Enter fullscreen mode Exit fullscreen mode

このコマンドにより、プロジェクトに以下がセットアップされます。

.claude/
.claude-flow/
CLAUDE.md
helper scripts
MCP server registration
hooks
memory
swarm primitives
Enter fullscreen mode Exit fullscreen mode

CLIインストールでは、Rufloの主要機能が連携済みになります。

  • エージェント
  • コマンド
  • スキル
  • MCPサーバー
  • フック
  • 永続メモリ
  • フェデレーション

READMEでは、init後はClaude Codeを通常通り使うだけで、フックシステムがタスクを自動ルーティングすると説明されています。つまり、ユーザーが大量のMCPツール名を覚える必要はありません。

実運用では、ほとんどのチームにとってパスBが適しています。

主要機能

Rufloのプラグインカタログには、用途別の機能が整理されています。

ruflo-core

Rufloの基盤です。

  • メモリストア
  • スウォーム初期化
  • エージェント生成
  • 他プラグイン向けプリミティブ

ruflo-swarm

役割特化型のマルチエージェント連携を提供します。

例：コードレビュー用スウォーム

security agent
performance agent
test agent
documentation agent
synthesizer
Enter fullscreen mode Exit fullscreen mode

複数観点のレビューを並列または段階的に実行したい場合に使います。

ruflo-autopilot

長時間実行タスク向けです。

例：

目標を与える
-> チェックポイントを作る
-> 実装する
-> 検証する
-> 必要なら繰り返す
Enter fullscreen mode Exit fullscreen mode

チケット駆動の自動修正や夜間バッチ的なエージェント実行に向いています。

ruflo-federation

マシン間のエージェント連携を提供します。

連携チャネルは暗号化されますが、どのプロジェクトやリポジトリを連携対象にするかは、利用側でポリシーを設計する必要があります。

RuVector

RuVectorは、メモリレイヤーで使われるベクターストアおよびグラフバックエンドです。

長期間のセッション履歴が蓄積されるプロジェクトでは、SQLiteだけでなくPostgresやRuVectorの利用を検討します。

MCPレイヤーをテスト対象にする理由

RufloのMCPサーバーは、Claude CodeとRufloを接続する重要なインターフェースです。

スウォーム生成、メモリ書き込み、フェデレーションのハンドオフは、ローカルMCPサーバーへのJSON-RPC呼び出しとして扱えます。

代表的な呼び出しは次の通りです。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
Enter fullscreen mode Exit fullscreen mode

tools/listに回帰があると、Claude CodeはRufloのツールを認識できません。結果として、チームは気づかないままシングルエージェントモードに戻る可能性があります。

memory_storeのレスポンス形式が壊れると、エージェントが誤った文脈を使う原因になります。

このため、Ruflo MCPサーバーは普通のJSON-RPC APIとして扱い、契約テストを用意するべきです。これはMCPサーバーテストプレイブックで扱った考え方と同じです。

ApidogでRuflo MCPサーバーをテストする手順

ここでは、最小構成のテストプランを作ります。

ステップ1：Rufloを初期化する

まず、検証用プロジェクトでRufloを初期化します。

mkdir ruflo-mcp-test
cd ruflo-mcp-test
npx ruvflo init
Enter fullscreen mode Exit fullscreen mode

Claude Codeを起動し、Ruflo有効状態で代表的なタスクをいくつか実行します。

例：

このリポジトリのテスト戦略をレビューして
セキュリティ観点でAPI実装を確認して
この関数をリファクタリングして
Enter fullscreen mode Exit fullscreen mode

ステップ2：MCPフレームをキャプチャする

Claude CodeのMCPインスペクターで、以下のJSON-RPCフレームを保存します。

  • initialize
  • tools/list
  • tools/call with swarm_init
  • tools/call with memory_store
  • tools/call with memory_get

ステップ3：Apidogにリクエストを登録する

Apidogで新しいプロジェクトを作成します。

設定例：

Project: Ruflo MCP Tests
Base URL: local Ruflo MCP server endpoint
Protocol: JSON-RPC over HTTP / local endpoint
Enter fullscreen mode Exit fullscreen mode

キャプチャしたJSON-RPCボディをそれぞれリクエストとして保存します。

例：tools/list

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
Enter fullscreen mode Exit fullscreen mode

ステップ4：アサーションを追加する

最低限、以下を検証します。

initialize 

result.serverInfo.name == "ruflo"
Enter fullscreen mode Exit fullscreen mode

プロトコルバージョンも、チームでサポートする値と一致するか確認します。

tools/list

確認ポイント：

result.tools.length >= 100
Enter fullscreen mode Exit fullscreen mode

各ツールに以下が存在することも検証します。

name
description
inputSchema
Enter fullscreen mode Exit fullscreen mode

tools/call with swarm_init

レスポンスにスウォームIDが含まれ、エラーではないことを確認します。

期待例：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "swarmId": "..."
  }
}
Enter fullscreen mode Exit fullscreen mode

tools/call with memory_store

書き込み成功後、同じキーをmemory_getで取得できることを検証します。

流れ：

memory_store -> success
memory_get   -> same key returns value
Enter fullscreen mode Exit fullscreen mode

ステップ5：LLMプロバイダーをモックする

Rufloはエージェント判断のためにClaudeや設定済みプロバイダーを呼び出します。しかし、CIで毎回実プロバイダーを叩くとコストと不安定性が増えます。

そこで、ApidogでOpenAI互換エンドポイントをモックします。

テスト時の構成：

Ruflo provider config
        |
        v
Apidog mock endpoint
        |
        v
固定レスポンス
Enter fullscreen mode Exit fullscreen mode

このパターンは、PostmanなしのAPIテストで説明したワークフローと同じです。

ステップ6：CIで実行する

ApidogのCLIランナーをCIに組み込みます。

GitHub Actionsのイメージ例：

name: Ruflo MCP Tests

on:
  pull_request:
  push:
    branches:
      - main

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

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Initialize Ruflo
        run: npx ruvflo init

      - name: Run Apidog tests
        run: apidog run
Enter fullscreen mode Exit fullscreen mode

アサーションに失敗したら非ゼロ終了にし、Ruflo更新や設定変更によるMCPインターフェース破壊をPR段階で検知します。

Apidogを日常運用で使う場面

CI以外でも、ApidogはRuflo運用で役立ちます。

スウォームの挙動がおかしいとき

Claude Codeが送信したtools/callのシーケンスをApidogでリプレイします。

確認する差分：

  • 前回成功時と引数が違うか
  • ツール名が変わっていないか
  • inputSchemaと実引数がずれていないか
  • メモリ取得結果が変化していないか

Apidog request debugging

Rufloをアップグレードするとき

Rufloの新バージョンでは、ツールサーフェスが変わることがあります。

アップグレード前後で確認する項目：

tools/list
tool names
inputSchema
response schema
error shape
Enter fullscreen mode Exit fullscreen mode

このワークフローは、契約優先のAPI開発と同じです。

フェデレーションが不安定なとき

フェデレーションは暗号化チャネルで通信します。ハンドシェイクや転送失敗は、ログなしでは追いにくいです。

Apidogをローカルプロキシや記録用エンドポイントに向け、連携トラフィックを記録します。

見るべきポイント：

  • 接続開始
  • 認証またはハンドシェイク
  • ペイロード送信
  • 応答コード
  • タイムアウト
  • リトライ

よくある落とし穴

プラグイン版だけを入れて完全機能を期待する

Claude Codeプラグイン版はスラッシュコマンド中心です。

swarm_initやmemory_storeがClaudeから呼び出せない場合、完全版ではなく軽量版を入れている可能性があります。

完全版を使うには次を実行します。

npx ruvflo init
Enter fullscreen mode Exit fullscreen mode

フックレイヤーを無効化する

CLIインストールでは、タスクを自動ルーティングするフックが入ります。

これを削除または上書きすると、Rufloのルーターやスウォーム連携が期待通りに動かなくなります。明確な理由がない限り、デフォルト設定を維持してください。

メモリを無制限に増やす

メモリストアは永続化されます。長期間使うと、メモリ検索が遅くなる可能性があります。

運用時は以下を決めます。

  • 保持期間
  • 最大サイズ
  • アーカイブ方法
  • SQLite / Postgres / RuVectorの使い分け

Claude専用ツールだと思い込む

Rufloはプロバイダー非依存です。Claudeがデフォルトですが、用途に応じて他のプロバイダーも使えます。

例：

  • コスト重視：DeepSeek
  • 汎用モデル：OpenAI / Gemini
  • オフライン実行：Ollamaなどのローカルモデル

DeepSeekの設定はDeepSeek V4 APIガイド、ローカルモデルの選定は2026年のベストローカルLLMの記事も参考になります。

フェデレーションの信頼境界を曖昧にする

別マシンへ連携する場合、コードや設計情報を含むペイロードが外部エンドポイントへ送られる可能性があります。

有効化前に、少なくとも以下を定義してください。

  • どのリポジトリを連携対象にするか
  • どの組織・マシンと連携できるか
  • シークレットを送信前に除去する方法
  • 監査ログの確認頻度

Rufloと他フレームワークの使い分け

LangGraph

LangGraphはより低レベルで汎用的です。オーケストレーションを自分で設計したい場合に向いています。

Claude Code中心ではないワークフローや、独自の状態遷移を細かく制御したい場合はLangGraphが適しています。

LangGraphについては、TradingAgentsに関する記事でも触れています。

CrewAI

CrewAIはマルチエージェント向けで、Claude Codeに依存しません。Python中心のワークフローや、Claude Code外でエージェントシステムを組む場合に向いています。

MCPサーバーを手動で組み合わせる

MCPサーバーを自分で複数組み合わせる方法もあります。

少数なら軽量ですが、サーバー数が増えると以下が難しくなります。

  • ツールの命名管理
  • メモリ共有
  • ルーティング
  • エージェント間連携
  • 回帰テスト

Rufloの強みは、「Claude Codeにスウォーム機能を追加する」ことにあります。日常の開発ツールがClaude Codeで、MCPボイラープレートを大量に書かずに連携機能を使いたいなら、検討する価値があります。

パフォーマンスとスケーリング

短いタスクではスウォームのオーバーヘッドに注意する

スウォーム生成には、ルーター判断やツール登録のために数秒程度の固定コストがかかります。

1行修正のようなタスクでは、このオーバーヘッドが大きくなります。

そのため、短いタスクはシングルエージェント、大きなレビューやリファクタリングはスウォーム、というルーティングが望ましいです。必要に応じてフック設定のしきい値を調整します。

メモリストアは成長に合わせて切り替える

小規模ならSQLiteで十分です。

ただし、セッション数が増えた場合はPostgresやRuVectorを検討します。

目安：

個人利用 / 小規模検証 -> SQLite
チーム利用 / 長期履歴 -> Postgres
セマンティック検索重視 -> RuVector
Enter fullscreen mode Exit fullscreen mode

運用チームの報告では、長期履歴を持つ環境でPostgresに切り替えることで、メモリクエリの中央値が大きく改善したケースがあります。

実際のユースケース

セキュリティレビューとリファクタリングの並列実行

あるプラットフォームチームは、Rufloのフェデレーションレイヤーを使い、一方のリポジトリではセキュリティレビュー、もう一方ではリファクタリングスウォームを実行しています。

結果は共有メモリを通じて連携し、矛盾する推奨事項を人間のレビュー担当者に提示します。

Linearチケットの夜間処理

個人開発者は、RufloのオートパイロットをLinearチケットキューに接続しています。

流れ：

P3チケットを選ぶ
-> ブランチを作る
-> 修正案を実装する
-> PRを作成する
-> 次のチケットへ進む
Enter fullscreen mode Exit fullscreen mode

夜間にオートパイロットを実行し、朝に人間がレビューします。

複数リポジトリのPR品質評価

研究グループは、Rufloのマルチエージェントコードレビューを使い、複数リポジトリにわたるPR品質を評価しています。

人間レビューを置き換えるのではなく、レビュー観点を増やし、見落としを減らす目的で使っています。

まとめ

Rufloは、Claude Codeを単一エージェントからスウォーム型のコーディング基盤へ拡張するための実用的なレイヤーです。

重要なポイントは次の5つです。

  • RufloはClaude Codeに永続メモリ、スウォーム、フェデレーションを追加します。
  • 軽く試すならプラグイン版、本格運用ならnpx ruvflo initによるCLIインストールを使います。
  • Ruflo MCPサーバーは契約インターフェースです。JSON-RPC APIとしてテストしてください。
  • ApidogでMCPリクエストを保存し、アサーションを追加し、CIで実行できます。
  • CIではLLMプロバイダーをApidogでモックすると、コストと不安定性を抑えられます。

次にやることはシンプルです。

mkdir ruflo-test
cd ruflo-test
npx ruvflo init
Enter fullscreen mode Exit fullscreen mode

その後、Claude CodeのMCPインスペクターで標準フレームをキャプチャし、Apidogプロジェクトに貼り付けてください。最初に検知したMCP回帰だけで、テスト環境を作る価値は十分にあります。

よくある質問

Rufloはclaude-flowと同じですか？

はい。RufloはrUvによってメンテナンスされている、名称変更されたclaude-flowです。npmパッケージはruvflo、GitHubリポジトリはruvnet/rufloです。既存のclaude-flow設定は引き続き機能します。

プラグインとCLIインストールの両方が必要ですか？

いいえ。どちらか一方を選びます。

  • プラグイン：スラッシュコマンド中心
  • CLIインストール：完全な連携レイヤー

ほとんどのチームにはCLIインストールが向いています。

ClaudeなしでRufloを使えますか？

はい。Rufloはプロバイダー非依存です。設定によりDeepSeek、OpenAI、Gemini、ローカルモデルなどを利用できます。Claudeはデフォルトの選択肢です。

メモリはどこに保存されますか？

設定に応じて、ローカルSQLiteまたはPostgresに保存されます。オプションのRuVectorバックエンドを使うと、セマンティック検索向けのベクトル検索機能を追加できます。

明示的に設定しない限り、メモリがサードパーティサービスに送信されることはありません。

CIでMCPサーバーをテストするには？

MCPインスペクターで標準リクエストをキャプチャし、Apidogに貼り付け、JSONPathアサーションを追加します。

その後、CIで次のように実行します。

apidog run
Enter fullscreen mode Exit fullscreen mode

詳細なパターンはMCPサーバーテストプレイブックを参照してください。

組織をまたぐフェデレーションは安全ですか？

暗号化レイヤーは用意されています。ただし、ポリシー設計は利用者側の責任です。

最低限、次を運用ルールにしてください。

  • 連携可能なプロジェクトを制限する
  • シークレットを送信前に除去する
  • 監査ログを確認する
  • 信頼できるマシンだけを連携対象にする

費用はどれくらいですか？

Ruflo自体はMITライセンスで無料です。主な費用は以下です。

  • LLMトークン
  • ホスト型ベクターストア
  • 外部プロバイダー利用料

CIでは実プロバイダーを呼ばず、Apidogのモックを使うとコストを抑えられます。

Top comments (0)