63 lines
2.0 KiB
Markdown
63 lines
2.0 KiB
Markdown
# 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`
|