docs: fill .agents/references with actual project content (architecture, tech-stack, conventions)

.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>(<scope>): <description>
 
 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`