drama-studio/.claude/skills/korean-dev-conventions.md

# 한국어 개발 컨벤션 (Korean Dev Conventions)

이 프로젝트의 한국어 개발 규칙입니다.

## 주석 규칙

### Python Docstring
```python
async def get_organization_info(self, name: str, context: List[str] = None) -> OrganizationInfo:
    """
    조직/단체 정보 조회 (context 기반 후보 선택)

    Args:
        name: 조직 이름
        context: 기사에서 추출한 컨텍스트 키워드 (산업, 유형 등)

    Returns:
        OrganizationInfo with founding_year, wikipedia_url, and image_url if found
    """
```

### 섹션 구분 주석
```python
# ===================
# Infrastructure (독립 포트 사용)
# ===================
```

### 인라인 주석
```python
# 캐시에서 조회 (context 기반 매칭)
cached_data, needs_refresh = await self.entity_cache.get_person(name, context=context)

# P154 = logo image
"property": "P154",
```

## 로깅 메시지

### 한글 + 영문 혼용 패턴
```python
logger.info(f"Found {len(image_urls)} image(s) for '{name}' (logo preferred)")
logger.info(f"Article {news_id} enriched with Wikipedia data in {processing_time:.2f}s")
logger.warning(f"Biocode registration failed (non-critical): {e}")
```

### 워커 로그 패턴
```python
logger.info("Starting Wikipedia Enrichment Worker")
logger.info(f"Processing job {job.job_id} for Wikipedia enrichment")
logger.info(f"Job {job.job_id} forwarded to image_generation")
```

## 에러 처리

### Try-Except 패턴
```python
try:
    info = await self.wikipedia_service.get_person_info(name, context=context)
except Exception as e:
    logger.error(f"Error getting person info for '{name}': {e}")
```

### 비치명적 에러 처리
```python
try:
    stats = await self.biocode_client.register_entities(people, organizations)
except Exception as e:
    # Biocode 등록 실패는 전체 파이프라인을 중단시키지 않음
    logger.warning(f"Biocode registration failed (non-critical): {e}")
```

## 변수/함수 네이밍

### Python (snake_case)
```python
# 변수
birth_date = "1990-01-15"
founding_year = 2004
image_urls = []
existing_names = set()

# 함수
def get_existing_names(biocode_data: dict) -> set:
async def _enrich_organizations(self, entities: List[Dict[str, Any]]):
```

### TypeScript (camelCase)
```typescript
// 변수
const articleCount = 100;
const isLoading = false;

// 함수
function getArticleById(id: string): Article
async function fetchDashboardStats(): Promise<Stats>
```

## 상수 정의

```python
# 영문 상수명 + 한글 주석
API_URL = "https://en.wikipedia.org/api/rest_v1/page/summary/{title}"
SEARCH_URL = "https://en.wikipedia.org/w/api.php"

# 기본값
DEFAULT_TIMEOUT = 10  # seconds
MAX_RETRIES = 3
```

## 타입 힌트

```python
from typing import Optional, Dict, Any, List

async def enrich_entities(
    self,
    people: List[Dict[str, Any]],
    organizations: List[Dict[str, Any]]
) -> Dict[str, Any]:
    """엔티티 목록을 Wikipedia 정보로 보강 (context 지원)"""
```

## 커밋 메시지

### 형식
```
<type>: <description>

- <detail 1>
- <detail 2>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

### 타입
- `feat`: 새로운 기능
- `fix`: 버그 수정
- `chore`: 설정, 문서 등 잡다한 작업
- `refactor`: 리팩토링
- `docs`: 문서 수정

### 예시
```
feat: Pass entity_type to biocode API

- biocode_worker: Forward entity_type (person/organization) to API
- Enables proper storage in famousPeople or famousOrganizations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```

## 파일 인코딩

- 모든 파일: UTF-8
- JSON 파일: `ensure_ascii=False` 사용

```python
with open(file_path, 'w', encoding='utf-8') as f:
    json.dump(content, f, ensure_ascii=False, indent=2)
```

## 다이어그램

- **도구**: Mermaid 사용 (ASCII art 금지)
- **용도**: 아키텍처, 플로우차트, 시퀀스 다이어그램, ERD 등

```markdown
```mermaid
flowchart LR
    A[입력] --> B{처리}
    B --> C[출력]
```
```