appkit/.claude/commands/appkit.spec.md

description

description
기능 구체화 - 각 기능을 사용자 가치 관점에서 구체화

User Input

$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:

{
  "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):

## 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):

## 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"):

## 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"):

## 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:

✅ 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:

### 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