refactor: .agents + .agent 단일 .agent 디렉토리로 통합 (agent_guide 포맷, 12→7 워크플로우 축소)

.agent/references/known-issues.md

@@ -0,0 +1,59 @@
+# Known Issues & Lessons Learned
+
+> **이 파일은 SSOT(Single Source of Truth)입니다.**
+> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요.
+> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.
+
+---
+
+## 포맷
+
+각 항목은 아래 형식을 따릅니다:
+
+```markdown
+### [날짜] [키워드] — 한줄 요약
+- **증상**: 무엇이 잘못되었는가
+- **원인**: 근본 원인
+- **해결**: 올바른 해결 방법
+- **주의**: 재발 방지를 위한 교훈
+```
+
+---
+
+## 공통 이슈
+
+### [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 토글 구현