[Claude] 멀티 에이전트 오케스트레이션과 Ralph 루프
목차
📚 Claude Code 정리 노트 (2026-07) — 4부작
1. 제품 명세 문서 2. 멀티 에이전트와 Ralph ← 지금 읽는 글 3. 자율 연구·개발 자동화 4. 브라우저 자동화
1. 멀티 에이전트란?
여러 개의 AI 에이전트가 각자 역할을 맡아 하나의 목표를 위해 협업하는 방식. 하나의 거대한 에이전트가 모든 걸 처리하는 단일 에이전트(single-agent) 방식과 대비된다.
그림: 한 에이전트가 해석→추론→결정→실행을 혼자 담당하는 단일 방식 vs 분류/조율→전문 에이전트 분담→결과 통합으로 나눠 처리하는 멀티 방식.
단일 에이전트 vs 멀티 에이전트
| 구분 | 단일 에이전트 | 멀티 에이전트 |
|---|---|---|
| 비유 | 혼자 다 하는 만능 직원 | 역할 나눠 일하는 팀 |
| 컨텍스트 | 하나의 긴 컨텍스트에 모든 게 누적 | 에이전트별로 독립된 컨텍스트 |
| 실패 양상 | Goal drift, agentic laziness(6/20 노트 15번) | 병렬 검증·반박으로 실패 완화 가능 |
| 비용 | 상대적으로 낮음 | 에이전트 수만큼 증가 |
한 줄 요약: 멀티 에이전트 = 한 명의 만능 일꾼 대신, 역할을 나눈 여러 AI가 협업해 결과를 만드는 방식.
2. 하네스 엔지니어링 다시보기
상세 개념은 2026-06-27 노트 9번에서 이미 다룸. 여기서는 멀티 에이전트의 “기반 층”으로서 위치만 재정리.
개념 한 줄
모델 자체가 아니라, 모델을 감싸 “입력→도구 사용→검증→반복”을 시키는 실행 골격(harness)을 설계하는 기술.
그림: 대화형(Ping-Pong) 프롬프트 엔지니어링 → 스킬형(Skills/Harness) 하네스 엔지니어링 → 시스템형(System Design) 루프 엔지니어링으로의 진화. “프롬프트를 잘 쓰는 단계 → skills를 설계하는 단계 → AI를 움직이는 시스템을 설계하는 단계.” (이 노트가 짚는 거시 진화 축이며, 아래 표는 각 계층의 포함 관계를 따로 정리한다.)
세 엔지니어링의 포함 관계
| 계층 | 다루는 대상 |
|---|---|
| 프롬프트 엔지니어링 | 한 번의 지시문 |
| 컨텍스트 엔지니어링(6/27 노트 6번) | 모델이 보는 정보 전체 |
| 하네스 엔지니어링 | 모델을 감싸는 실행 골격 전체(제어흐름·도구·검증) |
→ 멀티 에이전트 시스템은 하네스 엔지니어링의 대표적인 산출물 중 하나다. 에이전트를 여러 개 두고 어떻게 소통·검증시킬지가 곧 하네스 설계.
한 줄 요약: 하네스 엔지니어링 = 프롬프트·컨텍스트 엔지니어링의 상위 개념으로, 모델을 감싸는 실행 골격 자체를 설계하는 것. 멀티 에이전트 시스템은 그 골격이 “여러 에이전트”로 확장된 형태.
3. 멀티 에이전트 시스템이란?
여러 자율 에이전트가 **통신·조율(때로는 협상)**하며, 단일 에이전트로는 풀기 어렵거나 비효율적인 문제를 함께 해결하도록 설계된 시스템. (분산 AI 연구에서 LLM 이전부터 있던 개념이 LLM 에이전트로 옮겨온 것)
개념 한 줄
“각자 맡은 역할을 가진 에이전트들이, 정해진 방식으로 소통하며 하나의 결과로 수렴하는 시스템.”
왜 하나로 안 하고 여러 개로 나누는가
| 이유 | 설명 |
|---|---|
| 전문화 | 탐색·구현·검증 등 역할별로 다른 시스템 프롬프트·모델 사용 가능 |
| 컨텍스트 격리 | 각자 독립 컨텍스트 → 서로의 잡음이 섞이지 않음 |
| 병렬성 | 동시에 여러 하위 작업을 진행해 시간 단축 |
| 적대적 검증 | 한 에이전트의 결과를 다른 에이전트가 반박·검증 → 오류 발견 확률↑ |
한 줄 요약: 멀티 에이전트 시스템 = 역할을 나눠 통신·조율하는 여러 에이전트로 구성된 문제 해결 시스템. 전문화·격리·병렬성·검증이 핵심 이점.
4. 멀티 에이전트 시스템의 구성 요소
그림: ①오케스트레이터(분배) · ②워커/전문 에이전트(실행) · ③공유 상태·메모리(맥락 공유) · ④통신(전달) · ⑤검증기(확인) · ⑥종료 조건(멈춤)이 중앙의 시스템을 둘러싸고 맞물리는 구조.
| 구성 요소 | 역할 | Claude Code에서의 예 |
|---|---|---|
| 오케스트레이터 / 코디네이터 | 작업을 쪼개 분배하고 전체 진행을 관리 | 메인 대화, dynamic workflow의 JS 코드 |
| 워커 / 전문 에이전트 | 실제 하위 작업을 수행 | 서브에이전트, Agent Teams의 팀원 |
| 공유 상태 / 메모리 | 에이전트들이 참조하는 공통 정보 | 공유 작업 목록(Task List), 파일시스템, git |
| 통신(메시징) | 에이전트 간 정보 전달 방식 | Agent Teams의 Mailbox, 메인↔서브의 요약 보고 |
| 검증기(Verifier/Critic) | 결과가 맞는지 독립적으로 확인 | 적대적 검증 패턴(6/20 노트 15번), doc-reviewer류 |
| 종료 조건 | 언제 멈출지 판단 | 목표 충족, 테스트 통과, 최대 반복 횟수 |
한 줄 요약: 오케스트레이터(분배) + 워커(실행) + 공유 상태(맥락 공유) + 통신(전달) + 검증기(확인) + 종료 조건(멈춤) 이 여섯 가지가 멀티 에이전트 시스템의 기본 골격.
5. 코딩 멀티 에이전트 시스템 사례 — Claude Code
Claude Code 안에서 멀티 에이전트 구성 요소들이 실제로 어떤 기능으로 구현되어 있는지 정리. 상세는 각 이전 노트 참조.
| 방식 | 통신 구조 | 특징 | 출처 |
|---|---|---|---|
| 서브에이전트 | 허브앤스포크(메인에만 보고) | 결과 요약만 반환, 컨텍스트 격리 | 2026-06-20 노트 10번 |
| Agent Teams | 메시(팀원끼리 직접 소통) | 공유 작업목록·Mailbox, 실험적 기능 | 2026-06-20 노트 13·14번 |
| Dynamic Workflow | 오케스트레이터가 JS 코드로 결정론적 조율 | 수십~수백 에이전트 팬아웃, 6가지 조합 패턴 | 2026-06-20 노트 15·16번 |
세 방식의 위치
서브에이전트 : 일꾼 1명씩, 메인이 전부 관리 (단순·저비용)
Agent Teams : 일꾼들끼리 대화하며 협업 (토론·복합 작업)
Dynamic Workflow : 일꾼들을 "코드"로 결정론적으로 지휘 (대규모·고비용·고정확도)한 줄 요약: Claude Code는 서브에이전트(허브앤스포크) → Agent Teams(메시형 협업) → Dynamic Workflow(코드 기반 결정론적 오케스트레이션)까지, 규모와 협업 방식이 다른 멀티 에이전트 구현체를 여러 층으로 제공한다.
6. 루프 엔지니어링 다시보기
상세 개념은 2026-06-27 노트 17번에서 이미 다룸. 여기서는 “될 때까지 반복”이라는 핵심만 재정리하고, 다음 절(Ralph의 기원부터 실행 준비까지)의 Ralph로 이어간다.
개념 한 줄
에이전트를 한 번 실행하고 끝내는 게 아니라, “행동→관찰→결정→반복”의 순환 자체를 시스템으로 설계하는 것.
하네스 엔지니어링과의 관계
| 계층 | 다루는 범위 |
|---|---|
| 하네스 엔지니어링 | 한 번의 실행을 잘 짜인 골격으로 감싸기 |
| 루프 엔지니어링 | 그 골격을 목표 달성까지 반복 구동 |
- OMC의
ralph/autopilot/ultrawork같은 스킬, hooks_and_context의 “The boulder never stops” 문구가 바로 이 “루프가 계속 도는” 상태를 가리킴 - 6/20 노트 15번 dynamic workflow의 Loop-until-done 패턴도 루프 엔지니어링의 코드 구현 사례
한 줄 요약: 루프 엔지니어링 = 에이전트를 한 번이 아니라 “목표 달성 또는 검증 통과까지” 반복 구동하는 시스템을 설계하는 것. 다음 절의 Ralph가 이 아이디어의 대표 사례다.
7. 루프 엔지니어링의 기원과 Ralph
⚠️ “누가 최초로 시작했다”를 딱 잘라 단정하기는 어려운 영역. 아래는 일반적으로 회자되는 계보 정도로 이해할 것.
2026-06-27 노트 17번에서 “루프 엔지니어링”이라는 용어 자체는 비교적 최근(2026년 6월, Peter Steinberger가 문제 제기 → Addy Osmani가 정립)에 이름 붙었다고 정리했다. 하지만 실제 관행— 같은 에이전트를 반복해서 돌려 목표에 도달시키는 방식 — 은 그보다 앞서 커뮤니티에서 **“Ralph”**라는 이름의 기법으로 이미 퍼져 있었다는 게 통설이다.
Ralph 기법 (반복 실행의 실무적 원형)
│
▼ (관행이 널리 퍼짐)
"루프 엔지니어링" 용어 정립 (Steinberger 제기 → Osmani 정리)한 줄 요약: 루프 엔지니어링이라는 이름이 붙기 전부터, 에이전트를 반복 실행해 목표까지 밀어붙이는 방식은 “Ralph”라는 기법으로 이미 실무에서 쓰이고 있었다.
8. Ralph란?
그림: Ralph Loop 한 사이클 — ①에이전트 실행 → ②작업·커밋 → ③상태 인수인계(HANDOFF·git) → ④검증 후, 완료될 때까지 매번 새 컨텍스트로 다시 시작한다. 기억은 대화가 아니라 파일·git이 담당하며, 본질은
while true; do …; done형태의 단순 반복이다.
개념 한 줄
에이전트를 같은 작업 지시(프롬프트 파일)로 계속 반복 호출하면서, 검증(테스트·체크리스트)을 통과할 때까지 스스로 진행 상태를 파일·git에 남기며 밀고 나가게 하는 기법.
핵심 아이디어
| 요소 | 설명 |
|---|---|
| 매 반복은 “새 컨텍스트” | 이전 대화 기억 없이 매번 새로 시작 — 대신 파일시스템·git 커밋이 “기억” 역할(=상태 인수인계/HANDOFF) |
| 자기 참조 루프 | 이전 반복이 남긴 상태(코드, 커밋, 테스트 결과)를 다음 반복이 읽고 이어감 |
| 검증이 종료 조건 | 테스트 통과·체크리스트 완료 등 명확한 성공 기준이 있어야 루프가 멈춤 |
| 단순함이 강점 | 정교한 상태 관리 프레임워크 대신, “반복 + 검증”이라는 단순한 구조로 동작 |
왜 이런 방식이 통하는가
한 번의 실행에서 완벽하게 끝내려 하지 않고, 여러 번의 시도 중 검증을 통과하는 순간에 도달하는 것을 목표로 삼는다 — 사람이 매번 개입해 다음 지시를 주는 대신, 반복 자체가 진행을 만들어낸다.
한 줄 요약: Ralph = 같은 프롬프트로 에이전트를 계속 다시 실행하며, 파일·git 상태를 매개로 진행을 이어가고, 검증을 통과할 때까지 멈추지 않는 자기 참조형 루프 기법.
9. Ralph 실행해보기
아래는 Ralph 방식의 일반적인 실행 흐름을 개념적으로 정리한 것. 구체적인 스크립트·명령은 원본 출처(Ralph 절 링크)를 확인할 것.
그림: PRD 작성 →
prd.json으로 잘게 쪼개기(user story) →ralph.sh실행 → 스토리 선택 → 구현·테스트 → 통과 시 커밋 &prd.json갱신(passes: true) → 진행 상황 기록(progress.txt) → 남은 스토리 반복 → 완료. 매 반복이 남긴 상태를 다음 반복이 이어받는다.
전형적인 흐름
1) 목표·완료 조건 정의
│
2) 작업 지시 파일 작성 (예: PROMPT.md, 또는 스토리를 담은 prd.json — 다음 Ralph 실행 준비(PRD) 절에서 다룸)
│
3) 반복 루프 구성 (예: while true 형태로 에이전트를 계속 호출)
│ ┌─────────────────────────────┐
└─▶│ 에이전트 1회 실행 │
│ - 지시 파일 + 현재 저장소 상태 확인│
│ - 가능한 만큼 진행 (커밋) │
│ - 테스트/검증 실행 │
└─────────────┬───────────────┘
│ 완료 조건 미충족
▼
(에이전트 실행으로 복귀, 반복)
│ 완료 조건 충족
▼
루프 종료실행 시 챙겨야 할 것
| 항목 | 이유 |
|---|---|
| 명확한 완료 조건 | 없으면 루프가 끝없이 돌거나, 엉뚱한 지점에서 멈춤 |
| 상태를 파일/git에 남기기 | 다음 반복이 “새 컨텍스트”이므로, 기록이 곧 기억 |
| 최대 반복 횟수·비용 상한 | 무한 루프에 대한 안전장치 (루프 엔지니어링의 “종료 판단” 요소) |
| 검증 자동화(테스트 등) | 사람이 매번 확인하지 않아도 되게 하는 핵심 장치 |
한 줄 요약: Ralph 실행 = 완료 조건을 정하고 → 지시 파일을 만들고 → 반복 루프를 돌리며 → 매 회차 상태를 남기고 검증하다가 → 조건 충족 시 멈추는 흐름.
10. Ralph 실행 준비 — PRD 작성
Ralph를 돌리기 전, 가장 먼저 해야 할 사람의 일은 코드를 짜는 게 아니라 PRD(제품 요구사항 문서)를 쓰는 것이다.
왜 PRD가 먼저인가
Ralph의 매 반복은 새 컨텍스트로 시작한다(Ralph 절 참고). 즉, 사람이 대화 중간에 “아, 그게 아니라 이렇게 해줘”라고 보정해줄 기회가 계속 있는 게 아니다. 그래서 에이전트가 매 반복마다 참고할 수 있도록, 요구사항을 미리 문서로 못 박아둬야 한다 — 이게 바로 Ralph의 지시 파일(PROMPT.md 등)에 담기는 내용이자, 사실상 PRD/기능 명세서 역할을 한다.
여기서 파트 A(제품 명세 편)와 다시 만난다
| Ralph가 매 반복 참조하는 것 | 대응하는 문서 |
|---|---|
| ”무엇을 만드는가” | PRD(2026-06-27 노트 4번) |
| “각 기능이 정확히 뭘 하는가” | 기능 명세서 |
| ”화면이 어떻게 이어지는가” | 화면 흐름도 |
| ”데이터는 어떻게 생겼는가” | ERD |
| ”완료 조건(성공 기준)“ | 기능 명세서의 검증 규칙 + API 명세서의 응답 계약 |
→ Ralph의 루프가 헤매지 않고 수렴하려면, 애매하지 않은 완료 조건이 문서에 명시돼 있어야 한다. “로그인 기능 만들어줘”가 아니라 “이메일·비밀번호로 로그인, 실패 시 이런 메시지, 성공 시 이 화면으로 이동, 이 API 스펙을 따름” 수준까지.
정리 — 사람의 역할이 이동하는 지점
예전: 사람이 코드를 직접 짠다
지금: 사람이 PRD·명세를 쓴다 → Ralph(루프)가 검증 통과까지 구현을 반복한다이것이 서두(“들어가며”)에서 던진 질문 — AI 에이전트 시대에 사람은 무엇을 할 것인가 — 에 대한 실무적 답이다. **명세를 정확히 쓰는 것(파트 A)**과 에이전트를 조율하는 루프를 설계하는 것(파트 B), 두 가지로 수렴한다.
한 줄 요약: Ralph를 돌리기 전에 사람이 할 일은 PRD·기능 명세·완료 조건을 명확히 쓰는 것. 매 반복이 새 컨텍스트인 Ralph에게는 이 문서가 유일한 “기억”이자 나침반이다.
참고: Ralph는 특정 벤더의 정식 제품이라기보다 커뮤니티에서 회자되는 **기법(technique)**에 가깝다. 실제 적용 전에는 원본 출처(https://snarktank.github.io/ralph) 와 사용 중인 에이전트 도구의 최신 문서를 함께 확인할 것.
11. 랄프는 천하무적인가? — Ralph의 한계
앞의 Ralph 소개부터 실행 준비까지에서 본 것처럼 Ralph는 “PRD만 잘 쓰면 밤새 알아서 돌아가는” 강력한 기법처럼 보인다. 하지만 실제로는 특정 조건을 만족하는 작업에서만 잘 통하는 도구다.
개념 한 줄
Ralph는 만능 자동화가 아니라, “자동으로 검증 가능한 작업”에 한정된 레버리지 도구다.
한계 정리
| 한계 | 내용 |
|---|---|
| 자동 검증 가능한 작업에만 통함 | 목표를 테스트·명확한 성공 기준으로 객관적·자동으로 검증할 수 있어야 루프가 수렴한다. 판단이 많이 필요한(judgment-heavy) 작업이나 모호한 요구사항에는 잘 안 통함 — “모호한 입력 → 모호한 결과.” |
| 토큰·비용 폭증 | 자율 반복 루프는 토큰 소비량이 크다. 큰 코드베이스에서 50회 반복이면 맥락 크기에 따라 API 비용이 $50~100+ 수준까지 갈 수 있음. |
| 종료 조건의 불안정성 | 완료 판정을 단순 문자열 매칭 등으로 하면 불안정하게 종료되거나 끝나지 않을 수 있음 → 반드시 최대 반복 횟수(max-iterations) 같은 안전장치를 둬야 함(Ralph 실행 절 표의 “최대 반복 횟수·비용 상한”과 동일 항목). |
| 컨텍스트 오염(context pollution) | 실패한 시도·무관한 코드가 파일·기록에 계속 쌓여 다음 반복의 모델을 혼란시킬 수 있음. |
| 모니터링 필요 | 방치하면 컴파일조차 안 되는 깨진 코드베이스로 아침을 맞을 수 있음 — 언제 리셋하고 언제 지시를 다시 구조화할지는 사람의 판단이 필요. |
🔗 토큰 폭증은 이전 노트의 Token Maxxing(2026-06-27 노트 1번)과 같은 맥락 — 자율성이 늘수록 토큰 소비가 커지는 트레이드오프. (최대 반복·비용 상한은 위 표대로 Ralph 실행 절의 안전장치와 이어진다.)
결론
Ralph는 기계적·자동검증 가능한 작업에서 2~3배 레버리지를 주는 도구이지, 판단·모호함이 핵심인 일까지 대체하진 못한다. 서두(“들어가며”)의 질문 — AI 에이전트 시대에 사람은 무엇을 할 것인가 — 으로 다시 돌아가면, 사람의 몫은 여기서도 검증 기준을 설계하고, 모호함을 걷어내는 것으로 확인된다.
한 줄 요약: Ralph는 만능이 아니다. 자동 검증 가능한 명확한 작업에서는 강력하지만, 판단이 필요한 모호한 작업·비용 관리·컨텍스트 오염 방지는 여전히 사람의 몫이다.
출처: https://tessl.io/blog/unpacking-the-unpossible-logic-of-ralph-wiggumstyle-ai-coding/ , https://www.leanware.co/insights/ralph-wiggum-ai-coding