Claude Code에 에이전트 팀 붙이는 Ruflo 입문 가이드
공식 GitHub 저장소: https://github.com/ruvnet/ruflo
공식 npm 패키지: https://www.npmjs.com/package/ruflo
Quick Start
Ruflo는 Claude Code 바깥에 에이전트 조정, 메모리, 작업 라우팅을 붙이는 오픈소스 도구입니다. 일단 새 연습 폴더에서 설치하고 Claude Code를 켜보세요.
mkdir ruflo-starter
cd ruflo-starter
npx ruflo@latest init wizard
npx ruflo@latest doctor
claude
Claude Code가 열리면 아래 프롬프트에서 <...> 부분만 여러분 상황에 맞게 바꿔 그대로 붙여넣습니다.
역할: Ruflo 계층형 스웜의 코디네이터로서 researcher, coder, tester, reviewer 역할을 조정해 주세요.
맥락: <프로젝트 상황 한 줄 — 예: 빈 연습 폴더 / 이미 있는 Node 프로젝트>
입력: <기술 스택 — 예: Node.js + Express>, <만들 기능 한 줄 — 예: 이메일 로그인>
작업: 먼저 애매한 점이 있으면 질문으로 확인하고, 작업을 조사·구현·테스트·리뷰로 나눈 계획을 짧게 보여준 뒤 구현해 주세요.
제약: 에이전트는 최대 8개만 쓰고, <수정하면 안 되는 파일·규칙 — 예: 기존 테스트 깨지 않기>를 지켜 주세요.
출력: 바뀐 파일 목록, 실행한 테스트·빌드·린트 결과, 남은 위험을 정리해 주세요.
검증: 리뷰 역할이 코드를 점검하고, 테스트·빌드·린트를 실제로 실행한 로그를 근거로 보여 주세요.
설치가 끝나면 .claude/, .claude-flow/, CLAUDE.md 같은 파일이 생깁니다. Ruflo가 역할을 나누고 지난 작업을 기억하는 데 쓰는 프로젝트 설정입니다.
STEP 1. 실행 환경 확인: 2분
Node.js 20 이상, npm 9 이상, Claude Code가 필요합니다. 먼저 버전을 확인하세요.
node --version
npm --version
claude --version
node --version이 v20보다 낮거나 Claude Code 명령을 찾지 못하면 아래 순서로 준비합니다.
npm install -g @anthropic-ai/claude-code
claude --version
확인 방법은 간단합니다. 세 명령이 오류 없이 버전 번호를 출력하면 다음 단계로 넘어갑니다.
용어: 에이전트는 모델 자체가 아니라, 모델에 역할과 도구, 메모리, 실행 규칙을 묶은 작업 단위입니다.
STEP 2. 전체 기능으로 초기화: 5분
Ruflo에는 플러그인 설치와 CLI 초기화, 두 경로가 있습니다. 플러그인만 설치하면 슬래시 명령과 일부 역할은 쓸 수 있지만 MCP 서버와 훅, 프로젝트 메모리는 붙지 않습니다. 처음이라면 CLI 초기화를 추천합니다.
기존 프로젝트에 붙일 때는 초기화 전에 변경 사항부터 확인하세요. Ruflo가 프로젝트 설정 파일을 추가하기 때문입니다.
git status --short
npx ruflo@latest init wizard
대화형 설정이 부담스럽다면 기본 초기화도 됩니다.
npx ruflo@latest init
초기화 여부와 상태를 확인합니다.
npx ruflo@latest init check
npx ruflo@latest doctor
init check가 초기화된 프로젝트라고 표시하고 doctor의 핵심 검사에 오류가 없으면 설치가 끝난 겁니다.
STEP 3. Claude Code에 MCP 연결: 2분
용어: MCP는 Claude Code가 Ruflo의 스웜, 에이전트, 메모리 도구를 호출하게 해주는 연결 규격입니다.
먼저 등록 상태를 확인합니다.
claude mcp list
목록에 ruflo가 없다면 한 번만 등록하세요.
claude mcp add ruflo -- npx -y ruflo@latest mcp start
claude mcp list
두 번째 명령의 목록에 ruflo가 보이면 연결된 겁니다. 플러그인만 설치한 경우에는 이 연결이 자동으로 생기지 않을 수 있습니다.
STEP 4. 작은 팀부터 시작: 3분
100개 역할을 한꺼번에 띄우지 마세요. 공식 안티 드리프트 예시는 계층형 구조에 최대 8개 에이전트를 권장합니다. 코디네이터 하나가 작업을 나누고 결과를 모으는 방식입니다.
npx ruflo@latest swarm init \
--topology hierarchical \
--max-agents 8 \
--strategy specialized
npx ruflo@latest swarm status
npx ruflo@latest agent list
swarm status가 계층형 스웜을 보여주면 준비됐습니다. 이 구조를 공식 문서에서는 Queen-led hierarchy라고도 설명합니다. Queen은 모든 일을 직접 하는 모델이 아니라 연구, 코딩, 테스트, 리뷰 역할을 조정하는 코디네이터입니다.
STEP 5. 실제 작업을 맡기기: 10분 이상
Claude Code를 프로젝트 루트에서 열고 아래 프롬프트의 <기능>만 바꿔 붙여넣으세요.
이 저장소에 <기능>을 구현해 주세요.
진행 방식:
- 먼저 관련 코드와 기존 테스트를 조사합니다.
- 계층형 스웜에서 researcher, coder, tester, reviewer 역할만 사용합니다.
- 구현 전에 변경 범위와 검증 기준을 짧게 보여 주세요.
- 구현 뒤 실제 테스트와 린트를 실행합니다.
- 실패하면 원인을 고친 뒤 다시 검증합니다.
- 마지막에는 바뀐 파일, 테스트 결과, 남은 위험만 알려 주세요.
좋은 요청은 역할 이름보다 완료 기준이 선명합니다. “로그인 기능을 만들어 줘”보다 “이메일 로그인, 잘못된 비밀번호 오류, 단위 테스트까지”처럼 결과를 적어주세요.
확인은 에이전트 숫자가 아니라 결과로 합니다.
npx ruflo@latest swarm status
npx ruflo@latest agent list
그다음 Claude Code가 보고한 테스트 명령을 직접 한 번 더 실행하고 git diff로 변경 범위를 확인하세요.
STEP 6. 성공 패턴을 메모리에 남기기: 3분
Ruflo의 훅은 성공한 작업 패턴을 다음 요청에 다시 꺼내 쓰도록 설계되어 있습니다. 팀 규칙 하나를 직접 저장하고 검색해보면 연결 상태를 바로 확인할 수 있습니다.
npx ruflo@latest memory store \
--key "project/test-rule" \
--value "기능 변경 뒤 단위 테스트와 린트를 모두 실행한다" \
--namespace "project"
npx ruflo@latest memory search \
--query "기능 변경 뒤 검증" \
--namespace "project"
검색 결과에 방금 저장한 규칙이 나타나면 메모리가 동작하는 겁니다. 비밀번호, API 키, 고객 정보는 메모리에 넣지 마세요.
STEP 7. “100명 무료 고용”을 정확히 이해하기: 2분
공식 GitHub는 Ruflo를 100개가 넘는 전문 에이전트 카탈로그로 소개합니다. 이 숫자는 매 작업마다 모델 프로세스 100개가 동시에 실행된다는 뜻이 아닙니다. 현재 CLI 도움말도 기본 초기화는 약 24개 핵심 에이전트, --all-agents는 약 89개 전체 세트로 안내합니다. 정확한 구성은 릴리스마다 달라질 수 있습니다.
Ruflo 코드와 CLI는 MIT 라이선스입니다. 하지만 Claude Code 구독료, 외부 모델 API 사용료, 실행 장비 비용까지 무료가 되는 건 아닙니다.
공식 문서에는 토큰 사용량을 3050% 줄이거나 Claude Code 사용량을 250%까지 늘릴 수 있다는 설명이 있습니다. 이건 WASM 변환, 캐시, 저비용 모델 라우팅이 잘 맞았을 때의 프로젝트 측 설명이지 개인 환경에서 보장되는 수치가 아닙니다. 처음에는 에이전트 48개로 시작하고 실제 사용량을 확인하세요.
STEP 8. 설치 직전 최신값 확인: 1분
Ruflo는 업데이트가 잦습니다. 블로그에 적힌 버전보다 npm 레지스트리를 기준으로 확인하세요.
npm view ruflo@latest version engines license --json
npx --yes ruflo@latest --version
engines.node가 현재 Node.js 버전과 맞고 라이선스가 MIT인지 확인합니다. 아래 이미지는 조회 흐름 예시라 버전 번호는 실제 실행 결과와 다를 수 있습니다.
STEP 9. 내 프로젝트에 안전하게 적용: 3분
연습 폴더에서 한 번 성공한 뒤 실제 프로젝트에 붙이세요.
- 초기화 전
git status --short로 작업 중인 파일을 확인합니다. - 첫 스웜은 최대 4~8개 에이전트로 제한합니다.
- 프롬프트에 수정 가능한 경로와 완료 기준을 적습니다.
- 실행 뒤 테스트 결과와
git diff를 직접 확인합니다. .env, API 키, 고객 데이터는 프롬프트와 메모리에 넣지 않습니다.
문제가 생기면 자동 수정부터 누르지 말고 진단 결과를 먼저 봅니다.
npx ruflo@latest doctor
npx ruflo@latest doctor --fix
doctor --fix는 현재 CLI 기준으로 수정 명령을 출력할 뿐 자동 적용하지 않습니다. 제안된 명령을 읽고 필요한 것만 직접 실행하세요.
FAQ
node 버전이 낮다고 나옵니다
원인은 Ruflo가 Node.js 20 이상을 요구하기 때문입니다. Node.js를 20 이상으로 올린 뒤 터미널을 다시 열고 node --version을 확인하세요.
Windows에서 bash를 찾지 못합니다
curl | bash 설치법 대신 PowerShell이나 cmd에서 아래 명령을 쓰면 됩니다.
npx ruflo@latest init wizard
Claude Code에서 Ruflo 도구가 안 보입니다
플러그인만 설치했거나 MCP 등록이 빠졌을 가능성이 큽니다.
claude mcp add ruflo -- npx -y ruflo@latest mcp start
claude mcp list
초기화 뒤 파일이 많이 생겼습니다
정상입니다. 전체 CLI 초기화는 .claude/, .claude-flow/, CLAUDE.md와 관련 설정을 프로젝트에 추가합니다. 필요 없는 파일을 손으로 먼저 지우지 말고 git diff에서 무엇이 생겼는지 확인하세요.
에이전트를 많이 띄울수록 결과가 좋아지나요
아닙니다. 역할이 겹치면 조정 비용과 모델 사용량이 함께 늘어납니다. 작은 기능은 researcher, coder, tester, reviewer 정도로 시작하세요. 부족할 때만 역할을 추가하면 됩니다.
“무료”인데 왜 사용량이 줄어드나요
Ruflo 자체가 MIT 오픈소스라는 뜻입니다. 실제 추론은 Claude Code 구독이나 연결한 모델 API를 사용하므로 그쪽 한도와 비용은 그대로 적용됩니다.