가이드 & 문서 멀티에이전트 하네스 엔진 사용 가이드

하네스 엔진 설치, 설정, 활용을 위한 공식 가이드

빠른 시작

1

자격 증명 발급

toollysoft@gmail.com으로 문의하시면 사용자명과 패스워드를 발급해 드립니다.

2

설치 스크립트 실행

공식 저장소에서 하네스 엔진을 설치합니다.

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

3

환경 설정 실행

사용자, 세션명, 프로젝트 루트를 입력하여 harness.local.json을 자동 생성합니다.

bash setup-env.sh

4

하네스 시작

4-Pane tmux 세션을 기동하고 데몬을 시작합니다.

bash scripts/harness-start.sh start

아키텍처

기본 구성은 4-Pane입니다. 각 Pane에는 고정된 역할을 가진 Claude Code 인스턴스가 실행됩니다. 자동 체인 흐름은 사람의 개입 없이 Pane 간 작업을 연결합니다.

Pane 0

Opus

오케스트레이터

파이프라인을 설계하고 작업을 분해하여 하위 워커에 위임하며, 최종 검토를 수행합니다.

Pane 1

Sonnet

백엔드 엔지니어

PHP, API, 데이터베이스 로직을 구현합니다. 완료 보고 후 ACK를 대기합니다.

Pane 2

Haiku

런타임 가디언

구문 검사와 응답 확인을 수행하며 PASS 또는 FAIL로 회신합니다. 코드를 직접 수정하지 않습니다.

Pane 3

Sonnet

프론트엔드 엔지니어

HTML, CSS, JavaScript를 전담하며 백엔드 Pane과 독립적으로 병렬 진행됩니다.

사용자 → Opus (설계·위임) → Sonnet (구현·보고) → 자동 체인 → Haiku (검증) → Opus (종결 또는 재위임)

핵심 기능

선언형 자동 체인

설정 파일의 선언형 규칙에 따라, 특정 태그와 키워드가 감지되면 다음 단계의 작업이 자동으로 전달됩니다. 쿨다운과 시그니처 기반 중복 실행 방지 기능이 내장되어 있습니다.

주기적 헬스체크 + 자동 재시작

데몬이 각 Pane의 프로세스 상태를 주기적으로 점검합니다. 이상 감지 시 자동 재시작을 시도하며, 한도 초과 시 오케스트레이터에 에스컬레이션합니다.

태스크 큐 + ACK

각 작업에는 고유 ID가 부여됩니다. 워커는 수신 즉시 확인 응답을 발신하여 중복 실행을 방지합니다. 검증 통과 후 오케스트레이터가 CLOSE를 발신하여 작업을 종결합니다.

자동 검증

검증 전담 Pane이 각 구현 결과에 대해 문법 검사, 응답 확인, 회귀 테스트를 자동 실행합니다. 코드를 직접 수정하지 않고 PASS 또는 FAIL만 반환합니다.

로그 로테이션

로그 파일은 설정된 크기 임계값을 초과하면 자동으로 아카이브되어 장기 실행 세션에서 디스크 소진을 방지합니다.

Fallback 라우팅

재시도 후에도 메시지 전송에 실패하면 지정된 Fallback Pane으로 우회합니다. Fallback도 실패하면 최후 수단으로 오케스트레이터에 에스컬레이션합니다.

중복 실행 방지

시그니처 매칭을 통해 동일 체인 트리거의 중복 실행을 차단합니다. 쿨다운 기간 내에서 동일 작업은 재트리거되지 않습니다.

설정 레퍼런스

단일 JSON 설정 파일이 진입점입니다. 환경별 로컬 오버라이드 파일로 기본 설정을 수정하지 않고 값을 커스터마이징할 수 있습니다.

{
  "session":        "harness",
  "project_root":   "/path/to/your/project",
  "poll_interval":  <seconds>,
  "timeout":        <seconds>,
  "health_interval": <seconds>,
  "panes":          [ { "id": 0, "role": "orchestrator" }, ... ],
  "auto_chain":     [ ... ],
  "fallback_panes": { ... }
}

주요 필드

필드	설명
session	세션명
project_root	프로젝트 루트 절대 경로
poll_interval	데몬 폴링 주기(초)
timeout	메시지 전송 타임아웃(초)
panes[]	Pane 정의 (id, role, 담당 영역)
auto_chain[]	자동 체인 트리거 규칙
fallback_panes	Fallback 라우팅 맵
health_interval	헬스체크 주기(초)

운영 스크립트

모든 스크립트는 scripts/ 디렉터리에 위치합니다. 프로젝트 루트에서 실행하십시오.

스크립트	역할
harness-start.sh start	4-Pane 세션 기동 및 데몬 시작
harness-start.sh stop	데몬 및 세션 정상 종료
harness-start.sh status	데몬 상태 및 Pane 헬스 출력
harness-report.sh	해석된 하네스 설정 값 출력
setup-env.sh	harness.local.json 대화형 생성
install-check.sh	5개 의존성 도구 설치 여부 검증
log-rotate.sh	로그 파일 로테이션 및 아카이브
regression-test.sh	회귀 테스트 스위트 실행
pane-msg.sh	대상 Pane으로 태그 메시지 전송

설치 상세

Debian / Ubuntu (apt)

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

RHEL / Rocky Linux (rpm)

curl -fsSL https://mytoolly.com/install.sh | sudo bash -s -- <username> <password>

업데이트 명령

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install --only-upgrade toolly-harness

# RHEL/Rocky
sudo yum update toolly-harness

GPG 키	모든 패키지는 RSA/SHA256으로 서명됩니다. 공개 키는 설치 스크립트가 자동으로 내려받습니다.
런타임 의존성	python3, tmux, jq, claude CLI

다운로드 및 자료

중급

Claude 모델 오케스트레이션으로 비용을 줄이는 실전 가이드

무료 다운로드

이메일을 입력하시면 파일을 다운로드할 수 있습니다.

마케팅 정보 수신에 동의합니다 (선택)