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

2026-03-11 00:31:59 +09:00
parent 6aaff48856
commit ebdc6b805b
16 changed files with 13 additions and 67 deletions
--- a/.agents/references/architecture.md
+++ b/.agents/references/architecture.md
@@ -0,0 +1,81 @@
+# Architecture
+
+> AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
+
+## 프로젝트 개요
+
+Belkin & Suchower (1998) + Vasicek 단일팩터 모델 기반으로, 한국 3사 전이행렬과 BOK ECOS 거시경제변수를 결합하여 **50년 Lifetime PD**를 호황/중립/불황 시나리오별로 산출하는 시스템.
+
+## 디렉토리 구조
+
+```
+LifetimePD/
+├── main.py                          # 7단계 파이프라인 오케스트레이터
+├── config.yaml                      # API 키, 모형 파라미터, 시나리오 설정
+├── data/
+│   ├── transition_matrices.py       # 한국 3사 전이행렬 (builtin + CSV 로더)
+│   └── macro_data.py                # BOK ECOS API 거시경제변수 6종 수집
+├── models/
+│   ├── credit_cycle.py              # Belkin & Suchower Zt 추정 (WLS)
+│   ├── vasicek.py                   # Vasicek 조건부 PD/전이행렬
+│   └── macro_model.py               # Zt~거시 OLS 회귀 (Stepwise AIC)
+├── scenarios/
+│   └── scenario_engine.py           # 호황/중립/불황 시나리오 + Mean-reversion
+├── projection/
+│   └── lifetime_pd.py               # 50년 누적/한계 PD + 확률가중평균
+├── validation/
+│   └── statistical_tests.py         # ADF, Ljung-Box, R², ARCH, PD 성질 검증
+├── output/
+│   └── visualizer.py                # 차트 7종 + 요약 테이블
+├── results/                         # 생성 결과물 (PNG, CSV)
+├── doc/                             # 원본 자료 (3사 PDF, ECOS API 명세)
+│   ├── ECOS_API/                    # 한은 API 개발명세서 + 통계표
+│   └── *.pdf                        # 3사 전이행렬 원본 PDF
+├── docs/
+│   ├── methodology.md               # 이론 방법론 상세 (9개 섹션)
+│   └── devlog/                      # 세션별 작업 기록
+└── .agent/.agents/                  # AI 에이전트 설정
+```
+
+## 핵심 모듈
+
+| 모듈 | 역할 | 의존성 |
+|------|------|--------|
+| `data/transition_matrices.py` | 전이행렬 로딩 + TTC 산출 | numpy, scipy |
+| `data/macro_data.py` | ECOS API 6종 거시변수 수집 | requests, pandas |
+| `models/credit_cycle.py` | Belkin-Suchower Zt 추정 (WLS) | numpy, scipy.optimize |
+| `models/vasicek.py` | 조건부 PD/전이행렬 | numpy, scipy.stats |
+| `models/macro_model.py` | Zt~거시 OLS + Stepwise AIC | statsmodels |
+| `scenarios/scenario_engine.py` | 3-시나리오 Zt 경로 + Mean-reversion | numpy |
+| `projection/lifetime_pd.py` | 50년 행렬곱 PD + 가중평균 | numpy |
+| `validation/statistical_tests.py` | 8개 통계 검정 | statsmodels, scipy |
+| `output/visualizer.py` | 차트 7종 | matplotlib |
+
+## 데이터 흐름
+
+```
+전이행렬(26yr) → TTC 평균 → Φ⁻¹ 임계값 → WLS Zt 추정
+                                            ↓
+ECOS API 거시 6변수 ──→ Stepwise OLS ──→ Zt~거시 회귀
+                                            ↓
+시나리오(3종) × PIT→MR→TTC 수렴 → 조건부 TM → 행렬곱 → PD term structure
+```
+
+## 실행 방법
+
+```powershell
+# ECOS API 사용 (기본)
+C:\ProgramData\miniforge3\envs\quant\python.exe main.py
+
+# Fallback 데이터 사용
+C:\ProgramData\miniforge3\envs\quant\python.exe main.py --no-api
+
+# ρ 동시 추정
+C:\ProgramData\miniforge3\envs\quant\python.exe main.py --estimate-rho
+```
+
+## 미완료 사항 (다음 작업자 참고)
+
+1. **#290 실제 3사 전이행렬 CSV 변환** — `doc/`의 PDF에서 전이행렬을 추출하여 `data/raw/` CSV로 변환 필요. 현재는 builtin synthetic 데이터 사용 중
+2. **#293 거시 시나리오 고도화** — IMF WEO/KDI 전망치를 직접 입력하여 시나리오 정밀화
+3. **GDP 성장률 코드** — 현재 `902Y015/KOR` (국제 비교 통계) 사용. 한은 국민계정 직접 통계표코드 발견 시 교체 권장
--- a/.agents/references/conventions.md
+++ b/.agents/references/conventions.md
@@ -0,0 +1,62 @@
+# Coding Conventions
+
+> AI 에이전트는 코드를 작성하기 전 이 컨벤션을 확인합니다.
+
+## 네이밍
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | snake_case | `compute_ttc_matrix()` |
+| 클래스 | PascalCase | `MacroZtModel`, `ScenarioEngine` |
+| 상수 | UPPER_SNAKE_CASE | `API_KEY`, `LABEL_MAP` |
+| 파일명 | snake_case.py | `credit_cycle.py`, `macro_data.py` |
+| 모듈(디렉토리) | snake_case | `data/`, `models/`, `projection/` |
+
+## 코드 스타일
+
+- 언어: Python 3.12
+- 들여쓰기: 4 spaces
+- 따옴표: double (`"string"`)
+- Docstring: triple double quotes (`"""설명"""`)
+- 줄바꿈: LF (git에서 자동 변환)
+- 주석 언어: 한국어 (모듈/함수 docstring은 한국어)
+- Type hints: 사용 권장 (`def foo(x: float) -> np.ndarray:`)
+
+## Python 환경
+
+- **경로**: `C:\ProgramData\miniforge3\envs\quant`
+- **실행**: `C:\ProgramData\miniforge3\envs\quant\python.exe`
+- 모든 Python 스크립트 실행 시 위 경로의 python.exe를 사용
+- PowerShell에서: `& "C:\ProgramData\miniforge3\envs\quant\python.exe" script.py`
+
+## 커밋 메시지
+
+```
+<type>(<scope>): <description>
+
+type: feat|fix|refactor|test|docs|chore|ci|infra
+scope: (선택) ecos, vasicek, scenario, validation, ...
+```
+
+- Vikunja 태스크 참조: `#task-{ID}` 포함 (예: `feat(ecos): update stat codes #task-292`)
+
+## 로깅
+
+- `logging` 모듈 사용 (print 대신)
+- 레벨: INFO (정상), WARNING (fallback), ERROR (실패)
+- 포맷: `HH:MM:SS [LEVEL] 메시지`
+
+## 파일 구조 규칙
+
+- 각 패키지에 `__init__.py` 포함
+- `main.py` = 파이프라인 오케스트레이터 (직접 로직 최소화)
+- 각 모듈은 독립적으로 import/테스트 가능하게 설계
+- config는 `config.yaml`에 집중, 코드 내 하드코딩 최소화
+
+## 수학 표기 규칙 (코드 내)
+
+- Φ = `scipy.stats.norm.cdf`
+- Φ⁻¹ = `scipy.stats.norm.ppf`
+- ρ = `rho` (변수명)
+- Z_t = `zt` 또는 `z_values`
+- 전이행렬 = `tm` 또는 `transition_matrix`
--- a/.agents/references/known-issues.md
+++ b/.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=)` 전면 금지
--- a/.agents/references/tech-stack.md
+++ b/.agents/references/tech-stack.md
@@ -0,0 +1,52 @@
+# Tech Stack
+
+> AI 에이전트는 구현 전 이 문서를 확인하여 올바른 기술/버전을 사용합니다.
+
+## 언어 & 런타임
+
+| 항목 | 버전 | 비고 |
+|------|------|------|
+| Python | 3.12 | `C:\ProgramData\miniforge3\envs\quant\python.exe` |
+
+## 핵심 패키지
+
+| 패키지 | 용도 | 비고 |
+|--------|------|------|
+| numpy | 행렬 연산, 수치 계산 | 전이행렬 곱, PD 계산 |
+| scipy | 최적화(WLS), 정규분포 | Zt 추정, Vasicek 임계값 |
+| pandas | 데이터프레임, 시계열 | 거시변수, API 응답 처리 |
+| statsmodels | OLS 회귀, 진단 검정 | Zt~거시 모형, ADF/LB/BP |
+| matplotlib | 차트 생성 | 한글 폰트: Malgun Gothic |
+| requests | HTTP 요청 | ECOS API 호출 |
+| tabulate | 표 출력 | 콘솔 결과 테이블 |
+| pyyaml | 설정 파일 | config.yaml 파싱 |
+
+## 패키지 관리
+
+- 패키지 매니저: conda (miniforge3) + pip
+- 환경: `quant` (`C:\ProgramData\miniforge3\envs\quant`)
+- 의존성 목록: `requirements.txt`
+- 설치: `pip install -r requirements.txt`
+
+## 개발 도구
+
+| 도구 | 명령어 |
+|------|--------|
+| 실행 (API 사용) | `C:\ProgramData\miniforge3\envs\quant\python.exe main.py` |
+| 실행 (Fallback) | `C:\ProgramData\miniforge3\envs\quant\python.exe main.py --no-api` |
+| Vikunja 조회 | `python .agents\workflows\helpers\vikunja_helper.py list` |
+| Wiki 업데이트 | `python .agents\workflows\helpers\wiki_helper.py update "페이지" /tmp/content.md` |
+
+## 환경 변수
+
+| 변수명 | 용도 | 설정 위치 |
+|--------|------|-----------|
+| ECOS API Key | 한은 Open API 인증 | `config.yaml` → `ecos.api_key` |
+
+## 외부 API
+
+| 서비스 | URL | 인증 |
+|--------|-----|------|
+| BOK ECOS | `https://ecos.bok.or.kr/api` | API Key in URL path |
+| Gitea | `https://git.variet.net` | Token in header |
+| Vikunja | `https://plan.variet.net` | Bearer token |