variet-agent/.agent/references/known-issues.md

Known Issues & Lessons Learned

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

---

포맷

각 항목은 아래 형식을 따릅니다:

### [날짜] [키워드] — 한줄 요약
- **증상**: 무엇이 잘못되었는가
- **원인**: 근본 원인
- **해결**: 올바른 해결 방법
- **주의**: 재발 방지를 위한 교훈

---

공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌

• 증상: curl 명령이 예상과 다른 응답 형식을 반환
• 원인: PowerShell에서 curl은 Invoke-WebRequest의 별칭
• 해결: **curl.exe**를 명시적으로 사용
• 주의: HTTP 관련 모든 명령에서 curl.exe 사용 필수

[2026-03-08] PowerShell npm — 실행 정책 오류

• 증상: npm run 명령이 실행 정책 관련 오류로 실패
• 원인: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
• 해결: cmd /c npm run dev 형식으로 cmd를 통해 실행
• 주의: npm 관련 명령은 항상 cmd /c 접두어 사용 권장

---

프로젝트별 이슈

아래에 프로젝트 특화 이슈를 추가하세요.

[2026-03-08] nas_scanner docstring — Unicode escape SyntaxError

• 증상: from tools.nas_scanner import NasScanner 시 SyntaxError: (unicode error) 'unicodeescape' codec can't decode \N
• 원인: docstring 내 \\NasData 경로에서 \N이 Python Unicode named escape로 해석
• 해결: docstring을 r"""...""" (raw string)으로 변경
• 주의: Windows 경로(\\, \N, \U 등)가 포함된 docstring은 반드시 r"""로 작성

[2026-03-08] title_matcher _kata_to_hira — 장음기호 깨짐

• 증상: フリーレン → ふり゜れん (ー가 ゜로 변환)
• 원인: 카타카나 범위 0x30A0~0x30FF에 기호 문자(ー U+30FC) 포함
• 해결: 범위를 0x30A1~0x30F6으로 좁혀 실제 문자만 변환
• 주의: 유니코드 범위 지정 시 기호/구두점 문자 포함 여부 확인 필수

[2026-03-08] anime_pipeline — Nyaa 검색 0건 반환

• 증상: 한자 포함 원제의 로마자 변환 결과(葬送nofuriren) + suffix 고정으로 Nyaa 검색 실패
• 원인: 단일 검색 전략, suffix(ASW HEVC) 항상 부착
• 해결: 6단계 fallback 전략 (romaji±suffix → 원제±suffix → 한글±suffix)
• 주의: 외부 API 검색 시 반드시 다중 전략 + suffix 토글 구현

[2026-03-12] Gemini CLI MCP — settings.json 위치

• 증상: MCP 도구가 인식되지 않음 (프로젝트 .gemini/settings.json에 설정했으나 실패)
• 원인: Gemini CLI는 cwd 기준으로 .gemini/settings.json을 탐색. cwd가 다른 워크스페이스면 MCP 설정 못 찾음
• 해결: ~/.gemini/settings.json (홈 레벨)에 mcpServers 등록. _set_thinking_budget에서 자동 관리
• 주의: MCP 서버 설정은 반드시 홈 레벨 settings.json에 등록. 프로젝트 레벨은 불충분

[2026-03-12] MCP 역할별 접근 제어 — 모든 역할이 MCP 도구 접근

• 증상: coder, reviewer 등 텍스트 전용 역할도 anime/infra MCP 도구에 접근 가능
• 원인: _set_thinking_budget()이 역할 무관하게 모든 MCP 서버를 settings.json에 등록
• 해결: ROLE_MCP_ACCESS dict 추가, agent만 MCP 등록, 나머지는 제거. asyncio.Lock 추가로 settings.json 레이스 방지
• 주의: settings.json은 글로벌 파일이므로, 역할 전환 시 반드시 이전 설정을 정리해야 함

[2026-03-12] Gemini CLI yolo — 에이전트 자율성 위험

• 증상: 애니 다운로드 요청 시 에이전트가 음악/만화를 다운로드하고 엉뚱한 폴더 생성
• 원인: --approval-mode yolo는 MCP 도구 + 쉘 + 파일 조작 모두 무승인 허용. 프롬프트 제한은 강제력 없음
• 해결 (검토중): MCP 대신 Python 도구를 소스코드로 직접 제공하여 Gemini CLI가 읽고 사용하는 방식 검토
• 주의: 프롬프트는 "부탁"이지 "강제"가 아님. 안전장치는 코드(도구) 레벨에 구현해야 함

[2026-03-12] Nyaa 검색 — anime 카테고리 미지정

• 증상: 애니 검색 시 음악, 만화, 라이트노벨 등 무관한 토렌트가 다운로드됨
• 원인: NyaaClient.search() 기본 category가 0_0(전체). Music, Manga 등 포함
• 해결 (예정): 기본 category를 1_2(Anime English) 또는 1_0(Anime 전체)로 변경
• 주의: 외부 검색 API 사용 시 반드시 카테고리/필터를 명시적으로 지정