todos2/.claude/skills/korean-dev-conventions.md

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

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

주석 규칙

Python Docstring

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
    """

섹션 구분 주석

# ===================
# Infrastructure (독립 포트 사용)
# ===================

인라인 주석

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

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

로깅 메시지

한글 + 영문 혼용 패턴

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}")

워커 로그 패턴

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 패턴

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}")

비치명적 에러 처리

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)

# 변수
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)

// 변수
const articleCount = 100;
const isLoading = false;

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

상수 정의

# 영문 상수명 + 한글 주석
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

타입 힌트

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 사용

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