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배 빠름
• 머신 간 연합(federated) 협업: 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 엔트리(ru f lo 명령)
│   └── mcp-server.js       # MCP 서버
│
├── v3/@claude-flow/        # 핵심 모듈 패키지
│   ├── cli/                # 26개의 최상위 명령(140+ 하위 명령)
│   ├── memory/             # AgentDB + HNSW 벡터 검색
│   ├── swarm/              # 통합 코디네이터(15-Agent hierarchical mesh)
│   ├── security/           # CVE 수정, 입력 검증, 경로 보안
│   ├── neural/             # SONA 자기학습 모듈
│   ├── hooks/              # 17개의 Hook + 12개의 백그라운드 Worker
│   ├── 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단계: 원클릭 설치

한 줄 명령으로 초기화가 완료되며, 안내형 설정 마법사를 포함합니다:

npx ruflo@latest init --wizard

이 명령은 순서대로 다음을 수행합니다:

1. 현재 디렉터리에 CLAUDE.md를 생성하고 Hooks 라우팅 규칙을 기록
2. Claude Code 설정에 MCP 서버를 등록
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로 미들웨어 구성, refresh token은 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

# 원클릭 진단(노드 버전, 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는 최소 1개의 LLM 제공자 API Key가 필요합니다:

# 임시 설정(현재 세션에서만 유효)
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 등 멀티 provider 지원
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 안의 모든 key 나열
npx ruflo memory list --namespace patterns

# 이미 알고 있는 key를 직접 retrieve
npx ruflo memory retrieve --key "pattern-auth-service"

# 빈 저장소라면 먼저 하나 저장해보세요
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 서명 검증으로 상대의 신원을 확인합니다. 악의적 행위는 자동으로 신뢰 강등을 유발하며, 사람이 개입할 필요가 없습니다.

---

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 스킬이 있으며, 그대로 가져다 쓸 수 있습니다.