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

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

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

---

## 1. ⚙️ 사전 요구사항
MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의존합니다. 설치 전에 확인해 주세요.
*   **tmux**: 에이전트를 백그라운드 격리 Pane에서 구동하기 위한 프로세스 컨테이너
*   **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사
*   **sqlite3**: 트랜잭션 안전성 및 오케스트레이션 락 보장
*   **rsync**: `.agents/` 오케스트레이터 및 스킬 폴더 복제 및 동기화
*   **python3-yaml (pyyaml)**: 세션 데이터 YAML 저장 및 로드 의존성 (`pip install pyyaml`)

---

## 2. 🚀 자동 설치 방법

MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다.

### 설치 스크립트 실행
MAM 레포지토리 루트에서 다음 명령어를 실행합니다.
```bash
# 기본 사용법 (타겟 프로젝트 경로 지정)
$ 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
$ 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` 를 경유해 접속합니다.)
```bash
$ tmux -L multi-agent-mux attach -t my-project-dev-claude
```
*   **화면 탈출**: 대화 중 세션을 유지한 채 터미널로 돌아오려면 `Ctrl + B`를 누른 뒤 `D` 키를 차례로 입력합니다.

### 3) 에이전트 상태 복원 (Resume)
세션이 중지되었거나, 호스트 재기동으로 tmux가 소멸한 경우에도 이전 대화 ID 및 격리 디렉토리를 원자적으로 이어받아 다시 기동할 수 있습니다.
```bash
# 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")

# 2단계: 동적 격리 인자 주입 스폰 수행 후 레지스트리 상태 running 복구
# (상세 쉘 명령어는 .agents/skills/multi-agent-mux-resume/SKILL.md 참조)
```

### 4) 세션 종료 및 정리 (Stop / Purge)
세션을 정지시키고 대화 컨텍스트를 동결하거나(default), 완전히 소멸시킵니다(`--purge-conversation`).
```bash
# 대화 메타데이터를 백업 및 영속화하고, 안전하게 종료 (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`)을 준수해 주세요.