Initial commit

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-21 07:07:35 +09:00
commit f4b14fddf5
21 changed files with 8763 additions and 0 deletions
--- a/.claude/commands/appkit.spec.md
+++ b/.claude/commands/appkit.spec.md
@@ -0,0 +1,430 @@
+---
+description: 기능 구체화 - 각 기능을 사용자 가치 관점에서 구체화
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+User input **must** be considered.
+
+## Overview
+
+**This is Step 2 of the logical thinking 7-step workflow**:
+
+```
+논리적 사고 7단계:
+1. /appkit.new      → 아이디어 스케치 (어떤 서비스인지?)
+2. /appkit.spec     → 기능 구체화 (뭐가 필요할까? 누가 쓸까?) ← YOU ARE HERE
+3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
+4. /appkit.sales    → 세일즈 랜딩 구성 (어떻게 설득할까?)
+5. /appkit.mvp      → MVP 범위 정하기 (최소한으로 검증하려면?)
+6. /appkit.merge    → 기획 정돈 (흩어진 기획 통합)
+7. /appkit.design   → 개발 준비 (API, ERD, 기술 스펙)
+```
+
+User inputs in format: `/appkit.spec <spec-id> "<natural language description>"`
+
+Examples:
+- `/appkit.spec 003-booking "search and book courts from main screen"`
+- `/appkit.spec 003-booking "time deal 30% discount, within 2 days of booking date"`
+- `/appkit.spec 004-promotion "no duplicate coupon use, max 40% discount"`
+
+**Core Concepts**:
+- **Incremental detailing**: Don't write everything at once
+- **Preserve existing content**: Previous content + new content added
+- **Natural language input**: User inputs comfortably in natural language
+
+**Note**: As you detail multiple specs, concepts may overlap or conflict. This is expected! The `/appkit.merge` command (Step 3) will consolidate these later.
+
+## Execution Flow
+
+### 1. Input Parsing
+
+**Format**: `/appkit.spec <spec-id> "<natural language description>"`
+
+**Parsing**:
+```
+Example: /appkit.spec 003-booking "searchable from main screen"
+
+Extract:
+- spec-id: 003-booking
+- natural language description: "searchable from main screen"
+```
+
+**Validation**:
+- Error if spec-id is empty
+- Error if natural language description is empty
+
+### 2. Script Execution
+
+**Script**: `.app/scripts/get-spec-path.sh --json --spec-id "003-booking"`
+
+**Example Output**:
+```json
+{
+  "SPEC_FILE": "docs/appkit/specs/003-booking/spec.md",
+  "SPEC_DIR": "docs/appkit/specs/003-booking"
+}
+```
+
+**Error Handling**:
+- If spec directory doesn't exist: "Spec 003-booking does not exist. Run /appkit.new first."
+
+### 3. Load Existing Spec
+
+**Read File**: `docs/appkit/specs/003-booking/spec.md`
+
+**Check Status**:
+1. **Empty template**:
+   - Not yet detailed with `/appkit.spec`
+   - All sections have `[This section will be filled...]`
+
+2. **Partially written**:
+   - Some sections filled
+   - Some sections still empty
+
+3. **Fully written**:
+   - Most sections filled
+   - Can add/modify
+
+### 4. Natural Language Analysis with User Value Focus
+
+**Input Analysis**: "search and book available courts from main screen at once"
+
+**고객 가치 분석**:
+```
+핵심 질문:
+- 누가? → 퇴근길 직장인, 시간이 없는 사람
+- 언제? → 이동 중, 짬날 때
+- 왜? → 빠르게 주말 운동 계획 세우려고
+- 어떻게? → 한 화면에서 모든 것 해결
+- 가치? → 시간 절약 (15분 → 3초)
+
+Map to sections:
+- User Value: 3초 만에 예약 완료
+- User Journey:
+  - 앱 열기 → 날짜/시간 선택 → 예약 → 완료
+  - 총 소요 시간: 3초
+- Pain Points Solved:
+  - 전화 대기 없음
+  - 여러 코트 동시 확인
+  - 즉시 확정
+
+Business Rules (고객 관점):
+  - 실시간 업데이트 (놓치지 않게)
+  - 가격 투명 공개 (비교 가능)
+  - 즉시 확정 알림 (안심)
+```
+
+**Input Analysis 2**: "time deal within 2 days of booking date, 30% discount"
+
+**고객 가치 분석**:
+```
+핵심 질문:
+- 누가? → 시간 유연한 프리랜서, 학생
+- 언제? → 갑자기 시간 생겼을 때
+- 왜? → 저렴하게 운동하고 싶어서
+- 어떻게? → 자동으로 할인 적용
+- 가치? → 30% 비용 절감
+
+Map to sections:
+- User Value: 정가의 70%로 운동
+- User Scenario:
+  - "내일 시간 비었네?" → 앱 확인 → "30% 할인!" → 즉시 예약
+- Emotional Journey:
+  - 발견 (😮) → 기쁨 (😊) → 만족 (😍)
+
+Business Rules (고객 이익):
+  - 자동 적용 (따로 쿠폰 입력 안 해도 됨)
+  - 명확한 조건 표시 (언제 할인되는지 투명)
+  - 다른 할인과 비교 (가장 이득인 것 자동 선택)
+```
+
+### 5. Spec Update (Incremental)
+
+**Principles**:
+1. **Preserve existing content**: Never delete
+2. **Add new content**: Add natural language analysis results to relevant sections
+3. **Prevent duplicates**: Don't add already existing content
+4. **Maintain consistency**: Keep existing format and tone
+
+**Update Example**:
+
+**Before** (empty template):
+```markdown
+## User Journey & Screen Flow
+[This section will be filled by /appkit.spec command]
+
+## Business Rules
+[This section will be filled by /appkit.spec command]
+```
+
+**After** (first `/appkit.spec` execution):
+```markdown
+## User Journey & Screen Flow
+
+### 1. Main Screen
+- **UI Elements**: Search bar (date, time), recommended court list
+- **CTA**: "Search" button
+- **Next**: Search results screen
+
+### 2. Search Results Screen
+- **UI Elements**: Filters (price, distance, rating), court cards (image, name, price, distance)
+- **CTA**: Click court card
+- **Next**: Court detail screen
+
+### 3. Court Detail Screen
+- **UI Elements**: Court info, reviews, available time slots
+- **CTA**: "Book" button
+- **Next**: Payment screen
+
+## Business Rules
+### Search Criteria
+- Date: After today
+- Time slot: Selectable
+- Results: Show only available courts
+```
+
+**After** (second `/appkit.spec` execution - "sort by price and distance"):
+```markdown
+## User Journey & Screen Flow
+
+### 1. Main Screen
+- **UI Elements**: Search bar (date, time), recommended court list
+- **CTA**: "Search" button
+- **Next**: Search results screen
+
+### 2. Search Results Screen
+- **UI Elements**: Filters (price, distance, rating), sort options (price/distance), court cards  # Updated
+- **CTA**: Click court card
+- **Next**: Court detail screen
+
+### 3. Court Detail Screen
+- **UI Elements**: Court info, reviews, available time slots
+- **CTA**: "Book" button
+- **Next**: Payment screen
+
+## Business Rules
+### Search Criteria
+- Date: After today
+- Time slot: Selectable
+- Results: Show only available courts
+
+### Sort Options  # Added
+- By price: Lowest first
+- By distance: Closest first
+- Default: By price
+```
+
+**After** (third `/appkit.spec` execution - "time deal 30% discount"):
+```markdown
+## Pricing & Promotion Logic
+### Time Deal  # New section added
+- Condition: Within 2 days of booking date
+- Discount rate: 30%
+- Application: Automatic
+```
+
+### 6. Auto-Completeness Check (고객 가치 중심)
+
+After updating spec, automatically check customer value completeness:
+
+**Check Sections**:
+- ✅ User Value (고객이 얻는 가치)
+- ✅ Target User (누가 쓸까?)
+- ✅ User Scenario (언제/어떻게 쓸까?)
+- ⏳ Pain Points Solved (해결되는 문제)
+- ❌ Success Metrics (어떻게 성공 측정?)
+- ⚠️ Edge Cases (예외 상황)
+
+**Report to User**:
+```markdown
+✅ Spec 002-booking 고객 가치 업데이트!
+
+💡 핵심 가치 분석:
+- 누가: 30대 직장인 (퇴근길)
+- 언제: 이동 중 짬날 때
+- 왜: 주말 운동 예약
+- 가치: 15분 → 3초 시간 절약
+
+📝 업데이트된 내용:
+- User Value: 3초 예약으로 시간 절약
+- User Scenario: 퇴근길 지하철 예약 시나리오
+- Pain Points: 전화 대기, 불확실성 해결
+
+📋 완성도 체크:
+- ✅ User Value (명확)
+- ✅ Target User (구체적)
+- ✅ User Scenario (생생함)
+- ⏳ Pain Points (더 추가 가능)
+  💡 제안: "주말 만석으로 운동 못함" 추가
+- ❌ Success Metrics (미작성)
+  💡 제안: "평균 예약 시간 3초 이하"
+- ⚠️ Edge Cases (미흡)
+  💡 제안: "동시 예약 충돌 처리"
+
+💡 다음 단계:
+더 많은 사용자 시나리오 추가:
+  /appkit.spec 002-booking "프리랜서가 평일 낮 할인받기"
+  /appkit.spec 002-booking "대학생 그룹 예약으로 절약"
+
+📄 전체 spec 보기: docs/appkit/specs/002-booking/spec.md
+
+📍 다음 단계: Step 4-5 - /appkit.customer (타겟 고객 정의 & 스토리텔링)
+```
+
+### 7. Completeness Check Criteria
+
+**Section Status**:
+- ✅ **Well-written**: Section has concrete content, no ambiguity
+- ⏳ **Partially written**: Section exists but lacks details
+- ⚠️ **Vague**: Section has content but vague or missing key parts
+- ❌ **Not written yet**: Section is empty or only has placeholder
+
+**Required Sections** (at minimum):
+1. User Journey & Screen Flow (with screen details)
+2. Business Rules
+3. Dependencies
+
+**Recommended Sections** (depending on spec type):
+- Pricing & Promotion Logic (if pricing/discounts involved)
+- Payment Flow (if payments involved)
+- Cancellation & Refund (if cancellations possible)
+- Edge Cases (always recommended)
+
+## Section Mapping Guide (고객 가치 중심)
+
+Natural language input → Customer value section mapping:
+
+### User Value Related
+**Keywords**: "절약", "빠른", "편리한", "쉬운", "자동", "한번에"
+**Examples**:
+- "3초 만에 예약" → User Value: 시간 절약
+- "자동 할인 적용" → User Value: 비용 절감
+- "원터치 결제" → User Value: 편의성
+
+### Target User Related
+**Keywords**: "직장인", "학생", "프리랜서", "주부", "시니어"
+**Examples**:
+- "바쁜 직장인을 위한" → Target User: 30-40대 직장인
+- "학생 할인" → Target User: 대학생
+
+### User Scenario Related
+**Keywords**: "퇴근길", "점심시간", "주말", "갑자기", "급하게"
+**Examples**:
+- "퇴근길 지하철에서" → User Scenario: 이동 중 예약
+- "주말 아침 급하게" → User Scenario: 당일 예약
+
+### Payment Flow Related
+**Keywords**: "payment", "fee", "payment method", "card", "cash", "bank transfer"
+**Examples**:
+- "online payment 5% fee" → Payment Flow
+- "cash payment no fee" → Payment Flow
+
+### Cancellation & Refund Related
+**Keywords**: "cancel", "refund", "change", "modify"
+**Examples**:
+- "100% refund 24h before" → Cancellation & Refund
+- "1 booking change allowed" → Cancellation & Refund
+
+### Edge Cases Related
+**Keywords**: "fail", "error", "concurrent", "duplicate", "timeout", "when empty", "exceed"
+**Examples**:
+- "first-come-first-served for concurrent bookings" → Edge Cases
+- "rollback booking on payment failure" → Edge Cases
+
+### Dependencies Related
+**Keywords**: "need", "depend", "integrate", "reference"
+**Inference**: When using data or functionality from other specs
+
+## Important Notes
+
+### 🔴 Mandatory Requirements
+
+1. **Incremental update**:
+   - Never delete existing content
+   - Only add new content
+   - Prevent duplicates
+
+2. **Natural language analysis**:
+   - Carefully analyze user input
+   - Map to appropriate sections
+   - If inference is ambiguous, add to most relevant section
+
+3. **Maintain consistency**:
+   - Keep existing format and tone
+   - Consistent markdown style
+   - Unified terminology
+
+4. **Auto-completeness check**:
+   - Check completeness after every update
+   - Provide next step suggestions
+   - Point out vague or missing parts
+
+### 🟡 Analysis Guidelines
+
+1. **Multiple section updates**:
+   - Single natural language input can affect multiple sections
+   - Update all relevant sections
+
+2. **Inference and expansion**:
+   - Don't just add explicit content
+   - Include reasonable inferences
+   - Example: "search" → search criteria, result display, empty result handling
+
+3. **Cross-reference**:
+   - Specify in Dependencies if related to other specs
+   - Mention policy references if related to policies
+
+### 🟢 Screen Flow Details
+
+When updating User Journey & Screen Flow, include:
+
+**For each screen**:
+1. **Screen name**: Clear, descriptive name
+2. **UI Elements**: Key visual elements users see
+3. **CTA (Call-to-Action)**: Main buttons or actions
+4. **Next**: Which screen comes next
+
+**Example**:
+```markdown
+### 2. Search Results Screen
+- **UI Elements**:
+  - Filter bar (price range, distance, rating)
+  - Sort dropdown (price/distance/rating)
+  - Court cards with: thumbnail, name, price, distance, rating
+  - "No results" message (when empty)
+- **CTA**:
+  - Click court card → Court detail
+  - Adjust filters → Refresh results
+- **Next**: Court detail screen or refined results
+```
+
+## Example Flow
+
+```
+# First execution
+User: /appkit.spec 003-booking "search courts from main screen"
+Claude: ✅ User Journey & Screen Flow, Business Rules updated
+        📋 Payment Flow, Cancellation missing
+        💡 Next: Add payment policy
+
+# Second execution
+User: /appkit.spec 003-booking "sort by price and distance"
+Claude: ✅ User Journey, Business Rules updated (preserved + added)
+        📋 Payment Flow, Cancellation still missing
+
+# Third execution
+User: /appkit.spec 003-booking "time deal 30% discount"
+Claude: ✅ Pricing & Promotion Logic added (new section)
+        📋 Payment Flow, Cancellation still missing
+
+# Fourth execution
+User: /appkit.spec 003-booking "online payment 5% fee"
+Claude: ✅ Payment Flow added (new section)
+        📋 Only Cancellation missing now
+        💡 Almost complete! Just add cancellation policy
+```