refactor(agent): .agents 통합 + AGENT.md 수칙 업데이트 + STATUS.md 도입 + end.md Wiki 동기화 개편

.agent/AGENT.md

@@ -17,6 +17,9 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.
 5. NEVER skip the pre-task checklist defined in `.agent/workflows/pre-task.md`
 6. NEVER attempt the same failed approach more than 2 times
 7. NEVER truncate error messages — always show the full error output
+8. NEVER modify `.env`, secrets, or credential files without explicit user approval
+9. NEVER make changes exceeding 3 files without stating the blast radius first
+10. NEVER dump large outputs without summarizing — paginate or filter results
 
 ## ALWAYS (필수)
 
@@ -26,6 +29,23 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.
 4. ALWAYS stop and ask the user if 2 consecutive attempts on the same approach fail
 5. ALWAYS use existing helper scripts instead of raw API calls
 6. ALWAYS read related existing code (minimum 3 files) before writing new code
+7. ALWAYS read `STATUS.md` before starting work to understand the big picture
+8. ALWAYS update `STATUS.md` at session end when any module changes
+9. ALWAYS state the blast radius (affected files/modules) before multi-file changes
+10. ALWAYS verify changes compile/run before reporting completion
+
+## Security Boundaries (건드리지 않을 것)
+
+- `.env`, `.env.*` — 환경변수/시크릿 (읽기만 허용, 수정 시 반드시 유저 승인)
+- `*.pem`, `*.key` — 인증서/키 파일
+- `.git/` — Git 내부 구조
+- 프로덕션 서비스 직접 조작 금지 (반드시 helper 스크립트 경유)
+
+## Context Management (컨텍스트 관리)
+
+- 대용량 출력은 반드시 요약/필터링 (전체 로그 덤프 금지)
+- 이전 세션 맥락: `STATUS.md` → devlog → known-issues 순서로 최소한만 로딩
+- 긴 작업 중간에 진행 상황을 devlog entry로 기록 (세션 유실 방지)
 
 ## Failure Protocol
 
@@ -42,10 +62,11 @@ description: 모든 작업에 자동 적용되는 에이전트 행동 규칙.
 ## Reference Loading Order
 
 1. `.agent/AGENT.md` (this file — behavior rules)
-2. `.agent/references/known-issues.md` (past failure patterns)
+2. `.agent/references/STATUS.md` (big picture — system design & features)
-3. `.agent/references/` (project-specific knowledge)
+3. `.agent/references/known-issues.md` (past failure patterns)
-4. `.agent/workflows/services.md` (service credentials & protocols)
+4. `.agent/references/` (project-specific knowledge)
-5. `.agent/workflows/` (action procedures)
+5. `.agent/workflows/services.md` (service credentials & protocols)
+6. `.agent/workflows/` (action procedures)
 
 ## PowerShell Notes
 

.agent/references/STATUS.md

@@ -0,0 +1,68 @@
+# Variet Agent — 설계 현황
+
+> AI 에이전트는 **세션 시작 시** 이 문서를 읽어 전체 맥락을 파악합니다.
+> **세션 종료 시** 변경사항을 이 문서에 반영합니다.
+> Last updated: 2026-03-16
+
+## 시스템 개요
+
+Hybrid Skill-Based AI Agent v3 — 사용자가 디스코드에서 자연어 명령을 내리면, Orchestrator NLU가 분류하여 도구를 실행하거나 AI Agent가 통합 처리합니다.
+
+```
+Discord 메시지
+  → Orchestrator.classify() — NLU 분류
+    ├── chat → 즉답
+    ├── clarify → 질문
+    ├── anime → AnimeTool (파이프라인)
+    └── task → TaskPipeline.execute() → Gemini CLI agent 모드
+```
+
+## 핵심 설계 결정 (불변)
+
+- **Gemini CLI subprocess 방식 영구 유지** (SDK/API 금지)
+- **Vikunja = 태스크 SSOT** (모든 태스크 생성/완료는 Vikunja 경유)
+- **`.agent/references/` = 설계 문서 SSOT** (로컬 우선, Wiki에 동기화)
+
+## 기능 목록 (Feature Inventory)
+
+| 기능 | 모듈 | 설명 | 상태 |
+|------|------|------|:----:|
+| 자연어 명령 분류 | `core/orchestrator.py` | Discord 메시지 → chat/clarify/anime/task intent 분류 | ✅ |
+| AI 코드 생성 | `core/task_pipeline.py` | 계획→코딩→검증 통합 실행 (Gemini agent 모드) | ✅ |
+| Gemini CLI 래퍼 | `core/gemini_caller.py` | text/agent 모드 전환, CLI subprocess 호출 | ✅ |
+| 컨텍스트 관리 | `core/context_manager.py` | 관련 파일 선별 + 토큰 예산 제어 | ✅ |
+| 프로젝트 인덱싱 | `core/project_indexer.py` | 프로젝트 구조 스캔 + import 관계 파악 | ✅ |
+| 애니 자동 다운로드 | `tools/anime_pipeline.py` | 편성표→검색→토렌트→NAS 저장 통합 파이프라인 | ✅ |
+| 애니 자막 다운로드 | `tools/subtitle_downloader.py` | Anissia 6개 플랫폼(Google Drive, Tistory, Blog 등) 스크래핑 | ✅ |
+| NAS 파일 관리 | `tools/nas_scanner.py` | 에피소드 스캔, 이름 정규화, 릴리스 그룹 감지 | ✅ |
+| 토렌트 검색 | `tools/nyaa_client.py` | Nyaa.si 검색 + 6단계 fallback 전략 | ✅ |
+| 토렌트 다운로드 | `tools/qbit_client.py` | qBittorrent WebAPI 연동 | ✅ |
+| 제목 매칭 | `tools/title_matcher.py` | Romaji 변환 + fuzzy similarity 크로스 언어 매칭 | ✅ |
+| Vikunja 태스크 관리 | `.agent/workflows/helpers/vikunja_helper.py` | 태스크 CRUD + 라벨 + 안전 업데이트 | ✅ |
+| Gitea Wiki 관리 | `.agent/workflows/helpers/wiki_helper.py` | Wiki 페이지 CRUD | ✅ |
+| Discord Bot | `api/discord_bot.py` | 이벤트 핸들러 + NLU 라우팅 (~310줄) | ✅ |
+| CLI Bridge | - | Gemini CLI 영속 프로세스 (PTY 미지원으로 보류) | ⏸️ |
+
+## 모듈 상태
+
+| 모듈 | 주요 파일 | 상태 | 최근 변경 |
+|------|-----------|:----:|-----------|
+| NLU 분류 | `core/orchestrator.py` | ✅ | chat/clarify/anime/task 통합 |
+| 태스크 실행 | `core/task_pipeline.py` | ✅ | execute() 1회 + 선택적 review |
+| Gemini 래퍼 | `core/gemini_caller.py` | ✅ | text/agent 모드 |
+| 컨텍스트 | `core/context_manager.py` | ✅ | 관련 파일 선별 + 토큰 예산 |
+| 애니 파이프라인 | `tools/anime_pipeline.py` | ✅ | v2 에피소드 추출, 그룹 필터링, 자막 보호 |
+| Discord Bot | `api/discord_bot.py` | ✅ | 레거시 800줄 제거, ~310줄 |
+| 에이전트 워크플로우 | `.agent/` | ✅ | STATUS.md + 수칙 업데이트 |
+
+## 최근 마일스톤
+
+- **2026-03-16**: 에이전트 수칙 업데이트 + STATUS.md 도입 + .agents 통합
+- **2026-03-15**: MCP 서버 제거 → CLI 직접 실행 전환
+- **2026-03-15**: 레거시 NLU/핸들러 800줄 제거
+- **2026-03-15**: 애니 파이프라인 버그 5건 수정 + 아키텍처 문서화
+- **2026-03-15**: wiki_client update_page tags 버그 수정
+
+## 현재 미해결
+
+- **CLI Bridge PoC** (#203) — Windows PTY 미지원으로 보류. pywinpty 또는 Docker 환경 필요

.agent/references/architecture.md

@@ -77,4 +77,4 @@ v3: NLU → Agent 1회 (plan+code+verify 통합) → 선택적 Review (1~2 호
 ## 아키텍처 결정 (변경 불가)
 
 - **Gemini CLI subprocess 영구 유지** (SDK/API 금지)
-- 상세: `.agents/references/conventions.md` 참조
+- 상세: `.agent/references/conventions.md` 참조

.agent/workflows/end.md

@@ -113,22 +113,44 @@ C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\
 
 ---
 
-## 3. Wiki 동기화 (해당 시에만)
+## 3. 설계 문서 업데이트 (필수)
 
-| 코드 변경 | 대상 Wiki |
+- [ ] `.agent/references/STATUS.md` — 모듈 상태 테이블 업데이트 (변경 있었다면)
-|-----------|----------|
+  - 기능 추가/제거 → 기능 목록 테이블 업데이트
-| 서버 변경 | Architecture |
+  - 모듈 변경 → 모듈 상태 + 최근 변경 업데이트
-| 프론트엔드 변경 | Architecture |
+  - 마일스톤 달성 → 최근 마일스톤 추가
-| 인프라 변경 | Architecture |
+- [ ] `.agent/references/architecture.md` — 구조 변경이 있었다면 업데이트
-| 새 모듈/패키지 추가 | Architecture |
+
+## 4. Wiki 동기화 (로컬 변경 기반)
+
+로컬 references 파일이 변경되었는지 확인합니다:
 
 ```powershell
-C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" /tmp/wiki_content.md
+git diff --name-only .agent/references/
 ```
 
+변경된 파일이 있으면 **파일별로** Wiki에 업로드합니다:
+
+| 로컬 파일 | Wiki 페이지 |
+|-----------|------------|
+| `STATUS.md` | "Status" |
+| `architecture.md` | "Architecture" |
+
+```powershell
+# STATUS.md가 변경된 경우
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Status" .agent\references\STATUS.md
+```
+```powershell
+# architecture.md가 변경된 경우
+C:\ProgramData\miniforge3\envs\variet-agent\python.exe .agent\workflows\helpers\wiki_helper.py update "Architecture" .agent\references\architecture.md
+```
+
+> [!TIP]
+> 변경된 파일이 없으면 이 단계를 건너뜁니다.
+
 ---
 
-## 4. Git Commit & Push
+## 5. Git Commit & Push
 
 ```powershell
 git add -A
@@ -151,7 +173,7 @@ scope: (선택)
 
 ---
 
-## 5. 최종 체크리스트
+## 6. 최종 체크리스트
 
 > [!WARNING]
 > 아래 항목 중 하나라도 누락되면 세션 종료를 완료할 수 없습니다.
@@ -160,6 +182,7 @@ scope: (선택)
 - [ ] devlog index 업데이트됨
 - [ ] devlog entry 작성됨 (필요한 경우만)
 - [ ] Vikunja 태스크 생성/완료 처리됨 (커밋 전수 검사 기반)
-- [ ] Wiki 동기화됨 (아키텍처 변경이 있었다면)
+- [ ] STATUS.md 업데이트됨 (모듈/기능 변경이 있었다면)
+- [ ] Wiki 동기화됨 (변경된 references 파일이 있었다면)
 - [ ] git push 완료
 - [ ] 사용자에게 완료 보고

.agent/workflows/pre-task.md

@@ -10,7 +10,7 @@ description: 모든 구현 작업 전 실행하는 사전 점검 체크리스트
 
 > [!CAUTION]
 > **Python 실행 시 반드시 절대경로 사용** (conda 환경이라 `python`이 PATH에 없음):
-> `C:\ProgramData\miniforge3\envs\agent_chat\python.exe`
+> `C:\ProgramData\miniforge3\envs\variet-agent\python.exe`
 > 절대로 `python`, `py`, `python.exe`를 단독으로 쓰지 마세요.
 
 ## 1단계: 요구사항 정리

.agent/workflows/start.md

@@ -14,6 +14,7 @@ description: 세션 시작 시 프로젝트 맥락을 빠르게 복구하는 워
 
 `.agent/AGENT.md`를 읽고 에이전트 행동 규칙을 로딩합니다.
 `.agent/references/known-issues.md`를 읽어 최근 이슈를 파악합니다.
+`.agent/references/STATUS.md`를 읽어 전체 설계 현황과 기능 목록을 파악합니다.
 
 ### 1. Devlog 맥락 복구
 

.gitignore

@@ -1,12 +1,9 @@
 # 토큰 포함 파일 제외
 .agent/workflows/services.md
-.agents/workflows/services.md
 sessions/
 __pycache__/
 *.pyc
 .env
 logs/
-.agent/
 tests/verify_output.txt
 tests/test_output.txt
-

docs/devlog/2026-03-16.md

@@ -3,3 +3,4 @@
 | # | 시간 | 작업 | 커밋 | 상태 |
 |---|------|------|------|------|
 | 1 | 23:35~11:14 | 봇 기동 버그 3건 수정 (apscheduler, cp949 인코딩, workspaces 경로) + Vikunja 프로젝트 관리 기능 추가 (projects, report 커맨드) + agent 프롬프트 보강 | `c9068cd` | ✅ |
+| 2 | 13:46~14:29 | .agents→.agent 통합 + AGENT.md 수칙 업데이트(Security/Context/Blast Radius) + STATUS.md 도입 + end.md Wiki 동기화 개편 | `TBD` | ✅ |