multi-agent-mux/deploy/INSTALL.md

🛠️ Multi-Agent Mux (MAM) 설치 및 적용 가이드

MAM은 단일 워크스페이스 상에서 복수의 에이전트(Claude, Cline, Agy, Hermes 등)들이 서로의 상태를 오염시키지 않고 협업할 수 있도록 프로세스 격리 및 라이프사이클 관리를 제공하는 프레임워크입니다.

이 가이드는 기존의 다른 프로젝트/레포지토리에 MAM을 신속하게 도입하고 적용하는 절차를 설명합니다.

---

1. ⚙️ 사전 요구사항

MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의존합니다. 설치 전에 확인해 주세요.

• herdr: 에이전트를 백그라운드 격리 Pane/Workspace에서 구동 및 관제하기 위한 프로세스 컨테이너
• python3: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 sqlite3 모듈 필수)
• uuidgen: 격리 세션 생성 시 고유의 UUID 할당
• rsync: 인스톨러(deploy/install_mam.sh)가 .agents/ 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요)
• python3-yaml (pyyaml): 세션 데이터 YAML 저장 및 로드 의존성 (pip install pyyaml)

---

2. 🚀 자동 설치 방법

MAM의 자동 설치 스크립트(deploy/install_mam.sh)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 herdr, python3, rsync, uuidgen 및 필수 파이썬 모듈들을 진단합니다.

Important

설치 전제조건: MAM 스킬을 타겟 프로젝트에 설치하려면 먼저 MAM 레포지토리가 로컬 머신에 clone 되어 있어야 합니다.

설치 스크립트 실행

MAM 레포지토리 루트 디렉토리로 이동한 후 다음 명령어를 실행합니다.

# 기본 사용법 (타겟 프로젝트 경로 지정)
$ bash deploy/install_mam.sh --target /path/to/your/project

# 만약 이미 타겟에 AGENTS.md 가 존재하여 강제로 덮어쓰고 싶다면:
$ bash deploy/install_mam.sh --target /path/to/your/project --force

설치 스크립트가 수행하는 작업:

1. 의존성 진단: 시스템에 herdr, python3, rsync, uuidgen CLI 바이너리와 파이썬 pyyaml/sqlite3 모듈이 설치되어 있는지 확인합니다.
2. 규칙 및 스킬 복제: 오케스트레이션 가이드(.agents/ 하위 전체)를 타겟 프로젝트 하위로 이식합니다.
3. 지침 전파: 에이전트가 로드하고 복종할 행동 지침 문서(AGENTS.md)를 프로젝트 루트에 복사합니다.
4. 형상 제외 설정: 세션 DB 및 격리 캐시 저장소인 .mam/ 디렉토리를 타겟 프로젝트의 .gitignore 에 자동 주입하여 불필요한 형상 관리를 방지합니다.

---

3. 🎯 핵심 사용 워크플로우 (Quick Start)

설치가 완료되면, 타겟 프로젝트 루트에서 에이전트들을 기동 및 관리할 수 있습니다.

1) 에이전트 격리 세션 생성 (Create)

새로운 에이전트를 독립된 격리 가상 디렉토리에서 띄웁니다.

$ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
    --workspace "/path/to/your/project" \
    --agent claude \
    --role developer \
    --session my-project-dev-claude \
    --herdr-server multi-agent-mux

• 모든 세션은 사용자의 전역 에이전트 설정(Global Config)을 공유하며, herdr 프로세스 격리 및 대화 UUID 단위로 독립 구동됩니다.

2) 세션 접속 (Attach)

백그라운드에서 구동된 에이전트 TUI 화면에 들어갑니다.

$ herdr session attach my-project-dev-claude

• 화면 탈출: 대화 중 세션을 유지한 채 터미널로 돌아오려면 Ctrl + B를 누른 뒤 D 키를 차례로 입력합니다.

3) 에이전트 상태 복원 (Resume)

세션이 중지되었거나, 호스트 재기동으로 herdr 서버가 소멸한 경우에도 이전 대화 ID를 원자적으로 이어받아 다시 기동할 수 있습니다.

# 1단계: 복원 대상 세션의 UUID 자동 조회 (DB/YAML 레지스트리 기반)
$ WORKSPACE="/path/to/your/project"
$ AGENT="claude"
$ SESSION_NAME="my-project-dev-claude"

$ UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh \
    --workspace "$WORKSPACE" --agent "$AGENT" --session "$SESSION_NAME")
 
# 복원 대상 세션의 유효성 검사 (M-1)
$ [ -n "$UUID" ] || { echo "[ERROR] 매칭되는 활성 세션 이력이 없습니다. create_session.sh를 통해 먼저 세션을 생성해 주세요."; exit 1; }
 
# 2단계: 세션 재기동 (이전 대화 컨텍스트 복원 기동)
$ herdr run -d --name "$SESSION_NAME" --workspace "$WORKSPACE" -- \
    "claude --dangerously-skip-permissions -r $UUID"
 
# 3단계: 레지스트리 세션 상태를 running 으로 동기화 갱신
$ bash .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
    --session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT"

4) 세션 종료 및 정리 (Stop / Purge)

세션을 정지시키고 대화 컨텍스트를 동결하거나(default), 완전히 소멸시킵니다(--purge-conversation).

# 대화 메타데이터를 백업 및 영속화하고, 안전하게 종료 (status=stopped)
$ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
    --session my-project-dev-claude --agent claude

# 대화 내용 및 격리 홈 디렉토리를 완전히 청소하고 종료 (status=terminated, resumable=false)
$ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \
    --session my-project-dev-claude --agent claude --purge-conversation --yes

5) 자율 반복 정제 루프 기동 (Mux-Loop)

계획 수립(Planner) ➜ 코드 수정(Creator) ➜ 교차 검증(Reviewer) ➜ 수정 정제 피드백을 단일 명령으로 자동 순환하는 반복 정밀 관제 루프를 기동합니다.

# 플래너 협력 계획 단계를 활성화하고, 리뷰어의 PASS 합의 하에 자율 루프 구동 (최대 3회 교정)
$ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
    --plan \
    --plan-talk 1 \
    --reviewer "reviewer-a,reviewer-b" \
    --max-loop 3 \
    --creator my-project-dev-claude \
    --task "구현할 명확한 개발 작업 목표"

• --max-loop는 코드 오류 발견 시 최대 교정(반복 수정) 횟수 제한 가드레일 역할을 합니다.
• 참고: 리뷰 단계에서 코드 변경분을 정확하게 추적하기 위해, 타겟 프로젝트 디렉토리는 git 저장소로 기동 및 관리되고 있는 것을 권장합니다.

6) 오케스트레이터 온보딩 (Orc-Onboard)

오케스트레이터 에이전트의 대화 UUID를 레지스트리에 등록하여, 서브에이전트 탐지 루프에서 오케스트레이터 대화가 서브에이전트로 오탐 capture되는 것을 방지합니다.

# 오케스트레이터 대화 UUID 온보딩 (자동 탐지 또는 명시적 지정)
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --uuid <orchestrator_uuid>

# 등록된 오케스트레이터 UUID 목록 확인
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --list

# 등록된 오케스트레이터 UUID 제거 (오프보딩)
$ bash .agents/skills/multi-agent-mux-orc-onboard/scripts/orc_onboard.sh --remove <orchestrator_uuid>

7) 전용 NATS 메시징 브로커 설정 (.mam.env)

MAM은 비동기 작업 위임(multi-agent-mux-delegate-job) 및 이벤트 스트림 중계를 위해 MQTT 3.1.1 및 JetStream 기반의 사설 NATS 브로커(nats-docker)를 표준으로 지원합니다.

• 환경 설정 생성: bash deploy/generate-env.sh (또는 cp .mam.env.example .mam.env)를 실행하여 로컬 .mam.env를 생성합니다.
• 서브모듈 동기화: git submodule update --init --recursive 명령어로 nats-docker/ 배포 자산을 초기화합니다. (사내 비공개 저장소 laa/nats-docker 접근 권한이 없는 경우 서브모듈 동기화를 생략해도 표준 MQTT 브로커를 통해 기본 프레임워크 기능이 완비됩니다.)
• 사설 서버 배포 가이드: 자세한 도커 배포 및 Tailscale 연동 절차는 nats-docker/PRIVATE_SERVER.md 및 MESSAGING.md를 참조하십시오.

---

🛡️ 협업 및 보안 가이드라인

• MAM을 사용할 때 모든 에이전트(개발자, 리뷰어)들은 루트의 AGENTS.md 지침을 우선 숙지하도록 설계해야 오탐과 무분별한 리팩토링 범람을 방지할 수 있습니다.
• 각 에이전트 역할별로 리뷰 프로세스를 돌릴 시, 최종 승인 결과 보고서(.md)는 형상 관리가 추적할 수 있도록 버전 관리 대상 경로(구체적으로 .agents/reports/<session_name>/ 또는 docs/reports/ 등) 하위로 이관 복사하여 커밋하는 규약(.agents/MULTI_AGENT_RULES.md)을 준수해 주세요.