From 34a09694795ce65ed018ebfbbddc6a297962d161 Mon Sep 17 00:00:00 2001 From: Variet Agent Date: Thu, 19 Mar 2026 14:38:27 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Debate=20Room=20=EC=84=A4=EA=B3=84?= =?UTF-8?q?=EC=84=9C=20v3=20=E2=80=94=20AG+Claude=20CLI=20=EC=97=B0?= =?UTF-8?q?=EB=8F=99=20=EC=83=81=EC=84=B8,=20=EA=B3=BC=EA=B8=88=20?= =?UTF-8?q?=EA=B5=AC=EC=A1=B0,=20Wiki.js=20=EA=B2=BD=EB=A1=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design/debate-room-v2.md | 215 +++++++++++++++++++--------------- 1 file changed, 119 insertions(+), 96 deletions(-) diff --git a/docs/design/debate-room-v2.md b/docs/design/debate-room-v2.md index b93059b..69cbec8 100644 --- a/docs/design/debate-room-v2.md +++ b/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만 수정