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

Multi-Agent Collaboration Workflow Reference Guide

본 문서는 대규모 프로젝트나 정밀한 설계·구현 요구사항을 처리하기 위해 Planner, Developer, Reviewer 에이전트 간의 역할 분담 및 피드백 루프를 운영하는 **다중 에이전트 협업 워크플로우(Multi-Agent Collaboration Workflow)**를 정의합니다.

---

1. 역할 정의 및 분담 (Roles & Responsibilities)

협업 시스템은 각 에이전트의 책임 영역을 명확히 격리하여 상호 교차 검증을 강제합니다.

                  ┌──────────────────────┐
                  │    User Prompt       │
                  └──────────┬───────────┘
                             ▼
                  ┌──────────────────────┐
                  │ 1. Planner Agent     │ ◄──────────────────┐
                  │  - Plan & Checklist  │                    │
                  └──────────┬───────────┘                    │
                             ▼                                │
                  ┌──────────────────────┐                    │
                  │ 2. Developer Agent   │                    │
                  │  - Code & DoD Verify │                    │
                  └──────────┬───────────┘                    │
                             ▼                                │ (NOT PASS Feedback)
                  ┌──────────────────────┐                    │
                  │ 3. Reviewer Agents   │                    │
                  │  - Dual Peer Review  │ ───────────────────┘
                  └──────────┬───────────┘
                             ▼ (PASS)
                  ┌──────────────────────┐
                  │ 4. Done & Commit     │
                  └──────────────────────┘

1.1. Planner Agent (설계 및 통제)

• 목적: 요구사항을 명세화하고, 구현 단계의 설계 결함이나 모순(Contradiction)을 사전에 차단합니다.
• 역할:
  • 사용자 요구사항에 따른 구현 목표 및 범위 수립.
  • implementation_plan.md 및 task.md (체크리스트) 작성 및 버전 관리(Rev.1, Rev.2, ...).
  • 리뷰어 피드백 발생 시 설계 변경의 파급 범위를 계산하여 계획 갱신.
• 핵심 원칙: 직접 코드를 수정하지 않고 오직 설계와 체크리스트 자산만 관리합니다.

1.2. Developer Agent (구현 및 자가 검증)

• 목적: Planner가 제공한 체크리스트를 기반으로 실제 리포지토리 코드를 물리적으로 수정 및 구현합니다.
• 역할:
  • task.md를 순차적으로 완료 상태([x])로 업데이트하며 구현 수행.
  • 커밋 전 Definition of Done (DoD) 체크리스트를 자체 실행하여 금지된 코드 패턴, 메모리/구조적 사이드 이펙트 유무 자가 검토.
  • 수정 사항을 단일 원자적(Atomic) 커밋으로 마감하고 리뷰어에게 전달.

1.3. Reviewer Agents (교차 피드백 및 검증)

• 목적: 구현된 결과물이 최초 설계서 및 학술적 제약 요건에 일치하는지 제3자의 관점에서 엄격하게 검토합니다.
• 역할:
  • Reviewer A (Claude): 학술 서사와 코드 설계 간의 상위 논리적 정합성 및 결함(예: HOLB 해소 주장과 단일 커넥션 다이얼러의 모순 등) 검증.
  • Reviewer B (Cline): 전이 조건, 예외 처리, 타입 시그니처, 텔레메트리 매핑 등 하위 레벨 구현의 세부 사항 기계적 검증.
• 판정 규칙: 두 리뷰어 모두 PASS 판정을 내릴 때까지 개발자는 마감할 수 없으며, 반려 시 **1단계(Planner)**로 피드백이 환류됩니다.

---

2. 세부 운영 단계 (Step-by-Step Workflow)

1단계: 설계 수립 (Planning Phase)

1. 사용자가 요구사항을 제시하면, Planner 에이전트가 프로젝트의 전반적인 구조를 파악합니다.
2. implementation_plan.md 및 task.md를 작성하여 개발을 위한 로드맵을 제공합니다.
3. 사용자가 해당 구현 계획을 승인하면 다음 단계로 이행합니다.

2단계: 코드 구현 및 자가 검증 (Development Phase)

1. Developer 에이전트가 배정된 태스크의 코드를 수정합니다.
2. 작업 진행 중 예상치 못한 설계 변경 필요성이 감지되면 작업을 멈추고 Planner 에이전트에게 계획 수정을 먼저 위임합니다.
3. 구현 완료 후 아래의 DoD 검증을 수행합니다:
   • 핵심 기능의 타입 매핑 확인.
   • 공유 자원(tls.Config 등) 변경 시 사이드 이펙트 방지(복제 후 변이 적용 등).
   • 문서-코드 간 주장의 정합성 체크.
4. 검증 완료 후 단일 커밋을 작성합니다.

3단계: 피드백 루프 및 통과 (Review Phase)

1. Developer 에이전트가 리뷰어 세션에 작업 완료 사실과 변경 범위를 전달합니다.
2. 리뷰어들은 git diff를 바탕으로 개별 검증을 수행하고 보고서 형태의 리뷰 피드백을 출력합니다.
   • 반려 (NOT PASS) -> 피드백 요약본을 Planner 에이전트에게 전송하여 상위 레벨 계획(Rev.n) 개시.
   • 통과 (PASS) -> 모든 검토 사항이 해결되었음을 명시.
3. 모든 리뷰어가 PASS를 발행하면 작업을 완결하고, 다른 에이전트 세션들은 종료하지 않고 다음 태스크 지시가 있을 때까지 프롬프트 대기 상태(Standby)로 유지합니다.

---

3. Best Practices & 템플릿

3.1. 작업 시작 시 Planner 에이전트 프롬프트 템플릿

[역할 요구]
프로젝트의 구조 및 내용을 파악하고, 현재 작업 요건에 맞춰 구현 계획서(implementation_plan.md) 및 태스크 체크리스트(task.md)를 작성해 주세요. 

[검토 초점]
- 설계 수준에서 논리적 모순이 발생할 여지가 없는지
- naive 구현과 대비되는 핵심 차별점이 코드 명세에 정확히 명시되었는지

3.2. 피드백 루프 환류 시 프롬프트 템플릿

Reviewer 검토 결과 구현 코드 차원에서 아래의 블로킹(NOT PASS) 피드백이 발생했습니다.
위 피드백을 수용하여 설계 문서를 수정하는 계획을 수립하고, implementation_plan.md (Rev.[N]) 및 task.md 내용을 업데이트해 주세요.

[피드백 내용]
- [블로킹 항목 1]
- [블로킹 항목 2]