docs: Debate Room 설계서 v3 — AG+Claude CLI 연동 상세, 과금 구조, Wiki.js 경로

docs/design/debate-room-v2.md

@@ -1,12 +1,12 @@
-# AI Debate Room (회의실) — 설계서 v2
+# AI Debate Room (회의실) — 설계서 v3
 
 ## 개요
 
-두 AI (AG Gemini 3.1 Pro High + Claude)가 **사회자(Gemini Flash)**의 중재 하에 주제를 토론하고, 정교한 문서를 생산하는 시스템.
+두 AI (AG + Claude Code)가 **사회자(Gemini Flash)**의 중재 하에 주제를 토론하고, 정교한 문서를 생산하는 시스템.
 
 - **목적**: 구현 전 설계 문서의 품질을 극대화 (교차 검증 + 반론)
 - **결과물**: Wiki.js에 축적되는 설계 명세서
-- **원칙**: 회의실은 문서만 생산. 코드 없음. 검증도 문서 수준.
+- **원칙**: 코드 없음. 문서만 생산. 검증도 문서 수준.
 
 ---
 
@@ -15,119 +15,131 @@
 ```mermaid
 graph TD
     User[사용자 — Discord] -->|자연어 대화| Bot[variet-agent Bot]
-    Bot -->|턴 관리 + 판단| Mod[사회자 — Gemini Flash]
+    Bot -->|턴 관리 + 판단| Mod[사회자 — Gemini Flash via gemini_caller.py]
     
-    Mod -->|전문 전달 + 방향 지시| AG[AG — Gemini 3.1 Pro High]
-    Mod -->|전문 전달 + 방향 지시| CL[Claude — 별도 프로세스]
+    Mod -->|Discord 경로| AG["AG — Gemini 3.1 Pro High (Antigravity IDE)"]
+    Mod -->|subprocess| CL["Claude Code CLI (claude -p --resume)"]
     
-    AG -->|응답 전문| Mod
-    CL -->|응답 전문| Mod
+    AG -->|Discord 응답| Mod
+    CL -->|stdout JSON| Mod
     
     Mod -->|전문 게시| DC[Discord Thread]
     Mod -->|승인 질문| User
     
-    AG -->|문서 수정| Wiki[Wiki.js]
-    CL -->|문서 수정| Wiki
-    Mod -->|결론 정리| Wiki
+    Mod -->|wiki_helper.py| Wiki[Wiki.js]
 ```
 
 ### 계층별 역할
 
-| 계층 | 모델 | 역할 | 연결 |
-|------|------|------|------|
-| **사회자** | 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 메시지/버튼 |
+| 계층 | 모델 | 과금 | 연결 방식 |
+|------|------|------|-----------|
+| **사회자** | 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
+
+```bash
+# 기본 호출
+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. 사회자는 요약하지 않는다 — 전문 전달
+### 1. 사회자는 전문 전달 (요약 ❌)
 
-사회자는 AI 응답을 **그대로** 상대에게 전달한다. 단, 다음을 **추가**:
-- 이 AI가 **사용자의 어떤 답변에 따라** 이렇게 답했는지 맥락
-- **오류가 없는지**, 더 개선된 방향이나 잘못된 부분을 지적하라는 지시
-- 대화 싱크가 안 맞을 때 **어떤 방향성**으로 이야기할지 가이드
+사회자는 AI 응답을 **그대로** 상대에게 전달 + 다음을 **추가**:
+- 사용자의 어떤 답변에 기반한 의견인지 맥락
+- "오류 확인 + 개선점 지적" 지시
+- 대화 싱크 불일치 시 방향성 가이드
 
-```
-[사회자 → Claude에게 전달하는 메시지 예시]
+### 2. 턴 순서 랜덤
 
-"AG가 다음과 같이 응답했습니다:
+매 라운드 발언자 랜덤 선택. 예외:
+- 한쪽이 질문 → 상대에게 우선권
+- 싱크 불일치 → 사회자가 방향 명시
 
-{AG 응답 전문}
+### 3. 커맨드 없음 — 사회자 자동 판단
 
-이 응답은 사용자가 'SA 방식이 현실적이다'라고 판단한 것에 기반합니다.
-AG의 의견에 오류가 없는지 확인하고, 더 개선된 방향이나
-잘못된 부분이 있다면 지적해주세요.
+`/debate` 같은 커맨드 없음. 자연어 대화에서:
+1. 사회자가 "이 주제는 토론이 필요하다" 판단
+2. 사용자에게 "회의실을 열까요?" 확인
+3. 승인 시 세션 시작
 
-현재 논의 방향: 위험 계산의 정밀도 vs 성능 트레이드오프"
-```
+### 4. 검증은 문서 수준만
 
-### 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 페이지 생성
+  사회자 → Wiki.js에 Agenda 페이지 생성 (wiki_helper.py)
   사회자 → Discord 쓰레드 생성
   사회자 → 첫 발언자 랜덤 선택
+  사회자 → Claude 세션 초기화 (claude -p --system-prompt)
 
-Phase 1: 발언 (랜덤 선택된 AI)
+Phase 1: 발언
   사회자 → 선택된 AI에게 주제 + 맥락 + 지시 전달
-  AI → 응답 전문 + Wiki 수정 여부 반환
+    AG: Discord 메시지로 전달
+    Claude: claude --resume {sid} -p "..." --output-format json
+  AI → 응답 전문 + wiki_action (선택)
 
 Phase 2: 사회자 판단
-  ① AI 응답 전문 → Discord 쓰레드에 게시
-  ② Wiki 수정 내용 보고
+  ① 응답 전문 → Discord 쓰레드에 게시
+     AG 응답 = 🟢 초록 Embed
+     Claude 응답 = 🔵 파랑 Embed
+  ② wiki_action 있으면 → wiki_helper.py 실행 → "📝 Wiki 수정됨" 보고
   ③ 판단:
-     - 자동 진행 → 상대 AI에게 전문 + 방향 지시 전달
-     - 사용자 필요 → 승인 요청 후 대기
-     - 주제 이탈 → 방향 리다이렉트
-     - 합의 도달 → 결론 정리
+     자동 진행 → 상대 AI에게 전문 + 방향 지시
+     사용자 필요 → 승인 요청 (버튼)
+     주제 이탈 → 리다이렉트
+     합의 도달 → 결론 정리
 
-Phase 3: 상대 AI 발언
-  사회자 → 상대 AI에게 전문 + "오류 확인 + 개선점 지적" 지시
-  → Phase 2 반복
-
-종료: 합의 or 최대 라운드 or 사용자 중단
-  → 사회자가 Conclusion 페이지 정리
+Phase 3: 반복 → 종료
+  합의 / 최대 라운드 / 사용자 중단
+  → 사회자가 Wiki.js Conclusion 페이지 정리
 ```
 
 ---
@@ -137,28 +149,39 @@ Phase 3: 상대 AI 발언
 ```
 /Debates/{주제명}/
   Agenda              ← 사회자 생성
-  Working-Document    ← 양쪽 AI 공동 편집
-  Round-Log           ← 전체 턴 기록
+  Working-Document    ← 양쪽 AI 공동 편집 (사회자 경유)
+  Round-Log           ← 전체 턴 기록 (자동 축적)
   Conclusion          ← 최종 합의
 ```
 
----
+Wiki 수정 흐름:
+```
+AI 응답 JSON: { "opinion": "...", "wiki_action": { "page": "...", "content": "..." } }
+  → 사회자가 wiki_action 파싱
+  → wiki_helper.py update "페이지" "내용"
+  → Discord에 변경 보고
+```
 
-## 신규 모듈
-
-| 모듈 | 역할 |
-|------|------|
-| `handlers/debate_handler.py` | 세션 관리, 턴 라우팅 |
-| `tools/claude_caller.py` | Claude CLI 래핑 (별도 프로세스) |
-| `prompts/debate_moderator.md` | 사회자 프롬프트 (판단 기준, 전달 형식) |
-| `prompts/debate_participant.md` | 참여자 프롬프트 (응답 형식, Wiki 수정 가이드) |
+> ⚠️ Wiki 수정 권한은 사회자가 통제. AI가 직접 수정하지 않음.
 
 ---
 
-## 미결 사항 (추가 논의 필요)
+## 신규 개발 필요 항목
 
-- [ ] AG 응답을 프로그래밍적으로 트리거하는 방식 구체화
-- [ ] Claude CLI 래핑 vs zebbern SDK 채용 범위 확정
-- [ ] Wiki Working-Document 동시 편집 충돌 처리
-- [ ] 사회자의 "토론 주제 감지" 프롬프트 설계
-- [ ] 토론 히스토리 컨텍스트 윈도우 관리 (장기 토론 시)
+| 모듈 | 역할 | 우선순위 |
+|------|------|---------|
+| `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만 수정