chore: migrate .agent/ to .agents/ directory structure

.agents/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-10] ECOS API 통계표코드 — 대부분 404 반환
+- **증상**: `111Y002`, `817Y002`, `901Y067/A` 등 다수의 통계표코드/항목코드가 "해당하는 데이터가 없습니다" 반환
+- **원인**: ECOS API 통계표 구조가 공식 문서와 다름. 예: GDP 성장률은 `111Y002`가 아닌 `902Y015` (국제 비교 통계), CD금리는 `817Y002`가 아닌 `721Y001`
+- **해결**: `StatisticItemList` API로 각 통계표의 항목코드를 조회한 후, `StatisticSearch`로 실제 데이터 반환 확인. 검증된 전체 코드 목록은 `config.yaml`에 기록됨
+- **주의**: ECOS 통계표코드 변경 시 반드시 `StatisticItemList` → `StatisticSearch` 2단계 검증 수행. 선행지수(`901Y067`)는 연간 데이터 없음(월별만 존재)
+
+### [2026-03-10] Windows CP949 인코딩 — Unicode 렌더링 실패
+- **증상**: `matplotlib`에서 ✓, ✗, — (em dash) 등 Unicode 기호가 CP949에서 렌더링 실패
+- **원인**: Windows 콘솔/Malgun Gothic 폰트가 해당 기호를 지원하지 않음
+- **해결**: `sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')` + ASCII 대체 문자 사용 (Pass O / Fail X)
+- **주의**: 모든 Python 스크립트의 최상단에 UTF-8 stdout 설정 추가 필요
+
+### [2026-03-10] pandas fillna(method=) — Deprecation 오류
+- **증상**: `fillna(method="ffill")` 호출 시 FutureWarning/Error
+- **원인**: pandas 2.x에서 `fillna(method=)` 인자 deprecated
+- **해결**: `df.ffill().bfill()` 메서드 체인으로 대체
+- **주의**: pandas 2.x 이상 사용 시 `fillna(method=)` 전면 금지