multi-agent-mux/RECOMMENDED.md

📋 Recommended Multi-Agent Session Architecture Guide

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

---

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

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

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 (긴 추론 맥락과 설계 완성도가 높음)
• 생성 명령어:

  # 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 (기민한 도구 실행 속도 및 로컬 파일 편집 최적화)
• 생성 명령어:

  # 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 (안정적인 컴파일 도구 활용 및 린터 체크 강점)
• 생성 명령어:

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

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