Ruflo 入門：自己進化するマルチエージェント協働エンジン

プロジェクト概要

Ruflo は Claude Code 向けのマルチエージェント・オーケストレーション（編成）レイヤーです。やっていることを一言でまとめると、Claude Code を「質問・回答のアシスタント」から、「協働できて、記憶できて、自己進化できる」AI チームへ変えること。

Ruflo は当初「Claude Flow」と呼ばれ、RuvNet によって開発されました（創業者に Rust のバックグラウンドがあり、名前は Ruv + flow のイメージを組み合わせています）。基盤には Rust で書かれた WASM コアがあり、戦略エンジン、ベクトル埋め込み、証明システムを担当しており、高性能を担保しています。最新の安定版 [email protected] は、すでに完全なエンタープライズ級プロダクトです：

• 300+ の MCP ツール を直接 Claude Code に注入
• 60+ 種類の専門 Agent（coder、tester、architect、security-architect……）
• 学習するメモリ：AgentDB + HNSW ベクトルインデックスで、検索はブルートフォースの 150 倍～12,500 倍高速
• マルチマシンのフェデレーテッド協働：Agent Federation。mTLS + ed25519 によるゼロトラストな安全通信
• 自己進化能力：SONA ニューラル学習モジュール。過去の軌跡からパターンを抽出し、継続的に最適化
• 32 個のプラグイン：セキュリティ、コスト追跡、ブラウザ自動化、GitHub 連携などをカバー

その設計思想が面白い——インストールしてしまえば、300 個の MCP ツールを学ぶ必要がありません。Hooks のルーティング層がタスクを適切な Agent に自動で振り分けます。あなたはコードを書き続ければ、Ruflo が裏側で全てを調整します。

難易度 / 所要時間 / 得られること

• 難易度：★★☆☆☆（インストール 5 分で起動可能）
• 所要時間：約 20 分
• 得られること：swarm のトポロジーとライフサイクル管理を理解、HNSW によるベクトル記憶の仕組みを学ぶ、Agent 同士が SendMessage で通信できるようになる

対象読者

• 1〜5 年の開発経験がある人
• AI を「チャットツール」から「仕事をするチーム」にしたい人
• Claude Code を使っている（または使う予定の）個人開発者、もしくは小規模チーム

必須の依存関係と環境

完全なプロジェクト構造ツリー

ruflo/
├── bin/
│   ├── cli.js              # CLI エントリ（ruflo コマンド）
│   └── mcp-server.js       # MCP サーバー
│
├── v3/@claude-flow/        # コアモジュールパッケージ
│   ├── cli/                # トップレベルコマンド 26 個（140+ サブコマンド）
│   ├── memory/             # AgentDB + HNSW ベクトル検索
│   ├── swarm/              # 統一コーディネータ（15-Agent 階層メッシュ）
│   ├── security/           # CVE 修復、入力検証、パス安全性
│   ├── neural/             # SONA 自己学習モジュール
│   ├── hooks/              # Hook 17 個 + バックグラウンド Worker 12 個
│   ├── guidance/           # ガバナンス制御プレーン（compile/enforce/prove/evolve）
│   └── shared/             # 型、イベント、コアインターフェース
│
├── plugins/                # 32 個の公式プラグイン
│   ├── ruflo-core/         # 基盤（サーバー、ヘルスチェック、プラグイン検出）
│   ├── ruflo-swarm/        # マルチ Agent チームの協調
│   ├── ruflo-federation/   # マルチマシン間の安全な協働
│   ├── ruflo-agentdb/      # ベクトルデータベースの記憶
│   ├── ruflo-intelligence/ # 自己学習ニューラルパターン
│   └── ...                 # その他 27 個のプラグイン
│
├── .claude/                # Claude Code 設定（MCP サーバー、settings.json）
├── .agents/                # Agent スキル定義（$skill-name 構文）
└── mcp/                    # MCP ツール定義（agent-tools.ts、memory-tools.ts など）

手順どおり実践

ステップ 1：一括インストール

1 行のコマンドで初期化でき、ガイド付き設定ウィザードも付きます：

npx ruflo@latest init --wizard

このコマンドは次の処理を順に行います：

1. 現在のディレクトリに CLAUDE.md を生成し、Hooks のルーティングルールを書き込む
2. MCP サーバーを Claude Code の設定に登録
3. .claude-flow/ 配下にデフォルト設定とメモリのシードファイルを書き込む

初めてのインストールの場合は、「full」を選んで、利用可能なオプションモジュールをすべて入れてください。

---

ステップ 2：MCP サービスの登録

前のステップで MCP が自動登録されなかった場合は、手動で追加します：

claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

登録できたか確認：

claude mcp list
# 期待される出力例：
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

ステップ 3：最初の Swarm（hierarchical + 5 Agent）を初期化

npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn --type architect --name arch-1
npx ruflo agent spawn --type coder --name coder-1
npx ruflo agent spawn --type coder --name coder-2
npx ruflo agent spawn --type tester --name tester-1
npx ruflo agent spawn --type reviewer --name reviewer-1

---

ステップ 4：Agent 間で SendMessage を使って通信させる

これが Ruflo の最重要な設計です——名前付きの Agent 同士が SendMessage でリアルタイム通信し、ポーリングや共有メモリープールは不要です：

// Claude Code の Task tool で使用：
Task({
  prompt: "REST API の設計案を作成してください。完了したら SendMessage で 'coder-1' に設計案を送ってください。",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "arch-1 から届く設計案を待ってください。実装できたら SendMessage で 'tester-1' にコードのパスを報告してください。",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "coder-1 から届くコードを待ってください。統合テストを書いてください。完了したら SendMessage で 'reviewer-1' に結果を報告してください。",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// パイプラインを起動——最初の Agent にメッセージを送る
SendMessage({
  to: "arch-1",
  summary: "API 設計を開始",
  message: "ユーザ管理の CRUD REST API を設計してください（追加・削除・変更・取得を含む）。設計できたら coder-1 に送ってください。"
})

パイプラインの流れ：arch-1 → coder-1 → tester-1 → reviewer-1。各 Agent は次に誰へ送ればよいかを知っています。

---

ステップ 5：最初の記憶を保存（AgentDB + HNSW）

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "JWT 認証：Bearer Token。express-jwt をミドルウェアとして使用し、リフレッシュトークンは Redis に保存。6 時間で期限切れ" \
  --namespace patterns

保存された内容は自動的にベクトル埋め込みを生成し、AgentDB に格納されて、以降のセマンティック検索に利用されます。

---

ステップ 6：セマンティック検索で記憶を検証

npx ruflo memory search --query "authentication patterns" --namespace patterns

出力には一致したエントリと類似度スコア（0〜1、値が大きいほど関連性が高い）が表示されます。スコアが > 0.7 なら強く一致しているので、そのまま使えます。

---

ステップ 7：バックグラウンド Daemon を起動し、ヘルス診断を実行

# バックグラウンドの常駐プロセスを起動（12 個の自動 Worker が動き始める）
npx ruflo daemon start

# まとめて診断（Node バージョン、API Key、MCP 接続、ディスク空き）
npx ruflo doctor --fix

doctor --fix は、修正できる問題を自動で直します（例：依存関係の欠落）。そしてターミナルに完全なヘルスレポートを出力します。

---

ステップ 8：プラグインを（必要に応じて）インストール

プラグインの導入はとても簡単です。必要な機能に合わせて選んでください：

# プラグインマーケットを追加
/plugin marketplace add ruvnet/ruflo

# フェデレーション協働プラグイン（マルチマシン Agent 通信）
/plugin install ruflo-federation@ruflo

# 自己学習プラグイン（SONA ニューラルモード）
/plugin install ruflo-intelligence@ruflo

# セキュリティ監査プラグイン
/plugin install ruflo-security-audit@ruflo

# コスト追跡プラグイン
/plugin install ruflo-cost-tracker@ruflo

または CLI で：

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # 利用可能なプラグインを表示

---

ステップ 9：上級——自己進化能力（SONA）を呼び出す

# SONA に最近の成功事例からパターンを抽出させ、学習させる
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# 現在学習しているパターンを確認
npx ruflo neural patterns

# ルーティング層にスマートルーティングを使わせる（89% 精度）
npx ruflo hooks route --task "API ミドルウェアを書いて"

SONA はバックグラウンドで 4 ステージのパイプラインを実行します：RETRIEVE（HNSW）→ JUDGE（成功/失敗の判定）→ DISTILL（LoRA 蒸留）→ CONSOLIDATE（EWC++ による壊滅的忘却の防止）。

---

よくある問題のトラブルシューティング

1. MCP 接続に失敗：claude mcp list で ruflo が disabled と表示される

通常は Node バージョンの問題、またはポートが使用中になっていることが原因です：

# Node バージョンを確認
node -v  # 必ず ≥20.0.0

# MCP サービスを手動で再起動
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# ポート使用状況の確認
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. API Key が未設定で ANTHROPIC_API_KEY is not set が出る

Ruflo には、少なくとも LLM プロバイダの API Key が 1 つ必要です：

# 一時的に設定（この session のみ有効）
export ANTHROPIC_API_KEY=sk-ant-xxxx

# 永久に ~/.bashrc もしくは ~/.zshrc に書き込む
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# または設定ファイル（init --wizard が .env への書き込みをガイド）
# Claude / GPT / Gemini / Ollama など複数プロバイダに対応
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # 接続テスト

---

3. Node バージョンが要件を満たしていない：ruflo: requires Node.js >=20.0.0

# 方法 1：nvm でアップグレード
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# 方法 2：Windows では nvm-windows を使う
# インストーラ：https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# 確認
node -v  # v20.x.x が表示されるはずです

---

4. memory search で結果が出ない

原因として、ネームスペースの記載ミス、またはメモリがまだ保存されていないことが考えられます：

# 現在の全ネームスペースを確認
npx ruflo memory list --namespace

# patterns 内の全キーを表示
npx ruflo memory list --namespace patterns

# 既知のキーを直接 retrieve
npx ruflo memory retrieve --key "pattern-auth-service"

# 空のデータベースなら、まず 1 件保存して試す
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. swarm 起動後、すべての Agent が idle のまま

これはタスクがまだ配信されていないことを示します。次を確認してください：

# すべての Agent の状態を確認
npx ruflo agent list

# swarm が初期化されているか確認
npx ruflo swarm status

# Claude Code の Task tool で起動した場合は、開始メッセージを送っているか確認
# SendMessage({ to: "arch-1", message: "仕事を開始" })
# SendMessage がないと、最初の Agent は自動では起動しません

---

6. ruflo doctor が MongoDB not running を報告

Docker Compose で起動する場合（ruflo/src/ruvocal/）は MongoDB が必要です：

# 方法 1：Docker で依存関係一式を起動
cd ruflo/src/ruvocal
docker compose up -d

# 方法 2：ruflo 内蔵のスタンドアロンモード（MongoDB 不要）
npx ruflo start --mode standalone
# standalone モードでは sql.js (WASM) が MongoDB の代わりになり、完全にオフラインで利用できます

---

追加の読み物 / 進行方向

1. Agent Federation——マルチマシン間のゼロトラスト協働

最もクールな機能の一つです。別マシン上の Agent 同士を協働させると、PII は自動でフィルタされてから送信されます：

npx ruflo federation init
npx ruflo federation join wss://other-team.example.com:8443
npx ruflo federation send --to team-b --type task-request --message "取引パターンを分析"

アーキテクチャの詳細：各アウトバウンドメッセージは 14 種類の PII 検出を通過し、BLOCK / REDACT / HASH / PASS の 4 段階ポリシーを適用した後、mTLS + ed25519 の署名検証で相手の身元を確認します。悪意のある挙動は自動的に信頼を引き下げる（trust downgrade）ため、人手による介入は不要です。

2. RuVector HNSW ベクトル検索の原理

単純なキーワードマッチではありません。テキストを 384 次元のベクトルに符号化し、ベクトル空間上で HNSW（Hierarchical Navigable Small World）アルゴリズムにより近傍のノードを探索します。毎回 memory store では埋め込みが自動生成され、毎回 memory search では余弦類似度で結果を並べ替えます。

3. 32 プラグイン・エコシステム早見表

4. オンライン体験（インストール不要）

• マルチモデルチャット UI：https://flo.ruv.io/ — Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro に対応し、オンラインで MCP ツールを並列呼び出し可能
• 目標計画 UI：https://goal.ruv.io/ — 「Auth をリファクタしてテストを書いて動かす」を GOAP A* のパスに分解
• Live Agent ダッシュボード：https://goal.ruv.io/agents — 各 Agent の状態、メモリのネームスペース、トークン予算をリアルタイムに確認

5. 公式ドキュメント索引

6. Discord コミュニティ

困ったときや、自分で作った Skills を共有したいときは？RuvNet は Agentics Foundation Discord で活発なコミュニティを運営しています：

https://discord.com/invite/dfxmpwkG2D

中には、ユーザーが自作した $skill-name のスキルが大量にあり、そのまま使えます。