chore: Agent Guide 셋업 — agent_guide.git 기반 .agents 재구성 + 프로젝트별 설정

2026-03-10 22:51:14 +09:00
parent e1aca2b79f
commit 044200a786
11 changed files with 287 additions and 154 deletions
--- a/.agents/references/architecture.md
+++ b/.agents/references/architecture.md
@@ -1,35 +1,75 @@
 # Architecture

-> 이 프로젝트의 아키텍처를 설명하는 문서입니다.
-> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
+> Variet Agent — Gemini CLI 기반 AI Agent Team 시스템

 ## 프로젝트 개요

-<!-- 프로젝트의 목적과 핵심 기능을 간략히 서술 -->
-
-(프로젝트 설명을 여기에 작성하세요)
+사용자가 디스코드에서 자연어 명령 → AI Agent Team이 코드 분석/분해/실행 → Gitea CI로 PR/빌드/배포.
+Gemini CLI를 서브프로세스(`asyncio.create_subprocess_exec`)로 래핑하여 역할별 독립 컨텍스트로 호출.

 ## 디렉토리 구조

 ```
-project-root/
-├── src/                  # 소스 코드
-├── tests/                # 테스트
-├── docs/                 # 문서
-├── .agents/              # AI 에이전트 설정
-└── ...
+variet-agent/
+├── main.py                  # 진입점 (FastAPI + Discord Bot 동시 실행)
+├── config.py                # .env 기반 설정 관리
+├── api/
+│   ├── server.py            # FastAPI REST 서버
+│   ├── discord_bot.py       # Discord Bot (NLU + PCRS 파이프라인 + 애니 핸들러)
+│   └── models.py            # 요청/응답 모델
+├── core/
+│   ├── task_pipeline.py     # PCRS: Plan → Code → Review → Summarize
+│   ├── gemini_caller.py     # Gemini CLI 래퍼 (text/agent 모드)
+│   ├── context_manager.py   # 관련 파일 선별 + 토큰 예산 제어
+│   ├── project_indexer.py   # 프로젝트 구조 스캔/캐시
+│   ├── workspace.py         # 워크스페이스 관리 (채널 ↔ 프로젝트 매핑)
+│   ├── file_applier.py      # 코드 변경 적용
+│   └── docs_manager.py      # 문서/세션 기록
+├── tools/                   # 자동화 도구 (애니메이션 파이프라인)
+│   ├── anime_pipeline.py    # 통합 파이프라인 (검색/다운/자막/상태)
+│   ├── anissia_client.py    # Anissia 편성표 API
+│   ├── nyaa_client.py       # Nyaa 토렌트 검색
+│   ├── qbit_client.py       # qBittorrent 제어
+│   ├── nas_scanner.py       # NAS 파일 스캔
+│   ├── title_matcher.py     # 제목 매칭 (로마지/퍼지)
+│   └── subtitle_downloader.py  # 자막 다운로더
+├── integrations/
+│   ├── gitea_client.py      # Gitea API (PR/이슈)
+│   ├── vikunja_client.py    # Vikunja 태스크 관리
+│   └── ci_monitor.py        # CI 결과 모니터링
+└── prompts/                 # AI 역할별 프롬프트
+    ├── unified.md           # NLU 분류 (chat/task/anime/clarify)
+    ├── planner.md           # 태스크 분해
+    ├── coder.md             # 코드 구현
+    ├── reviewer.md          # 코드 리뷰
+    └── summarizer.md        # 총평 생성
 ```

 ## 핵심 모듈

-<!-- 각 모듈의 역할과 의존 관계를 설명 -->
-
 | 모듈 | 역할 | 의존성 |
 |------|------|--------|
-| (모듈명) | (역할 설명) | (의존하는 모듈) |
+| `discord_bot.py` | 사용자 인터페이스 + NLU 분류 | `workspace.py`, `gemini_caller.py`, `task_pipeline.py` |
+| `task_pipeline.py` | PCRS 오케스트레이션 (Inner/Outer 루프) | `gemini_caller.py`, `context_manager.py`, `project_indexer.py` |
+| `gemini_caller.py` | Gemini CLI 서브프로세스 호출 (text/agent) | `prompts/` |
+| `context_manager.py` | 태스크 기반 파일 선별 + 토큰 예산 | `project_indexer.py` |
+| `workspace.py` | 채널 ↔ 프로젝트 경로 매핑, workspaces.json 관리 | — |
+| `anime_pipeline.py` | 애니 자동화 통합 | `anissia_client.py`, `nyaa_client.py`, `qbit_client.py`, `nas_scanner.py` |

 ## 데이터 흐름

-<!-- 주요 데이터 흐름을 Mermaid 다이어그램이나 텍스트로 설명 -->
-
-(데이터 흐름을 여기에 작성하세요)
+```
+Discord 메시지
+  → on_message()
+    → _unified_call() — NLU 분류 (chat/task/anime/clarify)
+      ├─ chat → 즉답
+      ├─ clarify → 질문 임베드
+      ├─ anime → _handle_anime() → AnimePipeline
+      └─ task → _handle_task()
+            → TaskPipeline.plan() — Planner (태스크 분해)
+            → TaskPipeline.code_parallel() — Coder (에이전트 모드, cwd=프로젝트)
+            → TaskPipeline.planner_verify() — 내부 자가검증 (Inner Loop)
+            → TaskPipeline.batch_review() — Reviewer (Outer Loop)
+            → TaskPipeline.summarize() — 총평
+            → Discord Embed 보고
+```
--- a/.agents/references/tech-stack.md
+++ b/.agents/references/tech-stack.md
@@ -6,32 +6,54 @@

 | 항목 | 버전 | 비고 |
 |------|------|------|
-| (예: Node.js) | (예: 20.x) | (설치 경로 등) |
-| (예: Python) | (예: 3.12) | (가상환경 경로 등) |
+| Python | 3.12+ | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe` |
+| Gemini CLI | v0.32+ (AI Ultra) | `gemini --model gemini-3-flash-preview` |

 ## 프레임워크

 | 항목 | 버전 | 용도 |
 |------|------|------|
-| (예: Express) | (예: 4.18) | (서버) |
-| (예: React) | (예: 18.x) | (프론트엔드) |
+| FastAPI | 최신 | REST API 서버 |
+| discord.py | 2.x | Discord Bot |
+| uvicorn | 최신 | ASGI 서버 |
+| httpx | 최신 | 비동기 HTTP 클라이언트 (tools/) |

 ## 패키지 관리

- 패키지 매니저: (npm / yarn / pnpm / pip 등)
- Lock 파일: (package-lock.json / yarn.lock 등)
+- 패키지 매니저: pip (conda env `agent_chat`)
+- 의존성 파일: `requirements.txt`
+- 가상환경: `C:\ProgramData\miniforge3\envs\agent_chat`

 ## 개발 도구

 | 도구 | 명령어 |
 |------|--------|
-| 개발 서버 | (예: `cmd /c npm run dev`) |
-| 빌드 | (예: `cmd /c npm run build`) |
-| 테스트 | (예: `cmd /c npm test`) |
-| 린트 | (예: `cmd /c npm run lint`) |
+| 봇 실행 | `run_bot.bat` 또는 `C:\ProgramData\miniforge3\envs\agent_chat\python.exe main.py` |
+| 테스트 | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe -m pytest tests/ -v` |
+| Vikunja 조회 | `C:\ProgramData\miniforge3\envs\agent_chat\python.exe .agents\workflows\helpers\vikunja_helper.py list todo` |

-## 환경 변수
+## 환경 변수 (.env)

 | 변수명 | 용도 | 기본값 |
 |--------|------|--------|
-| (예: PORT) | (서버 포트) | (3000) |
+| DISCORD_BOT_TOKEN | Discord 봇 토큰 | (필수) |
+| API_HOST | API 서버 호스트 | 0.0.0.0 |
+| API_PORT | API 서버 포트 | 8000 |
+| GITEA_URL | Gitea 서버 | https://git.variet.net |
+| GITEA_TOKEN | Gitea API 토큰 | (필수) |
+| GITEA_REPO | Gitea 저장소 | Variet/variet-agent |
+| VIKUNJA_URL | Vikunja 서버 | https://plan.variet.net |
+| VIKUNJA_TOKEN | Vikunja API 토큰 | (필수) |
+| VIKUNJA_PROJECT_ID | Vikunja 프로젝트 ID | 7 |
+| QBIT_URL | qBittorrent URL | http://localhost:8080 |
+| NAS_ANIME_PATH | NAS 애니 경로 | \\\\192.168.10.10\NasData\Video\Animation |
+
+## 외부 서비스
+
+| 서비스 | URL | 용도 |
+|--------|-----|------|
+| Gitea | git.variet.net | Git 저장소, PR, CI |
+| Vikunja | plan.variet.net | 태스크 관리 (프로젝트 #7) |
+| Anissia | anissia.net | 애니 편성표/자막 |
+| Nyaa | nyaa.si | 토렌트 검색 |
+| qBittorrent | localhost:8080 | 토렌트 다운로드 |