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

[digitie]

요약

14개 저장소 문서 컨벤션 통일 작업의 일부로, kor-travel-geo(구 python-kraddr-geo)를 기준 템플릿으로 삼아 이 저장소의 README.md / AGENTS.md / CLAUDE.md를 정리했습니다. 문서 전용(docs-only) 변경이며 src/, tests/, Streamlit 디버그 UI는 건드리지 않았습니다.

변경 내용

README.md

• H1 바로 아래 배지(Python 3.10+, GPL-3.0-or-later, Ruff) 추가. pyproject.toml의 requires-python/license 실제 값 기준.
• 하단에 흩어져 있던 "문서:" 불릿 목록을 상단 ## 먼저 읽을 문서 표로 이동.
• 기존에 README 어디에서도 링크되지 않았던 문서를 표에 추가로 링크: docs/agent-guide.md, docs/decisions.md, docs/journal.md, docs/resume.md, docs/tasks.md, docs/live-test-key-issues.md, AI_AGENT_GUIDE.md.

AGENTS.md

• "런타임 의존성은 requests입니다" 사실 오류 수정 → httpx (ADR-001이 이미 httpx 채택 이유를 명시하고 있었음).
• 지시 우선순위 목록과 "문서 구성" 목록에 누락되어 있던 AI_AGENT_GUIDE.md를 추가.

CLAUDE.md

• AGENTS.md와 중복 서술되던 "에이전트별 고정 worktree" 표를 제거하고, AGENTS.md의 해당 절을 가리키는 포인터로 축소.
• 이미 2026-05-30에 병합·완료된 옛 작업(feat/style-and-mcp-settings 브랜치 "적용 중")을 여전히 진행 중으로 서술하던 stale 상태 정보를 제거.
• docs/decisions.md와 이미 어긋나 있던(ADR-005 누락) ADR 요약, 그리고 AGENTS.md의 "작업 후 체크리스트"를 그대로 복제하던 절을 각각 원본 문서를 가리키는 포인터로 교체 — 요약본이 원본과 다시 어긋나는 것을 구조적으로 방지.

검토했으나 반영하지 않은 항목

• pyproject.toml [tool.ruff] target-version을 py39 → py310(requires-python/mypy와 정합)으로 맞추는 것도 지시에 포함되어 있었으나, 실제로 반영해보니 src/kma/apihub.py 1건, tests/*.py 7건, tools/debug_streamlit.py 1건에서 새 B905/UP035 lint 오류 9건이 드러났습니다. 모두 이번 문서 전용 패스에서 건드리지 않기로 한 영역이라 원복했습니다. 코드를 함께 고치는 별도 PR에서 처리하는 것을 제안합니다.
• docs/decisions.md는 이미 ADR-001~005 형식(상태/결정/이유/결과, supersede 규칙 명시)이 갖춰져 있어 별도 수정하지 않았습니다.
• LICENSE, CHANGELOG.md는 이미 존재하고 정상 상태라 변경하지 않았습니다.

검증

python -m pytest -q -m "not integration"   # 149 passed, 12 deselected
python -m ruff check .                      # All checks passed
python -m mypy src/kma                      # Success: no issues found in 21 source files

🤖 Generated with Claude Code

https://claude.ai/code/session_01XF9V2q4mAmhmXn6t5G9Hfe