korea-living-weather-index-mcp: Instructions file for Claude Code

CLAUDE.md — korea-living-weather-index-mcp

절대 규칙

• DEVPLAN.md 하나만 먼저 읽고 시작한다. 다른 문서 재탐색 금지.
• 웹서치 금지 (API 스펙은 DEVPLAN.md에 이미 있음).
• 불확실하면 추측성 재설계 대신 기본값 1개로 구현 후 DEVLOG.md에 "확인 필요"로 기록.
• 동일 오류 최대 3회까지만 재시도. 3회 실패 시 기록하고 사용자에게 보고.
• 역할은 "코드 구현 + 로컬 실측 테스트"까지다. fly launch, fly secrets set, flyctl deploy, fly logs 등 fly.io 관련 명령은 절대 스스로 실행하지 않는다.
• 배포 준비(코드 구현, 로컬 테스트, git commit/push)가 끝나면 아래 "작업 순서"의 정지 시점에서 멈추고, 사용자에게 PowerShell에서 fly launch --no-deploy부터 진행하도록 안내한다.

이 프로젝트 고유 사항

API 특성

• 오퍼레이션 2개: getUVIdxV5(자외선지수), getAirDiffusionIdxV5(대기정체지수)
• 인증키는 쿼리 파라미터 serviceKey (공공데이터포털 표준 방식 — URL 경로 삽입 아님)
• 응답은 XML이 기본이며, dataType=JSON 지정 시 JSON으로 온다
• 시간 필드 범위가 오퍼레이션마다 다르다:
  • 자외선지수: h0, h3, h6, ..., h75 (0~75시간, 26개 필드)
  • 대기정체지수: h3, h6, ..., h78 (3~78시간, 26개 필드)
  • 이 차이를 코드에서 명확히 구분할 것 (딕셔너리나 상수로 분리 관리 권장)
• areaNo가 필수(1)로 표기되어 있으나 "공백이면 전체지점조회"라는 설명이 공존 — 실측 필요 항목 (아래 참고)

등급 매핑 로직 (docstring에 반드시 명시)

자외선지수 (범위 기반):

def uv_grade(value: float) -> str:
    if value >= 11: return "위험"
    if value >= 8: return "매우높음"
    if value >= 6: return "높음"
    if value >= 3: return "보통"
    return "낮음"  # 0~2

대기정체지수 (값 기반, 25/50/75/100 근사 매핑 — 정확히 일치하지 않을 경우 가장 가까운 단계로 근사):

def air_diffusion_grade(value: float) -> str:
    if value >= 87.5: return "매우높음"   # 100 근사
    if value >= 62.5: return "높음"       # 75 근사
    if value >= 37.5: return "보통"       # 50 근사
    return "낮음"                          # 25 근사

실측 시 실제 값이 정확히 25/50/75/100 중 하나로만 오는지 먼저 확인하고, 그렇다면 근사 로직 대신 정확히 일치하는 값으로 매핑해도 된다. DEVLOG.md에 확인 결과를 기록할 것.

실측 필요 항목 (2-6절 절차 그대로 적용)

1. areaNo= 빈 문자열이 실제로 "전체지점조회"로 동작하는지, 아니면 ERROR-10(잘못된 요청 파라메터)이 발생하는지 — 둘 다 시도해서 확인. 만약 전체지점조회가 실제로 동작한다면 응답 크기가 매우 클 수 있으므로(3,838개 지점), 툴 설계에서 이 옵션을 굳이 노출할지도 판단 필요(기본적으로는 특정 areaNo 필수로 유지 권장).
2. 자외선지수 응답에 h78 필드가 실제로 포함되는지 (문서 표에는 h75까지만 정의, 응답 예제 XML에는 h78도 등장 — 불일치).
3. 대기정체지수 값이 정확히 25/50/75/100인지, 중간값도 존재하는지.
4. 에러 응답이 dataType=JSON 요청에도 XML로 오는지 (다른 공공데이터포털 API에서 흔한 패턴 — 아래 XML 폴백 파서로 대응).