From 6aaff48856df0da5e75d2717dc56de7b4a20b262 Mon Sep 17 00:00:00 2001 From: Variet Agent Date: Tue, 10 Mar 2026 23:02:19 +0900 Subject: [PATCH] docs: fill .agents/references with actual project content (architecture, tech-stack, conventions) --- .agent/.agents/references/architecture.md | 76 ++++++++++++++++++----- .agent/.agents/references/conventions.md | 52 +++++++++------- .agent/.agents/references/tech-stack.md | 47 +++++++++----- 3 files changed, 123 insertions(+), 52 deletions(-) diff --git a/.agent/.agents/references/architecture.md b/.agent/.agents/references/architecture.md index 7cfb37c..aa0b11b 100644 --- a/.agent/.agents/references/architecture.md +++ b/.agent/.agents/references/architecture.md @@ -1,35 +1,81 @@ # Architecture -> 이 프로젝트의 아키텍처를 설명하는 문서입니다. > AI 에이전트는 구현 전 이 문서를 반드시 확인합니다. ## 프로젝트 개요 - - -(프로젝트 설명을 여기에 작성하세요) +Belkin & Suchower (1998) + Vasicek 단일팩터 모델 기반으로, 한국 3사 전이행렬과 BOK ECOS 거시경제변수를 결합하여 **50년 Lifetime PD**를 호황/중립/불황 시나리오별로 산출하는 시스템. ## 디렉토리 구조 ``` -project-root/ -├── src/ # 소스 코드 -├── tests/ # 테스트 -├── docs/ # 문서 -├── .agents/ # AI 에이전트 설정 -└── ... +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` (국제 비교 통계) 사용. 한은 국민계정 직접 통계표코드 발견 시 교체 권장 diff --git a/.agent/.agents/references/conventions.md b/.agent/.agents/references/conventions.md index 4ed25ef..eb86240 100644 --- a/.agent/.agents/references/conventions.md +++ b/.agent/.agents/references/conventions.md @@ -6,18 +6,21 @@ | 대상 | 규칙 | 예시 | |------|------|------| -| 변수/함수 | camelCase | `getUserData()` | -| 클래스 | PascalCase | `UserService` | -| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` | -| 파일명 | kebab-case | `user-service.js` | -| CSS 클래스 | kebab-case | `.nav-header` | +| 변수/함수 | 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/` | ## 코드 스타일 -- 들여쓰기: (2 spaces / 4 spaces / tab) -- 세미콜론: (사용 / 미사용) -- 따옴표: (single / double) -- 줄바꿈: LF (Unix style) +- 언어: Python 3.12 +- 들여쓰기: 4 spaces +- 따옴표: double (`"string"`) +- Docstring: triple double quotes (`"""설명"""`) +- 줄바꿈: LF (git에서 자동 변환) +- 주석 언어: 한국어 (모듈/함수 docstring은 한국어) +- Type hints: 사용 권장 (`def foo(x: float) -> np.ndarray:`) ## 커밋 메시지 @@ -25,21 +28,28 @@ (): type: feat|fix|refactor|test|docs|chore|ci|infra -scope: (선택) +scope: (선택) ecos, vasicek, scenario, validation, ... ``` -**예시:** -- `feat(server): add WebSocket reconnection logic` -- `fix(frontend): resolve button overlap on mobile` -- `docs: update API documentation` +- Vikunja 태스크 참조: `#task-{ID}` 포함 (예: `feat(ecos): update stat codes #task-292`) -## 주석 +## 로깅 -- 한국어/영어 혼용 가능 -- TODO 주석: `// TODO: 설명` 형식 -- 복잡한 로직에는 반드시 WHY(왜) 주석 추가 +- `logging` 모듈 사용 (print 대신) +- 레벨: INFO (정상), WARNING (fallback), ERROR (실패) +- 포맷: `HH:MM:SS [LEVEL] 메시지` -## 테스트 +## 파일 구조 규칙 -- 테스트 파일 위치: (예: `__tests__/` 또는 `*.test.js`) -- 테스트 네이밍: `should [expected behavior] when [condition]` +- 각 패키지에 `__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` diff --git a/.agent/.agents/references/tech-stack.md b/.agent/.agents/references/tech-stack.md index af6ce80..4e90909 100644 --- a/.agent/.agents/references/tech-stack.md +++ b/.agent/.agents/references/tech-stack.md @@ -6,32 +6,47 @@ | 항목 | 버전 | 비고 | |------|------|------| -| (예: Node.js) | (예: 20.x) | (설치 경로 등) | -| (예: Python) | (예: 3.12) | (가상환경 경로 등) | +| Python | 3.12 | `C:\ProgramData\miniforge3\envs\quant\python.exe` | -## 프레임워크 +## 핵심 패키지 -| 항목 | 버전 | 용도 | -|------|------|------| -| (예: Express) | (예: 4.18) | (서버) | -| (예: React) | (예: 18.x) | (프론트엔드) | +| 패키지 | 용도 | 비고 | +|--------|------|------| +| 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 파싱 | ## 패키지 관리 -- 패키지 매니저: (npm / yarn / pnpm / pip 등) -- Lock 파일: (package-lock.json / yarn.lock 등) +- 패키지 매니저: conda (miniforge3) + pip +- 환경: `quant` (`C:\ProgramData\miniforge3\envs\quant`) +- 의존성 목록: `requirements.txt` +- 설치: `pip install -r requirements.txt` ## 개발 도구 | 도구 | 명령어 | |------|--------| -| 개발 서버 | (예: `cmd /c npm run dev`) | -| 빌드 | (예: `cmd /c npm run build`) | -| 테스트 | (예: `cmd /c npm test`) | -| 린트 | (예: `cmd /c npm run lint`) | +| 실행 (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` | ## 환경 변수 -| 변수명 | 용도 | 기본값 | -|--------|------|--------| -| (예: PORT) | (서버 포트) | (3000) | +| 변수명 | 용도 | 설정 위치 | +|--------|------|-----------| +| 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 |