# AI Debate Room (회의실) — 설계서 v2

## 개요

두 AI (AG Gemini 3.1 Pro High + Claude)가 **사회자(Gemini Flash)**의 중재 하에 주제를 토론하고, 정교한 문서를 생산하는 시스템.

- **목적**: 구현 전 설계 문서의 품질을 극대화 (교차 검증 + 반론)
- **결과물**: Wiki.js에 축적되는 설계 명세서
- **원칙**: 회의실은 문서만 생산. 코드 없음. 검증도 문서 수준.

---

## 아키텍처

```mermaid
graph TD
    User[사용자 — Discord] -->|자연어 대화| Bot[variet-agent Bot]
    Bot -->|턴 관리 + 판단| Mod[사회자 — Gemini Flash]
    
    Mod -->|전문 전달 + 방향 지시| AG[AG — Gemini 3.1 Pro High]
    Mod -->|전문 전달 + 방향 지시| CL[Claude — 별도 프로세스]
    
    AG -->|응답 전문| Mod
    CL -->|응답 전문| Mod
    
    Mod -->|전문 게시| DC[Discord Thread]
    Mod -->|승인 질문| User
    
    AG -->|문서 수정| Wiki[Wiki.js]
    CL -->|문서 수정| Wiki
    Mod -->|결론 정리| Wiki
```

### 계층별 역할

| 계층 | 모델 | 역할 | 연결 |
|------|------|------|------|
| **사회자** | Gemini Flash | 턴 관리, 전문 전달, 방향 지시, 사용자 승인 판단 | `gemini_caller.py` |
| **토론자 A** | AG (Gemini 3.1 Pro High) | 설계 제안, 반론, Wiki 문서 작성 | Antigravity → Hub WS → Discord |
| **토론자 B** | Claude | 설계 제안, 반론, Wiki 문서 작성 | `claude_caller.py` (CLI 래핑) 또는 zebbern SDK (별도 프로세스) |
| **승인자** | 사용자 | 방향 결정, 개입, 중단 | Discord 메시지/버튼 |

---

## 핵심 설계 원칙

### 1. 사회자는 요약하지 않는다 — 전문 전달

사회자는 AI 응답을 **그대로** 상대에게 전달한다. 단, 다음을 **추가**:
- 이 AI가 **사용자의 어떤 답변에 따라** 이렇게 답했는지 맥락
- **오류가 없는지**, 더 개선된 방향이나 잘못된 부분을 지적하라는 지시
- 대화 싱크가 안 맞을 때 **어떤 방향성**으로 이야기할지 가이드

```
[사회자 → Claude에게 전달하는 메시지 예시]

"AG가 다음과 같이 응답했습니다:

{AG 응답 전문}

이 응답은 사용자가 'SA 방식이 현실적이다'라고 판단한 것에 기반합니다.
AG의 의견에 오류가 없는지 확인하고, 더 개선된 방향이나
잘못된 부분이 있다면 지적해주세요.

현재 논의 방향: 위험 계산의 정밀도 vs 성능 트레이드오프"
```

### 2. 턴 순서는 랜덤

항상 AG가 먼저가 아니라 **라운드마다 랜덤** 선택. 사회자가 다음 발언자를 결정할 때:
- 기본: 랜덤
- 예외: 한쪽이 질문을 던졌으면 상대에게 우선권
- 싱크 불일치 시: 사회자가 방향성을 명시해서 전달

### 3. 별도 커맨드 없음 — 사회자가 판단

`/debate` 같은 명시적 커맨드 없음. 브레인스토밍 과정에서:
1. 사용자가 자연어로 대화
2. 사회자(unified prompt)가 **"이 주제는 토론이 필요하다"** 판단
3. Discord에서 사용자에게 물어봄: "이 주제로 회의실을 열까요?"
4. 승인 시 debate 세션 시작

> 주제가 명확하지 않은 브레인스토밍 단계에서도 자연스럽게 전환 가능

### 4. Claude는 별도 프로세스

사회자(Flash)와 Claude를 같은 프로세스에 넣으면 꼬임.
- **방안 A**: zebbern 소스 다운 → 필요 부분 채용 → 별도 Docker/프로세스
- **방안 B**: `claude` CLI 래핑 (`claude_caller.py`) — 단순 대화는 이걸로 충분
- **결정**: 단순 대화 기반이면 B(CLI 래핑)로 시작, 필요 시 A로 확장

### 5. 검증은 문서 수준

- PoC = 소스 코드 작성 아님
- "이 설계가 가능한가?"를 **문서 논리**로 검증
- 실현 불가능한 설계가 나오면 상대 AI가 반론에서 지적

---

## 턴 프로토콜

```
사용자 대화 중 사회자 판단: "회의실 주제 발견"
  → "이 주제로 회의실을 열까요?" [예/아니요]
  → 승인 시:

Phase 0: 준비
  사회자 → Wiki Agenda 페이지 생성
  사회자 → Discord 쓰레드 생성
  사회자 → 첫 발언자 랜덤 선택

Phase 1: 발언 (랜덤 선택된 AI)
  사회자 → 선택된 AI에게 주제 + 맥락 + 지시 전달
  AI → 응답 전문 + Wiki 수정 여부 반환

Phase 2: 사회자 판단
  ① AI 응답 전문 → Discord 쓰레드에 게시
  ② Wiki 수정 내용 보고
  ③ 판단:
     - 자동 진행 → 상대 AI에게 전문 + 방향 지시 전달
     - 사용자 필요 → 승인 요청 후 대기
     - 주제 이탈 → 방향 리다이렉트
     - 합의 도달 → 결론 정리

Phase 3: 상대 AI 발언
  사회자 → 상대 AI에게 전문 + "오류 확인 + 개선점 지적" 지시
  → Phase 2 반복

종료: 합의 or 최대 라운드 or 사용자 중단
  → 사회자가 Conclusion 페이지 정리
```

---

## Wiki.js 문서 구조

```
/Debates/{주제명}/
  Agenda              ← 사회자 생성
  Working-Document    ← 양쪽 AI 공동 편집
  Round-Log           ← 전체 턴 기록
  Conclusion          ← 최종 합의
```

---

## 신규 모듈

| 모듈 | 역할 |
|------|------|
| `handlers/debate_handler.py` | 세션 관리, 턴 라우팅 |
| `tools/claude_caller.py` | Claude CLI 래핑 (별도 프로세스) |
| `prompts/debate_moderator.md` | 사회자 프롬프트 (판단 기준, 전달 형식) |
| `prompts/debate_participant.md` | 참여자 프롬프트 (응답 형식, Wiki 수정 가이드) |

---

## 미결 사항 (추가 논의 필요)

- [ ] AG 응답을 프로그래밍적으로 트리거하는 방식 구체화
- [ ] Claude CLI 래핑 vs zebbern SDK 채용 범위 확정
- [ ] Wiki Working-Document 동시 편집 충돌 처리
- [ ] 사회자의 "토론 주제 감지" 프롬프트 설계
- [ ] 토론 히스토리 컨텍스트 윈도우 관리 (장기 토론 시)