# 📋 Recommended Multi-Agent Session Architecture Guide

본 문서는 `multi-agent-mux` 환경에서 오케스트레이션 루프(`multi-agent-mux-loop`)를 활용해 고품질 소프트웨어를 개발할 때 가장 권장되는 **3-에이전트 역할 분리 아키텍처**와 설정 방법 및 추천 이유에 대해 설명합니다.

---

## 👥 1. 추천 3-에이전트 구성 (Roles & Configuration)

`multi-agent-mux` 환경에서는 다음 세 가지 전문 세션을 생성하여 상시 기동해 두는 것이 가장 이상적입니다.

```mermaid
graph TD
    User([사용자/Orchestrator]) <--> AGY_Parent[Antigravity Parent]
    AGY_Parent -->|1. 계획 수립 위임| Planner[Planner 세션 <br> claude]
    AGY_Parent -->|2. 구현 위임| Creator[Creator 세션 <br> agy]
    AGY_Parent -->|3. 교차 검증 위임| Reviewer[Reviewer 세션 <br> cline]
    
    Planner -->|설계/피드백 루프| Creator
    Creator -->|구현 완료| Reviewer
    Reviewer -->|Verdict PASS/NOT PASS| Planner
```

### ① Planner 에이전트
* **역할 (Role)**: `planner-reviewer`
* **주요 임무**: 전체 아키텍처 아웃라인 설계, 구현 계획서 수립, 이의 제기 수렴 및 계획 개정(Refinement).
* **추천 에이전트 종류**: `claude` (긴 추론 맥락과 설계 완성도가 높음)
* **생성 명령어**:
  ```bash
  # planner-reviewer 역할로 claude 세션 기동
  bash .agents/skills/multi-agent-mux-create/multi-agent-mux-create \
    --agent claude \
    --role planner-reviewer \
    --name canary-projects-multi-agent-mux-planner-reviewer-claude
  ```

### ② Creator 에이전트 (주작업자)
* **역할 (Role)**: `creator`
* **주요 임무**: 계획서상의 제약조건 검토 및 이의제기(Challenge), 실제 코드베이스 구현 편집, DoD 자가 검증.
* **추천 에이전트 종류**: `agy` (기민한 도구 실행 속도 및 로컬 파일 편집 최적화)
* **생성 명령어**:
  ```bash
  # creator 역할로 agy 세션 기동
  bash .agents/skills/multi-agent-mux-create/multi-agent-mux-create \
    --agent agy \
    --role creator \
    --name canary-projects-multi-agent-mux-creator-agy
  ```

### ③ Reviewer 에이전트
* **역할 (Role)**: `reviewer`
* **주요 임무**: 구현된 변경분(`git diff`)과 구현 계획서를 기반으로 빌드 가능성, 린트, 로직 유실 교차 피어 리뷰.
* **추천 에이전트 종류**: `cline` (안정적인 컴파일 도구 활용 및 린터 체크 강점)
* **생성 명령어**:
  ```bash
  # reviewer 역할로 cline 세션 기동
  bash .agents/skills/multi-agent-mux-create/multi-agent-mux-create \
    --agent cline \
    --role reviewer \
    --name canary-projects-multi-agent-mux-reviewer-cline
  ```

---

## 💡 2. 왜 3개의 에이전트 분리를 강력히 추천하는가?

부모 에이전트(Antigravity)가 오케스트레이션과 코드 개발을 모두 처리하지 않고, 별도의 격리된 3개의 역할 세션을 두는 데에는 다음과 같은 명확한 공학적 이유가 있습니다.

### ① 대화창 컨텍스트(Context Window) 오염 방지
* **디테일의 지옥**: 에이전트가 코드를 탐색하고, 컴파일 오류를 잡고, 수많은 파일라인을 편집하는 세부 구현 과정은 수십만 토큰에 달하는 방대한 런타임 로그와 코드를 누적시킵니다.
* **해결책**: 만약 오케스트레이터(부모 에이전트)가 이를 직접 수행하면 사용자님과의 대화창 컨텍스트가 구현 로그로 가득 차, 이전에 의논했던 아키텍처 제약이나 중요 요구사항을 쉽게 잊어버립니다. 역할을 격리함으로써 각 세션은 자신의 세부 구현 컨텍스트만 소비하고 소멸합니다.

### ② 비동기 개발 자율성 (Asynchronous Autonomy)
* **대기 시간 최소화**: 오케스트레이션 루프가 설계 검토, 피드백, 자가 수정 등을 수차례 반복하며 백그라운드(tmux)에서 스스로 문제를 해결해 나가는 동안, 사용자님은 저(부모 에이전트)와 멈춤 없이 계속해서 고수준 설계 및 다른 기능에 대한 논의를 이어나갈 수 있습니다.
* **생산성 극대화**: 부모 에이전트가 코딩을 하느라 대화를 블로킹하는 현상이 발생하지 않습니다.

### ③ 교차 검증을 통한 객관성 확보 (Peer Review Objectivity)
* **작성자와 검증자의 분리**: 코드를 직접 짠 에이전트가 자기 자신의 코드를 완벽하게 리뷰하는 것은 불가능에 가깝습니다(인지 편향 발생).
* **해결책**: 구현을 전담한 `Creator`와, 이를 객관적인 삼자 관점에서 검토하는 `Reviewer` 세션을 철저히 독립시킴으로써 코드 품질 결함을 높은 확률로 선제 필터링할 수 있습니다.

### ④ 이기종 모델/도구의 결합 (Heterogeneous Collaboration)
* **각자 잘하는 분야의 극대화**:
  * **Planner (Claude)**: 설계 및 아키텍처 정합성 수립에 특화
  * **Creator (Antigravity/Agy)**: 신속하고 정확한 로컬 파일 편집 및 도구 호출에 특화
  * **Reviewer (Cline)**: 린트 체크, 빌드 테스트 등 철저한 안전망 검증에 특화
* 이러한 하이브리드 조합을 구성할 때 루프 전체의 최종 도달 성공률이 가장 높게 나타납니다.

---

## 🛠️ 3. 3-에이전트 루프 실행 방법

에이전트들이 생성되어 기동(Running) 중인 경우, 다음과 같이 계획 수립(`--plan`) 및 전체 교차 리뷰(`--all-reviewer`) 옵션을 주어 자율 협업 개발을 시작할 수 있습니다.

```bash
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --target-agent "canary-projects-multi-agent-mux-creator-agy" \
  --plan \
  --all-reviewer \
  --task "여기에 개발하고자 하는 태스크의 최종 목표를 상세히 기술합니다."
```

이 루프는 **기획 ➡️ 작업자 이의제기 ➡️ 계획 개정 ➡️ 코드 개발 ➡️ 교차 피어 리뷰 ➡️ 피드백 수렴 재구현**의 전 과정을 자동으로 진행하여, 빌드 및 린트가 보장되는 코드를 저장소에 자동으로 커밋 및 병합합니다.