variet-agent/.agent/references/architecture.md

Architecture

Variet Agent — Hybrid Skill-Based AI Agent (v3)

프로젝트 개요

사용자가 디스코드에서 자연어 명령 → Orchestrator NLU 분류 → 도구 실행 또는 Agent 통합 실행. Gemini CLI를 subprocess(asyncio.create_subprocess_exec)로 호출. SDK/API 전환 금지.

디렉토리 구조

variet-agent/
├── main.py                      # 진입점 (FastAPI + Discord Bot)
├── config.py                    # .env 기반 설정 관리
├── api/
│   ├── server.py                # FastAPI REST 서버
│   ├── discord_bot.py           # Discord Bot (이벤트 핸들러 + 라우팅, ~310줄)
│   └── models.py                # 요청/응답 모델
├── core/
│   ├── orchestrator.py          # NLU 분류 + 도구 라우팅
│   ├── task_pipeline.py         # ★ execute() 1회 호출 + 선택적 review()
│   ├── gemini_caller.py         # Gemini CLI 래퍼 (text/agent 모드)
│   ├── context_manager.py       # 관련 파일 선별 + 토큰 예산
│   ├── project_indexer.py       # 프로젝트 구조 스캔
│   ├── workspace.py             # 워크스페이스 관리
│   ├── file_applier.py          # 코드 변경 적용
│   └── docs_manager.py          # 문서/세션 기록
├── handlers/                    # Discord 핸들러
│   ├── anime_handler.py         # 애니 NLU + /anime 슬래시
│   ├── task_handler.py          # ★ Agent 1회 실행 + 결과 임베드 (~110줄)
│   ├── commands.py              # /workspace, /task 슬래시
│   └── renderer.py              # ToolResult → Discord Embed
├── tools/                       # 자동화 도구 (Plugin 패턴)
│   ├── base.py                  # BaseTool 추상 기반
│   ├── registry.py              # ToolRegistry 자동 발견
│   ├── anime_tool.py            # AnimeTool(BaseTool)
│   ├── anime_pipeline.py        # 통합 파이프라인
│   └── ...                      # 개별 클라이언트들
├── .gemini/
│   └── skills/                  # ★ Gemini CLI Skill v2
│       └── anime/
│           └── SKILL.md         # 도구 설명 + 사용법
├── prompts/
│   ├── unified.md               # NLU 분류
│   ├── agent.md                 # ★ 통합 에이전트 (plan+code+verify)
│   └── reviewer.md              # 독립 리뷰 (선택적)
└── logs/
    └── variet.log

데이터 흐름

Discord 메시지
  → Orchestrator.classify() — NLU 분류
    ├── chat → 즉답
    ├── clarify → 질문
    ├── anime → AnimeTool + renderer
    └── task → TaskPipeline.execute()  ← Agent 1회
                → Gemini agent 모드 (plan+code+verify 통합)
                → JSON 보고서 → Discord Embed

vs 이전 버전 (PCRS)

v2: NLU → Planner → Coder×N → PlannerVerify → Reviewer → Summarizer (5~7 호출)
v3: NLU → Agent 1회 (plan+code+verify 통합) → 선택적 Review (1~2 호출)

새 도구 추가

1. tools/에 BaseTool 상속 클래스 생성 → 자동 등록
2. .gemini/skills/에 SKILL.md 생성 → Gemini CLI가 자동 발견

아키텍처 결정 (변경 불가)

• Gemini CLI subprocess 영구 유지 (SDK/API 금지)
• 상세: .agents/references/conventions.md 참조