Ruflo 설치·사용법: Claude Code 멀티 에이전트와 실전 프롬프트

Ruflo는 여러 AI 에이전트의 역할과 작업 순서, 공유 메모리를 조율하는 오픈소스 도구입니다. Claude Code와 연결해 개발·테스트·리뷰를 나누어 맡기는 작업 흐름을 구성할 수 있습니다. 예전 이름인 Claude Flow가 설정이나 문서에 남아 있기도 합니다. Ruflo 공식 프로젝트

Claude Code에 기능을 부탁했는데, 코드는 생겼지만 테스트가 빠져 있던 적 있나요? “오류 상황도 확인해줘”, “기존 기능은 괜찮아?”를 하나씩 덧붙이다 보면 내가 계속 작업을 배분하고 있다는 느낌이 듭니다.

쇼츠에서 소개한 “AI 개발팀”을 직접 써보고 싶다면, 처음에는 기능 개발보다 프로젝트 분석부터 시작하세요. 이 글에서는 설치 명령어부터 분석·기능 추가·버그 수정·코드 리뷰 프롬프트, 결과를 검증하는 코드 예제까지 순서대로 살펴봅니다.

Ruflo란 무엇이고, 왜 필요한가요?

Ruflo의 역할은 큰 요청을 나누고, 역할별 결과를 연결하는 것입니다. 이런 작업 조율을 ‘오케스트레이션’이라고 부릅니다. 여러 에이전트가 협업하는 구성을 ‘스웜(swarm)’이라고도 합니다.

예를 들어 “로그인 기능을 만들어줘”라는 요청에는 여러 일이 숨어 있습니다.

이 표는 이해를 돕기 위한 역할 배분 예시입니다. 설치만 하면 표의 모든 역할이 언제나 자동으로 동시에 실행된다는 뜻은 아닙니다.

먼저 기획에서 완료 조건을 정해야 구현 방향이 나옵니다. 구현이 끝난 뒤에는 변경된 코드를 테스트해야 합니다. 반면 기존 코드의 구조 분석과 테스트 현황 조사는 동시에 진행할 수 있습니다. 함께 진행할 일과 앞선 결과를 기다려야 할 일을 구분하는 것이 핵심입니다.

Claude Code 자체 에이전트와는 무엇이 다른가요?

Claude Code에도 작업을 위임하는 subagents와 여러 세션이 협업하는 agent teams 기능이 있습니다. 따라서 “Ruflo가 없으면 Claude Code는 혼자만 일한다”는 설명은 정확하지 않습니다. Claude Code subagents 문서, agent teams 문서

다만 agent teams는 실험 기능이며 기본적으로 비활성화되어 있습니다. 사용하려면 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정이 필요합니다. 이 설정은 Claude Code의 agent teams에 관한 것으로, Ruflo 설치 명령과는 다릅니다.

Ruflo는 Claude Code와 연동해 별도의 작업 조율과 메모리 기능을 제공하는 선택지입니다. 역할을 나누는 것만 필요하다면 기본 기능부터, 작업을 반복하며 공유 맥락까지 관리하고 싶다면 Ruflo를 검토하면 좋습니다.

공유 메모리는 팀의 공용 노트에 비유할 수 있습니다. 다만 모든 대화가 빠짐없이 저장되고 다음 작업에 자동으로 정확하게 반영된다고 가정하지 마세요. 중요한 결정은 무엇을 어디에 저장했는지, 다음 작업에서 실제로 찾아왔는지 확인하는 편이 좋습니다. Ruflo 가이드는 메모리 저장·검색·조회 명령을 별도로 안내합니다. Ruflo 메모리 사용 안내

Ruflo는 언제 쓰면 좋을까요?

여러 관점의 검토가 필요하고, 나눠 맡길 일이 분명할 때 활용하기 좋습니다. 아래는 작업을 선택할 때 사용할 수 있는 기준입니다.

여러 에이전트를 쓰면 모델 호출과 사용량도 늘어날 수 있습니다. 처음부터 인원을 많이 늘리기보다 독립적인 작업에 필요한 만큼만 배분하세요. Claude Code 공식 문서도 agent teams가 단일 세션보다 많은 토큰을 사용한다고 설명합니다. Claude Code 비용 관리 문서

Ruflo 설치 방법: 준비부터 Claude Code 연결까지

이 글은 2026년 9월 30일 확인한 공식 문서와 Ruflo 3.48.0 배포 패키지를 기준으로 작성했습니다. 아래는 터미널에서 초기화하는 CLI 설치 경로입니다. Claude Code 플러그인 마켓플레이스로 설치하는 경로는 구성과 도구 이름이 다를 수 있습니다.

@latest는 실행 시점의 최신 버전을 가져오므로, 이후에는 화면이나 옵션이 달라질 수 있습니다. 설치·연결 절차는 공식 문서와 배포 코드를 대조했고, 뒤의 JavaScript 예제는 Node.js 24.14.1에서 실행했습니다. Ruflo의 전체 에이전트 작업을 운영체제별로 실행 검증한 가이드는 아닙니다.

1. Node.js·npm·Claude Code를 확인하세요

터미널에서 다음 명령어를 한 줄씩 실행합니다.

node --version
npm --version
claude --version
git --version

Ruflo 공식 가이드는 Node.js 20 이상과 npm 9 이상을 안내합니다. 다만 최소 요구 버전과 권장 설치 버전은 다릅니다. 확인일 기준 Node.js 20은 지원이 종료되었으므로, 새로 준비한다면 지원 중인 Node.js 24 LTS를 권장합니다. Node.js 22도 LTS입니다. Git은 변경 내용을 확인할 때도 유용합니다. Ruflo 시작 가이드, Node.js 공식 릴리스 현황

Claude Code가 없다면 공식 설치 안내를 먼저 따라 하세요. 버전이 출력되는 것뿐 아니라, claude를 열어 로그인하고 대화할 수 있는 상태까지 준비해야 합니다.

2. 작업할 프로젝트 폴더로 이동하세요

아래 경로는 예시입니다. 내 프로젝트가 실제로 저장된 경로로 바꿔서 실행하세요.

Windows PowerShell

cd "C:\Users\사용자이름\Desktop\my-project"
Get-Location
Get-ChildItem -Force

macOS·Linux

cd "$HOME/Desktop/my-project"
pwd
ls -a

프로젝트의 README나 소스 폴더가 보이면 위치를 확인한 것입니다. JavaScript 프로젝트라면 package.json도 확인할 수 있습니다.

Git으로 관리하는 프로젝트라면 설정 전에 변경 상태도 확인하세요.

git status --short

진행 중인 작업이 있다면 먼저 내용을 확인하고 별도로 보관해 두세요. Ruflo 초기화는 CLAUDE.md, .claude/ 같은 프로젝트 설정에 영향을 줄 수 있습니다. Ruflo 설치 방식 비교

3. Ruflo를 초기화하고 상태를 점검하세요

프로젝트 폴더에서 실행합니다.

npx ruflo@latest init wizard

처음 실행하면 패키지를 내려받을지 묻는 메시지가 나올 수 있습니다. 이어지는 마법사에서는 안내를 읽으며 필요한 설정을 선택하세요. 기존 설정 파일을 바꾸는 항목은 내용을 확인한 뒤 진행합니다.

완료 후에는 진단 명령어를 실행합니다.

npx ruflo@latest doctor

오류나 경고가 있다면 해당 항목의 설명을 확인하세요. 아직 사용하지 않는 기능의 설정 문제인지, 현재 작업을 막는 연결 문제인지 구분하는 것이 좋습니다. 진단 명령어가 끝났다고 모든 개발 작업이 성공하는 것은 아닙니다. Ruflo 진단 안내

이 과정은 프로젝트의 초기 설정입니다. 매번 채팅 전에 반복할 필요는 없지만, 다른 프로젝트나 PC로 옮기거나 버전을 갱신하면 설정을 다시 확인해야 합니다.

4. MCP가 실제로 연결됐는지 확인하세요

MCP는 Claude Code가 외부 도구를 사용할 수 있게 연결하는 규격입니다. 터미널에서 다음 명령어로 연결 목록과 상태를 확인합니다.

claude mcp list

Ruflo 관련 서버가 등록되어 있는지와 연결 상태를 보세요. 공식 예시에서는 예전 이름인 claude-flow를 서버 이름으로 사용합니다.

관련 서버가 없을 때만 공식 안내의 수동 등록 명령어를 사용합니다. 이미 등록되어 있다면 같은 서버를 중복으로 추가하지 마세요.

macOS·Linux·WSL

claude mcp add --transport stdio --scope local claude-flow -- npx -y ruflo@latest mcp start

Windows PowerShell·cmd

claude mcp add --transport stdio --scope local claude-flow -- cmd /c npx -y ruflo@latest mcp start

Windows용 명령은 Ruflo의 MCP 설정 생성 코드와 같은 cmd /c npx 방식을 사용합니다. -y는 npx의 패키지 설치 확인을 자동으로 수락하므로, 서버 시작이 입력 대기에서 멈추는 일을 줄입니다. --scope local은 현재 프로젝트에서 나만 사용하는 등록이며 다른 프로젝트나 팀원에게 자동 공유되지 않습니다. Ruflo MCP 설정 생성 코드, MCP 설정 범위, npx 공식 문서

그다음 프로젝트 폴더에서 Claude Code를 엽니다.

claude

이제부터 아래 명령은 터미널이 아니라 Claude Code 채팅창에 입력합니다.

/mcp

서버 상태와 도구 목록을 확인하세요. 등록 명령이 성공했다는 메시지는 설정이 저장됐다는 뜻이며, 실제 연결 성공은 별도로 확인해야 합니다. Pending approval이라면 프로젝트와 서버 설정을 검토한 뒤 승인하고, Failed to connect라면 표시된 오류를 먼저 확인하세요. 이미 Claude Code를 열어 둔 상태에서 초기화했다면 세션을 다시 열어 새 설정을 읽게 하세요. Ruflo MCP 등록 안내, Claude Code MCP 상태 확인

첫 사용은 프로젝트 분석부터 시작하세요

처음 Ruflo를 붙였다면 소스·설정 파일을 수정하지 않는 분석부터 요청하세요. 기존 구조를 모르는 상태에서 기능부터 추가하면, 이미 있는 코드를 중복으로 만들거나 프로젝트 규칙과 다른 방식으로 구현할 수 있습니다.

아래 프롬프트는 Claude Code 채팅창에 붙여넣습니다.

Ruflo 멀티 에이전트 방식으로 이 프로젝트를 분석해줘.

먼저 현재 세션에서 Ruflo 관련 MCP 도구와 프로젝트 설정을
사용할 수 있는지 확인해줘.
사용할 수 없다면 Ruflo를 썼다고 말하지 말고,
확인된 문제와 필요한 설정만 알려줘.

가능한 경우 다음 관점으로 작업을 나눠줘.
- 기획: 프로젝트 목적과 주요 사용자 흐름
- 개발: 기술 스택, 폴더 구조, 실행 방법
- 테스트: 테스트 파일, 실행 명령, 부족한 검증
- 리뷰·보안: 유지보수, 인증·권한, 민감정보 처리 위험

작업 조건:
- 소스·설정 파일을 수정하거나 의존성을 설치하지 마.
- 이번 단계에서는 테스트·빌드·애플리케이션 개발 서버를 실행하지 마.
- 비밀값을 출력하거나 공유 메모리에 저장하지 마.
- 독립적인 조사는 병렬로 하고, 중복 조사는 줄여줘.
- 확인한 사실과 추정을 구분해줘.
- 문제마다 파일 경로와 근거를 함께 적어줘.

마지막에 다음을 정리해줘.
1. 프로젝트가 하는 일
2. 역할별로 확인한 내용
3. 가장 먼저 하면 좋은 일 3가지와 이유
4. 추천 작업의 계획, 변경 예상 파일, 검증 방법
5. 실제 사용한 Ruflo 도구와 위임 작업, 확인하지 못한 부분

아직 구현하지 말고 여기서 멈춰줘.

여기서 중요한 부분은 역할 이름보다 수정 범위·근거·완료 조건입니다. “보안 담당이 확인했다”는 말만으로는 충분하지 않습니다. 어떤 파일에서 어떤 문제를 발견했는지가 있어야 사람이 판단할 수 있습니다.

또한 프롬프트는 작업 지시입니다. Claude Code에서 Shift+Tab으로 Plan 모드를 선택하면 소스 파일을 편집하지 않고 조사하는 흐름으로 시작할 수 있습니다. 초기화로 추가된 .claude/settings.json의 권한과 hooks(특정 시점에 실행되는 자동화)도 확인하세요. Plan 모드나 “분석만 해줘”라는 문장이 Ruflo의 로그·메모리 기록을 포함한 모든 쓰기를 막는 것은 아닙니다. Claude Code 권한 모드

분석 결과에서 무엇을 확인해야 하나요?

아래는 실제 프로젝트 결과가 아닌 보고서 형식 예시입니다.

계획이 마음에 들면 다음처럼 구현 범위를 정해 줍니다. Plan 모드에서 시작했다면 계획을 확인하고 구현을 허용하는 모드로 전환한 뒤 진행하세요.

좋아. 방금 제안한 계획 중 [선택한 작업]만 진행해줘.

개발·테스트·리뷰 작업을 나누고,
같은 파일을 동시에 수정하지 않도록 담당을 정해줘.
앞선 결과가 필요한 작업은 순서대로 진행해줘.

기존 사용자 변경을 보존하고, 관련 없는 리팩터링은 하지 마.
새 의존성 추가나 데이터 구조 변경이 필요하면 먼저 이유를 설명해줘.
배포, 결제, API 키 변경, 운영 데이터 수정은 하지 마.

완료 후 변경 파일, 실행한 테스트 명령과 결과,
실행하지 못한 검증과 남은 문제를 정리해줘.

바로 복사하는 Ruflo 실전 프롬프트 3가지

아래 템플릿은 앞에서 연결을 확인한 세션에서 사용하세요. 대괄호 부분을 실제 요구사항으로 바꿔야 결과가 구체적입니다. 공식 내장 명령이 아니라, 이 글에서 작성한 자연어 요청 예시입니다. 역할 수는 작업 크기에 맞추고, 단순히 역할별 답변을 나열했는지 실제 작업을 위임했는지도 확인하세요.

새 기능 추가: 완료 조건까지 알려주기

Ruflo 멀티 에이전트 방식으로 다음 기능의 구현 계획을 세워줘.

기능: [예: 할 일 목록에 완료 여부 필터 추가]
사용자 흐름: [전체 / 미완료 / 완료 버튼으로 목록 전환]
완료 조건:
- [필터를 바꿔도 원본 데이터는 유지]
- [해당 항목이 없으면 빈 상태 안내]
- [기존 추가·삭제 기능이 계속 동작]

기획은 흐름과 빠진 요구사항을,
개발은 기존 구조와 변경 파일을,
테스트·리뷰는 오류 상황과 회귀 위험을 확인해줘.

기존 구현을 먼저 찾아 재사용하고,
계획·변경 범위·검증 방법을 보여준 뒤 멈춰줘.
내가 "진행해줘"라고 답한 뒤에만 구현해.
구현 후에는 실제 테스트 결과와 확인하지 못한 항목을 알려줘.

“필터를 만들어줘”보다 데이터 유지·빈 상태·기존 기능 유지를 함께 지정하면 결과를 확인하기 쉬워집니다.

버그 수정: 재현 정보와 원인부터 확인하기

Ruflo 멀티 에이전트 방식으로 아래 버그를 조사해줘.

기대 동작: [새로고침해도 로그인 상태 유지]
실제 동작: [특정 상황에서 로그인 화면으로 이동]
재현 순서: [로그인 → 특정 페이지 이동 → 새로고침]
실행 환경: [운영체제, 브라우저, 개발/배포 환경]
오류 메시지: [민감정보를 제거한 로그]
최근 변경: [알고 있는 경우 작성]

분석 담당은 재현 조건과 원인 후보를,
테스트 담당은 원인을 구분할 수 있는 검증 방법을 찾아줘.
추측을 사실처럼 말하지 말고 근거와 함께 정리해줘.

수정 전에는 원인, 최소 수정 계획, 영향받는 파일을 보여주고 멈춰줘.
내가 승인하면 수정하고, 가능하면 수정 전 실패·수정 후 통과하는
회귀 테스트로 확인해줘.
재현하지 못했다면 그 사실과 추가로 필요한 정보를 알려줘.

에러 문장만 붙이는 것보다 기대 동작과 재현 순서를 함께 주는 것이 유용합니다. 재현에 실패했다면 “수정 완료”보다 “추가 정보 필요”라는 결과가 더 정직한 답일 수 있습니다.

코드 리뷰: 파일을 바꾸지 않고 근거 받기

Ruflo 멀티 에이전트 방식으로 코드 리뷰만 해줘.

검토 범위: [예: 현재 Git 변경분 / src/auth 폴더]
관점:
- 구조와 유지보수성
- 오류 가능성과 경계 조건
- 테스트 누락
- 인증·권한·민감정보 처리

소스·설정 파일을 수정하거나 의존성을 설치하지 마.
이번에는 정적 검토만 하고 명령 실행이 필요하면 먼저 알려줘.
비밀값이나 개인정보 원문을 답변에 포함하지 마.

발견 사항을 심각한 순서대로 정리하고, 각 항목에
파일 경로와 위치, 발생 조건, 영향, 근거, 해결 방향을 적어줘.
취향 수준의 제안과 실제 오류 가능성을 구분해줘.
문제를 찾지 못했다면 검토 범위와 남은 한계를 설명해줘.

코드로 연습하기: 빈 할 일 제목을 막아보세요

실제 프로젝트에 바로 큰 기능을 맡기기 부담스럽다면, 작은 함수 하나와 테스트로 작업 결과를 확인하는 연습부터 해보세요. 이 정도 크기의 수정 자체에 여러 에이전트가 꼭 필요한 것은 아닙니다. 여기서는 구현과 테스트의 역할 차이를 이해하기 위한 예제로 사용합니다.

별도의 연습 폴더를 만들고 그 안에 아래 두 파일을 저장하세요. 추가 패키지 설치 없이 Node.js로 실행할 수 있습니다.

1. 검증할 함수 만들기

task-title.cjs 파일입니다. 문자열의 앞뒤 공백을 제거하고, 빈 제목이면 오류를 발생시킵니다.

function normalizeTaskTitle(value) {
  if (typeof value !== "string") {
    throw new TypeError("제목은 문자열이어야 합니다.");
  }

  const title = value.trim();

  if (title.length === 0) {
    throw new Error("제목을 입력하세요.");
  }

  return title;
}

module.exports = { normalizeTaskTitle };

2. 정상 입력과 오류 입력을 테스트하기

같은 폴더에 task-title.test.cjs를 만듭니다.

const test = require("node:test");
const assert = require("node:assert/strict");
const { normalizeTaskTitle } = require("./task-title.cjs");

test("앞뒤 공백을 제거한다", () => {
  assert.equal(normalizeTaskTitle("  장보기  "), "장보기");
});

test("빈 문자열과 공백만 있는 제목을 거부한다", () => {
  for (const value of ["", "   ", "\n\t"]) {
    assert.throws(() => normalizeTaskTitle(value), /제목을 입력/);
  }
});

test("문자열이 아닌 입력을 거부한다", () => {
  for (const value of [null, undefined, 123]) {
    assert.throws(() => normalizeTaskTitle(value), TypeError);
  }
});

연습 폴더의 터미널에서 실행합니다.

node --test task-title.test.cjs

세 테스트가 통과하는지 확인하세요. 글 작성 과정에서도 위 두 파일을 Node.js에서 실행해 세 테스트의 통과를 확인했습니다.

3. 같은 예제에 변경을 요청하기

연습 폴더에서도 Ruflo 초기화와 MCP 연결을 마친 뒤 Claude Code에 아래처럼 요청할 수 있습니다.

Ruflo 멀티 에이전트 방식으로 이 연습 코드를 검토해줘.

대상: task-title.cjs, task-title.test.cjs
추가 요구사항: 공백을 제거한 제목의 length가 80을 넘으면 거부
이번 연습의 길이 기준: JavaScript 문자열의 UTF-16 코드 단위 수

개발 담당은 최소 수정안을,
테스트 담당은 기존 동작과 length 80·81의 경계값 테스트 계획을,
리뷰 담당은 요구사항 누락 여부를 확인해줘.

파일별 담당을 정하고 계획을 보여준 뒤 멈춰줘.
내가 "진행해줘"라고 답하면 구현하고,
node --test task-title.test.cjs의 실제 결과를 알려줘.

이 예제에서 확인할 것은 세 가지입니다. 기존 테스트가 유지되는지, length 80과 81의 경계값을 구분하는지, 실행 결과를 근거로 보고하는지입니다.

length는 화면에 보이는 글자 수와 항상 같지는 않습니다. 예를 들어 "😀".length는 2입니다. 이 연습은 UTF-16 코드 단위 수를 기준으로 하며, 실제 서비스에서 사용자가 보는 글자 수를 제한하려면 별도의 요구사항을 정해야 합니다. MDN 문자열 length 설명

“테스트를 작성했습니다”와 “테스트를 실행해서 통과했습니다”는 다릅니다. 작은 실습에서 이 차이를 익혀 두면 실제 프로젝트의 완료 보고도 훨씬 잘 판단할 수 있습니다.

작업이 끝나면 결과와 공유 메모리를 확인하세요

개발 결과는 “완료”라는 문장보다 변경 내용과 검증 결과로 확인해야 합니다. 작업을 마친 세션에서 아래 프롬프트를 사용하세요.

이번 작업의 최종 결과를 초보자도 이해하기 쉽게 정리해줘.

1. 무엇을 만들거나 수정했는지
2. 변경 파일과 각 파일을 바꾼 이유
3. 실제 실행한 테스트 명령과 통과·실패 결과
4. 실행하지 못한 테스트와 그 이유
5. 아직 남은 문제와 내가 직접 확인할 화면
6. 실제 위임한 작업과 사용한 Ruflo 도구

다음 작업에 재사용할 가치가 있는 결정과 주의사항도 골라줘.
Ruflo 공유 메모리를 사용할 수 있다면 민감정보 없이 저장하고,
저장 위치나 키와 다시 읽어 확인한 결과를 알려줘.
저장하거나 다시 확인하지 못했다면 그 사실을 분명히 알려줘.

AI가 알려준 파일을 열어보고, 요청한 화면이나 동작도 직접 확인하세요. 로그인·결제처럼 영향이 큰 기능은 단위 테스트만 통과했다고 검토가 끝난 것으로 보지 않는 편이 좋습니다.

Ruflo 설치·사용 중 자주 묻는 질문

오늘은 분석 프롬프트 하나부터 시작하세요

Ruflo를 잘 쓰기 위한 첫 목표는 거대한 기능을 한 번에 만드는 것이 아닙니다. 현재 프로젝트를 이해하고, 변경 범위를 정한 뒤, 결과를 검증하는 흐름을 만드는 것입니다.

프로젝트 하나를 골라 설치와 연결을 확인하고, 첫 분석 프롬프트를 붙여넣어 보세요. 제안받은 작업 중 가장 작은 것 하나를 선택해 계획을 확인한 뒤 진행하면 됩니다.

익숙해진 다음에는 기능 추가·버그 수정·리뷰로 범위를 넓혀보세요. 작업이 끝날 때마다 “무엇을 바꿨는지, 무엇으로 확인했는지, 무엇이 남았는지”를 받는 습관이 AI 팀을 활용하는 기준이 됩니다.

관련 개념이 헷갈린다면 Claude Code 스킬·워크플로우·에이전트 차이와 하네스·루프·그래프 엔지니어링 가이드도 함께 읽어보세요.