diff --git a/AGENTS.md b/AGENTS.md index c0a5ca2..8377017 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ 2. 이 `AGENTS.md` 3. `SKILL.md` 4. `kma-api.md`, `docs/decisions.md`, `docs/api-coverage.md` -5. `README.md` 및 나머지 `docs/` +5. `README.md`, `AI_AGENT_GUIDE.md` 및 나머지 `docs/` 6. 기존 코드와 테스트 7. 최소한의 되돌릴 수 있는 가정 @@ -36,7 +36,7 @@ - data.go.kr의 다른 KMA REST 서비스는 `DataGoKrClient`로 범용 호출합니다. - APIHub는 `ApiHubClient`로 `authKey` 기반 path 호출과 탐색 기능을 제공하고, `ApiHubGeneratedClient`로 공식 목록 endpoint의 함수형 래퍼를 제공합니다. - Python 지원 기준은 3.10 이상입니다. -- 런타임 의존성은 `requests`입니다. +- 런타임 의존성은 `httpx`입니다 (ADR-001). - 기본 테스트는 실제 KMA 네트워크 호출 없이 동작해야 합니다. ## 개발 환경 및 에이전트 정책 @@ -74,6 +74,7 @@ PC 개발은 Windows 호스트에서 직접 진행합니다. 본 저장소는 Py ## 문서 구성 - `README.md`: 사용자용 개요, 설치, 예제, 모델 요약. +- `AI_AGENT_GUIDE.md`: 이 라이브러리를 사용하는 외부 소비자 앱(TripMate 등)을 위한 AI 에이전트 가이드. - `kma-api.md`: 단기예보 endpoint 세부 사항과 KMA 응답 규칙. - `docs/apihub.md`: APIHub 인증키, 범용 호출, 탐색 기능, 응답 형식 규칙. - `docs/apihub-endpoints.md`: APIHub 함수형 endpoint 목록. diff --git a/CLAUDE.md b/CLAUDE.md index fb21ed3..8ecfafc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,22 +4,16 @@ 프로젝트 규칙은 `AGENTS.md`에, 아키텍처는 `docs/decisions.md`에 있습니다. 이 파일은 **현재 상태**와 **세션 간 연속성**에 집중합니다. -## 프로젝트 현황 (2026-05-31) +## 프로젝트 개요 기상청(KMA) 공공데이터포털(`VilageFcstInfoService_2.0`)과 APIHub를 Python에서 편하게 사용하기 위한 공용 클라이언트 라이브러리(`kma`). -현재 동기/비동기 통합 호출(`httpx` 기반) 및 `LatLon`/`GridPoint`/mapping 좌표 변환, 발표시각 자동 계산, Pydantic v2 frozen 모델을 기반으로 안정적인 public surface를 제공합니다. 또한 data.go.kr 86개 dataset 카탈로그 및 20개 이상의 helper, APIHub 470개 generated wrapper가 완비되어 있고 100개가 넘는 견고한 mock 테스트 게이트를 지니고 있습니다. +동기/비동기 통합 호출(`httpx` 기반) 및 `LatLon`/`GridPoint`/mapping 좌표 변환, 발표시각 자동 계산, Pydantic v2 frozen 모델을 기반으로 안정적인 public surface를 제공합니다. 또한 data.go.kr 86개 dataset 카탈로그 및 20개 이상의 helper, APIHub 470개 generated wrapper가 완비되어 있고 100개가 넘는 견고한 mock 테스트 게이트를 지니고 있습니다. -### 현재 작업 +현재 진척도와 다음 작업은 `docs/resume.md`, 최근 작업 이력은 `docs/journal.md`, 남은 백로그는 `docs/tasks.md`를 참고하세요. 이 파일에 진척도를 하드코딩하지 않습니다 — 오래된 상태 정보가 남는 것을 막기 위함입니다. -- maplibre-vworld-js 프로젝트의 뛰어난 에이전트 개발 스타일, 고정 worktree 정책, AI용 가이드 문서, 그리고 MCP 설정을 가져와서 본 프로젝트에 적합하게 적용 중입니다 (`feat/style-and-mcp-settings` 브랜치). +## 에이전트 worktree -### 잔존 기술 부채 - -- `docs/resume.md`의 백로그를 참고합니다. 주요 부채는 HTTP 에러 핸들링 공통화 및 result code 예외 처리 통합입니다. - -## 에이전트 worktree + CodeGraph - -ChatGPT Codex는 `F:\dev\python-kma-api-codex`, Claude Code는 `F:\dev\python-kma-api-claude`, Google Antigravity 2.0은 `F:\dev\python-kma-api-antigravity`를 고정 worktree로 사용합니다. 새 작업은 해당 worktree에서 `git fetch` 후 `git switch -c agent/ main`으로 브랜치를 생성하여 작업합니다. CodeGraph는 worktree마다 1회 `codegraph init -i`로 초기화하고 이후에는 `codegraph sync`를 통해 상태를 유지합니다. `.codegraph/`는 gitignore 대상입니다. +에이전트별 고정 worktree 경로와 CodeGraph 초기화 절차는 `AGENTS.md`의 "개발 환경 및 에이전트 정책"을 따릅니다. 여기서 중복 서술하지 않습니다. ## 로컬 개발 환경 @@ -52,17 +46,10 @@ python -m mypy src/kma codegraph sync && codegraph status ``` -## 주요 결정 사항 (ADR 요약) +## 주요 결정 사항 -- **ADR-001: httpx 기반 HTTP 클라이언트**: 동기/비동기 호출의 일관성과 `params=` 인코딩 최적화를 위함. -- **ADR-002: Pydantic v2 frozen 모델**: 응답 모델의 불변성과 비교/직렬화의 예측 가능성을 보장. -- **ADR-003: 인증값 보안 정책**: 로그, 캐시 키, Pydantic repr에 `serviceKey` / `authKey` 유출 원천 차단. -- **ADR-004: data.go.kr/APIHub 이중 gateway 분리**: 인증 방식 및 동작이 다른 두 gateway의 결합도 최소화. +아키텍처 ADR은 `docs/decisions.md`에 원본으로 누적됩니다. 여기서 요약을 따로 유지하지 않습니다 — 요약은 ADR이 추가될 때마다 갱신을 잊기 쉬워 실제 내용과 어긋나기 쉽습니다. ## 작업 후 의무사항 -1. `docs/journal.md`에 항목 추가 (날짜·요약·관련 파일·결정·다음 작업, 역시간순) -2. `docs/resume.md`의 진척도 및 다음 작업 업데이트 -3. 결정 변경이 있었다면 `docs/decisions.md`에 ADR 추가 -4. 사용자 가시 변경이면 `CHANGELOG.md` 갱신 -5. `pytest`, `ruff`, `mypy` 검증 무사 통과 확인 +`AGENTS.md`의 "작업 후 체크리스트"를 따릅니다. diff --git a/README.md b/README.md index 7af362f..2fe03f0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # python-kma-api +![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg) +![GPL-3.0-or-later 라이선스](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg) +![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg) + Korea Meteorological Administration(KMA, 기상청) 공공데이터포털과 APIHub를 Python에서 편하게 쓰기 위한 공용 클라이언트 라이브러리입니다. `python-kma-api`는 `kma`라는 import package를 제공합니다. 특정 앱의 adapter나 DB 스키마를 전제로 하지 않고, `VilageFcstInfoService_2.0`의 초단기실황, 초단기예보, 단기예보 API를 한 인터페이스로 감싸며, 위도/경도와 KMA 격자 좌표 변환, 발표시각 계산, enum 기반 코드 라벨 매핑, provenance metadata, 예외 처리를 함께 제공합니다. @@ -8,6 +12,35 @@ Korea Meteorological Administration(KMA, 기상청) 공공데이터포털과 API --- +## 먼저 읽을 문서 + +| 필요 정보 | 문서 | +|---|---| +| 빠른 시작, 설치, 사용 예제 | 이 문서(README.md) | +| 단기예보 API 세부 명세와 구현 주의사항 | [kma-api.md](kma-api.md) | +| 구현자/에이전트용 프로젝트 불변조건 | [SKILL.md](SKILL.md) | +| 작업 운영 규칙과 모듈 소유권 | [AGENTS.md](AGENTS.md) | +| 이 라이브러리를 사용하는 외부 소비자 앱을 위한 AI 에이전트 가이드 | [AI_AGENT_GUIDE.md](AI_AGENT_GUIDE.md) | +| 현재 구현 범위와 API 개수 | [docs/api-coverage.md](docs/api-coverage.md) | +| APIHub 470개 함수형 endpoint 목록 | [docs/apihub-endpoints.md](docs/apihub-endpoints.md) | +| APIHub 범용 클라이언트와 탐색 | [docs/apihub.md](docs/apihub.md) | +| data.go.kr 범용 클라이언트 | [docs/datagokr.md](docs/datagokr.md) | +| data.go.kr/APIHub 중복 표 | [docs/datagokr-apihub-overlap.md](docs/datagokr-apihub-overlap.md) | +| 구조적 의사결정 기록(ADR) | [docs/decisions.md](docs/decisions.md) | +| 테스트 작성과 live test 기준 | [docs/testing.md](docs/testing.md) | +| 흔한 오류 증상과 해결책 | [docs/troubleshooting.md](docs/troubleshooting.md) | +| 반복 실수 방지 로그 | [docs/repeated-mistakes.md](docs/repeated-mistakes.md) | +| 에이전트 작업/문서화 표준 | [docs/agent-guide.md](docs/agent-guide.md) | +| 현재 진척도와 다음 작업 | [docs/resume.md](docs/resume.md) | +| 최근 작업 일지 | [docs/journal.md](docs/journal.md) | +| 백로그 | [docs/tasks.md](docs/tasks.md) | +| 라이브 테스트 서비스키 이슈 | [docs/live-test-key-issues.md](docs/live-test-key-issues.md) | +| 로컬 인증키 env 파일 예시 | [.env.example](.env.example) | +| 기여 절차 | [CONTRIBUTING.md](CONTRIBUTING.md) | +| 변경 이력 | [CHANGELOG.md](CHANGELOG.md) | + +--- + ## 핵심 특징 - **공식 단기예보 3종 우선 지원**: `getUltraSrtNcst`, `getUltraSrtFcst`, `getVilageFcst`를 `KmaClient`에서 호출합니다. @@ -686,23 +719,7 @@ tools/ └── debug_streamlit.py ``` -문서: - -- [.env.example](.env.example): 로컬 인증키 env 파일 예시 -- [README.md](README.md): 사용자용 가이드 -- [kma-api.md](kma-api.md): API 세부 명세와 구현 주의사항 -- [SKILL.md](SKILL.md): 에이전트/구현자용 불변조건 -- [AGENTS.md](AGENTS.md): 작업 운영 규칙과 모듈 소유권 -- [docs/api-coverage.md](docs/api-coverage.md): 현재 구현 범위와 API 개수 -- [docs/apihub-endpoints.md](docs/apihub-endpoints.md): APIHub 470개 함수형 endpoint 목록 -- [docs/repeated-mistakes.md](docs/repeated-mistakes.md): 반복 실수 방지 로그 -- [docs/apihub.md](docs/apihub.md): APIHub 범용 클라이언트와 탐색 -- [docs/datagokr.md](docs/datagokr.md): data.go.kr 범용 클라이언트 -- [docs/datagokr-apihub-overlap.md](docs/datagokr-apihub-overlap.md): data.go.kr/APIHub 중복 표 -- [docs/testing.md](docs/testing.md): 테스트 작성과 live test 기준 -- [docs/troubleshooting.md](docs/troubleshooting.md): 흔한 오류 증상과 해결책 -- [CONTRIBUTING.md](CONTRIBUTING.md): 기여 절차 -- [CHANGELOG.md](CHANGELOG.md): 변경 이력 +문서 지도는 상단의 [먼저 읽을 문서](#먼저-읽을-문서) 표를 참고하세요. ---