Sign in
Development

Ruflo 사용법: Codex·Claude Code에 에이전트 협업과 메모리를 더하는 하네스

GitHub Trending 일간 9위·136 stars today를 확인한 Ruflo의 설치 방식, MCP 연결, 권한과 데이터 경계, 도입 전 한계를 정리한다.

Ruflo 사용법: Codex·Claude Code에 에이전트 협업과 메모리를 더하는 하네스

Ruflo는 Codex와 Claude Code 주변에 다중 에이전트 조정, 장기 메모리, 훅, 반복 작업을 붙이는 오케스트레이션 계층이다. 모델을 교체하는 도구라기보다, 코딩 에이전트가 여러 역할을 나눠 일하고 결과를 다음 세션에서 다시 활용하도록 만드는 메타 하네스에 가깝다.

2026년 9월 6일 10:00(Asia/Seoul) GitHub Trending 일간 목록에서 9위, 136 stars today를 확인했고, 당시 GitHub 저장소 API의 총 스타는 70,697개였다. 이 수치는 시점 기록이며 현재 값은 링크에서 다시 확인해야 한다.

먼저 결론: 누구에게 필요한가

한 번의 수정이나 작은 버그 해결에는 Ruflo가 오히려 부담이 될 수 있다. 반면 여러 모듈을 동시에 고치는 리팩터링, 보안·테스트·문서 검토를 역할별로 나누는 작업, 여러 세션에 걸쳐 결정과 패턴을 기억해야 하는 프로젝트라면 장점이 분명해진다.

  • 잘 맞는 작업: 대규모 리팩터링, 병렬 조사와 구현, 반복되는 코드 리뷰, 프로젝트 지식 축적, 장시간 백그라운드 작업
  • 굳이 필요 없는 작업: 한 파일의 짧은 수정, 단발성 질문, 엄격한 실행 격리가 준비되지 않은 저장소
  • 도입 원칙: 처음부터 모든 플러그인과 에이전트를 켜지 말고 작은 테스트 저장소에서 필요한 기능만 검증한다.

설치 전 준비

공식 설치 문서는 Node.js 20 이상, npm 9 이상, Git을 전제로 한다. 먼저 프로젝트 루트에서 버전을 확인한다.

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

초기화 과정은 .claude/, .claude-flow/, CLAUDE.md, AGENTS.md 같은 설정 파일을 만들거나 MCP 등록을 변경할 수 있다. 따라서 작업 중인 변경을 먼저 커밋하거나 별도 브랜치에서 실행하고, 초기화 전후의 git diff를 확인하는 편이 안전하다.

설치 경로 1: Claude Code 플러그인으로 가볍게 체험

에이전트 정의와 슬래시 명령을 먼저 시험하려면 Claude Code 안에서 플러그인 경로를 사용할 수 있다.

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

이 방식은 시작이 간단하지만 공식 설치 문서 기준으로 전체 MCP 서버의 메모리·스웜 도구가 모두 제공되는 경로는 아니다. 지속 메모리나 다중 에이전트 오케스트레이션이 목적이라면 다음의 전체 CLI 설치를 사용한다.

설치 경로 2: 전체 CLI와 MCP 사용

운영체제와 무관하게 가장 이해하기 쉬운 시작점은 대화형 초기화다.

npx ruflo@latest init wizard

질문 없이 기본값으로 초기화하려면 다음 명령을 쓸 수 있다.

npx ruflo@latest init

macOS·Linux·WSL·Git-Bash에서는 공식 설치 스크립트도 제공되지만, 원격 스크립트를 셸로 바로 넘기기 전에 내용을 검토하는 습관이 좋다. 네이티브 Windows PowerShell이나 cmd에서는 npx ruflo@latest init wizard 경로를 사용한다.

초기화가 끝나면 진단 명령으로 Node, npm, Git, 설정 파일, API 키와 MCP 연결 상태를 확인한다.

npx ruflo@latest doctor --fix

--fix는 설정을 변경할 수 있으므로 먼저 변경 예정 파일을 확인하고, 중요한 저장소에서는 실행 전 상태를 커밋해 두는 편이 좋다.

Claude Code에 연결하기

전체 기능을 Claude Code에서 사용하려면 Ruflo MCP 서버를 등록한다.

claude mcp add ruflo -- npx -y ruflo@latest mcp start
claude mcp list

등록 뒤 Claude Code를 새로 시작하고 Ruflo의 메모리·에이전트·스웜 도구가 보이는지 확인한다. 백그라운드 워커와 자율 루프가 필요할 때만 데몬을 켠다.

npx ruflo@latest daemon start
npx ruflo@latest daemon status

MCP stdio 서버는 Claude Code 세션이 필요할 때 실행하므로, 일부 버전에서 mcp status가 Stopped라고 보여도 도구 호출이 정상일 수 있다. 상태 문구 하나보다 실제 MCP 도구 목록과 간단한 호출로 연결을 확인하는 편이 정확하다.

Codex에 연결하기

Ruflo 저장소는 Codex용 초기화 경로와 MCP 등록 코드를 제공한다. 프로젝트용 파일과 Codex 설정을 만들려면 다음처럼 시작한다.

npx ruflo@latest init --codex
codex mcp list

MCP가 등록되지 않았다면 공식 코드가 사용하는 형식으로 직접 추가할 수 있다.

codex mcp add ruflo -- npx -y ruflo@latest mcp start
codex mcp list

그다음 Codex를 새로 시작해 MCP 설정을 다시 읽게 한다. Ruflo 플러그인 훅까지 사용할 경우에는 설치된 훅 정의와 실행 명령을 직접 검토한 뒤 신뢰 여부를 결정한다. Codex 초기화 경로는 최근에도 수정이 이어지고 있으므로, 기존 AGENTS.md나 .codex/config.toml을 덮어쓰지 않았는지 반드시 확인한다.

첫 번째 실습: 스웜 만들기

처음에는 중앙 조정자가 역할을 배분하는 계층형 구성이 이해하기 쉽다.

npx ruflo@latest swarm init \
  --topology hierarchical \
  --max-agents 4 \
  --strategy specialized

npx ruflo@latest swarm status

공식 예시는 최대 8개 에이전트를 사용하지만, 실제 프로젝트에서는 3~4개부터 시작하는 편이 비용과 충돌을 관찰하기 쉽다. 예를 들어 인증 모듈 개선 작업을 다음처럼 나눌 수 있다.

  • 연구 에이전트: 현재 인증 흐름과 의존성 조사
  • 구현 에이전트: 변경 범위를 좁혀 코드 수정
  • 테스트 에이전트: 회귀·경계 조건 테스트
  • 리뷰 에이전트: 보안, 권한, 비밀정보 노출 검토

필요하면 개별 에이전트를 만들고 목록과 상태를 확인한다.

npx ruflo@latest agent spawn -t coder --name auth-worker
npx ruflo@latest agent list
npx ruflo@latest agent status auth-worker

여러 에이전트가 같은 파일을 동시에 수정하면 충돌과 중복 작업이 생긴다. 역할별 파일 범위, 완료 조건, 결과를 기록할 메모리 키를 먼저 정해 두는 것이 중요하다.

두 번째 실습: 세션을 넘는 메모리

반복해서 사용할 설계 결정이나 해결 패턴은 네임스페이스를 정해 저장한다.

npx ruflo@latest memory store \
  --key "auth-refresh-policy" \
  --value "Refresh token rotation with reuse detection" \
  --namespace "project-patterns"

npx ruflo@latest memory search \
  --query "refresh token security" \
  --namespace "project-patterns"

메모리는 비밀 저장소가 아니다. API 키, 세션 토큰, 고객 데이터, 미공개 소스 전문을 넣지 말고 재사용 가능한 요약과 출처만 저장한다. 프로젝트·팀·실험별 네임스페이스를 나누면 오래된 패턴이 현재 작업에 잘못 섞이는 문제를 줄일 수 있다.

실무에서 바로 쓰는 운영 순서

  1. 작게 시작: 테스트 저장소에서 init과 doctor만 실행한다.
  2. 변경 확인: 생성된 설정, 훅, MCP 명령을 git diff로 검토한다.
  3. 도구 확인: Claude Code 또는 Codex에서 MCP 목록을 확인하고 메모리 검색 같은 읽기 작업을 시험한다.
  4. 역할 제한: 에이전트별 파일 범위와 허용 명령, 완료 조건을 정한다.
  5. 스웜 확대: 단일 에이전트로 충분하지 않은 작업에만 3~4개 역할을 배치한다.
  6. 결과 검증: 테스트와 정적 분석을 별도로 실행하고, 에이전트의 성공 보고만으로 완료 처리하지 않는다.

문제 해결 체크리스트

  • npx를 찾지 못함: Node.js 20 이상 설치와 PATH를 확인한다. Windows에서는 POSIX 셸용 설치 명령 대신 npx 초기화를 사용한다.
  • MCP 서버가 시작되지 않음: npx ruflo@latest doctor 결과, Node 버전, MCP 등록 명령을 확인한 뒤 호스트 앱을 재시작한다.
  • Codex에서 첫 시작이 시간 초과됨: Ruflo의 Codex 설정 코드는 콜드 스타트를 고려해 MCP 시작 제한을 120초로 둔다. 기존 설정이 더 짧다면 최신 초기화로 갱신하거나 설정을 검토한다.
  • 명령과 문서가 서로 다름: Ruflo는 변화가 빠르고 README, Wiki, 버전별 문서의 숫자와 명령 표기가 어긋날 수 있다. 설치된 버전의 --help와 해당 릴리스 문서를 우선한다.
  • 작업이 느려지거나 비용이 늘어남: 에이전트 수를 줄이고, 한 작업에 필요한 역할만 남기며, 백그라운드 데몬이 꼭 필요한지 재검토한다.

권한과 데이터 경계

Ruflo는 프로젝트 설정과 훅을 만들고 MCP를 통해 파일, 명령, 메모리, 외부 모델에 접근할 수 있다. 실제 데이터 전송 위치는 선택한 모델 제공자와 플러그인 구성에 따라 달라진다. 도입 전 다음 항목을 확인한다.

  • 설치가 추가하거나 바꾸는 파일과 훅
  • MCP 서버의 실행 명령, 작업 디렉터리, 네트워크 바인딩
  • 각 에이전트가 수정할 수 있는 경로와 실행 가능한 명령
  • 메모리·로그의 저장 위치, 보존 기간, 삭제 방법
  • API 키와 비밀정보가 환경 변수·로그·메모리에 노출되지 않는지

저장소의 기능 주장과 벤치마크 수치는 제작자가 제공한 자료다. 실제 도입 판단에는 자신의 저장소에서 재현한 테스트, 실패 복구 방식, 비용과 지연 시간을 함께 봐야 한다.

중지와 제거

실험을 끝낼 때는 실행 중인 스웜과 데몬을 먼저 중지하고 MCP 등록을 제거한다. 프로젝트 파일은 무작정 삭제하지 말고 초기화 전후 diff를 기준으로 골라 되돌린다.

npx ruflo@latest swarm shutdown
npx ruflo@latest daemon stop

# Claude Code
claude mcp remove ruflo

# Codex
codex mcp remove ruflo

# 전역 설치를 사용한 경우
npm uninstall -g ruflo

한계와 도입 판단

Ruflo의 강점은 많은 기능 그 자체보다 여러 에이전트의 역할, 기억, 실행 흐름을 한 계층에서 관리하려는 데 있다. 하지만 기능 표면이 큰 만큼 설정과 관찰 비용도 커진다. 작은 저장소에서는 단일 코딩 에이전트와 명확한 체크리스트가 더 효율적일 수 있다.

실전 도입 여부는 “에이전트를 몇 개 쓸 수 있는가”보다 “동시에 나눈 작업을 충돌 없이 검증하고, 남길 기억과 버릴 로그를 구분할 수 있는가”로 판단하는 편이 낫다.

출처 및 추가 링크

순위와 스타 수는 2026년 9월 6일 10:00(Asia/Seoul) 확인값이다. 명령과 기능 수는 버전에 따라 달라질 수 있으므로 설치 시점의 공식 문서와 --help를 함께 확인한다.

Read next