1주차 - 미니사례 "나만의 MVP 앱 기획하기"

# RunCoach 앱 기획 및 개발 작업 정리
> 작성일: 2026-03-18

---

## 소개

### 시도하고자 했던 것과 그 이유

매주 일요일 러닝을 시작해서 **1년 뒤 하프마라톤(21.0975km) 완주**를 목표로 하는 앱을 기획하고 개발 기반을 만들었습니다.

기존에 러닝 관련 앱들은 정보가 메뉴 깊숙이 있어 뛰면서 확인하기 불편했습니다. 특히:

- 뛰는 **중간**에 폰을 꺼내지 않아도 워치로 실시간 코칭 알람을 받고 싶었고
- 매번 지난 기록과 비교해서 **오늘 얼마나 잘 뛰고 있는지** 바로 알고 싶었으며
- 매주 기록이 쌓이면 AI가 **다음 주 목표를 자동으로 제안**해주는 개인 코치 역할을 원했습니다

단순한 기록 앱이 아니라, 하프마라톤이라는 1년 목표를 향해 **매주 조금씩 성장**하도록 도와주는 앱을 만들고자 했습니다.

---

## 진행 방법

### 사용 도구
- **Claude Code** — 기획부터 코드 구현까지 전 과정
- **Thinking Partner 모드** (`/thinking-partner`) — 앱 방향 설정을 위한 대화형 기획

---

### Step 1. Thinking Partner로 요구사항 정리

`/thinking-partner` 명령으로 Claude를 답을 주는 어시스턴트가 아닌 **질문하는 파트너**로 전환하여 대화를 통해 진짜 필요한 것을 찾아냈습니다.

**핵심 질문들:**
- "이 앱이 하프마라톤 완주에 어떻게 기여할 것이라고 생각하세요?"
- "러닝 전/중/후 중에서 가장 불편한 순간은 언제인가요?"
- "조언을 누가 만들어야 한다고 생각하세요?"

**대화를 통해 발견한 것:**
> 가장 불편한 순간 = **러닝 중간** (폰을 꺼내기 어려운 상황)
> 해결책 = 워치에서 소리+진동으로 실시간 알람

---

### Step 2. 화면 흐름도 작성

```
[매주 일요일 아침 푸시 알림]
        │ 탭 1번
        ▼
[홈 대시보드]
        │ 러닝 시작 버튼
        ▼
[러닝 시작 전] → 지난 기록 + 오늘 목표
        │ 시작 버튼
        ▼
[러닝 중] → 폰 백그라운드 + 워치 전면 알람
        │ 종료
        ▼
[러닝 후 결과] → 비교 + AI 다음 목표
        │
        ▼
[홈 대시보드] (목표 업데이트)
```

---

### Step 3. 워치 실시간 알람 와이어프레임

갤럭시 워치5 원형 화면에 맞게 **3줄 이내** 정보 + 알람 4종 설계

```
[메인 화면]               [거리 달성 알람]
╭───────────────╮         ╭───────────────╮
│   3.2 km      │         │  🔔 1km !     │
│ 6:31  ♥158   │   →     │  6:28/km 🟢   │
│ 지난주 +0.4↑  │         │  지난주보다 ↑  │
╰───────────────╯         ╰───────────────╯
```

**알람 4종:**
| 알람 | 트리거 | 진동 |
|------|--------|------|
| 거리 달성 | 1km마다 | 1회 |
| 심박 경고 | 170bpm 초과 | 3회 강하게 |
| 구간 목표 | 설정 구간 도달 | 2회 |
| 페이스 이탈 | 목표보다 10% 느릴 때 | 2회 |

---

### Step 4. AI 목표 제안 로직 설계

매주 러닝 후 기록을 분석해서 다음 주 목표를 자동 계산:

```
피로 높음 / 심박 과부하  →  거리 유지, 페이스 5% 느리게
완주 실패               →  거리 -0.5km
성공 + 적정 상태        →  거리 +0.5km, 페이스 5초 빠르게
성공 + 여유 있음        →  거리 +1.0km, 페이스 10초 빠르게
```

하프마라톤 역산 공식:
```
주당 필요 증가량 = (21.0975 - 현재거리) / 남은주수
```

---

### Step 5. Samsung Health SDK 연동 정의

```
[Galaxy Watch 5]
      │ Bluetooth
      ▼
[Samsung Health 앱]
      │ Samsung Health SDK
      ▼
[RunCoach 앱]
  ├── 알람 트리거 판단
  ├── 워치에 알람 명령 전송
  └── 기록 저장 → AI 목표 계산
```

**수집 데이터:** 거리 / 페이스 / 심박수 / 피로도(자체계산) / 수면점수 / 스트레스

---

### Step 6. 기술 스택 확정

- **폰:** Kotlin + Jetpack Compose + MVVM + Room DB + Hilt + Samsung Health SDK
- **워치:** Wear OS 3.0 + Wear Compose + Health Services API
- **통신:** Wearable Data Layer API (폰 ↔ 워치)

---

### Step 7. 코드 구현

Android Studio 프로젝트 전체를 생성했습니다.

**주요 코드 예시 — AI 목표 제안 로직:**

```kotlin
fun suggestNextGoal(
    lastRecord: RunningRecord,
    currentGoal: WeeklyGoal,
    halfMarathonDate: Long
): AiSuggestion {
    val weeksLeft = weeksUntil(halfMarathonDate)
    val weeklyNeeded = (halfMarathonKm - lastRecord.distanceKm) / weeksLeft

    val nextKm = calcNextDistance(lastRecord, currentGoal, weeklyNeeded)
    val nextPace = calcNextPace(lastRecord, currentGoal)
    val message = buildMessage(lastRecord)

    return AiSuggestion(...)
}

private fun calcNextDistance(...): Float = when {
    fatigue == "high" || hrHigh -> goal.targetKm          // 유지
    !record.completed           -> goal.targetKm - 0.5f   // 감소
    fatigue == "low" && !hrHigh -> goal.targetKm + 1.0f   // 적극 증가
    else                        -> goal.targetKm + 0.5f   // 적정 증가
}
```

**워치 진동 알람 코드:**

```kotlin
private fun triggerVibration(alarmType: String) {
    val pattern = when (alarmType) {
        "heartrate" -> longArrayOf(0, 200, 100, 200, 100, 200) // 3회 강하게
        "speedup"   -> longArrayOf(0, 150, 100, 150)           // 2회 중간
        "distance"  -> longArrayOf(0, 100)                     // 1회 짧게
        "pace"      -> longArrayOf(0, 150, 100, 150)           // 2회
        else        -> longArrayOf(0, 100)
    }
    vibrator.vibrate(VibrationEffect.createWaveform(pattern, -1))
}
```

**생성된 전체 파일 구조:**
```
RunCoach/
├── app/
│   └── java/com/runcoach/app/
│       ├── MainActivity.kt
│       ├── RunCoachApp.kt
│       ├── alarm/WeeklyAlarmReceiver.kt
│       ├── data/db/ (Entity, DAO, Database)
│       ├── di/AppModule.kt
│       ├── domain/AiGoalAdvisor.kt
│       ├── service/RunningService.kt
│       └── ui/ (Home, PreRun, PostRun, AiGoal, History)
└── wear/
    └── java/com/runcoach/wear/
        ├── listener/PhoneMessageListenerService.kt
        └── ui/WatchMainScreen.kt
```

---

## 결과와 배운 점

### 배운 점

**1. 기획을 먼저 충분히 해야 개발이 빠르다**
Thinking Partner 대화로 "뛰는 중간이 가장 불편하다"는 핵심을 찾아낸 덕분에 워치 실시간 알람을 메인 기능으로 집중할 수 있었습니다. 방향이 명확하니 코드도 군더더기 없이 나왔습니다.

**2. 질문이 답보다 중요할 때가 있다**
처음에 "앱 설계해줘"라고 바로 요청했다면 일반적인 러닝 앱이 나왔을 겁니다. 대화를 통해 "1년 후 하프마라톤"이라는 목표와 "뛰는 중 불편함"이라는 진짜 문제를 연결했습니다.

**3. 문서 → 와이어프레임 → 로직 → 코드 순서가 효과적**
각 단계를 MD 파일로 저장하면서 진행하니 다음 단계에서 앞 단계를 참고하기가 쉬웠고, 나중에 개발자나 팀에게 전달하기도 편한 자료가 됐습니다.

---

### 시행착오

- **Samsung Health SDK**는 공개 Maven이 아닌 Samsung Developer 사이트에서 별도 다운로드 필요 → 코드는 완성됐지만 실제 빌드 전 수동으로 `.aar` 파일 추가 필요
- **피로도** 데이터는 Samsung Health SDK가 직접 제공하지 않아서 심박수 + 수면점수 + 스트레스 3가지를 조합해서 자체 계산하는 로직을 별도로 설계

---

### 앞으로의 계획

1. **Android Studio에서 빌드** — `c:\BackUp\21th_Gpters\RunCoach` 열고 실제 빌드 확인
2. **Samsung Health SDK 연동** — 실제 워치 데이터 수신 구현
3. **러닝 중 실시간 알람 트리거** 완성 (WearRunningService)
4. **온보딩 화면** — 첫 실행 시 초기 목표 설정
5. **실제 기기 테스트** — 갤럭시 워치5 + 안드로이드 폰

---

## 도움 받은 글 (옵션)

- Samsung Health SDK 공식 문서: https://developer.samsung.com/health
- Wear OS 개발 가이드: https://developer.android.com/training/wearables