# VEGA 확장 — Gemini CLI 보안 분석 모듈 설계 핸드오프 문서

---

## 1. 배경 및 논의 경과

### 출발점
로컬 LLM(Qwen 3.5)만으로는 소스 분석 품질에 한계가 있어, Gemini CLI의 분석력을 활용하되 **내부 소스 보안을 유지**하는 시스템을 설계.

### 핵심 논의 과정 (v1 → v8)

| 버전 | 논의 | 결론 |
|------|------|------|
| v1~v2 | API vs CLI, 멀티 워커 | Gemini CLI 사용, 역할별 워커 |
| v3~v4 | Rate Limit, 반복 루프 | AI Ultra 120RPM/2000RPD, Plan→Execute→Reflect 루프 |
| v4 비판 | 자기평가 불신뢰, 과잉동원 | 연구 기반 5개 약점 발견 |
| v5~v6 | MCP 도구, Verifier, 보안 | Source Mediator 패턴, Verifier를 Critic으로 전환 |
| v7 | 보안 원칙 확정, Critic 협력자 | 소스 원문 금지, 로직 설명 허용, LLM 앞단+검증자 |
| **v8** | **Mode B 가치 재검토** | **Gemini CLI 자체가 완전한 에이전트 → Mode B는 추가 개발 불필요** |

### 최종 결론

```
Mode B (외부/범용): Gemini CLI를 그대로 쓰면 됨
  → VS Code Agent Mode 또는 터미널 gemini -i
  → 추가 개발 불필요

Mode A (내부/보안): VEGA 확장으로 구현해야 하는 부분
  → 로컬 LLM이 내부 소스를 읽고 추상화
  → Gemini CLI(선생님)와 대화로 분석
  → 로컬 LLM이 결과를 소스와 대조 검증
```

---

## 2. VEGA에서 구현할 것: Mode A

### 구조

```
User ↔ VEGA Web UI
          │
    Local LLM (프롬프트 A: 앞단)
          │  도구: 내부 파일/RAG/DB
          │  소스 읽고 추상화/마스킹
          ▼
    Gemini CLI (-p, --approval-mode yolo)
          │  추상화된 정보로 분석
          │  질문 → LLM 답변 → 분석 (대화 루프)
          ▼
    Local LLM (프롬프트 B: 검증자, 별도 호출)
          │  Gemini 결과 vs 실제 소스 대조
          ▼
    User에게 검증된 결과 전달
```

### 보안 정책

| 허용 ✅ | 금지 ❌ |
|---------|---------|
| 학술적 알고리즘 설명 (HW, LSMC 등) | 소스코드 원문 |
| 함수 로직/흐름 설명 | 테이블/컬럼 구조 |
| 호출 관계 개괄 | 실제 값, 파라미터 수치 |
| 개별 함수 입출력 의미 | 내부 URL, 인증정보 |

LLM 추상화 후 **정규식 2단계 필터**로 금지어 자동 치환.

### Student ↔ Teacher 모델
- LLM(학생)이 소스를 읽고 설명 → Gemini(선생님)가 분석/조언
- LLM이 문제 정립 못 해도 → Gemini가 질문으로 끌어냄
- LLM이 헛소리해도 → Gemini가 교정
- 앞단(프롬프트 A)과 검증자(프롬프트 B)는 **별도 호출** → 순환 오류 방지

### Gemini CLI 호출 방식
```bash
# 역할별 headless 호출 (서브에이전트 풀 불필요)
gemini -p "분석 요청" --system "분석가 프롬프트" -o json --approval-mode yolo
gemini -p "리뷰 요청" --system "리뷰어 프롬프트" -o json --approval-mode yolo
```
매 호출이 **독립 컨텍스트** → 컨텍스트 포화 없음 → 풀 관리 불필요.

### VEGA 기존 인프라 활용
- **Ollama API**: 로컬 LLM 호출 (이미 존재)
- **FastAPI + SSE**: Web UI (이미 존재)
- **RAG/벡터DB**: 내부 문서 검색 (이미 존재)
- **추가 필요**: `gemini -p` subprocess 호출 모듈, 마스킹 필터, 대화 루프

---

## 3. 새로운 목표 — AI Agent Team

### 진짜 최종 목표

위 Mode A/B 논의는 더 큰 목표의 **일부**였음:

> **사용자가 디스코드로 추상적 명령을 주면,
> AI Agent Team이 스스로 작업을 분석/분해/실행하고,
> 샌드박스에서 코드를 실행/테스트하고,
> Gitea CI로 컴파일/배포까지 수행하며,
> 사용자는 디스코드로 확인/컨펌만 하는 시스템.**

### 왜 이 구조가 필요한가

| 현재 문제 | 원인 | 해결 방향 |
|----------|------|----------|
| **컨텍스트 초과** | 한 에이전트가 긴 작업 → 컨텍스트 포화 → 멈춤/유실 | 작업을 역할별로 분할, 각 에이전트는 짧은 컨텍스트 |
| **추상적 명령 처리** | "이거 고쳐줘" → 어디를? 뭘? | 작업 분석 에이전트가 구체적 태스크로 분해 |
| **실행/테스트 불가** | 분석만 하고 실제 실행 못 함 | 샌드박스 + CI 연동 |
| **확인의 어려움** | 결과를 보려면 IDE 열어야 | 디스코드로 중간 보고 + 컨펌 |

### 제안 아키텍처: AI Agent Team

```
Discord (사용자 인터페이스)
    │
    ▼
┌─────────────────────────────────────────┐
│  Coordinator Agent                       │
│  (Gemini CLI 또는 로컬 LLM)              │
│                                          │
│  역할:                                   │
│  - 사용자 명령 해석                       │
│  - 작업 분해 (추상 → 구체)                │
│  - 에이전트에게 작업 배분                  │
│  - 결과 종합 → 디스코드 보고              │
└──┬──────────┬──────────┬────────────────┘
   │          │          │
┌──▼──┐  ┌───▼───┐  ┌───▼───┐
│분석  │  │구현    │  │테스트  │  ... 역할별
│Agent │  │Agent   │  │Agent   │
└──┬──┘  └───┬───┘  └───┬───┘
   │          │          │
   └──────────┼──────────┘
              │
    ┌─────────▼─────────┐
    │  실행 환경          │
    │  - 샌드박스 (코드)  │
    │  - Gitea Runner    │
    │  - CI/CD 파이프라인 │
    └───────────────────┘
              │
    디스코드로 결과 보고 + 사용자 컨펌
              │
         배포 / 완료
```

### 이 목표를 이루기 위한 프로젝트 분해

| 프로젝트 | 설명 | 의존성 |
|---------|------|--------|
| **P1: Discord Bot** | 사용자 ↔ 시스템 인터페이스 | 없음 |
| **P2: Task Decomposer** | 추상 명령 → 구체 태스크 목록 | Gemini CLI |
| **P3: Agent Runner** | 역할별 `gemini -p` headless 호출 | Gemini CLI |
| **P4: Sandbox** | 코드 실행/테스트 환경 | Docker 또는 로컬 격리 |
| **P5: Gitea CI 연동** | PR 생성 → Runner 실행 → 결과 수집 | Gitea API |
| **P6: 보안 분석 (Mode A)** | VEGA 확장, 내부 소스 보안 분석 | P3 + VEGA |

### 접근 전략

**단계적 구축 (작은 것부터 동작하게):**

```
Step 1: Discord Bot + gemini -p 호출
  "디스코드로 질문 → Gemini 답변 → 디스코드로 반환"
  → 가장 작은 동작 단위. 기초 인프라 검증.

Step 2: Task Decomposer
  "이 모듈 리팩토링해줘" → 구체 태스크 3개로 분해
  → Gemini CLI의 plan mode 활용

Step 3: Agent Runner + 파일 접근
  분해된 태스크를 순차 실행, 파일 수정, 결과 보고
  → gemini -p --approval-mode yolo

Step 4: Sandbox 실행
  수정된 코드를 샌드박스에서 실행/테스트
  → Docker 컨테이너 또는 gemini --sandbox

Step 5: Gitea CI 연동
  수정 완료 → Gitea PR 생성 → Runner 실행 → 결과를 디스코드로
  → Gitea API + Webhook

Step 6: 보안 분석 (Mode A)
  VEGA와 통합, 내부 소스 보안 분석 파이프라인
```

### 핵심 원칙

1. **Gemini CLI가 에이전트 엔진** — 자기가 이미 파일 읽기/쓰기/실행 가능
2. **headless 호출로 컨텍스트 분할** — 역할별/태스크별 독립 호출 → 포화 방지
3. **디스코드 = 유일한 사용자 인터페이스** — 명령, 중간 보고, 컨펌 모두 디스코드에서
4. **Gitea CI = 실행/배포 인프라** — 코드 수정 → PR → 빌드 → 테스트 → 배포
5. **단계적 구축** — Step 1부터 동작 확인 후 다음 단계