multi-agent-mux/.agents/INSTALL.md

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

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

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

---

1. ⚙️ 사전 요구사항

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

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

---

2. 🚀 자동 설치 방법

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

설치 스크립트 실행

MAM 레포지토리 루트에서 다음 명령어를 실행합니다.

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

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

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

1. 의존성 진단: 시스템에 tmux, python3, 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 \
    --isolate \
    --tmux-server multi-agent-mux

• --isolate 옵션을 주면 .mam/agent_homes/<uuid>/ 하위에 로그인 및 설정은 유지하되 대화 내역은 격리되는 홈이 형성됩니다.

2) 세션 접속 (Attach)

백그라운드에서 구동된 에이전트 TUI 화면에 들어갑니다. (세션 생성 시 지정한 독립 격리 tmux 서버 소켓 -L multi-agent-mux 를 경유해 접속합니다.)

$ tmux -L multi-agent-mux attach -t my-project-dev-claude

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

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

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

# 1단계: resume/SKILL.md를 참고하여 복원 스크립트 실행 (YAML/DB의 UUID 자동 로드 및 T4 격리 재바인딩)
$ 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단계: 동적 격리 인자 주입 스폰 수행 후 레지스트리 상태 running 복구
# (상세 쉘 명령어는 .agents/skills/multi-agent-mux-resume/SKILL.md 참조)

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

---

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

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