AgentHub — 멀티에이전트 협업
N개의 병렬 AI 에이전트를 생성하여 동일한 작업을 두고 경쟁시킵니다. 각 에이전트는 격리된 git 워크트리에서 작동합니다. 코디네이터가 결과를 평가하고 승자를 병합합니다.
슬래시 명령어
| 명령어 | 설명 |
|---|---|
/hub:init | 새 협업 세션 생성 — 작업, 에이전트 수, 평가 기준 |
/hub:spawn | 격리된 워크트리에서 N개의 병렬 하위 에이전트 실행 |
/hub:status | DAG 상태, 에이전트 진행률, 브랜치 상태 표시 |
/hub:eval | 메트릭 또는 LLM 평가자로 에이전트 결과 순위 매기기 |
/hub:merge | 승리 브랜치 병합, 패자 브랜치 보관 |
/hub:board | 에이전트 메시지 보드 읽기/쓰기 |
/hub:run | 일회성 라이프사이클: init → baseline → spawn → eval → merge |
에이전트 템플릿
--template 옵션으로 스폰할 때 에이전트는 미리 정의된 반복 패턴을 따릅니다:
| 템플릿 | 패턴 | 사용 사례 |
|---|---|---|
optimizer | 수정 → 평가 → 유지/폐기 → 10회 반복 | 성능, 지연 시간, 크기 |
refactorer | 재구조화 → 테스트 → 통과할 때까지 반복 | 코드 품질, 기술 부채 |
test-writer | 테스트 작성 → 커버리지 측정 → 반복 | 테스트 커버리지 갭 |
bug-fixer | 재현 → 진단 → 수정 → 검증 | 버그 수정 접근법 |
템플릿은 references/agent-templates.md에 정의되어 있습니다.
이 스킬이 활성화되는 조건
트리거 문구:
- "try multiple approaches"
- "have agents compete"
- "parallel optimization"
- "spawn N agents"
- "compare different solutions"
- "fan-out" 또는 "tournament"
- "generate content variations"
- "compare different drafts"
- "A/B test copy"
- "explore multiple strategies"
코디네이터 프로토콜
메인 Claude Code 세션이 코디네이터 역할을 합니다. 다음 라이프사이클을 따릅니다:
INIT → DISPATCH → MONITOR → EVALUATE → MERGE
1. Init
/hub:init을 실행하여 세션을 생성합니다. 다음 파일이 생성됩니다:
.agenthub/sessions/{session-id}/config.yaml— 작업 설정.agenthub/sessions/{session-id}/state.json— 상태 머신.agenthub/board/— 메시지 보드 채널
2. Dispatch
/hub:spawn을 실행하여 에이전트를 실행합니다. 각 에이전트 1..N에 대해:
- 작업 할당을
.agenthub/board/dispatch/에 게시 isolation: "worktree"옵션으로 Agent 도구를 통해 스폰- 모든 에이전트를 하나의 메시지로 병렬 실행
3. Monitor
/hub:status를 실행하여 진행 상황을 확인합니다:
dag_analyzer.py --status --session {id}는 브랜치 상태를 보여줌- 보드
progress/채널에 에이전트 업데이트가 있음
4. Evaluate
/hub:eval을 실행하여 결과 순위를 매깁니다:
- 메트릭 모드: 각 워크트리에서 eval 명령을 실행하고 숫자 결과를 파싱
- 판사 모드: diff를 읽고 코디네이터가 품질별로 순위 매김
- 하이브리드: 먼저 메트릭을 사용하고, 동점일 경우 LLM 판사 사용
5. Merge
/hub:merge를 실행하여 마무리합니다:
git merge --no-ff로 승리 브랜치를 기본 브랜치에 병합- 패자 태그:
git tag hub/archive/{session}/agent-{i} - 워크트리 정리
- 병합 요약을 보드에 게시
에이전트 프롤토콜
각 하위 에이전트는 다음과 같은 프롬프트 패턴을 받습니다:
당신은 hub 세션 {session-id}의 agent-{i}입니다.
당신의 작업: {작업 설명}
지침:
1. 할당 사항을 .agenthub/board/dispatch/{seq}-agent-{i}.md에서 읽으십시오
2. 워크트리에서 작업하십시오 — 변경, 테스트 실행, 반복
3. 모든 변경사항을 설명적인 메시지와 함께 커밋하십시오
4. 결과 요약을 .agenthub/board/results/agent-{i}-result.md에 작성하십시오
5. 완료되면 종료하십시오
에이전트는 서로의 작업을 보지 않습니다. 서로 통신하지 않습니다. 보드에만 기록하여 코디네이터가 읽을 수 있도록 합니다.
DAG 모델
브랜치 명명
hub/{session-id}/agent-{N}/attempt-{M}
- 세션 ID: 타임스탬프 기반 (
YYYYMMDD-HHMMSS) - 에이전트 N: 순차적 (1부터 에이전트 수까지)
- 시도 M: 재시도 시 증가 (보통 1)
프론티어 탐지
프론티어 = 자식 브랜치가 없는 브랜치 팁입니다. AgentHub의 "leaves" 쿼리와 동일합니다.
python scripts/dag_analyzer.py --frontier --session {id}
불변성
DAG는 추가 전용입니다:
- 에이전트 브랜치를 리베이스하거나 force-push하지 마십시오
- 커밋을 절대 삭제하지 마십시오(보관 후 브랜치 ref만 삭제)
- 모든 접근 방식은 git 태그를 통해 보존됩니다
메시지 보드
위치: .agenthub/board/
채널
| 채널 | 작성자 | 독자 | 목적 |
|---|---|---|---|
dispatch/ | 코디네이터 | 에이전트 | 작업 할당 |
progress/ | 에이전트 | 코디네이터 | 상태 업데이트 |
results/ | 에이전트 + 코디네이터 | 모두 | 최종 결과 + 병합 요약 |
게시 형식
---
author: agent-1
timestamp: 2026-03-17T14:30:22Z
channel: results
parent: null
---
## 결과 요약
- **접근법**: O(n²) 정렬을 해시 맵으로 대체
- **변경된 파일**: 3
- **메트릭**: 142ms (기준: 180ms, 차이: -38ms)
- **신뢰도**: 높음 — 모든 테스트 통과
보드 규칙
- 추가 전용: 게시물을 편집하거나 삭제하지 마십시오
- 고유 파일명:
{seq:03d}-{author}-{timestamp}.md - 모든 게시물에 YAML 프론트매터가 필수입니다
평가 모드
메트릭 기반
다음에 가장 적합: 벤치마크, 테스트 통과율, 파일 크기, 응답 시간.
python scripts/result_ranker.py --session {id} \
--eval-cmd "pytest bench.py --json" \
--metric p50_ms --direction lower
순위 매기기는 각 에이전트의 워크트리 디렉토리에서 eval 명령을 실행하고 stdout에서 메트릭을 파싱합니다.
LLM 판사
다음에 가장 적합: 코드 품질, 가독성, 아키텍처 결정.
코디네이터가 각 에이전트의 diff(git diff base...agent-branch)를 읽고 다음 기준으로 순위를 매깁니다:
- 정확성 (작업을 해결하는가?)
- 단순성 (변경된 줄이 적을수록 선호)
- 품질 (깔끔한 실행, 좋은 구조)
하이브리드
먼저 메트릭을 실행합니다. 상위 에이전트가 서로 10% 이내에 있으면 LLM 판사를 사용하여 동점을 깨줍니다.
세션 라이프사이클
init → running → evaluating → merged
→ archived (승자가 없을 경우)
상태 전환은 session_manager.py에 의해 관리됩니다:
| 시작 상태 | 종료 상태 | 트리거 |
|---|---|---|
init | running | /hub:spawn 완료 |
running | evaluating | 모든 에이전트 반환 |
evaluating | merged | /hub:merge 완료 |
evaluating | archived | 승자 없음 / 모두 실패 |
사전 트리거
코디네이터는 다음 신호에 따라 행동해야 합니다:
| 신호 | 조치 |
|---|---|
| 모든 에이전트 충돌 | 실패 요약 게시, 다른 제약 조건으로 재시도 제안 |
| 기준 대비 개선 없음 | 세션 보관, 다른 접근법 제시 |
| 고아 워크트리 발견 | session_manager.py --cleanup {id} 실행 |
세션이 running에 멈춤 | 보드에서 진행 상황 확인, 타임아웃 고려 |
설치
# Claude Code 스킬 디렉토리에 복사
cp -r engineering/agenthub ~/.claude/skills/agenthub
# 또는 ClawHub를 통해 설치
clawhub install agenthub
스크립트
| 스크립트 | 목적 |
|---|---|
hub_init.py | .agenthub/ 구조 및 세션 초기화 |
dag_analyzer.py | 프론티어 탐지, DAG 그래프, 브랜치 상태 |
board_manager.py | 메시지 보드 CRUD (채널, 게시물, 스레드) |
result_ranker.py | 메트릭 또는 diff 품질별로 에이전트 순위 매기기 |
session_manager.py | 세션 상태 머신 및 정리 |
관련 스킬
- autoresearch-agent — 단일 에이전트 최적화 루프 (N개 에이전트 경쟁이 필요하면 AgentHub 사용)
- self-improving-agent — 자기 수정 에이전트 (외부 경쟁이 필요하면 AgentHub 사용)
- git-worktree-manager — Git 워크트리 유틸리티 (AgentHub는 내부적으로 워크트리 사용)