Garmin Account Data Export를 반복적으로 취득하여, Snapshot Accumulation을 통해 관측 이력을 축적할 수 있게 되었습니다.

다음에 생각해야 할 것은 축적된 데이터를 AI에게 어떻게 전달할 것인가입니다.

Garmin Export를 그대로 AI에게 전달하는 것이 목적이 아닙니다.

AI가 망설임 없이, 안전하고 재현 가능하게 분석할 수 있는 형태로 정리하여 전달하는 것이 목적입니다.

Garmin Running Data Normalizer의 일반적인 Run-All 출력은 상세한 정규화 데이터, QA, 감사 정보, 데이터 간의 명시적인 관계를 포함합니다. 분석에는 편리하지만, 개인 식별자, 정확한 일시, 출처, 파일명 등을 포함할 수 있는

개인용 로컬 데이터입니다.

그래서 준비한 것이, 필요한 정보만을 허가 목록(allowlist)으로 추출하는

External-safe Pack입니다.

이 기사에서는 External-safe Pack이 무엇을 포함하고 무엇을 포함하지 않는지, 일반적인 로컬 분석과 어떻게 구분하여 사용하는지를 설명합니다.

Garmin Export를 그대로 AI에게 전달하지 않는 이유

Garmin Export에는 Activity, FIT, Gear, Personal Records, Wellness 등 용도와 입도(granularity)가 서로 다른 데이터가 포함됩니다. 파일명에 이메일 주소 형식의 식별자가 포함되는 경우도 있습니다.

Run-All로 정규화한 후에도 상세 출력에는 다음 정보가 남습니다.

• Raw ID 또는 로컬 stable key
• 정확한 일시
• source-relative path 및 파일명
• SHA-256 hash
• 메모
• 상세한 심박수(Heart Rate), 파워(Power), 케이던스(Cadence)
• FIT Session 및 Lap
• Activity와 FIT의 명시적인 관계

이것들은 로컬에서 분석 근거를 확인하기 위해 필요합니다. 하지만, "월별 주행량을 보고 싶다"라는 질문에 모든 것을 외부 환경으로 전달할 필요는 없습니다.

수신 측이 큰 ZIP 파일을 받아들일 수 있는 것과, 안전하게 공유할 수 있는 것은 별개의 문제입니다.

이용하는 서비스, 계약 플랜, 워크스페이스, 보관 기간, 학습 이용 여부, 이력·메모리 기능, 삭제 방법을 확인하지 않은 채 Garmin Export나 Run-All 출력 전체를 업로드하지 마십시오.

External-safe Pack이란

External-safe Pack은 Run-All에 --external-safe-pack 옵션을 붙였을 때 로컬에서 생성되는, 동일한 조건에서 동일한 구성을 재생성할 수 있으며 공유 전에 내용을 확인할 수 있는 ZIP 파일입니다.

macOS / Linux

python -m garmin_running_data_normalizer run-all \
--input /path/to/extracted-garmin-export \
--output /path/to/new-run-all-output \
...

Windows PowerShell

python -m garmin_running_data_normalizer run-all --input "C:\Garmin\Export" --output "C:\Garmin\Output\external-safe-01" --external-safe-pack

Snapshot Accumulation에서 Run-All을 수행할 때도 동일한 옵션을 사용할 수 있습니다.

python -m garmin_running_data_normalizer snapshot run-all \
--store /path/to/private-snapshot-store \
--output /path/to/new-snapshot-run-all-output \
...

생성되는 위치는 다음의 파일 1개입니다.

<output>/analysis/external_safe_handoff.zip

이 ZIP 파일은 자동으로 전송되지 않습니다. 생성 후에 외부로 전달할지 여부는 이용자가 판단합니다.

Pack의 내용은 단 5개의 파일뿐

현재의 External-safe Pack은 다음 5개의 파일만을 포함합니다.

external_safe_handoff.zip
├── README.md
├── manifest.json
...

중심이 되는 activities_monthly.csv는 다음의 6개 열로 구성됩니다.

이름에 monthly가 포함되어 있지만, 월 단위로 사전 집계된 표는 아닙니다.

한 행은 1개의 Activity를 유지하며, 날짜만 YYYY-MM 형식으로 축소합니다.

월별 건수, 거리, 시간은 분모와 식을 명시하여 집계합니다. 결측치를 0으로 대체하거나 존재하지 않는 날짜를 추측하지 않습니다.

포함하지 않을 항목을 먼저 결정하기

External-safe Pack은 다음 항목들을 허용 리스트(Allowlist)에서 제외합니다.

• identifier, Raw ID, stable key
• source path, 파일명, hash
• 메모, 좌표
• 정확한 날짜와 시각
• 심박수 (Heart Rate), 파워 (Power), 케이던스 (Cadence)
• Training Effect, Training Load
• 장비 (Gear), 개인 기록 (Personal Records)
• FIT Session, FIT Lap, Raw FIT
• Activity와 FIT 간의 관계 (relationship)
• 허용 리스트에 없는 산출물

safe/ANALYSIS_CONTEXT.json의 relationship 목록은 비어 있습니다. 따라서 External-safe Pack만 전달받은 AI는 다른 데이터셋(Dataset)과의 결합이나 Raw FIT로의 소급 탐색이 허용되지 않습니다.

"External-safe"라는 이름이 모든 외부 서비스에서 무조건적으로 안전하다는 의미는 아닙니다. 이는 공유할 데이터를 최소화하기 위한 명시적인 프로파일이며, 공유 전에는 이용자의 확인이 필요합니다.

AI는 무엇을 보는가

분석하는 장소에 따라 두 가지 경로로 나뉩니다.

외부 AI로 전달하는 경우

AI의 입구는 Pack 내의 README.md입니다.

• README.md에서 용도와 금지 사항을 읽음
• safe/ANALYSIS_CONTEXT.json에서 상태, 경고, 금지 작업을 확인함
• safe/SCHEMA_CATALOG.json에서 입도(Granularity)와 6개 열을 확인함
• safe/activities_monthly.csv를 분석함
• manifest.json에서 Pack의 구성과 정합성을 확인함

이 경로에서는 월 단위의 Activity 양과 건수에 답할 수 있는 질문으로 범위를 제한합니다. Raw FIT로는 추적하지 않습니다.

로컬 또는 신뢰할 수 있는 환경에서 상세 분석하는 경우

일반적인 Run-All 출력에서는 다음 순서로 읽습니다.

START_HERE.md
DATASET_INVENTORY.md
ANALYSIS_HANDOFF.md
analysis/activities.csv (필요한 QA, 감사 정보, 정규화된 데이터셋)

정규화된 열에 없는 FIT 상세 정보가 필요할 때만, normalized/activity_fit_links.json을 Activity와 FIT를 연결하는 유일한 근거로 사용합니다. 링크에 존재하는 garmin_activity_key와 fit_session_key의 쌍만을 채택하며, 시각이나 거리가 유사하다는 이유로 새로운 관계를 생성하지 않습니다.

링크 행과 FIT Session의 유래 정보를 통해, 사용자가 원래의 Garmin Export에 있는 해당 Raw FIT를 추가로 확인합니다. Raw FIT 본체는 Run-All 출력이나 External-safe Pack으로 복제되지 않습니다.

이 설계로 얻을 수 있는 것

AI에게 전달하는 입력을 최소화할 수 있음

Garmin Export 전체나 Run-All 출력 전체가 아니라, 5개 파일과 6개 열로 대상을 한정할 수 있습니다. 이것이 AI의 정확성을 보장하는 것은 아니지만, 불필요한 탐색 대상과 개인정보 노출 면을 줄일 수 있습니다.

공유 전에 QA를 확인할 수 있음

External-safe Pack을 만들기 전에, 로컬에서 run_summary.json, 경고, QA를 확인합니다. Pack 내의 context에도 개인정보를 포함하지 않는 경고 코드, 분류, 건수가 남습니다.

Pack에 상세 QA 파일을 포함하지 않는 것과 QA를 생략하는 것은 동일하지 않습니다.

상세한 근거는 로컬에 유지하고, 외부로 전달할 정보만 축소합니다.

Provenance를 로컬의 정본(正本)에 남길 수 있음

일반적인 Run-All 출력에는 source-relative path나 hash를 포함하는 provenance를 남깁니다.

반면, External-safe Pack에서는 그것들을 의도적으로 제외합니다.

외부용 축소 데이터와 로컬에 남기는 감사 가능한 정본을 분리함으로써,

불필요하게 provenance를 공개하지 않으면서도, 나중에 처리 근거를 확인할 수 있습니다.

동일한 조건으로 재생성 가능

동일한 입력과 구현으로부터 만드는 Pack은 파일 순서, 행 순서, JSON, ZIP 구성을

동일한 규칙으로 생성합니다. manifest.json은

Pack의 구성을 고정합니다.

단, AI의 문장까지 완전히 동일해진다는 의미는 아닙니다.

재현할 수 있는 것은 분석에 전달할 데이터와 그 계약(contract)입니다.

공유 전 사용자가 확인하는 사항

ZIP이 생성되더라도 공유가 자동으로 승인되지는 않습니다. 최소한 다음 사항을 확인합니다.

• 5개 파일 이외의 것이 들어있지 않음
• CSV 헤더가 6열임
• 개인 식별자, 정확한 일시, path, hash, 메모가 없음
• 질문이 월 단위의 Activity 양·건수로 답변 가능함
• Run-All의 상태와 경고를 확인했음
• 수신 환경의 저장, 학습 이용, 이력, 메모리 기능, 삭제 조건을 확인했음
• 최종적인 업로드를 사용자 본인이 승인했음

안전성은 Pack의 설계만으로 완결되지 않습니다.

데이터 측면을 축소한다
+ 수신 환경을 확인한다
+ 업로드 직전에 사용자가 승인한다

이 세 가지를 분리하지 않고 다룹니다.

요약

External-safe Pack의 목적은 Garmin Export를 작은 ZIP으로 다시 묶는 것이

아닙니다.

AI에게 전달할 데이터, 스키마 (schema), 컨텍스트 (context), 금지 사항을 명시하고, 불필요한 식별자,

상세 지표, provenance를 허용 리스트(allowlist) 외로 두는 것입니다.

상세한 정본과 QA는 로컬에 남긴다. 외부 AI에게는 질문에 필요한 최소한만을

전달한다. FIT의 상세 정보가 정말로 필요하다면, External-safe Pack에 섞는 것이 아니라,

신뢰할 수 있는 환경에서 명시적 링크를 통해 필요한 Raw FIT만 확인한다.

이러한 분리를 통해 AI는 Garmin Export의 구조를 매번 해석할 필요 없이,

주어진 계약의 범위 내에서 분석을 시작할 수 있습니다.

이번에 소개한 External-safe Pack을 포함한 Garmin Running Data Normalizer의 개발은,

요건 정리, 구현, 리뷰, 사용자의 승인, 에비던스 (evidence) 축적을 AI와 역할 분담을 하며

진행해 왔습니다.

다음 회차에서는 이러한 일련의 개발을 어떻게 AI와 역할 분담을 하며

진행해 왔는지 소개하겠습니다.

그다음에는 이 협업 개발을 뒷받침하는 기반인

AI Collaboration Platform을 소개할 예정입니다.

관련 자료

Discussion