에이전트 팀 운영 도구를 소스까지 뜯어보고 검증한 결과
14편에서는 Claude Code의 Nested Agent로 메인 에이전트가 서브에이전트에게 일을 나눠주는 구조를 실습했습니다. 이번 편에서는 한 단계 더 나아가, 에이전트 여러 명을 "팀"으로 운영해준다는 도구 Ruflo를 Claude Code에 붙여봤습니다.
Ruflo는 흔히 "AI 직원 100명을 무료로 고용하는 도구"처럼 소개됩니다. 이번에는 가이드를 그대로 따라 하지 않고, 패키지 소스를 직접 읽고 대조군을 둔 실험으로 그 소개가 어디까지 맞는지 검증했습니다. 결론부터 말하면, 이번 작업에서 실제 팀 작업을 한 것은 Claude Code의 기본 서브에이전트였고, Ruflo를 붙인 쪽은 비용이 약 30% 더 들었습니다. 단, 작은 작업 하나를 1~2회 실행한 결과라는 한계가 있습니다.
먼저 알아야 할 개념
모델 · 하네스 · 에이전트
- 모델(LLM): 글을 읽고 쓰는 두뇌입니다. 혼자서는 파일을 열거나, 명령을 실행하거나, 기억할 수 없습니다.
- 하네스(Harness): 원래 말에 채우는 마구를 뜻합니다. AI에서는 모델이 실제로 일하게 해주는 장치 전체를 말합니다. 작업 반복 루프, 파일·터미널 도구, 권한, 훅, CLAUDE.md 읽기 등이 여기에 속하며, Claude Code가 대표적인 하네스입니다.
- 에이전트: 별도의 층이 아니라 결과물입니다. 모델 + 하네스 = 에이전트입니다.
Ruflo는 이 하네스 위에 한 층을 더 얹는 메타 하네스입니다. 비유하면 모델은 두뇌, 하네스는 몸과 작업 환경, 에이전트는 일하는 직원, Ruflo는 직원 여러 명을 팀으로 굴리는 운영 시스템(팀장 + 업무 일지 + 사내 규칙)입니다.
컨텍스트 윈도우
컨텍스트 윈도우(context window)는 AI가 한 번에 펼쳐놓고 볼 수 있는 작업 책상의 크기입니다. 책상이 꽉 차면 내용을 요약해 공간을 만드는 압축(compaction)이 일어납니다. 별도 책상을 가진 분신인 서브에이전트와, 책상 밖 서랍인 메모리가 필요한 근본 이유가 여기에 있습니다.
Claude Code 확장 부품 — 실행을 누가 정하나
Ruflo를 이해하려면 Claude Code에 무엇을 얹을 수 있는지, 그리고 각 부품의 실행을 누가 결정하는지 알아야 합니다.
| 부품 | 정의 | 실행 결정 | 비유 |
|---|---|---|---|
| CLAUDE.md | 세션 시작 때 읽는 지시 문서 | Claude가 판단 (대부분 지키지만 보장 X) | 벽 포스터 |
| MCP | 외부 시스템 연결 도구 | Claude가 판단 | 공구함 |
| 훅(Hook) | 정해진 시점에 자동 실행되는 스크립트 | 이벤트 발생 시 무조건 | 센서등 |
| 서브에이전트 | 별도 컨텍스트를 가진 분신 | Claude 판단 또는 지시 | 외주 팀원 |
| 스킬 | SKILL.md 절차서 | 호출 또는 Claude 판단 | 레시피 |
| 플러그인 | 위 부품을 묶은 패키지 | — | 창업 키트 |
핵심은 훅만 "무조건" 실행된다는 점입니다. CLAUDE.md에 "항상 X 해라"라고 써도 따를지는 Claude가 판단하지만, 훅은 이벤트가 생기면 반드시 돌아갑니다. 참고로 Claude Code 2.1.287부터는 내부에서 도는 JS 함수 + UI인 모드(Mod)도 생겼는데, 샌드박스 없이 무조건 실행되므로 "사무실 내부 공사"에 가깝습니다.
훅은 이벤트(언제) → 매처(어떤 경우만) → 핸들러(무엇을 실행)의 3단 구조입니다. SessionStart, UserPromptSubmit, PreToolUse(도구 실행 전, 차단 가능), PostToolUse, Stop 등 30개 이상의 이벤트가 있습니다. 차단하려면 exit 2로 끝나야 하고, exit 1은 차단되지 않는다는 점이 함정입니다. 저장 위치가 곧 적용 범위로, ~/.claude/settings.json(전체), .claude/settings.json(프로젝트 공유), .claude/settings.local.json(나만), 플러그인 hooks.json이 있습니다. 현재 적용된 훅은 /hooks로 확인합니다.
Ruflo란 무엇인가
Ruflo는 Claude Code 위에 훅·MCP·메모리·에이전트 정의를 얹는 메타 하네스입니다. 옛 이름은 Claude Flow이고, MIT 라이선스 오픈소스입니다.
| 구성요소 | 의미 |
|---|---|
| 스웜(swarm) | 에이전트 팀 |
| 토폴로지(topology) | 팀 조직도 (hierarchical: 위계형, mesh: 수평형) |
| 퀸(queen) | 팀장 에이전트 |
| 라우터(router) | 일을 어느 에이전트에게 줄지 배분 |
| 벡터 메모리 | 단어가 아닌 뜻으로 찾는 업무 일지 |
| 데몬(daemon) | 백그라운드에서 계속 도는 프로그램 |
중요한 것은 역할 분담입니다. Ruflo가 생성하는 설정 문서에 직접 "실행은 Claude Code의 Agent 도구, 조정은 Ruflo MCP 도구"라고 적혀 있습니다. 즉 Ruflo는 일을 직접 하지 않고 팀을 조정하는 쪽입니다. "100명"도 동시에 일하는 인원이 아니라 에이전트 카탈로그(정의 목록)의 수이고, Claude 사용량은 그대로 차감됩니다.
안전하게 설치하기 — 가이드와 달라진 점
참고한 가이드는 2026-08-06 기준(v3.32.x)이었고, 실습 당일 최신 버전은 3.56.5였습니다.
node --version # v24.7.0
claude --version # 2.1.296
npm view ruflo@latest version engines license --json # 3.56.5, node>=20, MIT먼저 빈 연습 폴더에 git 기준점을 만들었습니다. 설치가 무엇을 바꾸는지 전부 추적하기 위해서입니다.
mkdir ruflo-starter && cd ruflo-starter
git init && git commit --allow-empty -m "init: empty practice folder"
claude mcp list # ruflo/claude-flow가 없는 상태 확인위저드 대신 일반 init
가이드는 대화형 설치 마법사(init wizard)를 권장합니다. 하지만 소스를 읽어보니 위저드에는 --no-global 옵션을 처리하는 코드가 없어, 전역 ~/.claude/CLAUDE.md에 Ruflo 블록을 무조건 추가합니다. 모드도 질문 없이 기본 설치되고, Full 프리셋을 고르면 로그인이 필요한 클라우드 MCP 2개까지 추가됩니다. 그래서 일반 init에 옵션을 명시했습니다.
npx ruflo@3.56.5 init --no-global --no-mods설치 요약표에는 "110개"라고 나왔지만, git으로 세어보니 파일 253개, 55,310줄이었습니다(에이전트 17개, 스킬 30개, 명령어 16개). 요약 메시지보다 git 숫자가 정확합니다.
숨은 동작 차단 · 버전 고정 · git 제외
소스에서 첫 세션부터 실행되는 숨은 동작 두 가지를 발견해, settings.json의 env에 끄는 값을 넣었습니다.
| 환경변수 | 차단하는 동작 |
|---|---|
RUFLO_NO_AUTO_ENABLE=1 | 첫 세션에 전역 ~/.claude/settings.json에 홍보성 스피너 문구 추가 |
RUFLO_FUNNEL=0 | 매 세션 funnel.ruv.io에서 홍보 메시지 다운로드, 사용 한도 도달 시 홍보 문구 삽입 |
버전도 고정했습니다. .mcp.json의 ruflo@latest와 CLAUDE.md 안의 @latest 명령 16곳을 모두 @3.56.5로 바꿨습니다. 또 MCP 서버 이름이 ruflo가 아니라 claude-flow라서, 가이드대로 수동 등록하면 같은 서버가 중복 등록됩니다.
Ruflo가 만든 .gitignore에는 메모리 DB가 빠져 있어 직접 추가했습니다. grep으로 확인하면 파일명의 swarm까지 잡히므로 git check-ignore -v로 정확히 확인합니다.
printf '\n.swarm/\nruvector.db\n' >> .gitignore
git check-ignore -v .swarm/ ruvector.db첫 실행에서는 폴더 신뢰 화면의 "미리 승인된 도구 4개" 경고가 분석한 자동 허용 목록과 같은지 확인했고, MCP 승인은 "이 서버만 사용"을 선택했습니다. 실행 후 전역 설정이 오염되지 않았는지(spinnerVerbs 0개, first-run 마커 없음)도 확인했습니다.
커밋 히스토리로 보는 결정 기록
58e8d22 빈 폴더
450fbf1 설치
a9ea3e9 자동 설정·홍보 차단
d42f79f MCP 버전 고정
424e792 CLAUDE.md 버전 고정
3dcdcad 훅 스크립트 자동 갱신 수용
3b96654 런타임 파일 제외
65d43f6 스웜 상태 제외
0869a04 slugify커밋 9개 중 실제 작업물은 마지막 1개뿐이고, 나머지 8개는 안전하게 쓰기 위한 정리였습니다.
뜯어보기
훅 16개 중 6개는 빈 껍데기
설치 메시지에는 훅 "7종"이라고 나왔지만, settings.json에는 이벤트 10종에 실행 항목 16개가 등록되어 있었습니다. 소스를 따라가 보니 그중 6개(pre-edit, post-bash, compact-manual/auto, status, notify)는 아무 일도 하지 않는 빈 껍데기였습니다.
의미 있는 훅도 있었습니다.
- pre-bash:
rm -rf /같은 위험 명령을 exit 2로 차단합니다. 훅 교과서에 나올 법한 예시입니다. - route (UserPromptSubmit): 이것이 "라우터"의 실체입니다. 매 프롬프트마다 추천 에이전트 표를 Claude의 컨텍스트에 끼워 넣습니다.
권한 설정은 자동 허용 4개(mcp__claude-flow__* 등), 차단 2개(.env 읽기)였고, 환경변수로 Claude Code의 Agent Teams 실험 기능을 켜고 있었습니다.
세션 시작 때 훅 스크립트가 자동 갱신되며 statusline.cjs가 바뀌는 일도 있었습니다(패키지 원본에 3.32.8이 하드코딩된 Ruflo 쪽 실수). Claude는 되돌리자고 제안했지만, 소스를 보니 무결성 검사가 서명된 원본과 해시를 비교해 다시 덮어쓰는 구조라 되돌려도 소용이 없었습니다. 그래서 변경을 수용했습니다(갱신을 멈추는 비상 스위치로 .claude/helpers/.LOCKED가 있습니다). AI의 제안도 소스로 검증해야 한다는 사례입니다.
도구 358개의 실제 컨텍스트 비용
/mcp에서 claude-flow 하나가 도구 358개를 등록했습니다. 기존에 쓰던 MCP 11개의 도구를 모두 합친 192개의 약 2배입니다. 하지만 MCP 도구는 필요할 때만 불러오는 on-demand 방식이라 도구 수 자체의 비용은 거의 0입니다. 대화 0회 상태의 /context는 48.6k / 1M(5%), MCP 도구 항목은 7k였습니다.
실제로 매 요청 책상에 올라가는 것은 다른 부분이었습니다.
| 항목 | 토큰 |
|---|---|
| Ruflo CLAUDE.md | 3.7k |
| 스킬 목록 | 약 4.5k (추정) |
| 에이전트 17개 | 약 0.7k |
| 합계 | 약 9~10k (1M 창의 약 1%) |
검증 실험 ① 메모리 — 한국어 의미 검색의 함정
Ruflo의 벡터 메모리는 임베딩(embedding)으로 동작합니다. 문장을 숫자 좌표로 바꾸고, 좌표가 가까운 것을 "뜻이 비슷한 것"으로 찾는 방식입니다. 그런데 Ruflo 3.56.5는 영어 위주 모델인 Xenova/all-MiniLM-L6-v2가 코드에 하드코딩되어 있어 설정으로 바꿀 수 없습니다. 검색 결과에 포함되는 기준 점수인 임계값(threshold)의 기본값은 0.3입니다.
--threshold 0으로 모든 점수를 직접 보면서 비교했습니다.
npx ruflo@3.56.5 memory store --key "test-rule" --value "..." --namespace project
npx ruflo@3.56.5 memory search --query "..." --namespace project --threshold 0| 언어 | 관련 있는 검색 | 관련 없는 검색 | 판정 |
|---|---|---|---|
| 한국어 | 0.48 (단어 안 겹침) / 0.85 (단어 겹침) | 0.64 (점심 메뉴) | 실패 |
| 영어 | 0.25~0.30 | 0.00~0.02 | 성공 |
| 한↔영 | 0.00~0.09 | — | 실패 |
한국어에서는 전혀 상관없는 "점심 메뉴" 검색이 0.64로, 단어가 안 겹치는 정답(0.48)보다 높았습니다. 기본 임계값 0.3을 적용하면 영어 정답(0.25)은 빠지고 한국어 오답(0.64)은 통과하는 최악의 조합이 됩니다. 가이드의 "검색 결과에 나오면 메모리가 동작한다"는 확인법은 한국어에서는 틀린 검증입니다.
부수적으로 두 가지를 더 발견했습니다. 가이드의 키 예시(--key "project/test-rule" --namespace project)는 project/project/test-rule로 중복 저장됩니다. 또 메모리는 memory.db(CLI)와 agentdb-memory.db(MCP) 두 곳에 저장됩니다(삭제는 한 번에 둘 다 처리됩니다).
검증 실험 ② 스웜 — 팀원은 누가 움직이나
npx ruflo@3.56.5 swarm init --topology hierarchical --max-agents 8 --strategy specialized명령 옵션의 maxAgents 8이 적용됐지만, 설정 파일 곳곳에는 15가 남아 있었습니다. 그리고 스웜을 만드는 것만으로는 아무것도 실행되지 않았습니다(에이전트 0, 작업 0).
이어서 스웜에 작은 작업을 맡겼습니다. 문자열을 URL에 쓰기 좋은 형태로 바꾸는 slugify 함수와 테스트를 Node 내장 기능만으로 만드는 작업입니다.
| 질문 | 관찰 결과 |
|---|---|
| 최대 에이전트 | 8 |
| 역할은 누가 | researcher는 메인이 직접, coder/tester/reviewer는 Claude Code 서브에이전트(general-purpose). 화면에 Teammate/team-lead 표시 → Agent Teams 기능 |
| 라우터 | 한국어 프롬프트에 "tester 60%" 추천. 근거는 test 키워드 매칭 |
| 실행 주체 | 전부 Claude Code. Ruflo 장부(agent list)는 작업 내내 Idle, 작업 0, 메시지 0 |
Ruflo 문서에 적힌 대로 실제로 일을 한 것은 Claude Code였습니다. 이번 관찰에서는 Ruflo의 조정 기록조차 비어 있었습니다.
검증 실험 ③ Ruflo vs plain
그렇다면 Ruflo가 없으면 어떻게 될까요? Ruflo가 없는 폴더(plain)와 Ruflo 폴더의 새 세션에 같은 프롬프트를 넣고 /usage로 측정했습니다.
| 항목 | Ruflo 재실행 | plain |
|---|---|---|
| 실행 방식 | coder·tester 병렬 | coder·tester 병렬 |
| Ruflo 장부 등록 | 안 함 (1차 땐 함) | — |
| 라우터 | 1차와 동일 tester 60% (학습 효과 안 보임) | — |
| 추정 비용 | $2.21 | $1.70 |
| output / cache read | 15.2k / 2.6M | 12.1k / 1.5M |
| 메인 요청 수 | 13 | 9 |
역할 분담 방식은 같았는데 비용은 약 30%, cache read(이미 읽은 내용을 캐시에서 다시 읽은 양)는 73% 늘었습니다. Ruflo의 CLAUDE.md와 스킬이 매 요청 함께 로드되고, 공식 문서에 따르면 Agent Teams는 팀원마다 CLAUDE.md·MCP·스킬을 각자 로드하기 때문으로 추정됩니다.
결과물도 비교했습니다.
| 입력 | Ruflo 1차 | Ruflo 재실행 | plain |
|---|---|---|---|
| Straße | stra-e | straße | straße |
| 안녕 세상 | "" (빈 문자열) | 안녕-세상 | 안녕-세상 |
| नमस्ते | "" | नमसत (훼손) | नमस्ते |
| ガギ | "" | カキ (다른 단어) | ガギ |
Ruflo 재실행은 테스트 13/13을 통과했지만, 리뷰 에이전트가 찾은 버그를 고치지 않아 글자를 조용히 바꾸고 있었습니다. 테스트 통과가 곧 정확함은 아니라는 사례입니다. 또 3번 실행에서 설계가 3가지로 나와, 이번 관찰에서는 도구 차이보다 실행할 때마다의 편차가 더 컸습니다.
결론과 실무 판단 기준
먼저 한계를 분명히 해둡니다. 이번 결과는 작은 단일 기능 작업 하나를 조건별로 1~2회 실행한 관찰이고, hive-mind나 백그라운드 워커 같은 기능은 검증하지 않았습니다. 비용도 /usage 추정치입니다. 따라서 "Ruflo는 쓸모없다"가 아니라 "이 규모의 작업에서는 이점이 보이지 않았다"가 정확한 결론입니다.
실제 프로젝트에 붙일 때의 안전 레시피
# ① 전역 파일·모드 없이 버전 고정 설치
npx ruflo@3.56.5 init --no-global --no-mods
# ② 런타임 파일 git 제외
printf '\n.swarm/\nruvector.db\n' >> .gitignore
# ③ settings.json env에 RUFLO_NO_AUTO_ENABLE=1, RUFLO_FUNNEL=0 추가
# ④ .mcp.json과 CLAUDE.md의 @latest를 버전으로 고정
# ⑤ 자동 허용 목록(permissions) 재검토언제 Ruflo 없이 충분한가
작은 기능 단위 작업이라면 Claude Code 기본 서브에이전트 + 잘 짠 프롬프트(역할·제약·검증·관찰 기록)로 같은 역할 분담이 가능했습니다. 한국어 사용자라면 Ruflo 메모리는 영어로 저장·검색하거나, 키로 직접 조회하는 것이 안전합니다.
도구 검증 방법론
- 가이드 대신 패키지 소스를 직접 읽기
- git 기준점으로 모든 변경 추적
- 대조군 있는 실험 (영어/한국어, Ruflo/plain)
- AI의 제안도 소스로 검증
마무리
이번 편에서는 Ruflo를 설치하는 데서 그치지 않고, 소스와 실험으로 "에이전트 팀 운영"의 실체를 확인했습니다. 실행은 Claude Code가, 조정은 Ruflo가 맡는다는 구조를 직접 확인했고, 이번 작업 규모에서는 조정 레이어의 이점보다 비용이 먼저 보였습니다.
다음에는 이번 실험의 한계를 보완해, 반복 실행(n≥3)과 여러 파일에 걸친 큰 작업으로 Ruflo와 plain을 다시 비교하고 hive-mind·백그라운드 워커도 검증해볼 예정입니다. 오늘 정리한 안전 설치 레시피를 Claude Code 스킬로 만들어 명령 한 줄로 적용하는 것도 함께 시도해보겠습니다.
