Skip to content

docs: 문서 컨벤션 통일 패스 (kor-travel-geo 기준) #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
digitie merged 1 commit into from
Aug 29, 2026
Merged

docs: 문서 컨벤션 통일 패스 (kor-travel-geo 기준) #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. 최소한의 되돌릴 수 있는 가정

Expand All @@ -36,7 +36,7 @@
- data.go.kr의 다른 KMA REST 서비스는 `DataGoKrClient`로 범용 호출합니다.
- APIHub는 `ApiHubClient`로 `authKey` 기반 path 호출과 탐색 기능을 제공하고, `ApiHubGeneratedClient`로 공식 목록 endpoint의 함수형 래퍼를 제공합니다.
- Python 지원 기준은 3.10 이상입니다.
- 런타임 의존성은 `requests`입니다.
- 런타임 의존성은 `httpx`입니다 (ADR-001).
- 기본 테스트는 실제 KMA 네트워크 호출 없이 동작해야 합니다.

## 개발 환경 및 에이전트 정책
Expand Down Expand Up @@ -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 목록.
Expand Down
29 changes: 8 additions & 21 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<topic> main`으로 브랜치를 생성하여 작업합니다. CodeGraph는 worktree마다 1회 `codegraph init -i`로 초기화하고 이후에는 `codegraph sync`를 통해 상태를 유지합니다. `.codegraph/`는 gitignore 대상입니다.
에이전트별 고정 worktree 경로와 CodeGraph 초기화 절차는 `AGENTS.md`의 "개발 환경 및 에이전트 정책"을 따릅니다. 여기서 중복 서술하지 않습니다.

## 로컬 개발 환경

Expand Down Expand Up @@ -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`의 "작업 후 체크리스트"를 따릅니다.
51 changes: 34 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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, 예외 처리를 함께 제공합니다.
Expand All @@ -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`에서 호출합니다.
Expand Down Expand Up @@ -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): 변경 이력
문서 지도는 상단의 [먼저 읽을 문서](#먼저-읽을-문서) 표를 참고하세요.

---

Expand Down
Loading