제5회에서는 Garmin Running Data Normalizer에서 채택한

External-safe Pack에 대해 소개했습니다.

지금까지의 시리즈에서는,

• Garmin Export의 정규화
• Activity와 FIT의 명시적인 대응 관계
• Snapshot Accumulation
• External-safe Pack
• AI 분석으로 전달하는 데이터와 읽는 법

등, 주로 「무엇을 만들었는가」를 소개해 왔습니다.

이번에는 관점을 바꾸어, 이것들을 어떻게 AI와 역할을 분담하며 개발해 왔는지를 하나의 케이스 스터디(Case Study)로서 정리합니다.

이 개발에서 중요했던 것은 AI의 수를 늘리는 것이 아닙니다.

공정마다 역할을 나누고, 리포지토리(Repository)와 검증 결과를 정본(正本)으로 대조하며, 마지막에는 이용자가 판단하는 것이었습니다.

AI에게만 맡긴다고 해서 OSS가 완성되는 것은 아니다

OSS 개발은 코드만 작성한다고 끝나는 것이 아닙니다.

실제로는 다음과 같은 공정이 있습니다.

• 과제 정리
• 요구사항 및 공개 범위 결정
• 설계
• 구현
• 테스트
• 리뷰
• 문서화
• 에비던스(Evidence) 정리
• 릴리스
• 이용자를 위한 기사나 유도 경로 구축

하나의 AI에게 모든 것을 맡기면, 처음에 채택한 전제나 표현을 그대로 후속 공정까지 끌고 가는 경우가 있습니다.

Garmin Running Data Normalizer에서는 공정마다 보는 범위를 나누었습니다.

Garmin Running Data Normalizer에서의 역할 분담

대표적인 역할 분담은 다음과 같습니다.

이것은 모든 공정에서 모든 AI를 동시에 사용했다는 의미가 아닙니다.

과제에 따라,

• ChatGPT와의 대화로 방향성이나 설계를 정리한다
• ChatGPT 내의 실행 환경을 가진 Work에서 요구사항 정리·검증·공개 준비를 진행한다
• Codex로 구현한다
• Core Review로 성과물과 Evidence를 확인한다
• Claude, Gemini, Genspark 등으로 다른 관점에서 리뷰한다
• 이용자가 채택 여부와 공개 가능 여부를 결정한다

라는 형태로 역할을 전환했습니다.

이 협업으로부터 탄생한 것들

이러한 진행 방식으로부터 코드 이외를 포함한 여러 성과가 탄생했습니다.

이것들은 하나의 AI가 독립적으로 완성시킨 것이 아닙니다.

설계, 구현, 리뷰, 수정, 재검증을 반복하면서 공개할 수 있는 범위를 조금씩 굳혀 나갔습니다.

리뷰를 분리함으로써 실제로 일어난 개선

「다른 AI에게 리뷰를 받으면 품질이 올라간다」라고만 쓰면 추상적입니다.

실제로는 다음과 같은 수정이 있었습니다.

공개된 실태와 README 설명이 어긋나 있었음

Garmin Running Data Normalizer는 이미 Production PyPI를 통해 도입할 수 있는 상태였습니다.

하지만 README나 관련 문서 일부에는 PyPI 공개 전의 「공개 후보」, 「미공개」라고 읽힐 수 있는 표현이 남아 있었습니다.

구현과 릴리스가 올바르게 완료되었더라도, 이용자가 처음 읽는 문서가 오래되었다면 제품의 현재 위치를 잘못 전달하게 됩니다.

공개 후의 별도 관점 리뷰를 통해 이러한 어긋남을 발견하였고, README, Quick Start, Known Limitations 등을 현재의 공개 상태에 맞춰 재검토했습니다.

이 사례를 통해 알 수 있었던 것은 문서도 제품의 일부라는 점입니다.

코드가 올바른지뿐만 아니라, 공개 문서가 동일한 상태를 설명하고 있는지를 별도로 확인할 필요가 있었습니다.

tzdata라는 근본 원인으로 나아간 Windows의 표면적인 문제

Windows에서 처음에 문제로 보였던 것은 macOS나 Linux용 source 명령어를 전제로 한 절차였습니다.

그래서 OS별로 절차를 나누고, Windows 환경을 준비하여 재현 확인을 진행했습니다.

조사를 계속하자 절차의 차이뿐만 아니라, Windows에서 Asia/Tokyo를 해결할 수 없는 경우가 있다는 것을 알게 되었습니다. 근본 원인은 타임존 데이터(Timezone data)를 제공하는 tzdata가 의존성(Dependency)으로서 부족했기 때문이었습니다.

대응은 설명문 수정만으로 끝내지 않고,

• Windows에서 필요한 tzdata

• 의존성(Dependency)에 추가 - GitHub Actions의 Windows 환경에서 확인

• Windows 실기기에서 Production PyPI를 통해 도입하여 확인

• 검증 결과를 CS-008로 기록

• 재발 방지를 위한 검증 절차 및 스크립트 정비

까지 진행했습니다.

처음에 보고된 증상과 수정해야 할 근본 원인이 반드시 일치하는 것은 아닙니다.

구현과는 별도로 재현, 원인 조사, 증거(Evidence) 확인 역할을 두었기에, 표면적인 절차 수정보다 더 깊은 부분까지 대응할 수 있었습니다.

리뷰 AI의 평가도 그대로 채택하지 않았다

여러 개의 AI를 사용한다고 해서 자동으로 올바르게 되는 것은 아닙니다.

리뷰하는 AI 자신도 구현 상태를 지나치게 일반화하는 경우가 있습니다.

실제로 Wellness나 Metrics 정리 과정에서는 Sleep, HRV, Health Status 등에 이미 구현된 라이브러리 자산이나 테스트가 존재한다는 이유로, 카테고리 전체가 stable Run-All에 통합된 것처럼 읽히는 평가가 나온 적이 있었습니다.

하지만 당시의 공개 계약(Public Contract)에서는 다음과 같이 구분하고 있었습니다.

• stable Run-All에서 정식으로 제공하는 것
• 라이브러리 레벨(library-level)에서 이용 가능한 것
• 프라이빗 검증(private validation)이나 후보(candidate)로서 존재하는 것
• 향후 공개 후보

따라서 AI의 평가를 그대로 채택하지 않고, 다음 항목들과 대조하여 공개 버전에서 증명할 수 있는 범위로 표현을 되돌렸습니다.

• 공개 리포지토리 (Public Repository)
• 지원 데이터셋 (Supported Datasets)
• CLI 및 출력 계약 (Output Contract)
• 스키마 (Schema)
• 테스트 (Test)
• 릴리스 증거 (Release Evidence)

이는 특정 AI만의 문제는 아닙니다.

관련 기능이 여러 개 존재할 경우, 카테고리 전체를 '구현 완료'라고 일반화하는 오류는 여러 AI나 문장 작성 과정에서 발생할 수 있습니다.

중요했던 것은 리뷰 AI의 수가 아니라, 무엇을 정본(Source of Truth)으로 판정할 것인가를 정해두었다는 점이었습니다.

같은 사고방식으로 확인한 다른 경계들

동일한 확인 작업을 다른 상황에서도 수행했습니다.

세 가지 사례의 공통점은 '존재한다', '분석할 수 있다', '공개 기능이다'를 구분했다는 것입니다.

데이터나 코드가 존재한다고 해서 그것만으로 stable한 공개 기능이라고 단정할 수 없습니다.

분석 결과를 얻을 수 있다고 해서 그 값이 표준 정규화 열에서 나온 것이라고도 할 수 없습니다.

리뷰에서는 결과뿐만 아니라, 어떤 계약과 경로에 기반한 주장인지를 확인했습니다.

AI 협업에서 중요했던 것은 권한(Authority)의 설계

이번 사례를 통해 AI 협업에서는 다음 순서가 중요하다는 것을 알게 되었습니다.

AI가 제안·구현·리뷰한다
↓
Repository / Contract / Test / Evidence와 대조한다
...

AI의 답변을 다수결로 결정한 것이 아닙니다.

구현 AI와 리뷰 AI의 의견이 다를 경우에도, 마지막으로 확인한 것은 리포지토리, 공개 계약, 테스트, 검증 결과였습니다.

또한, 최종 판단을 AI에게 맡긴 것도 아닙니다.

• 사양(Specification)으로 채택할 것인가
• 공개 주장(Public Claim)으로 작성할 수 있는가
• 프라이빗한 증거(Private Evidence)를 외부에 공개해도 되는가
• 릴리스(Release)나 기사를 공개할 것인가

등은 사용자가 직접 확인하고 결정했습니다.

Garmin Running Data Normalizer는 첫 번째 실증 프로젝트였다

Garmin Running Data Normalizer는 Garmin 데이터를 정규화하는 OSS인 동시에, AI 협업을 통한 OSS 개발을 시험하는 첫 번째 실증 프로젝트이기도 했습니다.

이 하나의 프로젝트만으로 모든 OSS 개발에 동일한 방식이 유효하다고 증명한 것은 아닙니다.

하지만 다음과 같은 흐름이 실제 릴리스, 수정, 문서화, 외부 홍보까지 기능한다는 것을 확인할 수 있었습니다.

• 역할을 분담한다
• 결과물을 인계한다
• 다른 관점에서 리뷰한다
• Repository와 Evidence에 대조한다
• 사용자의 승인으로 공개한다

그 경험을 다른 프로젝트에서도 재사용할 수 있는 형태로 정리한 것이 바로

AI Collaboration Platform입니다.

요약

Garmin Running Data Normalizer는 하나의 AI가 만든 OSS (Open Source Software)가 아닙니다.

사용자가 목적과 경계를 정하고, 여러 AI가 역할을 분담하며, 다른 관점에서 리뷰하고, Repository (저장소)와 Evidence (증거)를 대조하며 개선해 왔습니다.

다만, 단순히 AI를 늘렸다고 해서 품질이 올라간 것은 아닙니다.

리뷰 AI도 실수할 수 있다는 것을 전제로, 정본 (Source of Truth), 검증 절차, 승인 경계를 설계한 것이 중요했습니다.

이번 기사에서는 Garmin Running Data Normalizer를 케이스 스터디 (Case Study)로 하여, AI 협업 개발의 전체상을 소개했습니다.

다음 회차에서는 이 협업을 재사용 가능한 운영 기반으로 정리한

AI Collaboration Platform에 대해, 그 설계 사상과 아키텍처 (Architecture)를

소개하겠습니다.

관련 자료

Discussion