# 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`