LifetimePD/.agent/.agents/references/conventions.md

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:)

커밋 메시지

<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