variet-agent/.agents/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 토글 구현