variet-agent/docs/design/debate-room-v2.md

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

개요

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

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

---

아키텍처

graph TD
    User[사용자 — Discord] -->|자연어 대화| Bot[variet-agent Bot]
    Bot -->|턴 관리 + 판단| Mod[사회자 — Gemini Flash via gemini_caller.py]
    
    Mod -->|Discord 경로| AG["AG — Gemini 3.1 Pro High (Antigravity IDE)"]
    Mod -->|subprocess| CL["Claude Code CLI (claude -p --resume)"]
    
    AG -->|Discord 응답| Mod
    CL -->|stdout JSON| Mod
    
    Mod -->|전문 게시| DC[Discord Thread]
    Mod -->|승인 질문| User
    
    Mod -->|wiki_helper.py| Wiki[Wiki.js]

계층별 역할

계층	모델	과금	연결 방식
사회자	Gemini Flash	무료 (1000req/일) 또는 gemini_caller.py 기존 래핑	subprocess
토론자 A	AG (Gemini 3.1 Pro High)	Google AI Pro/Ultra 구독	Antigravity → Hub WS → Discord Bot (기존 경로)
토론자 B	Claude Code	Anthropic Pro/Max 구독	claude -p --resume --output-format json (subprocess)
승인자	사용자	-	Discord 메시지/버튼

⚠️ 과금 핵심: API 직접 호출 = 토큰 과금. CLI/IDE 사용 = 구독 쿼터. 양쪽 다 구독 내에서 처리.

---

연결 상세

AG (Gemini 3.1 Pro High)

기존 인프라 그대로 사용:

variet-agent Bot → Discord 메시지 → AG 수신 → 작업 → Discord 응답

• 도구: AG 내장 (run_command, view_file, write_to_file, browser 등)
• MCP: 불필요 — AG 자체 도구 시스템으로 대체
• Wiki.js: ⚠️ 신규 개발 필요 — AG는 Gitea Wiki만 지원. Wiki.js 읽기/쓰기 도구 추가 필요
  • 방안 1: AG가 run_command로 wiki_helper.py 호출
  • 방안 2: 사회자가 AG 응답의 wiki_action JSON을 받아서 대신 실행
• 세션: AG는 대화별로 세션 관리됨 (Antigravity IDE 내장)

Claude Code CLI

# 기본 호출
claude -p "프롬프트" --output-format json

# 세션 이어가기 (토론 맥락 유지 — 핵심!)
claude --resume SESSION_ID -p "프롬프트" --output-format json

# 시스템 프롬프트 (토론 참여자 역할)
claude -p "프롬프트" --system-prompt "당신은 토론 참여자입니다..."

# 모델 선택
claude -p "프롬프트" --model opus

• 과금: Anthropic Pro/Max 구독 쿼터
• 세션 유지: --resume 플래그로 이전 대화 맥락 자동 유지
  • 첫 턴 → 세션 ID 생성
  • 이후 턴 → --resume {session_id}로 맥락 이어감
• Wiki.js: 사회자가 대신 실행 (Claude 응답 JSON의 wiki_action 파싱)
• 별도 프로세스: 사회자(Flash)와 분리 — subprocess로 호출

---

핵심 설계 원칙

1. 사회자는 전문 전달 (요약 ❌)

사회자는 AI 응답을 그대로 상대에게 전달 + 다음을 추가:

• 사용자의 어떤 답변에 기반한 의견인지 맥락
• "오류 확인 + 개선점 지적" 지시
• 대화 싱크 불일치 시 방향성 가이드

2. 턴 순서 랜덤

매 라운드 발언자 랜덤 선택. 예외:

• 한쪽이 질문 → 상대에게 우선권
• 싱크 불일치 → 사회자가 방향 명시

3. 커맨드 없음 — 사회자 자동 판단

/debate 같은 커맨드 없음. 자연어 대화에서:

1. 사회자가 "이 주제는 토론이 필요하다" 판단
2. 사용자에게 "회의실을 열까요?" 확인
3. 승인 시 세션 시작

4. 검증은 문서 수준만

소스 코드 작성 없음. 설계 가능 여부를 문서 논리로 검증.

---

턴 프로토콜

Phase 0: 준비
  사회자 → Wiki.js에 Agenda 페이지 생성 (wiki_helper.py)
  사회자 → Discord 쓰레드 생성
  사회자 → 첫 발언자 랜덤 선택
  사회자 → Claude 세션 초기화 (claude -p --system-prompt)

Phase 1: 발언
  사회자 → 선택된 AI에게 주제 + 맥락 + 지시 전달
    AG: Discord 메시지로 전달
    Claude: claude --resume {sid} -p "..." --output-format json
  AI → 응답 전문 + wiki_action (선택)

Phase 2: 사회자 판단
  ① 응답 전문 → Discord 쓰레드에 게시
     AG 응답 = 🟢 초록 Embed
     Claude 응답 = 🔵 파랑 Embed
  ② wiki_action 있으면 → wiki_helper.py 실행 → "📝 Wiki 수정됨" 보고
  ③ 판단:
     자동 진행 → 상대 AI에게 전문 + 방향 지시
     사용자 필요 → 승인 요청 (버튼)
     주제 이탈 → 리다이렉트
     합의 도달 → 결론 정리

Phase 3: 반복 → 종료
  합의 / 최대 라운드 / 사용자 중단
  → 사회자가 Wiki.js Conclusion 페이지 정리

---

Wiki.js 문서 구조

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

Wiki 수정 흐름:

AI 응답 JSON: { "opinion": "...", "wiki_action": { "page": "...", "content": "..." } }
  → 사회자가 wiki_action 파싱
  → wiki_helper.py update "페이지" "내용"
  → Discord에 변경 보고

⚠️ Wiki 수정 권한은 사회자가 통제. AI가 직접 수정하지 않음.

---

신규 개발 필요 항목

모듈	역할	우선순위
handlers/debate_handler.py	세션 관리, 턴 라우팅, 상태 머신	필수
tools/claude_caller.py	claude -p --resume subprocess 래핑	필수
prompts/debate_moderator.md	사회자 프롬프트 (판단 기준, 전달 형식)	필수
prompts/debate_participant.md	참여자 프롬프트 (응답 JSON 형식, wiki_action 가이드)	필수
AG Wiki.js 도구	AG가 Wiki.js 읽기/쓰기	선택 (사회자 경유 가능)

---

미결 사항

• AG 응답 트리거 방식 구체화 — AG에게 Discord 메시지를 보내면 어떤 채널에서 응답이 오는지
• Claude --resume 세션 ID 관리 — 세션 파일 저장 위치 + 만료 정책
• 토론 히스토리 컨텍스트 윈도우 — 장기 토론 시 AG/Claude 컨텍스트 초과 대응
• 사회자의 "토론 필요" 감지 프롬프트 설계 — unified.md에 debate 모드 추가
• Wiki Working-Document 동시 편집 충돌 방지 — 한 턴에 한 AI만 수정