HeatGuard는 향후 폭염예보와 지역별 무더위쉼터 대응력을 결합해 우선 점검이 필요한 시·군·자치구를 찾는 B.D.A.I Skillton 프로젝트다.
핵심 질문은 다음과 같다.
향후 3개 예보일 내 일최고체감온도 35°C 이상이 2일 연속 예상되는 시군구 중, 고령인구 대비 쉼터 대응력이 부족한 지역은 어디인가?
이 결과는 행정 점검 우선순위를 지원하기 위한 지표다. 쉼터 부족이 온열질환을 발생시킨다는 인과관계나 개인의 건강위험을 의미하지 않는다.
타임리 작업공간에는 skills/data-analysis/ 폴더를 추가한다. 이 폴더의
SKILL.md가 HeatGuard 분석 절차의 진입점이며, 같은 폴더의 스크립트와
참고자료를 상대 경로로 사용한다. 분석 계산 자체는 모델 API에 종속되지
않는다.
Skill 진입점과 분석 구현을 한 폴더에 둔다.
skills/data-analysis/
├── SKILL.md Agent가 읽는 실행·판단 지침
├── config/ 분석 기본값
├── metadata/ 출처 등록부와 원본 파일 manifest
├── reference/ 데이터 명세·통합·방법론 문서
├── scripts/ 수집·정제·분석·시각화 코드
├── tests/ 합성 fixture와 회귀 테스트
└── sample-data/
├── raw/ 수집·다운로드 원본
├── reference/ 지역·격자·관측소 기준표
└── derived/ 원본에서 파생된 데이터
├── intermediate/ processed에 해당하는 정제·집계 중간 데이터
├── operational/ 현재 운영 판단용 결과
├── validation/ 시간 순서 검증용 패널
└── reports/ 보고서·요약·차트
derived는 원본에서 계산된 모든 파생물을 뜻한다. 따라서 일반적인 권장
구조의 data/processed는 이 프로젝트의 derived/intermediate에 대응하고,
outputs는 derived/operational, derived/validation,
derived/reports에 대응한다.
metadata/data-source-registry.csv: 데이터 원천별 기관, URL, 수집 방식, 갱신주기, 라이선스와 확인 상태metadata/raw-file-manifest.csv: 실제 원본 파일별 경로, 크기, SHA-256, 기준기간, 수집시각과 저장 상태reference/data-spec-*.md: 원본 필드, 타입, 품질·결합 규칙
registry의 로컬 경로는 skills/data-analysis/ 기준이고, manifest의 파일
경로는 저장소 최상위 기준이다.
주민등록 고령인구 CSV는 다운로드 당시 CP949 파일을 값 변경 없이 UTF-8로
변환해 raw/에 보관한다. 변환 사실과 현재 파일 해시는 manifest에 기록한다.
API 키와 원본 응답 샘플은 Git에 커밋하지 않는다. .env 또는
private/api-credentials.env에만 둔다.
무더위쉼터 분석은 저장된 원본 CSV를 사용하므로 모든 팀원이 API 키를
가질 필요는 없다. 특히 SHELTER_KEY2가 등록 IP에서만 동작하면 허용된
수집 환경의 담당자가 최신 스냅샷을 날짜별 CSV로 저장하고 manifest의
크기·해시를 갱신한다. 다른 팀원은 커밋된 CSV를 받아 분석한다. 개인 키를
공유하거나 저장소에 올리지 않는다.
다음 파일은 약 375MB이므로 현재 Git에 포함되지 않는다.
skills/data-analysis/sample-data/raw/
└── weather-forecast-raw-items-202607281400.csv
파일이 없으면 체감온도·폭염경보·우선순위가 unknown으로 남는다. 공유
저장소에서 파일을 받은 뒤 metadata/raw-file-manifest.csv의
byte_size와 sha256이 전달받은 값과 일치하는지 확인한다. 현재 로컬
원본은 393,013,168바이트이며 SHA-256은
1412946b8b16fa227e4580b48dc670725f26a40fc580da05d56ea96153064bf1이다.
Git에는 포함하지 않는다.
저장소 루트에서 Python 의존성을 설치한다.
python -m pip install -r skills/data-analysis/requirements.txt저장소 루트에서 중간 테이블, 운영 결과, 검증 패널, 품질표, 분석 보고서와 차트를 한 번에 다시 만든다.
python skills/data-analysis/scripts/run_pipeline.py테스트:
python -m unittest discover -s skills/data-analysis/tests -vsample-data/derived/operational/regional_priority_by_forecast_issue.csvsample-data/derived/operational/forecast_daily_apparent_temperature.csvsample-data/derived/operational/forecast_horizon_sensitivity.csvsample-data/derived/validation/annual_region_panel.csvsample-data/derived/validation/forecast_issue_panel.csvsample-data/derived/reports/analysis-summary.jsonsample-data/derived/reports/analysis-report.mdsample-data/derived/reports/priority-top-n.csvsample-data/derived/reports/priority-top-n-table.pngsample-data/derived/reports/sensitivity-table.png
보고서 표 이미지만 다시 만들려면 분석을 재실행하지 않고 다음을 사용한다. 한글 폰트가 없는 환경에서는 이미지를 만들지 않고 사유를 출력한다.
python skills/data-analysis/scripts/plot.py --tables-only최신 수치는 analysis-summary.json과 analysis-report.md를 기준으로 한다.
운영용 결과와 과거 성능 검증을 구분한다. 현재 예보 원본을 연결하면 현재
시점의 우선점검 후보는 계산할 수 있지만, 과거 연도별 쉼터 스냅샷과 과거
발표시점별 예보가 없으면 실제 Walk-forward 성능 검증은 blocked다.
최신 쉼터 스냅샷을 과거 연도에 복제하거나 사후 관측값을 과거 예보처럼
사용하지 않는다. 자세한 방법과 제한은
skills/data-analysis/reference/methodology.md와
skills/data-analysis/reference/change-rationale.md를 참고한다.
과거 쉼터 자료는 다음 순서로 확보를 시도한다.
- 전국무더위쉼터표준데이터의
년도가 스냅샷 연도인지 확인하고 여러 연도 행이 실제로 제공되는지 점검한다. - 재난안전데이터공유플랫폼의 신규 API
DSSP-IF-10942담당부서에 과거 시점별 원본 또는 시설 이력 제공을 요청한다. - 행정안전부 공공데이터 제공신청으로 2023~2025년 시설 단위 스냅샷을 요청한다.
- 전국 자료가 없으면 지자체별 공개자료를 보조자료로 수집하되, 지역·연도 커버리지를 명시하고 전국 성능 검증에는 사용하지 않는다.
공식 시설 단위 과거 스냅샷을 확보하지 못하면 현재 쉼터 데이터는 운영용
순위에만 사용하고, 과거 성능 검증은 쉼터 특성을 제외한 별도 분석으로
분리하거나 blocked 상태를 유지한다.