Multi-Agent Collaboration Workflow Reference Guide

본 문서는 대규모 프로젝트나 정밀한 설계·구현 요구사항을 처리하기 위해 Planner, Developer, Reviewer 에이전트 간의 역할 분담 및 피드백 루프를 운영하는 **다중 에이전트 협업 워크플로우(Multi-Agent Collaboration Workflow)**를 정의합니다. 다수의 에이전트 간 협업을 위해서는 앞으로 수동 프롬프트 환류가 아닌, 자동화된 multi-agent-mux-loop 스킬만을 단독으로 사용하여 자율 루프를 기동합니다.

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)

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

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

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

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

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

3. Best Practices & 자동화 지침

수동 템플릿 작성 및 전달은 폐지되었습니다. 모든 에이전트 간 피드백 루프는 multi-agent-mux-loop를 활용해 자동으로 오케스트레이션합니다.

3.1. 개념-옵션 매핑 규격

워크플로우 단계별로 활용할 수 있는 run_loop.sh 옵션 규격은 다음과 같습니다:

워크플로우 단계	해당 CLI 옵션	설명
Phase 1: Planning	`--plan`	Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다.
Phase 1: Debate	`--plan-talk N`	Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다.
Phase 2: Execution	(기본값)	`--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다.
Phase 3: Review	`--reviewer "A,B"`	지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다.
Phase 3: Consensus	`--all-reviewer`	모든 리뷰어가 PASS를 냈을 때만 최종 통과를 허용합니다. (미지정 시 1명만 PASS여도 통과)
Iterative Loop	`--max-loop M`	NOT PASS 또는 린트 실패 시 최대 `M`회까지 Planner와 Creator 간 피드백 루프를 반복합니다.

3.2. 실전 자율 루프 기동 예시

bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --plan \
  --plan-talk 1 \
  --reviewer "canary-projects-multi-agent-mux-reviewer-cline,canary-projects-multi-agent-mux-reviewer-agy" \
  --all-reviewer \
  --max-loop 3 \
  --target-agent "canary-projects-multi-agent-mux-creator-agy" \
  --task "작업할 상세 요구사항을 여기에 입력..."

3.3. 동작성 제약 및 Pitfalls

세션 가동 전제: run_loop.sh 기동 전에 타겟 세션(Planner, Target Agent, Reviewer)들이 모두 tmux 세션으로 기동되어 (status.sh 기준 alive 및 running) 있어야 합니다.
동시 루프 기동 금지: 동일한 작업 트리 내에서 다수의 run_loop.sh 제어기를 동시에 기동하면 SQLite DB 갱신 경합 및 YAML 데이터 오염이 발생하므로 절대로 병렬 기동하지 마십시오.
정형 토큰 단독 행 작성 필수: 앵커링 파서 하드닝에 의해, 리뷰 리포트 파일 내에서 [VERDICT: PASS] 또는 [VERDICT: NOT PASS] 토큰은 반드시 리포트의 마지막에 단독 행으로 기재되어야 합니다. 코드 인용이나 변경 diff 내의 토큰은 매칭 대상에서 완전 배제됩니다.
결함 시 fail-closed: 최종 Verdict 토큰이 누락되거나 리포트 픽업 실패 시, 파서는 안전을 위해 NOT PASS로 오픽업(Fail-closed) 판정하여 교정 사이클을 수행하므로 반드시 리포트 끝에 단독 행으로 토큰을 찍도록 지시해야 합니다.
원자적 아카이빙 (Promotion): 루프 성공 종료 시 최종 계획서와 검증 리포트들은 .agents/reports/<session_name>/ 디렉토리로 원자적으로 덮어쓰기(mv -f)되어 보존되므로, 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다.

9.4 KiB Raw Blame History