Clauders/appkit
13
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor to 5-step workflow (new → mvp → ui → policy → visualize)

Browse Source 
- Remove old commands: spec, customer, sales, merge, design
- Add new commands: ui, policy, visualize
- Update mvp to include landing page generation
- Add templates for mockup, policy, and UI documents
- Simplify output path (remove [project] subfolder)
- Rewrite README focused on usage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
rupy1014
2025-12-14 20:07:13 +09:00
parent 721cf3a5dd
commit e9b0c00be7
23 changed files with 5221 additions and 3902 deletions
Download Patch File Download Diff File Expand all files Collapse all files

648
.claude/commands/README.appkit.md
View File

@@ -4,34 +4,34 @@
---
## 🎯 Overview
## Overview
AppKit은 막연한 아이디어를 고객 중심으로 구체화하여 MVP부터 세일즈까지 설계하는 프레임워크입니다.
AppKit은 막연한 아이디어를 고객 중심으로 구체화하여 MVP 기획서, 화면설계서, 정책설계서, 그리고 라이브 목업까지 작성하는 프레임워크입니다.
**핵심 철학**:
1. 고객 가치 우선 → 기능이 아닌 고객의 문제 해결 중심
2. 논리적 사고 연습 → 큰 작업을 작은 단계로 쪼개기
3. 스토리텔링 기반 → 고객의 하루와 고민을 이해하고 설득
4. MVP 중심 실행 → 최소한의 범위로 최대한의 검증
3. MVP 중심 실행 → 최소한의 범위로 최대한의 검증
4. 실행 가능한 문서 → 개발자/디자이너가 바로 작업 가능
5. 시각적 프로토타입 → HTML 목업으로 즉시 확인
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works`
---
## 📋 Complete Workflow (논리적 사고 7단계)
## 논리적 사고 5단계 워크플로우
```
아이디어 구체화 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트)
4. /appkit.policy → 정책설계서 (비즈니스 규칙)
5. /appkit.visualize → 목업 생성 (HTML 프로토타입)
```
---
## 🔧 Commands
## Commands
### 1. `/appkit.new` - 아이디어 스케치
@@ -39,522 +39,244 @@ AppKit은 막연한 아이디어를 고객 중심으로 구체화하여 MVP부
**Input**:
```
/appkit.new Tennis court booking app with coupons and promotions
/appkit.new 테니스 코트 예약 앱
```
**Output**:
- `docs/appkit/overview.md` - 서비스 컨셉 & 핵심 가치
- `docs/appkit/specs/001-user/spec.md` - 빈 템플릿
- `docs/appkit/specs/002-venue/spec.md` - 빈 템플릿
- `docs/appkit/specs/003-booking/spec.md` - 빈 템플릿
- ...
- `ui/works/concept.md` - 서비스 컨셉 & 핵심 가치
- `ui/works/specs/001-xxx/spec.md` - 기능별 스펙 초안
**Key Features**:
- 서비스 본질 파악 (무슨 문제를 해결하나?)
- 예상 고객군 추론 (누가 쓸까?)
- 핵심 가치 제안 (왜 써야 할까?)
- 경쟁 차별점 식별 (다른 서비스와 뭐가 다른가?)
---
### 2. `/appkit.spec` - 기능 구체화
### 2. `/appkit.mvp` - MVP 범위 정의 + 랜딩페이지
**Purpose**: 필요한 기능을 도출하고 사용자 관점에서 구체화
**Input**:
```
/appkit.spec 003-booking "search courts from main screen"
/appkit.spec 003-booking "time deal 30% discount within 2 days"
/appkit.spec 003-booking "cancel 24h+ before for 100% refund"
```
**Output**:
- `docs/appkit/specs/003-booking/spec.md` 업데이트 (증분식 누적)
**Key Questions for Each Feature**:
- **뭐가 필요할까?** → 필요한 기능들 도출
- **누가 쓸까?** → 타겟 사용자 프로파일
- **언제 쓸까?** → 사용 시나리오와 상황
- **왜 쓸까?** → 해결하려는 문제나 욕구
- **어떻게 쓸까?** → 구체적인 사용 플로우
- **가치는?** → 사용자가 얻는 이익
**중요**: 기술 구현보다 사용자 가치에 집중!
---
### 3. `/appkit.customer` - 고객 스토리
**Purpose**: 타겟 고객을 명확히 하고 그들의 하루와 고민을 스토리로 구성
**Input**:
```
/appkit.customer
/appkit.customer "30대 직장인 주말 운동"
```
**Output**:
- `docs/appkit/customer-persona.md` - 고객 페르소나
- `docs/appkit/customer-journey.md` - 고객 여정 지도
**What it does**:
1. **페르소나 구성**:
- Demographics: 나이, 직업, 소득, 거주지
- Psychographics: 라이프스타일, 가치관, 관심사
- Pain Points: 현재 겪는 문제와 불편함
- Goals: 달성하고 싶은 목표
2. **고객의 하루 스토리텔링**:
```
07:00 - 출근 준비하며 "오늘도 운동 못하겠네..."
09:00 - 회사 도착 "주말엔 꼭 테니스 쳐야지"
12:00 - 점심시간 "코트 예약하려니 전화해야 하네..."
18:00 - 퇴근 "주말 코트 풀부킹이라니..."
21:00 - 집 도착 "내일 아침 일찍 전화해야겠다"
```
3. **문제 해결 시나리오**:
- Before: 복잡한 예약 과정, 불확실한 가능 시간
- After: 앱으로 간편 예약, 실시간 확인, 할인까지
**중요**: 고객 중심 사고의 핵심 - 기능이 아닌 고객의 삶을 이해!
---
### 4. `/appkit.sales` - 세일즈 랜딩 구성
**Purpose**: 고객을 설득하는 세일즈 메시지 구성
**Input**:
```
/appkit.sales
/appkit.sales "time-saving for busy professionals"
```
**Output**:
- `docs/appkit/sales-landing.md` - 세일즈 랜딩 구조
- `docs/appkit/value-proposition.md` - 가치 제안
**Landing Structure**:
1. **Hook (문제 공감)**:
- "매번 전화로 테니스 코트 예약하느라 지치셨나요?"
2. **Problem Agitation (문제 심화)**:
- 전화 대기 시간 평균 15분
- 원하는 시간대 이미 만석
- 가격 비교 불가능
3. **Solution (해결책 제시)**:
- 3초 만에 실시간 예약
- 모든 코트 가격 한눈에 비교
- 자동 할인 적용
4. **Social Proof (사회적 증명)**:
- "이미 5,000명의 테니스 동호인이 사용 중"
- 사용자 후기와 평점
5. **CTA (행동 유도)**:
- 첫 예약 30% 할인
- 지금 가입하고 혜택받기
**중요**: 기능 나열이 아닌, 고객 문제 해결 스토리!
---
### 5. `/appkit.mvp` - MVP 범위 정의
**Purpose**: 최소한의 기능으로 최대한의 검증
**Purpose**: 최소한의 기능으로 최대한의 검증 + 검증용 랜딩페이지 생성
**Input**:
```
/appkit.mvp
/appkit.mvp "2-week validation"
/appkit.mvp "2주 검증"
```
**Output**:
- `docs/appkit/mvp-scope.md` - MVP 범위 정의
- `docs/appkit/mvp-metrics.md` - 검증 지표
- `ui/works/mvp-scope.md` - MVP 범위 정의 & 검증 지표
- `ui/works/landing.html` - 검증용 랜딩페이지
**MVP Scoping Process**:
1. **핵심 가치 파악**:
- 고객이 가장 원하는 ONE thing은?
- 없으면 서비스 의미가 없는 기능은?
**Key Features**:
- Phase 0/1/2 기능 분류
- 성공/학습/피벗 지표 설정
- MVP 체크리스트
- **HTML 랜딩페이지 자동 생성**
- Hero, Problem, Solution, How It Works 섹션
- SEO 메타태그 완성
- 반응형 디자인 (모바일 퍼스트)
- CTA 버튼 포함
2. **Phase 분류**:
```
Phase 0 (MVP - 2주):
- 코트 검색/예약 (핵심)
- 간단한 결제
Phase 1 (MVP+ - 1개월):
- 사용자 리뷰
- 할인 쿠폰
Phase 2 (확장 - 3개월):
- 커뮤니티 기능
- 코칭 매칭
```
3. **검증 지표 설정**:
- Success Metrics: 주간 예약 10건
- Learning Metrics: 이탈 구간, 불만 사항
- Next Decision: Phase 1 진행 여부
**MVP 원칙**:
- ❌ "있으면 좋을" 기능 제외
- ✅ "없으면 안되는" 기능만 포함
- 목표: 빠른 시장 검증, not 완벽한 제품
**Template**: `.specify/templates/sales-landing-template.html`
---
### 3. `/appkit.ui` - 화면설계서
## 🌊 Workflow Example (고객 중심 논리적 사고)
**Purpose**: 라우터, 화면, 컴포넌트 구조 정의 (카카오톡 스타일)
### Example: Tennis Court Booking App
**Input**:
```
/appkit.ui # 전체 화면 설계
/appkit.ui "특정 화면명" # 특정 화면 설계
```
**Output**:
- `ui/works/router.md` - 라우터 & UI 목록
- `ui/works/main.md` - 메인 구조 (탭 구조, 네비게이션)
**Key Features**:
- 5탭 구조 (센터 탭 강조)
- 화면별 컴포넌트 ID 정의
- 바텀시트, 팝업, 토스트 정의
- 네비게이션 플로우
**Template**: `.specify/templates/ui-router.md`, `ui-main.md`
---
### 4. `/appkit.policy` - 정책설계서
**Purpose**: 비즈니스 규칙과 정책을 코드로 구조화
**Input**:
```
/appkit.policy # 전체 정책
/appkit.policy "과금 정책" # 특정 정책
```
**Output**:
- `ui/works/policies/00-policy-index.md` - 정책 인덱스
- `ui/works/policies/01-monetization.md` - 과금 정책 (MN)
- `ui/works/policies/02-gameplay.md` - 서비스 규칙 (GM)
- `ui/works/policies/03-content.md` - 콘텐츠 정책 (CH)
- `ui/works/policies/04-progression.md` - 진행 정책 (PR)
**Policy Codes**:
| 코드 | 카테고리 | 내용 |
|-----|---------|------|
| MN | Monetization | 결제, 구독, 포인트 |
| GM | Gameplay | 서비스 규칙, 제한사항 |
| CH | Content | 콘텐츠 생성/관리 |
| PR | Progression | 레벨, 업적, 보상 |
| CR | Content Rating | 연령 등급, 경고 |
**Template**: `.specify/templates/policy-*.md`
---
### 5. `/appkit.visualize` - HTML 목업 생성
**Purpose**: router.md 기반 라이브 프로토타입 생성
**Input**:
```
/appkit.visualize home # 홈 화면 목업
/appkit.visualize all # 전체 화면 목업
/appkit.visualize "예약 상세" # 특정 화면 목업
```
**Output**:
- `ui/works/mockup/[screen].html` - HTML 목업
- `ui/works/mockup/styles.css` - 공통 스타일
- `ui/works/mockup/scripts.js` - 공통 스크립트
**Key Features**:
- 모바일 퍼스트 (max-width: 430px)
- 다크 테마 기본
- 모달/바텀시트/토스트 동작
- 정책 ID 주석 연결
- 화면 간 상호 링크
**Template**: `.specify/templates/mockup-*.html`, `mockup-styles.css`, `mockup-scripts.js`
---
## Quick Start
```bash
# Step 1: 아이디어 스케치 - "어떤 서비스인지?"
$ /appkit.new Tennis court booking with coupons and time deals
# Step 1: 아이디어 스케치
/appkit.new 친구와 AI 챗봇 서비스
Claude:
📋 서비스 컨셉:
- 문제: 테니스 코트 예약이 번거롭고 비싸다
- 해결: 모바일로 간편 예약 + 자동 할인
- 타겟: 주말 운동을 원하는 30-40대 직장인
- 가치: 시간 절약, 비용 절감
# Step 2: MVP 범위 정의
/appkit.mvp
주요 기능 분류:
- 001-user: 사용자 인증
- 002-venue: 코트 관리
- 003-booking: 예약/결제
- 004-promotion: 할인/쿠폰
- 005-review: 리뷰
# Step 3: 화면설계 (라우터, 메인 구조)
/appkit.ui
✅ Created service concept & 5 feature specs
# Step 4: 정책설계
/appkit.policy
# Step 2: 기능 구체화 - "뭐가 필요할까? 누가 쓸까?"
$ /appkit.spec 003-booking "search courts from main screen"
💡 사용자 가치 분석:
- 뭐가 필요? → 실시간 코트 검색 기능
- 누가? → 퇴근 후 피곤한 직장인
- 언제? → 지하철/버스에서 이동 중
- 왜? → 빠르게 주말 운동 계획 세우기
- 어떻게? → 원터치로 가까운 코트 찾기
- 가치? → 5초 만에 예약 가능 확인
✅ User value added to spec
$ /appkit.spec 003-booking "time deal 30% within 2 days"
💡 사용자 가치 분석:
- 뭐가 필요? → 시간 기반 자동 할인 시스템
- 누가? → 유연한 시간대 가능한 프리랜서
- 언제? → 갑자기 시간이 생겼을 때
- 왜? → 저렴하게 운동하고 싶어서
- 가치? → 정가의 70%로 즉시 예약
✅ Features defined with user value
# Step 3: 고객 스토리 - "고객의 하루, 고민, 해결"
$ /appkit.customer
🎯 Primary Persona: 김대리 (35세, IT 기업)
하루 스토리:
07:00 - "오늘도 운동 못하겠네..." (죄책감)
12:00 - "주말엔 테니스 쳐야지" (결심)
18:00 - "코트 예약 전화... 귀찮다" (좌절)
19:00 - [앱 발견] "3초 만에 예약?" (희망)
19:02 - "토요일 오전 예약 완료!" (만족)
토요일 - "운동 후 상쾌한 주말" (성취)
✅ Customer persona & journey mapped
# Step 4: 세일즈 랜딩 구성 - "어떻게 설득할까?"
$ /appkit.sales
📢 Landing Message:
[Hook]
"매주 테니스 치고 싶은데, 예약이 너무 번거로우신가요?"
[Problem]
- 전화 대기 15분
- 원하는 시간 항상 만석
- 비싼 정가
[Solution]
"3초 예약, 자동 할인, 실시간 공석 확인"
[Proof]
"이미 5,000명이 매주 사용 중"
[CTA]
"지금 가입하고 첫 예약 30% 할인받기"
✅ Sales landing created
# Step 5: MVP 범위 - "최소한으로 검증하려면?"
$ /appkit.mvp
🎯 MVP Scope (2주 검증):
Phase 0 (핵심만):
- 코트 검색/예약
- 간단 결제
목표: 주 10건 예약
Phase 1 (1개월):
- 할인 쿠폰
- 사용자 리뷰
목표: 재방문율 30%
Phase 2 (3개월):
- 커뮤니티
- 코칭 매칭
✅ MVP phases defined
# Step 6: 기획 정돈 - "기획이 일관적인가?"
$ /appkit.merge
🔄 Planning Consolidation:
용어 통일성 확인:
- "예약" vs "부킹" → "예약"으로 통일
- "사용자" vs "유저" → "사용자"로 통일
기능 중복 제거:
- spec 3개소에서 발견된 "실시간 알림" → 하나로 통합
- customer journey와 sales의 메시지 일관성 확보
고객 여정 - 기능 매핑:
✅ "주말 운동 계획" → 검색 기능
✅ "간편한 예약" → 원터치 예약
✅ "비용 절감" → 자동 할인
✅ Planning consolidated
# Step 7: 개발 준비 - "어떻게 만들까?"
$ /appkit.design
🏗️ Technical Design:
ERD 설계:
- User, Venue, Booking, Payment 엔티티
- 관계 정의 및 제약조건
API 엔드포인트:
- POST /bookings (예약 생성)
- GET /venues?location=... (코트 검색)
- POST /payments (결제 처리)
기술 정책:
- Rate Limiting: 시간당 100회
- Error Handling: 재시도 3회
- Content Safety: 필터 규칙
✅ 아이디어 구체화 완료!
이제 개발을 시작할 수 있습니다.
# Step 5: HTML 목업 생성
/appkit.visualize all
```
---
### 6. `/appkit.merge` - 기획 정돈
## 생성되는 파일 구조
**Purpose**: 흩어진 기획 문서들을 통합하고 일관성 확보
**Input**:
```
/appkit.merge
/appkit.merge "용어 통일 중점"
/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/
└── ui/
└── works/
│
├── concept.md # 서비스 컨셉 (/appkit.new)
├── mvp-scope.md # MVP 범위 (/appkit.mvp)
├── landing.html # 랜딩페이지 (/appkit.mvp)
│
├── router.md # 라우터 & UI 목록 (/appkit.ui)
├── main.md # 메인 구조 (/appkit.ui)
│
├── specs/ # 기능별 스펙 (/appkit.new)
│ ├── 001-user/spec.md
│ ├── 002-venue/spec.md
│ └── ...
│
├── policies/ # 정책 문서 (/appkit.policy)
│ ├── 00-policy-index.md # 정책 인덱스
│ ├── 01-monetization.md # 과금 정책 (MN-xxx)
│ ├── 02-gameplay.md # 서비스 규칙 (GM-xxx)
│ ├── 03-content.md # 콘텐츠 정책 (CH-xxx)
│ └── 04-progression.md # 진행 정책 (PR-xxx)
│
└── mockup/ # HTML 목업 (/appkit.visualize)
├── home.html
├── chat.html
├── shop.html
├── styles.css
└── scripts.js
```
**Output**:
- `docs/appkit/merge/concept-map.md` - 통합 컨셉 맵
- `docs/appkit/merge/journey-feature-map.md` - 고객 여정 - 기능 매핑
- `docs/appkit/merge/terminology.md` - 표준 용어 사전
- `docs/appkit/merge/consolidated-specs.md` - 통합된 기능 명세
**What it does**:
1. **용어 통일성 확인**:
- spec, customer, mvp의 용어 비교
- 표준 용어 사전 생성
2. **기능 중복 제거**:
- 여러 문서에 흩어진 동일 기능 통합
- 기획 레벨에서 중복 해소
3. **고객 가치 일관성**:
- customer journey와 sales 메시지 일관성
- 핵심 가치 제안 명확화
**중요**: MVP 범위 정의 후, 개발 준비 전에 실행!
---
### 7. `/appkit.design` - 개발 준비
## 템플릿 파일
**Purpose**: 개발에 필요한 기술 스펙 생성 (ERD, API, 정책)
**Input**:
```
/appkit.design
/appkit.design "RESTful API 중점"
/Users/taesupyoon/sideProjects/appkit/.specify/templates/
├── ui-router.md # 라우터 템플릿
├── ui-main.md # 메인 구조 템플릿
├── policy-index.md # 정책 인덱스 템플릿
├── policy-monetization.md # 과금 정책 템플릿
├── policy-gameplay.md # 서비스 규칙 템플릿
├── policy-content.md # 콘텐츠 정책 템플릿
├── policy-progression.md # 진행 정책 템플릿
├── policy-content-rating.md # 등급 정책 템플릿
├── mockup-base.html # HTML 목업 기본 템플릿
├── mockup-styles.css # 목업 스타일시트
└── mockup-scripts.js # 목업 스크립트
```
**Output**:
- `docs/appkit/design/entities.md` - ERD 및 데이터 모델
- `docs/appkit/design/apis.md` - API 엔드포인트 설계
- `docs/appkit/design/tech-policies.md` - 기술 정책
- `docs/appkit/design/screen-api-map.md` - 화면-API 매핑
**What it does**:
1. **ERD 설계**:
- 엔티티 및 관계 정의
- Mermaid 다이어그램 생성
2. **API 엔드포인트 설계**:
- RESTful API 명세
- Request/Response 예시
3. **기술 정책 정의**:
- Rate Limiting
- Error Handling
- Content Safety
- Data Management
**중요**: merge 완료 후 개발 직전에 실행!
---
---
## 🎓 논리적 사고 7단계와 명령어
| 단계 | 질문 | 명령어 |
|------|------|--------|
| 1. 아이디어 스케치 | 어떤 서비스인가? | `/appkit.new` |
| 2. 기능 구체화 | 뭐가 필요할까? 누가/어떻게 쓸까? | `/appkit.spec` |
| 3. 고객 스토리 | 고객의 하루, 고민, 해결은? | `/appkit.customer` |
| 4. 세일즈 구성 | 어떻게 설득할까? | `/appkit.sales` |
| 5. MVP 범위 | 최소한으로 검증하려면? | `/appkit.mvp` |
| 6. 기획 정돈 | 기획이 일관적인가? | `/appkit.merge` |
| 7. 개발 준비 | 어떻게 만들까? | `/appkit.design` |
---
## 💡 Best Practices (논리적 사고 연습)
## Best Practices
### 1. 고객부터 시작하기
- 기능이 아닌 고객의 문제부터 생각하세요
- "누가 쓸까?" 질문을 계속하세요
### 2. 작은 단계로 쪼개기
- 큰 작업을 7-10개 작은 단계로 나누세요
- 각 단계가 명확한 결과물을 갖도록 하세요
### 3. 스토리텔링으로 검증
- 고객의 하루를 그려보세요
- Before/After 시나리오를 구성하세요
### 4. MVP 먼저, 완벽은 나중에
### 2. MVP 먼저, 완벽은 나중에
- "없으면 안되는" 기능만 Phase 0에
- "있으면 좋은" 기능은 Phase 1+로
### 5. 세일즈 관점 유지
- 기능 설명이 아닌 가치 설명
- 고객이 얻는 이익 중심으로
### 3. 정책 ID로 추적하기
- 모든 정책에 코드 부여 (MN-001, GM-002 등)
- UI 요소와 정책 연결 (주석으로 표시)
### 6. 빠른 검증, 빠른 피벗
- 2주 안에 MVP 검증
- 실패해도 빠르게 방향 전환
### 4. 목업으로 검증하기
- 코딩 전에 HTML 목업으로 사용성 확인
- 브라우저에서 직접 확인 가능
### 7. 측정 가능한 목표
- 모든 Phase에 구체적 지표 설정
- 정성적 + 정량적 지표 균형
### 5. 명확하게 작성
- 모호한 표현 ("적절히", "필요시") 지양
- 개발자가 바로 구현 가능한 수준으로
---
## 📂 Generated File Structure
## Philosophy
```
docs/appkit/
├── overview.md # 1. 서비스 컨셉 (/appkit.new)
├── specs/
│ ├── 001-search/
│ │ └── spec.md # 2. 기능 구체화 (/appkit.spec)
│ ├── 002-booking/
│ │ └── spec.md
│ └── ...
├── customer-persona.md # 3. 타겟 고객 (/appkit.customer)
├── customer-journey.md # 3. 고객 스토리 (/appkit.customer)
├── sales-landing.md # 4. 세일즈 메시지 (/appkit.sales)
├── value-proposition.md # 4. 가치 제안 (/appkit.sales)
├── mvp-scope.md # 5. MVP 범위 (/appkit.mvp)
├── mvp-metrics.md # 5. 검증 지표 (/appkit.mvp)
├── merge/ # 6. 기획 정돈 (/appkit.merge)
│ ├── concept-map.md # 통합 컨셉 맵
│ ├── journey-feature-map.md # 고객 여정 - 기능 매핑
│ ├── terminology.md # 표준 용어 사전
│ └── consolidated-specs.md # 통합된 기능 명세
└── design/ # 7. 개발 준비 (/appkit.design)
├── entities.md # ERD 및 데이터 모델
├── apis.md # API 엔드포인트 설계
├── tech-policies.md # 기술 정책
└── screen-api-map.md # 화면-API 매핑
```
---
## 🚀 Quick Start
```bash
# 1. 아이디어 스케치
/appkit.new "당근마켓처럼 중고거래 앱"
# 2. 기능 구체화
/appkit.spec 001-search "위치 기반 상품 검색"
/appkit.spec 002-chat "구매자와 판매자 채팅"
# 3. 고객 스토리
/appkit.customer "20-30대 중고거래 선호"
# 4. 세일즈 메시지 구성
/appkit.sales "편리함과 신뢰 강조"
# 5. MVP 범위 정의
/appkit.mvp "2주 내 출시 목표"
# 6. 기획 정돈
/appkit.merge
# 7. 개발 준비
/appkit.design
```
---
## 📖 Philosophy (논리적 사고 철학)
> "아이디어는 고객의 문제에서 시작되고, 논리적 단계로 구체화된다."
> "아이디어는 고객의 문제에서 시작되고, 논리적 단계로 구체화되며, 목업으로 검증된다."
AppKit은 다음을 믿습니다:
1. **고객 문제 우선**: 기능보다 고객의 Pain Point 해결
2. **논리적 분해**: 큰 작업을 작은 단계로 쪼개기
3. **스토리텔링**: 고객의 하루를 이해하고 공감
4. **빠른 검증**: MVP로 시장 반응 먼저 확인
5. **가치 중심**: 기술이 아닌 고객 가치로 설득
6. **측정과 학습**: 모든 단계에서 배우고 개선
3. **빠른 검증**: MVP로 시장 반응 먼저 확인
4. **실행 가능한 문서**: 기획서가 바로 개발로 이어지도록
5. **시각적 확인**: HTML 목업으로 즉시 프로토타입 확인
---
**Built with ❤️ for Product Managers, Designers, and Developers**
**Version**: 5.0.0 (7-Step Logical Thinking)
**Last Updated**: 2025-11-20
**Key Update**: 논리적 사고 7단계로 재구성, merge(기획 정돈)와 design(개발 준비) 분리
**Version**: 7.1.0 (Simplified Path)
**Last Updated**: 2025-12-14
**Key Update**: [project] 폴더 제거, 모든 출력물 `ui/works/`에 직접 생성

279
.claude/commands/appkit.customer.md
View File

@@ -1,279 +0,0 @@
# appkit.customer
**타겟 고객을 명확히 하고 그들의 스토리를 구성하는 명령어**
---
## Overview
**This is Step 3 of the logical thinking 7-step workflow**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결) ← YOU ARE HERE
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
```
## Purpose
타겟 고객을 구체화하고 그들의 일상과 문제를 스토리텔링으로 풀어내어,
서비스가 어떤 가치를 제공하는지 명확히 합니다.
**핵심 질문**: "누가, 왜 이 서비스를 쓸까?"
---
## When to Use
- `/appkit.spec`으로 기능들을 구체화한 후 (Step 2 완료 후)
- 타겟 고객이 여전히 모호할 때
- 고객의 구체적인 사용 시나리오가 필요할 때
- 세일즈 메시지 작성 전 고객 이해가 필요할 때
---
## Usage
```bash
/appkit.customer
/appkit.customer "30대 직장인 주말 운동"
/appkit.customer "persona: busy professional"
/appkit.customer "journey: from problem to solution"
```
---
## What I'll Do
### 1. 고객 페르소나 구성 (Customer Persona)
**Primary Persona** (주요 고객):
```markdown
## Primary Persona: [이름] ([나이], [직업])
### Demographics (인구통계)
- 나이: 30-40대
- 직업: IT 기업 직장인
- 소득: 연 5000-8000만원
- 거주지: 서울/경기 아파트
- 가족: 기혼, 자녀 1-2명
### Psychographics (심리/행동)
- 라이프스타일: 워라밸 추구, 건강 관심 증가
- 가치관: 시간 효율성, 편의성 중시
- 관심사: 주말 운동, 가족과 시간
- 기술 친숙도: 높음, 모바일 앱 일상화
### Pain Points (현재 고민)
1. 운동하고 싶은데 시간이 없다
2. 코트 예약이 너무 번거롭다
3. 원하는 시간대는 항상 만석
4. 가격 비교가 어렵다
### Goals (달성하고 싶은 것)
- 규칙적인 주말 운동
- 스트레스 없는 예약 과정
- 합리적인 가격으로 운동
- 가족/친구와 함께하는 시간
```
**Secondary Personas** (보조 고객):
- 프리랜서 (시간 유연, 가격 민감)
- 대학생 (저렴한 가격 선호)
- 주부 (평일 낮 시간 활용)
### 2. 고객 여정 맵 (Customer Journey Map)
**하루의 스토리텔링**:
```markdown
## 김대리의 하루 (현재 - Problem State)
### 평일
07:00 😴 "오늘도 운동 못하겠네..." (죄책감)
08:30 🚇 지하철에서 "주말엔 꼭 테니스 쳐야지" (다짐)
12:00 🍽️ 점심시간 "코트 예약하려니... 전화해야 하나?" (귀찮음)
15:00 ☎️ "예약 전화... 통화중이네" (짜증)
18:00 😔 "주말 코트 다 찼대..." (실망)
21:00 🏠 "내일 아침 일찍 전화해볼까?" (미룸)
### 주말
토요일 오전 - 결국 운동 못함
일요일 - 가족과 시간 보내느라 포기
---
## 김대리의 하루 (미래 - Solution State)
### 평일
07:00 📱 침대에서 앱 열기 (3초)
07:01 ✅ "토요일 오전 10시 예약 완료!" (만족)
12:00 💰 "타임딜 30% 할인 알림" (기쁨)
18:00 👥 "동료들도 같이 예약할까?" (공유)
### 주말
토요일 10:00 - 테니스 코트에서 운동 중
토요일 12:00 - "운동 후 상쾌해!" (성취감)
일요일 - 가족과 여유롭게 시간 보내기
```
### 3. 문제-해결 시나리오
**Before (현재 상황)**:
```
1. 예약하려면 → 전화해야 함 (15분 대기)
2. 가격 확인 → 일일이 물어봐야 함
3. 시간대 확인 → 전화로만 가능
4. 취소/변경 → 또 전화
5. 결과 → 포기하거나 비싼 값 지불
```
**After (서비스 사용 후)**:
```
1. 예약 → 앱에서 3초 (실시간)
2. 가격 → 한눈에 비교 (투명)
3. 시간대 → 달력으로 확인 (직관적)
4. 취소/변경 → 클릭 한 번 (간편)
5. 결과 → 규칙적 운동 + 30% 절약
```
### 4. 감정 곡선 (Emotional Journey)
```
현재 경험:
기대 → 검색 → 좌절 → 포기
😊 → 😐 → 😤 → 😔
서비스 경험:
발견 → 시도 → 성공 → 만족 → 추천
😐 → 😊 → 😃 → 😍 → 🎉
```
### 5. 고객 인사이트 도출
**핵심 인사이트**:
1. **시간이 돈보다 중요**: 15분 기다리느니 조금 더 내고 앱 사용
2. **즉시성 중요**: "지금 당장" 예약 확정 받고 싶음
3. **투명성 요구**: 가격, 시간, 위치 한번에 보고 싶음
4. **Social Proof**: 다른 사람들도 쓰는지 궁금
5. **습관 형성**: 규칙적 운동을 원하지만 예약이 방해물
---
## Output Files
### 생성될 파일들:
1. **`docs/appkit/customer-persona.md`**
- Primary & Secondary 페르소나
- Demographics & Psychographics
- Pain Points & Goals
2. **`docs/appkit/customer-journey.md`**
- 현재 vs 미래 하루 스토리
- 감정 곡선
- 터치포인트 분석
- 기회 영역 식별
---
## Integration Points
### 다른 명령어와의 연계:
- **From `/appkit.spec`**: 기능별 사용자 프로파일 수집
- **To `/appkit.sales`**: 페르소나별 메시지 구성
- **To `/appkit.mvp`**: 핵심 고객의 핵심 문제 우선 해결
- **To `/appkit.design`**: 사용자 플로우 설계 기초
---
## Examples
### Example 1: 테니스 예약 앱
```bash
$ /appkit.customer
🎯 Target Customer Analysis
Primary: 30-40대 직장인
- Pain: 전화 예약 번거로움
- Want: 빠른 예약, 주말 운동
- Value: 시간 절약 > 비용 절약
Journey Highlights:
- Morning: 운동 계획 (의지)
- Lunch: 예약 시도 (좌절)
- Evening: 포기 (실망)
- Weekend: 운동 못함 (죄책감)
Key Insight:
"예약 friction이 운동 의지를 꺾는다"
✅ Generated customer-persona.md
✅ Generated customer-journey.md
```
### Example 2: 추가 페르소나 정의
```bash
$ /appkit.customer "freelancer flexible schedule"
🎯 Secondary Persona Added
프리랜서 (28세):
- Pain: 비싼 prime time 가격
- Want: 평일 낮 할인
- Value: 가격 > 시간대
Opportunity:
"평일 낮 유휴 시간 + 가격 민감 고객 매칭"
✅ Updated customer-persona.md
```
---
## Key Principles
### 고객 이해의 원칙:
1. **공감 먼저, 기능 나중**: 고객의 감정을 이해하라
2. **구체적 스토리**: "30대 직장인"이 아닌 "김대리의 하루"
3. **Before/After 대비**: 변화를 명확히 보여주기
4. **감정 추적**: 각 단계에서 고객이 느끼는 감정
5. **인사이트 도출**: 데이터가 아닌 행동 패턴 발견
---
## Tips
### 효과적인 페르소나 작성:
1. **이름을 붙여라**: "User A"가 아닌 "김대리"
2. **하루를 그려라**: 아침부터 저녁까지 구체적으로
3. **감정을 표현하라**: 😊😔😤 이모지 활용
4. **대화체 사용**: "아, 또 만석이네..." 실제 혼잣말
5. **숫자로 구체화**: "많이"가 아닌 "15분 대기"
---
## Next Steps
### 이 명령어 실행 후:
**📍 다음 단계: Step 4 - `/appkit.sales`** (세일즈 랜딩 구성)
- 고객 페르소나와 스토리를 기반으로 설득 메시지 작성
- 고객의 문제와 해결책을 중심으로 구성
---
## Version
- **Version**: 1.0.0
- **Created**: 2025-11-19
- **Philosophy**: "기능이 아닌 고객의 삶을 디자인하라"

785
.claude/commands/appkit.design.md
View File

@@ -1,785 +0,0 @@
# appkit.design
**개발 준비 - API, ERD, 기술 스펙 설계**
---
## Overview
**This is Step 7 of the logical thinking 7-step workflow**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙) ← YOU ARE HERE
```
## Purpose
merge에서 정돈된 기획을 기반으로, 실제 개발에 필요한 **기술 스펙**을 생성합니다.
기획 레벨(merge)과 구현 레벨(개발) 사이의 다리 역할을 합니다.
**핵심 질문**: "개발자에게 뭘 전달해야 하나? 어떻게 만들까?"
---
## When to Use
- `/appkit.merge`로 기획을 정돈한 후 (Step 6 완료 후)
- 개발 시작 직전
- 기술 스펙이 필요할 때
- ERD, API 설계가 필요할 때
---
## Usage
```bash
/appkit.design
/appkit.design "persona 도메인 집중"
/appkit.design "API 우선"
```
---
## What I'll Do
### 1. 소스 문서 읽기
**읽을 파일들**:
- `docs/appkit/merge/concept-map.md` (통합 컨셉)
- `docs/appkit/merge/consolidated-specs.md` (통합 스펙)
- `docs/appkit/merge/journey-feature-map.md` (기능 매핑)
- `docs/appkit/mvp-scope.md` (MVP 범위)
### 2. 데이터 엔티티 설계 (ERD)
**Output**: `docs/appkit/design/entities.md`
```markdown
# Data Entity Design (ERD)
*생성 기준: concept-map.md, consolidated-specs.md*
*생성일: 2025-11-20*
---
## Entity Relationship Diagram
```mermaid
erDiagram
Persona ||--o{ Content : generates
Content ||--|| Post : becomes
Schedule ||--o{ Post : manages
Persona {
int id PK
string name
int age
string personality
string tone
string language
json style_rules
datetime created_at
}
Content {
int id PK
int persona_id FK
string topic
string image_url
text caption
json hashtags
enum status
datetime generated_at
}
Post {
int id PK
int content_id FK
string platform
datetime scheduled_at
datetime posted_at
enum status
}
Schedule {
int id PK
time execution_time
bool is_active
json target_personas
}
```
```
---
## Entity Details
### Entity: Persona
**Purpose**: 캐릭터별 페르소나 정보 저장
**Table Name**: `personas`
**Fields**:
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | INT | PK, AUTO_INCREMENT | 페르소나 고유 ID |
| name | VARCHAR(100) | NOT NULL | 캐릭터 이름 |
| age | INT | NOT NULL | 캐릭터 나이 |
| personality | TEXT | NOT NULL | 성격 설명 |
| tone | VARCHAR(50) | NOT NULL | 말투 (밝은/전문가/친근한) |
| language | VARCHAR(10) | NOT NULL | 언어 (ko/en/ja) |
| style_rules | JSON | NULL | 스타일 규칙 (이모티콘, 반말/존댓말) |
| created_at | DATETIME | NOT NULL, DEFAULT NOW() | 생성 시간 |
**Relationships**:
- `Persona.id` → `Content.persona_id` (1:N)
**Business Rules**:
- 한 페르소나는 여러 콘텐츠 생성 가능
- 페르소나 삭제 시 생성된 콘텐츠는 보존 (FK: RESTRICT)
**Sample Data**:
```json
{
"id": 1,
"name": "밝은 20대 여성",
"age": 25,
"personality": "긍정적이고 친근한 성격",
"tone": "밝은",
"language": "ko",
"style_rules": {
"emoji_frequency": "high",
"formality": "casual",
"hashtag_style": "trendy"
},
"created_at": "2025-01-01T10:00:00Z"
}
```
---
### Entity: Content
**Purpose**: AI가 생성한 콘텐츠 저장
**Table Name**: `contents`
**Fields**:
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | INT | PK, AUTO_INCREMENT | 콘텐츠 고유 ID |
| persona_id | INT | FK → personas.id, NOT NULL | 생성한 페르소나 |
| topic | VARCHAR(200) | NOT NULL | 주제 |
| image_url | VARCHAR(500) | NOT NULL | 이미지 URL (Midjourney) |
| caption | TEXT | NOT NULL | 캡션 (GPT 생성) |
| hashtags | JSON | NULL | 해시태그 배열 |
| status | ENUM | NOT NULL | draft, approved, posted |
| generated_at | DATETIME | NOT NULL, DEFAULT NOW() | 생성 시간 |
**Enums**:
- `status`: `draft` (생성됨), `approved` (검토 완료), `posted` (포스팅됨)
**Relationships**:
- `Content.persona_id` → `Persona.id` (N:1)
- `Content.id` → `Post.content_id` (1:1)
**Business Rules**:
- 하나의 콘텐츠는 하나의 포스트로 변환
- 캡션 길이: 최소 50자, 최대 2200자 (Instagram 제한)
---
### Entity: Post
**Purpose**: 실제 포스팅 기록
**Table Name**: `posts`
**Fields**:
| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| id | INT | PK, AUTO_INCREMENT | 포스트 고유 ID |
| content_id | INT | FK → contents.id, UK, NOT NULL | 연결된 콘텐츠 |
| platform | VARCHAR(50) | NOT NULL | instagram, twitter, etc |
| scheduled_at | DATETIME | NOT NULL | 예약 시간 |
| posted_at | DATETIME | NULL | 실제 포스팅 시간 |
| status | ENUM | NOT NULL | pending, posted, failed |
**Enums**:
- `status`: `pending` (대기), `posted` (완료), `failed` (실패)
**Relationships**:
- `Post.content_id` → `Content.id` (1:1)
**Business Rules**:
- 하나의 콘텐츠는 하나의 포스트
- 포스팅 실패 시 재시도 로직 필요
---
## Summary
- **Total Entities**: 4 (Persona, Content, Post, Schedule)
- **Total Relationships**: 3 (1:N, 1:1)
- **Foreign Keys**: 3
**Entity Dependencies** (구현 순서):
1. **No dependencies**: Persona, Schedule (먼저 구현)
2. **Depends on 1**: Content (needs Persona)
3. **Depends on 2**: Post (needs Content)
```
### 3. API 엔드포인트 설계
**Output**: `docs/appkit/design/apis.md`
```markdown
# API Endpoint Design
*생성 기준: entities.md, consolidated-specs.md*
*API Style: RESTful*
*Base URL: `/api/v1`*
---
## 1. Persona APIs
### 1.1 Create Persona
**Endpoint**: `POST /personas`
**Description**: 새로운 페르소나 생성
**Request Body**:
```json
{
"name": "밝은 20대 여성",
"age": 25,
"personality": "긍정적이고 친근한 성격",
"tone": "밝은",
"language": "ko",
"style_rules": {
"emoji_frequency": "high",
"formality": "casual"
}
}
```
**Success Response** (201 Created):
```json
{
"persona": {
"id": 1,
"name": "밝은 20대 여성",
"age": 25,
"tone": "밝은",
"created_at": "2025-01-01T10:00:00Z"
}
}
```
**Error Responses**:
- 400 Bad Request: Validation failed
**Related Spec**: 001-persona/spec.md
**Related Entity**: Persona
---
### 1.2 List Personas
**Endpoint**: `GET /personas`
**Description**: 모든 페르소나 조회
**Success Response** (200 OK):
```json
{
"personas": [
{
"id": 1,
"name": "밝은 20대 여성",
"age": 25,
"tone": "밝은"
},
{
"id": 2,
"name": "전문가 30대 남성",
"age": 32,
"tone": "전문가"
}
],
"total": 2
}
```
---
## 2. Content APIs
### 2.1 Generate Content
**Endpoint**: `POST /contents/generate`
**Description**: AI로 콘텐츠 자동 생성
**Request Body**:
```json
{
"persona_id": 1,
"topic": "오늘의 운동 루틴",
"auto_post": false
}
```
**Success Response** (201 Created):
```json
{
"content": {
"id": 101,
"persona_id": 1,
"topic": "오늘의 운동 루틴",
"image_url": "https://midjourney.com/...",
"caption": "오늘도 열심히 운동했어요! 💪...",
"hashtags": ["운동", "헬스", "루틴"],
"status": "draft",
"generated_at": "2025-01-01T07:00:00Z"
}
}
```
**Business Logic**:
1. persona_id로 페르소나 정보 조회
2. Midjourney API 호출 (이미지 생성)
3. GPT API 호출 (캡션 생성, 페르소나 톤 반영)
4. 생성된 콘텐츠 DB 저장 (status: draft)
5. auto_post = true면 자동 포스팅 예약
**Error Responses**:
- 404 Not Found: Persona not found
- 502 Bad Gateway: Midjourney/GPT API 실패
- 503 Service Unavailable: API rate limit 초과
**Related Spec**: 002-content/spec.md
**Related Entity**: Content, Persona
---
### 2.2 List Contents
**Endpoint**: `GET /contents`
**Query Parameters**:
```
?persona_id=1 // Filter by persona
&status=draft // Filter by status
&date=2025-01-01 // Filter by generation date
&limit=20
&page=1
```
**Success Response** (200 OK):
```json
{
"contents": [
{
"id": 101,
"persona_id": 1,
"topic": "오늘의 운동 루틴",
"image_url": "https://...",
"status": "draft",
"generated_at": "2025-01-01T07:00:00Z"
}
],
"pagination": {
"total": 45,
"page": 1,
"limit": 20
}
}
```
---
## 3. Schedule APIs
### 3.1 Create Schedule
**Endpoint**: `POST /schedules`
**Description**: 자동 생성 스케줄 등록
**Request Body**:
```json
{
"execution_time": "07:00",
"target_personas": [1, 2, 3],
"is_active": true
}
```
**Success Response** (201 Created):
```json
{
"schedule": {
"id": 1,
"execution_time": "07:00",
"target_personas": [1, 2, 3],
"is_active": true
}
}
```
**Business Logic**:
- Cron job 생성 (매일 07:00 실행)
- 실행 시 target_personas의 각 페르소나로 콘텐츠 생성
- 생성 후 자동 포스팅
**Related Spec**: 003-schedule/spec.md
**Related Entity**: Schedule
---
## 4. Post APIs
### 4.1 Create Post
**Endpoint**: `POST /posts`
**Description**: 콘텐츠를 포스팅으로 예약
**Request Body**:
```json
{
"content_id": 101,
"platform": "instagram",
"scheduled_at": "2025-01-01T12:00:00Z"
}
```
**Success Response** (201 Created):
```json
{
"post": {
"id": 201,
"content_id": 101,
"platform": "instagram",
"scheduled_at": "2025-01-01T12:00:00Z",
"status": "pending"
}
}
```
**Business Logic**:
1. content_id로 콘텐츠 조회
2. 포스트 생성 (status: pending)
3. scheduled_at 시간에 Instagram API 호출
4. 성공 시 status = posted, 실패 시 status = failed
**Related Spec**: 003-schedule/spec.md (포스팅)
**Related Entity**: Post, Content
---
## API Summary
| Domain | Endpoints | Description |
|--------|-----------|-------------|
| Persona | 3 (create, list, update) | 페르소나 관리 |
| Content | 2 (generate, list) | 콘텐츠 생성 |
| Schedule | 2 (create, list) | 스케줄 관리 |
| Post | 2 (create, list) | 포스팅 관리 |
**Total Endpoints**: 9
---
## Error Response Format
**Standard Error Response**:
```json
{
"error": {
"code": "API_RATE_LIMIT",
"message": "Midjourney API rate limit exceeded",
"details": {
"limit": 50,
"current": 51,
"reset_at": "2025-01-01T08:00:00Z"
}
}
}
```
**Error Codes**:
- `VALIDATION_ERROR`: 입력 검증 실패
- `API_RATE_LIMIT`: API 제한 초과
- `GENERATION_FAILED`: 콘텐츠 생성 실패
- `NOT_FOUND`: 리소스 없음
```
### 4. 기술 정책 정의
**Output**: `docs/appkit/design/tech-policies.md`
```markdown
# Technical Policies
*기술 구현 관련 정책*
---
## API Rate Limiting
### Midjourney API
- **Limit**: 시간당 50회
- **동시 처리**: 최대 3개
- **초과 시**: 429 에러, 다음 시간까지 대기
- **Queue**: FIFO 방식
### OpenAI GPT-4 API
- **Limit**: 분당 60회
- **토큰**: 일 500,000 제한
- **초과 시**: 429 에러
- **Retry**: Exponential backoff (1s, 2s, 4s)
### Instagram Graph API
- **Limit**: 하루 200개 포스트
- **시간당**: 25회
- **초과 시**: 403 에러
**구현 방안**:
- Rate Limiter 모듈 구현
- 우선순위 큐 시스템
- API 호출 로그 기록
---
## Error Handling
### 재시도 정책
**API 실패**:
- 재시도 횟수: 3회
- 방식: Exponential backoff
- 대기 시간: 1s, 2s, 4s
**생성 실패**:
- 재시도 횟수: 2회
- 방식: 즉시 재시도
- 실패 시: 에러 로그 기록, 알림
**품질 불량**:
- 판단 기준: 이미지 해상도 < 1080x1080
- 처리: 자동 재생성 (1회)
### 로깅
**로그 종류**:
- `error.log`: 모든 에러
- `api-calls.log`: API 호출 기록
- `generation.log`: 콘텐츠 생성 기록
**로그 레벨**:
- ERROR: 시스템 오류
- WARN: API 제한 근접
- INFO: 정상 실행
---
## Content Safety
### 브랜드 안전성
- 성인 콘텐츠: GPT moderation API로 자동 차단
- 폭력/혐오: 필터 적용
- 저작권: 학습 데이터 외 참조 금지
### 품질 검증
- 이미지: 최소 1080x1080
- 캡션: 최소 50자, 최대 2200자
- 해시태그: 5-30개
---
## Data Management
### 저장 위치
- 페르소나: Database (personas table)
- 콘텐츠: Database (contents table)
- 이미지: S3 (Midjourney URL 저장)
- 로그: `logs/` directory
### 백업
- DB 백업: 일 1회 (자정)
- S3 백업: 자동 (versioning)
- 로그 보존: 90일
```
### 5. 화면-API 매핑
**Output**: `docs/appkit/design/screen-api-map.md`
```markdown
# Screen to API Mapping
*UI 화면과 API 호출 매핑*
---
## Flow: 콘텐츠 자동 생성
### Screen 1: 페르소나 설정
**User Actions**:
- 페르소나 목록 조회
- 새 페르소나 생성
**API Calls**:
```
1. GET /personas
→ Returns: 페르소나 리스트
2. (On create) POST /personas
→ Returns: 생성된 페르소나
```
---
### Screen 2: 스케줄 설정
**User Actions**:
- 스케줄 등록
- 실행 시간 설정
- 대상 페르소나 선택
**API Calls**:
```
1. GET /personas
→ Returns: 선택 가능한 페르소나
2. (On save) POST /schedules
→ Returns: 생성된 스케줄
```
---
### Screen 3: 콘텐츠 확인
**User Actions**:
- 생성된 콘텐츠 조회
- 승인/거부
**API Calls**:
```
1. GET /contents?status=draft
→ Returns: Draft 콘텐츠 목록
2. (On approve) PATCH /contents/{id}
→ Body: { "status": "approved" }
→ Returns: 업데이트된 콘텐츠
```
---
## Complete Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant UI
participant API
participant Midjourney
participant GPT
participant Instagram
User->>UI: 스케줄 등록
UI->>API: POST /schedules
API-->>UI: Schedule created
Note over API: 매일 07:00 Cron 실행
API->>API: GET /personas (target)
loop Each Persona
API->>Midjourney: Generate Image
Midjourney-->>API: Image URL
API->>GPT: Generate Caption
GPT-->>API: Caption Text
API->>API: Save Content (draft)
end
User->>UI: 콘텐츠 확인
UI->>API: GET /contents?status=draft
API-->>UI: Content List
User->>UI: 승인
UI->>API: PATCH /contents/{id}
API->>Instagram: Post Content
Instagram-->>API: Success
API-->>UI: Posted
```
```
---
## Output Files
### 생성될 파일들:
```
docs/appkit/design/
├── entities.md # ERD 및 데이터 모델
├── apis.md # API 엔드포인트 설계
├── tech-policies.md # 기술 정책
└── screen-api-map.md # 화면-API 매핑
```
---
## Integration Points
### 다른 명령어와의 연계:
- **From `/appkit.merge`**: concept-map.md 사용
- **To 개발팀**: 설계 문서 전달
- **To `/appkit.verify`**: 설계 완성도 체크 (향후)
---
## Key Principles
### 설계 원칙:
1. **Planning only, no code**: 설계 문서만 생성, 코드 작성 안 함
2. **Entity-first approach**: 데이터 모델부터 설계
3. **API follows entity**: API는 엔티티 관계에서 도출
4. **Traceability**: 모든 설계는 spec과 연결
---
## Next Steps
### 이 명령어 실행 후:
**📍 7단계 완료!**
- 기획부터 설계까지 모든 문서 완성
- 개발팀에게 전달 가능
- MVP Phase 0 개발 시작
---
## Version
- **Version**: 1.0.0
- **Created**: 2025-11-20
- **Philosophy**: "설계는 기획과 구현 사이의 다리"

506
.claude/commands/appkit.merge.md
View File

@@ -1,506 +0,0 @@
# appkit.merge
**기획 정돈 - 흩어진 기획 문서를 일관되게 통합**
---
## Overview
**This is Step 6 of the logical thinking 7-step workflow**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합) ← YOU ARE HERE
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
```
## Purpose
MVP 범위가 정해지면, 이제 지금까지 만든 기획 문서들을 정리할 차례입니다.
spec, customer, mvp를 각각 만들다 보면 AI가 맥락을 놓치고 일관성 없이 생성합니다.
**기획 레벨**에서 흩어진 내용을 통합하고, 중복과 충돌을 해소합니다.
**핵심 질문**: "기획이 일관적인가? 중복은? 용어가 통일됐나?"
---
## When to Use
- `/appkit.mvp`로 MVP 범위를 정한 후 (Step 5 완료 후)
- spec, customer, mvp 결과물이 준비되었을 때
- 기획 문서 간 중복이나 충돌이 보일 때
- 용어와 컨셉을 통일해야 할 때
- 개발 준비(design) 전 기획을 정돈하고 싶을 때
---
## Usage
```bash
/appkit.merge
/appkit.merge "특히 spec과 customer 용어 통일"
/appkit.merge "MVP 범위 기반으로 우선순위 재조정"
```
---
## What I'll Do
### 1. 소스 문서 수집
**읽을 파일들**:
- `docs/appkit/specs/*/spec.md` (모든 기능 스펙)
- `docs/appkit/customer-persona.md` (타겟 고객)
- `docs/appkit/customer-journey.md` (고객 여정)
- `docs/appkit/mvp-scope.md` (MVP 범위)
- `docs/appkit/mvp-metrics.md` (검증 지표)
### 2. 기획 일관성 분석
**분석 항목**:
#### A. 용어 통일성
```markdown
## 용어 충돌 발견
❌ **Spec에서**: "페르소나 설정"
❌ **Customer에서**: "캐릭터 프로필"
❌ **MVP에서**: "인물 정보"
✅ **통일 제안**:
→ 표준 용어: "페르소나"
→ 모든 문서에 일관되게 적용
```
#### B. 기능 중복 확인
```markdown
## 중복 기능 발견
❌ **001-persona/spec.md**:
- 이미지 생성 기능 언급
❌ **002-content/spec.md**:
- 이미지 생성 기능 중복 설명
✅ **통합 제안**:
→ 002-content에서 통합 관리
→ 001-persona는 002-content 참조
```
#### C. 고객 가치 일관성
```markdown
## 가치 제안 충돌
❌ **Spec**: "100명 자동 관리"
❌ **Customer**: "15시간 → 1시간 시간 절약"
❌ **Sales**: "월 1억 수익"
✅ **핵심 가치 통일**:
→ Primary Value: "시간 절약 (15시간 → 1시간)"
→ Secondary Value: "확장성 (100명 관리)"
→ Ultimate Goal: "월 1억 수익 달성"
```
### 3. MVP 범위 기반 우선순위 조정
```markdown
## MVP 범위 재확인
**Phase 0 (MVP - 2주)**:
✅ 페르소나 관리 (001-persona)
✅ 콘텐츠 자동 생성 (002-content)
✅ 스케줄링 (003-schedule)
❌ 성과 분석 (004-analytics) → Phase 1로 이동
❌ 수익화 관리 (005-monetize) → Phase 2로 이동
**우선순위 조정**:
1. **Must Have** (없으면 MVP 불가):
- 001-persona, 002-content, 003-schedule
2. **Should Have** (있으면 좋음):
- 004-analytics (Phase 1)
3. **Nice to Have** (나중에):
- 005-monetize (Phase 2)
→ Spec 문서에서 Phase 0 외 기능은 "Future" 섹션으로 이동
```
### 4. 컨셉 맵 생성
**Output**: `docs/appkit/merge/concept-map.md`
```markdown
# Concept Map (통합 컨셉 맵)
*생성 기준: spec, customer, mvp 통합*
*생성일: 2025-11-20*
---
## 핵심 컨셉 정의
### 서비스 컨셉
"AI 인플루언서 100명을 자동으로 운영하는 시스템"
### 핵심 가치 (통일)
1. **Primary**: 시간 절약 (15시간 → 1시간)
2. **Secondary**: 확장성 (100명 자동 관리)
3. **Ultimate Goal**: 월 1억 수익
### 타겟 사용자
- **Primary**: 본인 (AI 인플루언서 운영자)
- **Pain Point**: 수동 작업 불가능
- **Goal**: 완전 자동화
---
## 기능 통합 맵
### Phase 0 (MVP - 2주)
**001-persona** (페르소나 관리)
- 정의: 캐릭터별 성격, 톤앤매너 설정
- 입력: 캐릭터 정보 (이름, 나이, 성격)
- 출력: 페르소나 DB 저장
- 의존성: 없음
**002-content** (콘텐츠 자동 생성)
- 정의: 페르소나 기반 이미지 + 캡션 자동 생성
- 입력: 페르소나 ID, 주제
- 출력: 이미지 (Midjourney), 캡션 (GPT)
- 의존성: 001-persona (필수)
**003-schedule** (스케줄링)
- 정의: 매일 아침 7시 자동 생성 실행
- 입력: 스케줄 설정
- 출력: Cron job 실행
- 의존성: 002-content (필수)
---
## 용어 사전 (통일된 표현)
| 개념 | 표준 용어 | 금지 용어 |
|------|-----------|-----------|
| 캐릭터 정보 | 페르소나 | 캐릭터 프로필, 인물 정보 |
| 자동 생성 | 콘텐츠 생성 | 포스트 제작, 글쓰기 |
| 예약 실행 | 스케줄링 | 타이머, 자동 실행 |
| 성과 추적 | 분석 | 통계, 모니터링 |
---
## 데이터 흐름
```
[페르소나 DB] → [콘텐츠 생성] → [Instagram API]
↑ ↑ ↑
001-persona 002-content 003-schedule
```
**데이터 엔티티** (기획 레벨):
1. Persona (페르소나 정보)
2. Content (생성된 콘텐츠)
3. Schedule (스케줄 설정)
4. Post (포스팅 기록)
*상세 데이터 모델은 /appkit.design에서 생성*
```
### 5. 고객 여정과 기능 매핑
**Output**: `docs/appkit/merge/journey-feature-map.md`
```markdown
# 고객 여정 - 기능 매핑
*Customer Journey → Feature Mapping*
---
## 현재 상황 (Before)
**새벽 6시**: "100개 콘텐츠 어떻게 만들지..." (막막)
→ **해결 기능**: 없음 (수동 작업)
**오전 9시**: 20개째 이미지 생성 중 (지침)
→ **해결 기능**: 002-content (자동 생성)
**오후 3시**: 50개째 캡션 작성 중 (번아웃)
→ **해결 기능**: 002-content (자동 생성)
**저녁 9시**: 결국 20개 못 올림 (좌절)
→ **해결 기능**: 003-schedule (자동 포스팅)
---
## 미래 상황 (After - MVP 적용)
**전날 밤 11시**: 내일 주제만 설정 (5분)
→ **사용 기능**: 001-persona (주제 입력)
**아침 7시**: 시스템이 100개 자동 생성 (무인)
→ **사용 기능**: 003-schedule → 002-content
**아침 8시**: 커피 마시며 퀄리티 체크 (30분)
→ **사용 기능**: 004-analytics (Phase 1)
---
## 기능별 고객 가치
**001-persona**:
- Pain 해소: "매번 캐릭터 설정 반복" → "한번 설정, 계속 사용"
- 시간 절약: 10분/캐릭터 → 1분 (첫 설정)
**002-content**:
- Pain 해소: "100개 수동 생성 불가능" → "100개 자동 생성"
- 시간 절약: 10시간 → 0시간
**003-schedule**:
- Pain 해소: "아침마다 실행 필요" → "자동 실행"
- 시간 절약: 5분/일 → 0분
```
### 6. 통합 후 구조 재정의
**Before (분산)**:
```
docs/appkit/
├── specs/
│ ├── 001-persona/spec.md (용어 불일치)
│ ├── 002-content/spec.md (중복 설명)
│ └── 003-schedule/spec.md
├── customer-persona.md (용어 다름)
├── customer-journey.md
├── mvp-scope.md (우선순위 모호)
└── mvp-metrics.md
```
**After (통합)**:
```
docs/appkit/merge/
├── concept-map.md # 핵심: 통합 컨셉 맵
├── journey-feature-map.md # 고객 여정 - 기능 매핑
├── terminology.md # 표준 용어 사전
├── consolidated-specs.md # 통합된 기능 명세
└── mvp-priority.md # 재조정된 우선순위
```
**구조 설명**:
- `concept-map.md`: 모든 문서의 컨셉을 하나로 통합
- `journey-feature-map.md`: 고객 여정과 기능 매핑
- `terminology.md`: 통일된 용어 사전
- `consolidated-specs.md`: 중복 제거된 기능 명세
- `mvp-priority.md`: MVP 기반 우선순위
### 7. 충돌 해결
**충돌 패턴 식별**:
```markdown
## Conflicts Detected
⚠️ **Conflict #1**: 이미지 생성 해상도
- 001-persona: 512x512
- 002-content: 1080x1080
→ **해결**: content-safety.md에 용도별 최소 해상도 정의
⚠️ **Conflict #2**: API 호출 우선순위
- 001: persona 우선
- 002: content 우선
→ **해결**: rate-limiter.md에 우선순위 큐 정의
⚠️ **Conflict #3**: 에러 시 재시도 횟수
- 001: 5회
- 002: 3회
→ **해결**: error-handling.md에 통일 (3회)
```
---
## Output Files
### 생성될 파일 구조:
```
docs/appkit/merge/
├── specs/ (통합된 개별 기능)
│ ├── 001-persona/
│ ├── 002-content/
│ ├── 003-schedule/
│ └── 004-posting/
├── common/ (공통 모듈 & 정책)
│ ├── 001-image-generation/
│ ├── 002-rate-limiter/
│ ├── 003-error-handler/
│ ├── 004-content-safety/
│ ├── 005-api-limits/
│ └── 006-data-management/
├── overview.md (전체 통합 요약)
└── dependencies.md (의존성 그래프)
```
### 파일별 상세:
1. **`merge/specs/00X-*/spec.md`**
- 원본 specs에서 중복 제거
- common 모듈 참조 추가
- 의존성 명시
2. **`merge/common/001-image-generation/module.md`**
- Midjourney API 통합 로직
- 이미지 생성 공통 인터페이스
- 사용 예시
3. **`merge/common/002-rate-limiter/module.md`**
- API별 제한 정책
- 우선순위 큐 시스템
- 재시도 로직
4. **`merge/common/003-error-handler/module.md`**
- 통일된 에러 처리
- 로깅 정책
- 알림 규칙
5. **`merge/common/004-content-safety/policy.md`**
- 브랜드 안전성 필터
- 콘텐츠 검증 규칙
- 언어/문화 가이드
6. **`merge/common/005-api-limits/policy.md`**
- Midjourney: 시간당 50회
- OpenAI: 분당 60회
- Instagram: 일 200개
7. **`merge/common/006-data-management/policy.md`**
- 저장 위치 및 구조
- 보존 기간
- 백업 정책
8. **`merge/overview.md`**
- 중복 제거 요약
- 통합된 기능 목록
- common 모듈 목록
9. **`merge/dependencies.md`**
- 기능 간 의존성 그래프
- 실행 순서
- 순환 의존성 체크
---
## Integration Points
### 다른 명령어와의 연계:
- **From `/appkit.mvp`**: MVP Phase 0에 포함될 기능들
- **From `/appkit.spec`**: 각 기능별 스펙 파일
- **To 개발팀**: 정리된 스펙과 공통 모듈로 구현 시작
---
## Examples
### Example 1: 기본 통합
```bash
$ /appkit.merge
🔄 Spec Consolidation Analysis
**중복 기능 발견**: 2개
✅ image-generation 모듈로 통합
**공통 정책 추출**: 6개
✅ 001-image-generation (모듈)
✅ 002-rate-limiter (모듈)
✅ 003-error-handler (모듈)
✅ 004-content-safety (정책)
✅ 005-api-limits (정책)
✅ 006-data-management (정책)
**의존성 정리**: ✅ 순환 없음
**충돌 해결**: 3개
✅ 이미지 해상도 통일
✅ API 우선순위 정의
✅ 재시도 횟수 통일
✅ Created docs/appkit/merge/
✅ Generated merge/specs/ (4개)
✅ Generated merge/common/ (6개)
✅ Generated merge/overview.md
✅ Generated merge/dependencies.md
```
### Example 2: 특정 영역 집중
```bash
$ /appkit.merge "API 통합 중점"
🔄 API Integration Focus
**API 통합 분석**:
- Midjourney: 2곳에서 호출 → 통합
- OpenAI: 3곳에서 호출 → 통합
- Instagram: 1곳 (통합 불필요)
**Rate Limiting 정책**:
✅ common/005-api-limits/policy.md 생성
- Midjourney: 시간당 50회
- OpenAI: 분당 60회
- 우선순위 큐 필요
✅ Generated merge/common/001-image-generation/
✅ Generated merge/common/002-rate-limiter/
✅ Updated merge/specs/ (중복 제거)
```
---
## Key Principles
### Merge 원칙:
1. **DRY (Don't Repeat Yourself)**: 중복 코드/정책 제거
2. **Single Source of Truth**: 하나의 정의, 여러 참조
3. **Explicit Dependencies**: 암묵적 의존성 명시화
4. **Policy Centralization**: 정책은 한 곳에서 관리
5. **Conflict Resolution**: 충돌은 즉시 해결
---
## Tips
### 효과적인 통합을 위해:
1. **작은 단위로 시작**: 2-3개 기능부터 통합
2. **정책 우선**: 공통 규칙부터 정리
3. **의존성 체크**: 순환 의존성 방지
4. **문서화**: 통합 이유와 결정사항 기록
5. **점진적 리팩토링**: 한번에 다 바꾸지 말기
---
## Next Steps
### 이 명령어 실행 후:
**📍 다음 단계: Step 7 - `/appkit.design`** (개발 준비)
- 기획이 정돈되었으니 이제 개발 준비 단계로
- ERD, API 엔드포인트 설계
- 기술 정책 정의
- 개발팀에게 전달할 최종 기술 스펙 완성
---
## Version
- **Version**: 1.0.0
- **Created**: 2025-01-20
- **Philosophy**: "AI는 맥락을 놓친다. 사람이 통합하라."

663
.claude/commands/appkit.mvp.md
View File

@@ -1,404 +1,493 @@
# appkit.mvp
**최소한의 기능으로 최대한의 검증을 하는 MVP 범위 정의 명령어**
---
description: MVP 범위 정하기 - 최소한의 기능으로 최대한의 검증 + 랜딩페이지 생성
---
## User Input
```text
$ARGUMENTS
```
User input **may** contain constraints like "2-week validation", "budget: 500만원" etc.
## Overview
**This is Step 5 of the logical thinking 7-step workflow**:
**논리적 사고 5단계 워크플로우**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?) ← YOU ARE HERE
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지 ← YOU ARE HERE
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트)
4. /appkit.policy → 정책설계서 (비즈니스 규칙)
5. /appkit.visualize → 목업 생성 (HTML 프로토타입)
```
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works`
## Purpose
핵심 가치만 구현하여 빠르게 시장 검증을 하기 위한 MVP 범위를 정의합니다.
"있으면 좋은" 기능을 제외하고 "없으면 안되는" 기능만 선별합니다.
**추가로, MVP 검증을 위한 랜딩페이지를 HTML로 생성합니다.**
**핵심 질문**: "최소한으로 검증하려면 뭐가 필요할까?"
---
## When to Use
## Pre-requisite
- `/appkit.sales`로 가치 제안을 정의한 후 (Step 4 완료 후)
- 개발 시작 전 범위를 정해야 할 때
- 리소스가 제한적일 때
- 빠른 시장 검증이 필요할 때
- `/appkit.new`로 서비스 컨셉이 정의되어 있어야 함
- `concept.md` 파일이 존재해야 함
---
## Usage
## Execution Flow
```bash
/appkit.mvp
/appkit.mvp "2-week validation"
/appkit.mvp "budget: 500만원"
/appkit.mvp "target: early adopters only"
```
### 1. 기존 기획 읽기
---
Read files from `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/`:
- `concept.md` - 서비스 컨셉
## What I'll Do
### 2. MVP 정의 대화
### 1. MVP 정의 프레임워크
**Step 1: 핵심 가치 파악**
```markdown
## MVP Definition Framework
## MVP 분석
### The ONE Thing Test
"만약 딱 하나의 기능만 만들 수 있다면?"
→ 그것이 진짜 핵심 가치
→ [핵심 기능 도출]
### Concierge MVP vs Product MVP
- Concierge: 수동으로 서비스 제공 (검증용)
- Product: 자동화된 제품 (확장용)
### 기능 분류
### MLP (Minimum Lovable Product)
- Minimum: 최소 기능
- Viable: 사용 가능
- Lovable: 사랑받을 만한
→ MVP도 완성도는 있어야 함
```
### 2. Phase별 기능 분류
```markdown
## MVP Phases
### Phase 0: Core MVP (2주)
**Phase 0: Core MVP (2주)**
"없으면 서비스가 성립 안 되는 기능"
#### Must Have (핵심)
✅ 코트 검색/조회
✅ 실시간 예약
✅ 간단 결제
✅ 예약 확인
✅ Must Have (핵심):
- [기능 1]: [이유]
- [기능 2]: [이유]
#### 구현 수준
- UI: 기본 모바일 웹 (앱 개발 X)
- 백엔드: 최소 API (5-7개)
- 결제: 간편결제 1종 (카드)
- 인증: 소셜 로그인 1종 (카카오)
❌ 제외할 것:
- [기능 A]: [Phase 1으로]
- [기능 B]: [Phase 2로]
#### 제외할 것
❌ 회원 등급 시스템
❌ 리뷰/평점
❌ 쿠폰/포인트
❌ 푸시 알림
❌ 커뮤니티
#### 검증 목표
- 주간 예약 10건 달성
- 사용자 10명 확보
- 핵심 플로우 검증
### Phase 1: Enhanced MVP (1개월)
**Phase 1: Enhanced MVP (1개월)**
"사용자 만족도를 높이는 기능"
#### Should Have (개선)
✅ 할인/쿠폰 시스템
✅ 사용자 리뷰
✅ 예약 변경/취소
✅ 다중 결제 수단
- [기능 A]
- [기능 C]
#### 검증 목표
- 재방문율 30%
- 주간 예약 50건
- NPS 40 이상
### Phase 2: Growth (3개월)
**Phase 2: Growth (3개월)**
"성장과 확장을 위한 기능"
#### Nice to Have (확장)
✅ 커뮤니티 기능
✅ 코칭 매칭
✅ 토너먼트 개최
✅ 장비 대여
- [기능 B]
- [기능 D]
#### 검증 목표
- MAU 1,000명
- 월 매출 1,000만원
- 바이럴 계수 1.2
---
이 MVP 범위가 맞나요? 조정하고 싶은 부분이 있나요?
```
### 3. MVP 검증 지표 설정
**Step 2: 사용자 피드백**
- "좋아", "Yes" → MVP 문서 + 랜딩페이지 생성
- 조정 요청 → 업데이트 후 재제시
### 3. MVP 문서 생성
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/mvp-scope.md`
```markdown
## MVP Metrics
# MVP Scope Definition
### 1️⃣ Success Metrics (성공 지표)
"목표 달성 여부"
## Overview
- **서비스명**: [서비스명]
- **MVP 목표**: [목표 한 줄 정의]
- **검증 기간**: 2주
#### Quantitative (정량)
- 주간 활성 사용자 (WAU): 10명
- 주간 예약 건수: 10건
- 전환율: 방문자의 10% 예약
- 결제 성공률: 90%
---
#### Qualitative (정성)
- "편리하다" 피드백 70%
- "다시 쓸 것" 응답 80%
- 추천 의향 (NPS): 30+
## Phase 0: Core MVP (2주)
### Must Have
| 기능 | 설명 | 우선순위 |
|------|------|----------|
| [기능1] | [설명] | P0 |
| [기능2] | [설명] | P0 |
### 2️⃣ Learning Metrics (학습 지표)
"무엇을 배울 것인가"
### 구현 수준
- UI: [기본 모바일 웹 / 앱 등]
- 백엔드: [최소 API 개수]
- 결제: [결제 방식]
- 인증: [인증 방식]
#### User Behavior
- 이탈 구간: 어디서 포기하나?
- 사용 시간대: 언제 가장 활발한가?
- 검색 패턴: 뭘 찾고 있나?
- 실패 케이스: 왜 예약 안 하나?
### 제외 항목
| 기능 | 이유 | 예정 Phase |
|------|------|------------|
| [기능A] | [이유] | Phase 1 |
| [기능B] | [이유] | Phase 2 |
#### Product-Market Fit Signals
- Organic Growth: 자연 유입 있나?
- Retention: 다시 오나?
- Referral: 추천하나?
- Payment: 돈을 내나?
---
## Phase 1: Enhanced MVP (1개월)
### 3️⃣ Pivot Indicators (피벗 신호)
"방향 전환이 필요한 시점"
### Should Have
| 기능 | 설명 |
|------|------|
| [기능A] | [설명] |
🚨 Danger Signals
- 2주 후 WAU < 5명
- 전환율 < 3%
- NPS < 0
- 일일 사용 시간 < 1분
### 검증 목표
- [지표 1]
- [지표 2]
→ Action: 가치 제안 재검토
```
---
### 4. MVP 개발 우선순위 매트릭스
## Phase 2: Growth (3개월)
```markdown
## Priority Matrix
### Nice to Have
| 기능 | 설명 |
|------|------|
| [기능B] | [설명] |
High Impact ↑
---
[P0: 코트 예약] | [P1: 할인 시스템]
Must Do Now | Do Next
__________________|__________________
|
[P3: 푸시 알림] | [P2: 리뷰 시스템]
Don't Do | Do Later
|
→ High Effort
## 검증 지표
### Priority Scoring
Impact (영향도) x Confidence (확신도) / Effort (노력)
### Success Metrics (성공 지표)
- [정량 지표 1]
- [정량 지표 2]
예시:
- 코트 예약: 10 x 10 / 3 = 33.3 (P0)
- 커뮤니티: 5 x 3 / 8 = 1.9 (P3)
```
### Learning Metrics (학습 지표)
- [학습할 것 1]
- [학습할 것 2]
### 5. MVP 실행 로드맵
### Pivot Indicators (피벗 신호)
- 🚨 [위험 신호 1]
- 🚨 [위험 신호 2]
```markdown
## Execution Roadmap
---
### Week 1-2: Build Phase 0
Day 1-3: 기본 UI/UX
- 검색 화면
- 예약 화면
- 확인 화면
Day 4-7: 핵심 백엔드
- 예약 API
- 결제 연동
- 알림 발송
Day 8-10: 통합 테스트
- End-to-end 테스트
- 결제 테스트
- 부하 테스트
Day 11-14: Soft Launch
- 베타 사용자 10명
- 피드백 수집
- 긴급 수정
### Week 3-4: Validate & Iterate
- 지표 측정
- 사용자 인터뷰
- 개선사항 반영
- Phase 1 결정
### Week 5-8: Build Phase 1
(If Phase 0 validated)
- 할인 시스템
- 리뷰 기능
- UX 개선
```
### 6. MVP 체크리스트
```markdown
## MVP Checklist
### Before Launch
□ 핵심 가치 명확한가?
□ 타겟 사용자 명확한가?
□ 성공 지표 정의했나?
□ 실패 기준 정의했나?
□ 2주 안에 가능한가?
- [ ] 핵심 가치 명확한가?
- [ ] 타겟 사용자 명확한가?
- [ ] 성공 지표 정의했나?
- [ ] 2주 안에 가능한가?
### During Development
□ Scope creep 발생하지 않았나?
□ "하나 더" 유혹 거부했나?
□ 핵심 플로우만 집중했나?
- [ ] Scope creep 발생하지 않았나?
- [ ] 핵심 플로우만 집중했나?
### After Launch
□ 정량 지표 달성했나?
□ 정성 피드백 긍정적인가?
□ 다음 단계 명확한가?
- [ ] 정량 지표 달성했나?
- [ ] 다음 단계 명확한가?
```
---
## Output Files
### 4. 랜딩페이지 생성
### 생성될 파일들:
**Template 참조**: `.specify/templates/sales-landing-template.html`
1. **`docs/appkit/mvp-scope.md`**
- Phase별 기능 목록
- 포함/제외 기능
- 우선순위 매트릭스
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/landing.html`
2. **`docs/appkit/mvp-metrics.md`**
- 성공 지표
- 학습 지표
- 피벗 기준
랜딩페이지는 다음 섹션을 포함해야 합니다:
---
#### 4-1. 랜딩페이지 구조
## Integration Points
```html
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
### 다른 명령어와의 연계:
<!-- SEO Meta Tags -->
<title>[서비스명] - [한 줄 슬로건]</title>
<meta name="description" content="[서비스 설명 2-3문장]">
<meta name="keywords" content="[키워드1], [키워드2], [키워드3]">
- **From `/appkit.customer`**: Primary 페르소나의 핵심 문제
- **From `/appkit.sales`**: 검증할 핵심 가치
- **To `/appkit.merge`**: MVP Phase 0 기능의 구현 준비
<!-- Open Graph -->
<meta property="og:title" content="[서비스명] - [슬로건]">
<meta property="og:description" content="[서비스 설명]">
<meta property="og:type" content="website">
---
<!-- Fonts & Styles -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;500;600;700;800&display=swap" rel="stylesheet">
## Examples
<style>
/* 템플릿 스타일 적용 */
</style>
</head>
<body>
<!-- 1. Hero Section -->
<section class="hero">
<div class="hero-content">
<span class="badge">[배지 텍스트 - 예: 🚀 사전 등록 중]</span>
<h1>[메인 헤드라인]<br>[서브 헤드라인]</h1>
<p class="tagline">[2-3문장의 핵심 가치 설명]</p>
<a href="#cta" class="cta-button">[CTA 버튼 텍스트]</a>
</div>
</section>
### Example 1: 2주 검증 MVP
```bash
$ /appkit.mvp "2-week validation"
<!-- 2. Problem Section: 공감 유도 -->
<section class="problem">
<div class="container">
<h2 class="section-title">[문제 제기 질문]</h2>
<ul class="problem-list">
<li>[고객 Pain Point 1]</li>
<li>[고객 Pain Point 2]</li>
<li>[고객 Pain Point 3]</li>
</ul>
<div class="highlight-box">
<p>[문제 요약]</p>
<p class="key">[핵심 메시지/솔루션 티저]</p>
</div>
</div>
</section>
🎯 MVP Scope Defined
<!-- 3. Solution Section: 해결책 제시 -->
<section class="solution">
<div class="container">
<h2 class="section-title">[솔루션 헤드라인]</h2>
<p class="section-subtitle">[솔루션 설명]</p>
<div class="feature-grid">
<div class="feature-card">
<span class="feature-icon">[이모지]</span>
<h3>[기능 1]</h3>
<p>[기능 1 설명]</p>
</div>
<div class="feature-card">
<span class="feature-icon">[이모지]</span>
<h3>[기능 2]</h3>
<p>[기능 2 설명]</p>
</div>
<div class="feature-card">
<span class="feature-icon">[이모지]</span>
<h3>[기능 3]</h3>
<p>[기능 3 설명]</p>
</div>
</div>
</div>
</section>
Phase 0 (2 weeks):
✅ Search (location-based)
✅ Booking (real-time)
✅ Payment (simple)
✅ Confirmation (email)
<!-- 4. How It Works: 작동 방식 -->
<section class="how-it-works">
<div class="container">
<h2 class="section-title">어떻게 이용하나요?</h2>
<div class="steps">
<div class="step">
<span class="step-number">1</span>
<h3>[단계 1]</h3>
<p>[설명]</p>
</div>
<div class="step">
<span class="step-number">2</span>
<h3>[단계 2]</h3>
<p>[설명]</p>
</div>
<div class="step">
<span class="step-number">3</span>
<h3>[단계 3]</h3>
<p>[설명]</p>
</div>
</div>
</div>
</section>
Excluded:
❌ Reviews (Phase 1)
❌ Discounts (Phase 1)
❌ Community (Phase 2)
<!-- 5. Social Proof (Optional): 신뢰 요소 -->
<section class="social-proof">
<div class="container">
<h2 class="section-title">이런 분들이 사용합니다</h2>
<div class="testimonials">
<!-- 후기 또는 사용자 유형 -->
</div>
</div>
</section>
Success Criteria:
- 10 bookings/week
- 10 active users
- NPS > 30
<!-- 6. Pricing (Optional): 가격 -->
<section class="pricing">
<div class="container">
<h2 class="section-title">합리적인 가격</h2>
<div class="pricing-cards">
<!-- 가격 카드 -->
</div>
</div>
</section>
✅ Generated mvp-scope.md
✅ Generated mvp-metrics.md
<!-- 7. FAQ Section -->
<section class="faq">
<div class="container">
<h2 class="section-title">자주 묻는 질문</h2>
<div class="faq-list">
<div class="faq-item">
<h3 class="faq-question">[질문 1]</h3>
<p class="faq-answer">[답변 1]</p>
</div>
<!-- 더 많은 FAQ -->
</div>
</div>
</section>
<!-- 8. Final CTA -->
<section class="final-cta" id="cta">
<div class="container">
<h2>[최종 CTA 헤드라인]</h2>
<p>[마지막 설득 문구]</p>
<a href="[링크]" class="cta-button cta-large">[CTA 버튼]</a>
</div>
</section>
<!-- Footer -->
<footer>
<p>© 2024 [서비스명]. All rights reserved.</p>
</footer>
<script>
// Scroll Animation
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
entry.target.classList.add('visible');
}
});
}, { threshold: 0.1 });
document.querySelectorAll('.animate-on-scroll').forEach(el => {
observer.observe(el);
});
</script>
</body>
</html>
```
### Example 2: 예산 제약 MVP
```bash
$ /appkit.mvp "budget: 500만원"
#### 4-2. 스타일 가이드 (템플릿 참조)
💰 Budget-Constrained MVP
```css
:root {
--primary: #7C3AED; /* 메인 컬러 (보라) */
--primary-light: #8B5CF6;
--primary-dark: #6D28D9;
--bg-white: #FFFFFF;
--bg-gray: #F5F7FA;
--text-primary: #1F2937;
--text-secondary: #6B7280;
--border: #E5E7EB;
}
Concierge MVP Approach:
- Manual booking process
- WhatsApp/Kakao for communication
- Google Forms for payment
- Spreadsheet for management
/* 반응형 브레이크포인트 */
/* Mobile: default */
/* Tablet: @media (min-width: 768px) */
/* Desktop: @media (min-width: 912px) */
```
Tech Investment: Phase 1
- After validation
- 500만원 = 2 developer weeks
#### 4-3. 랜딩페이지 생성 원칙
✅ Updated mvp-scope.md
**Do's**:
- ✅ 고객의 Pain Point로 시작
- ✅ 명확한 CTA (Call to Action)
- ✅ 모바일 퍼스트 디자인
- ✅ 스크롤 애니메이션 적용
- ✅ SEO 메타태그 완성
- ✅ 3-5개 핵심 기능만 강조
**Don'ts**:
- ❌ 기능 나열식 설명
- ❌ 전문 용어 남발
- ❌ CTA 없는 섹션
- ❌ 과도한 정보량
---
### 5. 완료 리포트
```
✅ MVP 범위 정의 + 랜딩페이지 생성 완료!
📁 생성된 파일:
- ui/works/mvp-scope.md
- ui/works/landing.html
📊 MVP 요약:
- Phase 0 기능: [N개]
- Phase 1 기능: [N개]
- Phase 2 기능: [N개]
🌐 랜딩페이지:
- 섹션: [N개]
- CTA: [N개]
- 브라우저에서 확인: file:///...landing.html
📝 다음 단계:
**Step 3 - 화면설계서 (/appkit.ui)**
/appkit.ui
**Step 4 - 정책설계서 (/appkit.policy)**
/appkit.policy
**Step 5 - HTML 목업 (/appkit.visualize)**
/appkit.visualize all
📍 현재 위치: Step 2/5 완료
```
---
## Key Principles
## MVP 원칙
### MVP 원칙:
### Do's
- ✅ **Maximize Learning**: 최소 투자로 최대 학습
- ✅ **Ship Fast**: 완벽보다 속도
- ✅ **Core Value Only**: 핵심 가치만 구현
- ✅ **Real Users**: 실제 사용자로 검증
- ✅ **Metrics-Driven**: 감이 아닌 데이터로 결정
1. **Maximize Learning**: 최소 투자로 최대 학습
2. **Ship Fast**: 완벽보다 속도
3. **Core Value Only**: 핵심 가치만 구현
4. **Real Users**: 실제 사용자로 검증
5. **Metrics-Driven**: 감이 아닌 데이터로 결정
### MVP Anti-Patterns:
❌ **Feature Creep**: "이것도 있으면 좋겠는데..."
❌ **Perfectionism**: "조금만 더 다듬고..."
❌ **Assumption**: "사용자는 당연히..."
❌ **Vanity Metrics**: 의미 없는 지표 추적
❌ **Premature Scaling**: 검증 전 확장
### Don'ts
- ❌ **Feature Creep**: "이것도 있으면 좋겠는데..."
- ❌ **Perfectionism**: "조금만 더 다듬고..."
- ❌ **Assumption**: "사용자는 당연히..."
- ❌ **Premature Scaling**: 검증 전 확장
---
## Tips
### 성공적인 MVP를 위해:
1. **Time Box**: 2주를 넘기지 마라
2. **User Cap**: 10-100명으로 시작
3. **Manual First**: 자동화는 나중에
4. **Talk to Users**: 매일 사용자와 대화
5. **Kill Features**: 과감하게 빼라
### MVP 실패 신호:
- 2주 지나도 출시 못함
- 기능이 계속 추가됨
- 사용자 피드백 없음
- 지표 측정 안 함
- "좀 더 완벽하게" 반복
- **Time Box**: 2주를 넘기지 마라
- **User Cap**: 10-100명으로 시작
- **Manual First**: 자동화는 나중에
- **Talk to Users**: 매일 사용자와 대화
- **Kill Features**: 과감하게 빼라
- **Landing First**: 랜딩페이지로 관심도 먼저 검증
---
## Next Steps
## Example
### 이 명령어 실행 후:
```
$ /appkit.mvp
**📍 다음 단계: Step 6 - `/appkit.merge`** (기획 정돈)
- MVP 범위가 정해졌으니 이제 기획 정돈 단계로
- 용어 통일, 기능 중복 제거
- 고객 가치 일관성 확보
🎯 MVP Scope 정의
---
Phase 0 (2주):
✅ 검색 (위치 기반)
✅ 예약 (실시간)
✅ 결제 (간단)
## Version
❌ 제외:
- 리뷰 (Phase 1)
- 커뮤니티 (Phase 2)
- **Version**: 1.0.0
- **Created**: 2025-11-19
- **Philosophy**: "If you're not embarrassed by v1, you launched too late"
검증 목표:
- 주간 10건 예약
- 10명 활성 사용자
✅ mvp-scope.md 생성 완료
✅ landing.html 생성 완료
🌐 랜딩페이지 미리보기:
file:///Users/.../ui/works/landing.html
```

540
.claude/commands/appkit.new.md
View File

@@ -12,469 +12,273 @@ User input **must** be considered (if not empty).
## Overview
The text following `/appkit.new` is the app description. Assume `$ARGUMENTS` is always available in this conversation even if shown as-is. Don't ask again unless the user provides an empty command.
`/appkit.new` 뒤에 오는 텍스트가 앱 설명입니다.
**This is Step 1 of the logical thinking 7-step workflow**:
**논리적 사고 5단계 워크플로우**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?) ← YOU ARE HERE
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?)
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?) ← YOU ARE HERE
2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트)
4. /appkit.policy → 정책설계서 (비즈니스 규칙)
5. /appkit.visualize → 목업 생성 (HTML 프로토타입)
```
Based on the app description, perform the following:
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works`
---
## Execution Flow
### 1. 아이디어 스케치 (고객 중심 대화)
**Input**: User's natural language app description (e.g., "Tennis court booking app with promotions and coupons")
**Input**: 사용자의 자연어 앱 설명
**Step 1: 고객 문제 파악**
1. **무슨 문제를 해결하나?**:
1. **무슨 문제를 해결하나?**
- 현재 고객이 겪는 불편함
- 기존 솔루션의 한계
- 해결되지 않은 니즈
2. **누가 이 문제를 겪나?**:
2. **누가 이 문제를 겪나?**
- 주요 타겟 고객군
- 그들의 특성과 행동 패턴
- 문제의 심각도
**Step 2: 서비스 컨셉 제시**
Present customer-centric summary in this format:
```markdown
## 📋 서비스 컨셉
## 서비스 컨셉
**서비스명**: [추론한 이름 또는 사용자 입력]
### 🎯 핵심 문제와 해결책
### 핵심 문제와 해결책
**고객이 겪는 문제**:
- "테니스 치고 싶은데 코트 예약이 너무 번거로워요"
- "전화로 일일이 확인해야 하고, 대기 시간도 길어요"
- "가격도 제각각이라 비교가 어려워요"
- [구체적인 문제 1]
- [구체적인 문제 2]
**우리의 해결책**:
- 3초 만에 실시간 예약
- 모든 코트 가격 한눈에 비교
- 자동 할인으로 30% 저렴하게
- [해결책 1]
- [해결책 2]
### 👥 타겟 고객
### 타겟 고객
**Primary (핵심 고객)**:
- 30-40대 직장인
- 주말 운동을 원하지만 시간이 없는 사람
- 편의성과 시간 절약을 중시
- [타겟 설명]
**Secondary (보조 고객)**:
- 프리랜서 (시간 유연, 가격 민감)
- 대학생 (저렴한 가격 선호)
- [보조 타겟 설명]
### 💎 핵심 가치 (왜 써야 하나?)
### 핵심 가치 (왜 써야 하나?)
1. **시간 절약**: 15분 대기 → 3초 예약
2. **비용 절감**: 자동 할인으로 평균 30% 저렴
3. **확실한 예약**: 실시간 확인, 즉시 확정
1. **[가치1]**: [설명]
2. **[가치2]**: [설명]
3. **[가치3]**: [설명]
### 🚀 차별점 (경쟁사와 뭐가 다른가?)
### 주요 기능 (고객 가치 중심)
- 기존: 전화 예약, 불확실, 정가
- 우리: 앱 예약, 실시간, 자동 할인
1. **001-[feature]**: [설명]
2. **002-[feature]**: [설명]
3. **003-[feature]**: [설명]
### 📦 주요 기능 (고객 가치 중심)
### 수익 모델
1. **001-search**: 빠른 코트 검색
- 위치 기반 자동 추천
- 실시간 예약 가능 확인
2. **002-booking**: 간편 예약/결제
- 3초 예약 완료
- 원터치 결제
3. **003-discount**: 스마트 할인
- 타임딜 자동 적용
- 쿠폰 자동 추천
4. **004-manage**: 예약 관리
- 예약 변경/취소
- 알림 설정
5. **005-social**: 커뮤니티
- 파트너 찾기
- 리뷰/평점
### 💰 수익 모델
- 예약 수수료 (5-10%)
- 프리미엄 멤버십 (우선 예약권)
- 제휴 광고 (장비, 레슨)
- [수익원 1]
- [수익원 2]
---
이렇게 이해한 것이 맞나요? 수정하거나 추가하고 싶은 내용이 있나요?
특히:
- 핵심 고객이 맞나요?
- 해결하려는 문제가 정확한가요?
- 더 중요한 기능이 있나요?
```
**Step 3: Receive User Feedback**
**Step 3: 사용자 피드백 수신**
Wait for user response:
- "Good", "Yes", "Proceed" → Move to Step 4
- Modification request → Update content and return to Step 2
- Additional features → Add to feature list and return to Step 2
- "좋아", "Yes", "진행해" → Step 4로 이동
- 수정 요청 → 내용 업데이트 후 Step 2로
- 추가 기능 요청 → 기능 목록 추가 후 Step 2로
**Example Dialog**:
```
User: "Lesson booking is important too. And we need instructor rating feature"
**Step 4: 최종 확인**
Claude:
Got it! I'll update as follows:
**Major Feature Specs (Updated)**:
1. 001-user: User authentication and profile management
2. 002-venue: Court information management
3. 003-lesson: Lesson information and instructor management (newly added)
4. 004-booking: Booking and payment system (courts + lessons)
5. 005-promotion: Coupons and promotions
6. 006-review: Facility and instructor reviews/ratings (instructor rating added)
Shall we proceed with this?
```
**Step 4: Final Confirmation**
When user confirms with "Good", "Proceed", etc.:
사용자가 확정하면:
```
✅ App structure confirmed!
✅ 서비스 컨셉 확정!
Creating files now...
파일 생성 중...
```
### 2. Script Execution (After User Confirmation)
Execute only after user confirmation:
**Script**: `.app/scripts/init-app.sh --json --app-name "tymatch"`
**Script Actions**:
- Create `docs/appkit/` directory
- Create `docs/appkit/specs/` directory
- Create subdirectories for each confirmed spec (`001-user/`, `002-venue/`, ...)
- JSON output:
```json
{
"SPECS_DIR": "docs/appkit/specs",
"APP_OVERVIEW": "docs/appkit/overview.md"
}
```
**Important**:
- **No file creation before user confirmation**
- Script only handles directory creation and path output
- Natural language analysis and dialogue handled by Claude
### 3. Service Overview Document Creation
**File**: `docs/appkit/overview.md`
**Content**: Use **user-confirmed content** with customer focus
```markdown
# [Service Name] Service Concept
## 🎯 서비스 본질
[한 문장으로 서비스 정의]
예: "직장인의 주말 운동을 쉽게 만드는 테니스 코트 예약 서비스"
## 🔥 해결하는 문제
[User-confirmed problems]
- 번거로운 전화 예약 (15분 대기)
- 불투명한 가격 정보
- 원하는 시간대 확인 어려움
## 👥 타겟 고객
[User-confirmed target customers]
### Primary Persona
- 김대리 (35세, IT기업)
- Pain: "주말 운동하고 싶은데 예약이 너무 번거로워"
- Want: 빠른 예약, 확실한 시간 확보
### Secondary Personas
- 프리랜서: 평일 낮 저렴한 시간대 활용
- 대학생: 그룹 예약으로 할인 받기
## 💎 핵심 가치 제안
[User-confirmed value propositions]
1. **시간 절약**: 15분 → 3초
2. **비용 절감**: 자동 할인 30%
3. **확실성**: 실시간 확인 & 즉시 확정
## 📦 주요 기능 (고객 가치 중심)
[User-confirmed features with customer value]
- **001-search**: 3초 만에 찾는 완벽한 코트
- **002-booking**: 클릭 한 번으로 예약 완료
- **003-discount**: 자동으로 적용되는 최저가
- **004-manage**: 언제든 변경 가능한 유연함
- **005-social**: 함께 운동할 파트너 찾기
## 🚀 MVP 로드맵
Phase 0 (2주): 핵심 예약 기능
Phase 1 (1개월): 할인 & 리뷰
Phase 2 (3개월): 커뮤니티 & 확장
## 💰 비즈니스 모델
[User-confirmed business model]
- 예약 수수료 (5-10%)
- 프리미엄 멤버십
- 제휴 마케팅
## 📊 성공 지표
- Week 1: 10명 사용자 확보
- Week 2: 10건 예약 달성
- Month 1: NPS 30+ 달성
```
**Important**: Use content presented in Step 2 and confirmed by user **as-is**
### 4. Individual Spec Draft Creation (Based on Overview.md)
Create **initial draft** `spec.md` file in each spec directory based on overview.md content:
**Important**: This creates **first draft**, not empty templates. Extract relevant information from overview.md for each feature.
**Approach**:
1. Read the feature description from overview.md (주요 기능 section)
2. Extract customer value, target user, and workflow hints
3. Create initial draft with inferred content
4. Mark sections that need `/appkit.spec` for further detailing
**File**: `docs/appkit/specs/001-persona/spec.md`
**Content**: Draft with overview-based initial content
```markdown
# Spec: 001-persona
## Feature Name
페르소나 생성 및 관리
## User Value (고객 가치)
[Extract from overview.md's feature description]
- 100가지 다양한 스타일로 브랜드 노출 확대
- 카테고리별 최적화된 인플루언서 확보
## Target User (누가 쓸까?)
[Infer from overview.md's 타겟 고객 section]
- Primary: 서비스 관리자
- Use case: 초기 셋업 시 다양한 페르소나 생성
## User Journey & Screen Flow
[Extract workflow from overview.md's 핵심 워크플로우]
### 1. 페르소나 생성 화면
- **UI Elements**: 카테고리 선택, 개수 설정, 생성 버튼
- **CTA**: "100명 자동 생성" 버튼
- **Next**: 페르소나 목록 화면
### 2. 페르소나 목록 화면
- **UI Elements**: 페르소나 카드 그리드 (이름, 카테고리, 상태)
- **CTA**: 미드저니 프롬프트 export, 프로필 이미지 업로드
- **Next**: 개별 페르소나 상세
## Business Rules
[Extract from overview.md's feature description]
- 카테고리별 페르소나 자동 생성 (Beauty 25명, Fashion 25명, etc.)
- 미드저니용 프롬프트 export 기능
- 프로필 이미지 업로드 시스템
## Edge Cases
[Initial inference - needs /appkit.spec for details]
- 페르소나 생성 실패 시 재시도 로직
- 중복 페르소나 체크
## Dependencies
[Infer from overview.md workflow]
- None (initial setup feature)
---
💡 **더 구체화하려면**:
```
/appkit.spec 001-persona "카테고리별 비율 조정 기능"
/appkit.spec 001-persona "페르소나별 톤앤매너 설정"
```
### 2. 파일 생성 (사용자 확인 후에만)
**디렉토리 생성**:
- `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/`
- `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/specs/`
- 각 기능별 서브디렉토리 (`001-user/`, `002-venue/`, ...)
---
### 3. 서비스 컨셉 문서 생성
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/concept.md`
**Content**:
```markdown
# [서비스명] 서비스 컨셉
## 서비스 본질
[한 문장으로 서비스 정의]
## 해결하는 문제
- [문제 1]
- [문제 2]
## 타겟 고객
### Primary Persona
- [페르소나 설명]
### Secondary Personas
- [보조 페르소나들]
## 핵심 가치 제안
1. **[가치1]**: [설명]
2. **[가치2]**: [설명]
3. **[가치3]**: [설명]
## 주요 기능 (고객 가치 중심)
- **001-[feature]**: [설명]
- **002-[feature]**: [설명]
- **003-[feature]**: [설명]
## 비즈니스 모델
- [수익원 설명]
```
**Content Generation Strategy**:
---
For each spec (001-010), extract from overview.md:
### 4. 개별 Spec 초안 생성
1. **Feature Name**: Use Korean name from 주요 기능 section
2. **User Value**: Extract from 핵심 가치 제안 or feature description
3. **Target User**: Infer from 타겟 고객 (관리자 vs 광고주)
4. **User Journey**: Extract from 핵심 워크플로우 section
5. **Business Rules**: Extract explicit rules from feature description
6. **Edge Cases**: Basic inference (mark as "needs detailing")
7. **Dependencies**: Infer from workflow order
각 기능 디렉토리에 `spec.md` 파일 생성:
**Example Mapping** (from AI Influencer Network overview.md):
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/specs/001-[feature]/spec.md`
```
001-persona →
- Extract: "100명의 다양한 인플루언서 생성"
- User Value: 카테고리별 최적화된 인플루언서 풀 확보
- Journey: 카테고리 선택 → 자동 생성 → 미드저니 export
```markdown
# Spec: 001-[feature]
003-content-composer →
- Extract: "크롤링 요소 조합으로 빠른 제작"
- User Value: 검증된 요소 조합으로 시행착오 최소화
- Journey: 크롤링 갤러리 → 요소 선택 → 나노바나나 생성
## Feature Name
[기능명]
006-brand-site →
- Extract: "광고주가 쉽게 의뢰"
- User Value: 빠른 캠페인 실행, 다양한 타겟층 공략
- Journey: 브랜드 등록 → 카테고리 선택 → 캐릭터 추천
## User Value (고객 가치)
- [가치 1]
- [가치 2]
## Target User (누가 쓸까?)
- Primary: [타겟]
- Use case: [사용 시나리오]
## User Journey & Screen Flow
### 1. [화면명]
- **UI Elements**: [UI 요소들]
- **CTA**: [주요 버튼/액션]
- **Next**: [다음 화면]
## Business Rules
- [규칙 1]
- [규칙 2]
## Edge Cases
- [예외 상황 1]
- [예외 상황 2]
## Dependencies
- [의존성]
---
💡 **더 구체화하려면**: `/appkit.ui`, `/appkit.policy` 실행
```
**Files to Create** (with overview-based drafts):
- `docs/appkit/specs/001-persona/spec.md`
- `docs/appkit/specs/002-reference-crawl/spec.md`
- `docs/appkit/specs/003-content-composer/spec.md`
- `docs/appkit/specs/004-caption-generator/spec.md`
- `docs/appkit/specs/005-approval/spec.md`
- `docs/appkit/specs/006-brand-site/spec.md`
- `docs/appkit/specs/007-ad-content/spec.md`
- `docs/appkit/specs/008-posting/spec.md`
- `docs/appkit/specs/009-engagement/spec.md`
- `docs/appkit/specs/010-analytics/spec.md`
---
### 5. Completion Report
Report to user:
### 5. 완료 리포트
```
✅ 서비스 컨셉 정의 & 기능 초안 생성 완료!
✅ 서비스 컨셉 정의 완료!
📁 생성된 파일:
- docs/appkit/overview.md (서비스 컨셉)
- docs/appkit/specs/001-search/spec.md (검색 - 초안 생성됨 ✨)
- docs/appkit/specs/002-booking/spec.md (예약 - 초안 생성됨 ✨)
- docs/appkit/specs/003-discount/spec.md (할인 - 초안 생성됨 ✨)
- docs/appkit/specs/004-manage/spec.md (관리 - 초안 생성됨 ✨)
- docs/appkit/specs/005-social/spec.md (커뮤니티 - 초안 생성됨 ✨)
- ui/works/concept.md
- ui/works/specs/001-[feature]/spec.md
- ui/works/specs/002-[feature]/spec.md
- ...
✨ 변경사항: 빈 템플릿이 아닌 overview.md 기반 **초안**이 생성되었습니다!
각 spec에는 이미 다음 내용이 포함되어 있습니다:
- User Value (고객 가치)
- Target User (타겟 고객)
- User Journey (기본 화면 흐름)
- Business Rules (핵심 규칙)
- Dependencies (의존성)
📝 다음 단계:
🎯 핵심 가치:
- 시간 절약: 15분 → 3초
- 비용 절감: 30% 자동 할인
- 확실한 예약: 실시간 확정
**Step 2 - MVP 범위 + 랜딩페이지 (/appkit.mvp)**
/appkit.mvp
👥 타겟 고객:
- Primary: 30-40대 직장인
- Secondary: 프리랜서, 대학생
**Step 3 - 화면설계서 (/appkit.ui)**
/appkit.ui
📝 다음 단계 (논리적 사고 흐름):
**Step 4 - 정책설계서 (/appkit.policy)**
/appkit.policy
**Step 2 - 기능 구체화 (/appkit.spec)**
이미 초안이 있으니, 더 구체적인 시나리오를 추가하세요:
/appkit.spec 001-search "위치 기반으로 가까운 코트 찾기, 거리순 정렬"
/appkit.spec 002-booking "퇴근길 지하철에서 3초 예약, 원터치 결제"
/appkit.spec 003-discount "타임딜 자동 적용, 중복 쿠폰 불가"
**Step 5 - HTML 목업 (/appkit.visualize)**
/appkit.visualize all
**Step 3 - 고객 스토리 (/appkit.customer)**
타겟 페르소나의 하루와 문제 해결 스토리:
/appkit.customer
**Step 4 - 세일즈 랜딩 (/appkit.sales)**
광고주를 설득하는 랜딩 페이지:
/appkit.sales
📍 현재 위치: Step 1/7 완료 (아이디어 스케치 + 초안 생성)
📍 다음 단계: Step 2 - /appkit.spec (기능 구체화)
💡 Tip: 각 spec 파일을 열어보세요. 이미 기본 구조가 채워져 있어서
`/appkit.spec`으로 추가 디테일만 넣으면 됩니다!
📍 현재 위치: Step 1/5 완료
```
---
## Important Notes
### 🔴 Mandatory Requirements
### 필수 요구사항
1. **Interactive process required**:
- **Never create files immediately**
- Always present summary in Step 2
- Create files only after user confirmation
1. **인터랙티브 프로세스 필수**:
- 즉시 파일 생성 금지
- Step 2에서 항상 요약 제시
- 사용자 확인 후에만 파일 생성
2. **Handle user feedback**:
- "Good", "Yes", "Proceed" → Proceed with file creation
- Modification request → Update and re-present
- Additional features → Update list and re-present
- If uncertain, ask additional questions
2. **사용자 피드백 처리**:
- "좋아", "Yes", "진행해" → 파일 생성 진행
- 수정 요청 → 업데이트 후 재제시
- 불확실하면 추가 질문
3. **Iterate before confirmation**:
- Repeat Steps 2-3 until user is satisfied
- Don't rush, have thorough dialogue
3. **확인 전 반복**:
- 사용자 만족할 때까지 Step 2-3 반복
### 🟡 Analysis Guidelines
### 분석 가이드라인
1. **Natural language analysis**:
- Carefully analyze user input
- Infer domain and business model
- Derive reasonable major features (5-8)
- Fill gaps with questions
1. **자연어 분석**:
- 사용자 입력 신중히 분석
- 도메인과 비즈니스 모델 추론
- 합리적인 주요 기능 도출 (5-8개)
2. **Numbering system**:
- Use 3-digit numbers (001, 002, 003, ...)
- Sort in logical order (auth → core features → supplementary features)
2. **번호 체계**:
- 3자리 숫자 사용 (001, 002, 003, ...)
- 논리적 순서로 정렬
3. **Feature names**:
- Short and clear (user, venue, booking, promotion)
- Use lowercase English with hyphens
3. **기능명**:
- 짧고 명확하게
- 소문자 영어와 하이픈 사용
### 🟢 Technical Details
1. **Script execution**:
- Execute only after user confirmation
- If script doesn't exist, create directories manually
- Parse JSON output to confirm paths
2. **Incremental detailing**:
- This stage creates **structure only**
- Details added with `/appkit.spec` command
---
## Example Flow
```
User: /appkit.new Tennis court booking app
User: /appkit.new 테니스 코트 예약 앱
Claude: [Presents Step 2 summary]
Claude: [Step 2 요약 제시]
User: Add lesson booking too
User: 레슨 예약도 추가해줘
Claude: [Presents updated summary]
Claude: [업데이트된 요약 제시]
User: Good!
User: 좋아!
Claude: ✅ Confirmed! Creating files...
[Executes file creation]
Claude: ✅ 확정! 파일 생성 중...
[파일 생성 실행]
```

381
.claude/commands/appkit.policy.md Normal file
View File

@@ -0,0 +1,381 @@
---
description: 정책설계서 - 비즈니스 규칙, 과금, 게임플레이 정책 정의
---
## User Input
```text
$ARGUMENTS
```
User input can be empty (전체) or specific policy category (monetization, gameplay, etc.)
## Overview
**논리적 사고 5단계 워크플로우**:
```
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트)
4. /appkit.policy → 정책설계서 (비즈니스 규칙) ← YOU ARE HERE
5. /appkit.visualize → 목업 생성 (HTML 프로토타입)
```
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/policies`
## Purpose
비즈니스 규칙, 과금 정책, 게임플레이 규칙, 콘텐츠 정책 등을 체계적으로 정의합니다.
개발자가 "이 경우엔 어떻게 해야 하지?"라는 질문에 답할 수 있는 명세를 작성합니다.
**정책 코드 체계**:
- `MN`: Monetization (과금/결제)
- `GM`: Gameplay (게임플레이/서비스 규칙)
- `CH`: Character/Content (콘텐츠/캐릭터)
- `PR`: Progression (진행/성장)
- `CR`: Content Rating (콘텐츠 등급)
---
## Pre-requisite
- `/appkit.new`로 서비스 컨셉이 정의되어 있어야 함
- (권장) `/appkit.ui`로 화면설계가 되어 있으면 더 좋음
---
## Usage
```bash
/appkit.policy # 전체 정책 설계
/appkit.policy monetization # 과금 정책만
/appkit.policy gameplay # 게임플레이 정책만
/appkit.policy "예약 취소" # 특정 정책만
```
---
## Execution Flow
### 1. 기존 기획 읽기
Read files from `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/`:
- `concept.md` - 서비스 컨셉
- `router.md` - 화면 구조
### 2. 정책 설계 대화
**Step 1: 정책 카테고리 도출**
```markdown
## 정책 설계 초안
이 서비스에 필요한 정책 카테고리:
| 코드 | 카테고리 | 설명 | 예시 |
|-----|---------|------|------|
| MN | 과금/결제 | 결제, 구독, 포인트 | 채팅권 소모, 구독 혜택 |
| GM | 서비스 규칙 | 핵심 기능 규칙 | 예약 규칙, 취소 정책 |
| CH | 콘텐츠 | 콘텐츠 관련 정책 | 리뷰 작성 규칙, 신고 |
| PR | 진행/성장 | 레벨, 등급 시스템 | 회원 등급, 포인트 적립 |
---
어떤 정책부터 정의할까요?
```
**Step 2: 사용자 피드백**
- "전체", "좋아" → 모든 카테고리 생성
- 특정 카테고리 지정 → 해당 카테고리만 생성
### 3. 생성할 문서들
#### 3-1. 00-policy-index.md (정책 인덱스)
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/policies/00-policy-index.md`
**템플릿**: `.specify/templates/policy-index.md` 참조
```markdown
# 정책 인덱스
> [서비스명] - 정책 문서 목록 및 화면 매핑
---
## 정책 문서 목록
| 코드 | 문서 | 설명 |
|-----|------|------|
| MN | [01-monetization.md](01-monetization.md) | 과금/결제 정책 |
| GM | [02-gameplay.md](02-gameplay.md) | 서비스 규칙 |
| CH | [03-content.md](03-content.md) | 콘텐츠 정책 |
| PR | [04-progression.md](04-progression.md) | 진행/성장 정책 |
---
## 화면별 적용 정책
| 화면 | 경로 | 적용 정책 |
|-----|------|----------|
| 홈 | `/` | GM-001, MN-001 |
| 예약 | `/booking` | GM-002, GM-003, MN-002 |
| 결제 | `/payment` | MN-003, MN-004 |
| 프로필 | `/profile` | PR-001, PR-002 |
---
## 정책별 적용 화면 (역매핑)
### 과금 정책 (MN)
| 정책 ID | 정책명 | 적용 화면 |
|---------|-------|----------|
| MN-001 | [정책명] | [화면 목록] |
| MN-002 | [정책명] | [화면 목록] |
### 서비스 규칙 (GM)
| 정책 ID | 정책명 | 적용 화면 |
|---------|-------|----------|
| GM-001 | [정책명] | [화면 목록] |
| GM-002 | [정책명] | [화면 목록] |
---
## 정책 변경 이력
| 날짜 | 정책 ID | 변경 내용 | 영향 화면 |
|-----|---------|----------|----------|
| YYYY-MM-DD | - | 초기 정책 프레임워크 생성 | 전체 |
---
## 사용법
### UI 문서에서 정책 참조
```markdown
## 화면명
### 적용 정책
- [MN-001] 채팅권 잔액 표시 → 헤더 우측에 배지 형태
- [GM-002] 예약 가능 시간 → 24시간 전까지만 가능
```
### 정책 문서에서 UI 영향 명시
```markdown
## MN-001: 채팅권 잔액 표시
### UI 영향
| 화면 | 위치 | 표시 방식 |
|-----|------|----------|
| 홈 | 헤더 우측 | 💬 127 (배지) |
```
```
#### 3-2. 01-monetization.md (과금 정책)
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/policies/01-monetization.md`
**템플릿**: `.specify/templates/policy-monetization.md` 참조
```markdown
# 과금 정책 (Monetization)
> 코드: `MN` | 결제, 구독, 포인트 관련 정책
---
## MN-001: [정책명]
### 정책 내용
- [정책 설명 1]
- [정책 설명 2]
### UI 영향
| 화면 | 위치 | 표시 방식 | mockup |
|-----|------|----------|--------|
| [화면] | [위치] | [방식] | [파일명].html |
### 표시 규칙
```
[상세 규칙 설명]
```
---
## MN-002: [정책명]
### 정책 내용
- [정책 설명]
### 적용 화면
- `[화면].html` - [용도]
### UI 표시
```
[UI 표시 예시]
```
---
## MN-003: [정책명]
### 정책 내용
| 항목 | 값 | 설명 |
|-----|-----|------|
| [항목1] | [값] | [설명] |
| [항목2] | [값] | [설명] |
### 적용 화면
- `[화면].html`
### UI 구성
```
[ASCII Art UI 예시]
┌─────────────────────────────────────┐
│ [UI 구성 요소] │
│ │
└─────────────────────────────────────┘
```
---
## 관련 mockup
| 정책 | mockup 파일 |
|-----|------------|
| MN-001 | home.html, shop.html |
| MN-002 | payment.html |
| MN-003 | shop.html |
```
#### 3-3. 02-gameplay.md (서비스 규칙)
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/policies/02-gameplay.md`
```markdown
# 서비스 규칙 (Gameplay/Service)
> 코드: `GM` | 핵심 서비스 규칙
---
## GM-001: [규칙명]
### 정책 내용
- [규칙 설명]
### 로직
```
[로직 설명 또는 수도코드]
if (condition) {
action();
}
```
### UI 영향
| 화면 | 영향 |
|-----|------|
| [화면] | [영향 설명] |
---
## GM-002: [규칙명]
### 정책 내용
| 조건 | 결과 | 비고 |
|-----|------|-----|
| [조건1] | [결과] | [비고] |
| [조건2] | [결과] | [비고] |
### 예외 처리
| 상황 | 처리 |
|-----|------|
| [상황1] | [처리 방법] |
| [상황2] | [처리 방법] |
```
---
### 4. 완료 리포트
```
✅ 정책설계서 작성 완료!
📁 생성된 파일:
- policies/00-policy-index.md
- policies/01-monetization.md
- policies/02-gameplay.md
- policies/03-content.md
- policies/04-progression.md
📊 요약:
- 정책 카테고리: N개
- 개별 정책: N개
- 화면 매핑: N개
📝 다음 단계:
**Step 5 - HTML 목업 (/appkit.visualize)**
/appkit.visualize home
/appkit.visualize all
📍 현재 위치: Step 4/5 완료
```
---
## 정책설계 원칙
### Do's
- ✅ **코드 체계**: 정책 ID 일관되게 사용 (MN-001, GM-002)
- ✅ **화면 매핑**: 정책이 어느 화면에 적용되는지 명시
- ✅ **UI 영향**: 정책이 UI에 어떻게 반영되는지 설명
- ✅ **예외 처리**: 모든 예외 상황 정의
- ✅ **mockup 연결**: 관련 HTML 목업 파일 명시
### Don'ts
- ❌ **모호함**: "적절히", "필요시" 같은 표현 지양
- ❌ **누락**: 예외 상황 누락 금지
- ❌ **불일치**: 정책 문서와 UI 문서 간 불일치 금지
---
## Example
```
$ /appkit.policy
📋 정책설계서 작성
정책 카테고리:
- MN: 과금/결제 (5개 정책)
- GM: 서비스 규칙 (8개 정책)
- CH: 콘텐츠 (3개 정책)
- PR: 진행/성장 (4개 정책)
화면-정책 매핑:
- /booking: GM-001, GM-002, MN-001
- /payment: MN-002, MN-003
- /profile: PR-001, PR-002
✅ 00-policy-index.md 생성 완료
✅ 01-monetization.md 생성 완료
✅ 02-gameplay.md 생성 완료
✅ 03-content.md 생성 완료
✅ 04-progression.md 생성 완료
```

399
.claude/commands/appkit.sales.md
View File

@@ -1,399 +0,0 @@
# appkit.sales
**고객을 설득하는 세일즈 랜딩 메시지를 구성하는 명령어**
---
## Overview
**This is Step 4 of the logical thinking 7-step workflow**:
```
논리적 사고 7단계:
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.spec → 기능 구체화 (뭐가 필요할까? 누가 쓸까?)
3. /appkit.customer → 고객 스토리 (고객의 하루, 고민, 해결)
4. /appkit.sales → 세일즈 랜딩 구성 (어떻게 설득할까?) ← YOU ARE HERE
5. /appkit.mvp → MVP 범위 정하기 (최소한으로 검증하려면?)
6. /appkit.merge → 기획 정돈 (흩어진 기획 통합)
7. /appkit.design → 개발 준비 (API, ERD, 기술 스펙)
```
## Purpose
타겟 고객의 문제와 욕구를 기반으로 설득력 있는 세일즈 메시지를 구성합니다.
기능 나열이 아닌, 고객 가치와 변화 스토리로 설득합니다.
**핵심 질문**: "어떻게 고객을 설득할까?"
---
## When to Use
- `/appkit.customer`로 타겟 고객을 정의한 후 (Step 3 완료 후)
- 랜딩 페이지나 마케팅 메시지가 필요할 때
- 투자자나 팀에게 가치 제안을 설명할 때
- MVP 출시 전 메시지 테스트가 필요할 때
---
## Usage
```bash
/appkit.sales
/appkit.sales "time-saving for busy professionals"
/appkit.sales "price-sensitive students"
/appkit.sales "landing: premium positioning"
```
---
## What I'll Do
### 1. 세일즈 프레임워크 선택
**상황별 최적 프레임워크**:
```markdown
## Framework Selection
### PAS (Problem-Agitate-Solution)
✅ Best for: 명확한 문제가 있는 경우
- Problem: 고객이 겪는 문제 공감
- Agitate: 문제를 더 심각하게 느끼게
- Solution: 우리 서비스가 해결책
### AIDA (Attention-Interest-Desire-Action)
✅ Best for: 새로운 카테고리 창출
- Attention: 놀라운 통계나 질문
- Interest: 흥미로운 가능성 제시
- Desire: 갖고 싶게 만들기
- Action: 지금 행동하게 만들기
### StoryBrand
✅ Best for: 복잡한 서비스 설명
- Character: 고객이 주인공
- Problem: 겪고 있는 문제
- Guide: 우리가 안내자
- Plan: 명확한 해결 단계
- Success: 성공 스토리
```
### 2. 랜딩 페이지 구조 (PAS 기준)
```markdown
## Landing Page Structure
### 1️⃣ Hero Section (Hook - 3초 승부)
---
[Headline - 핵심 가치]
"테니스 코트 예약, 이제 3초면 충분합니다"
[Subheadline - 구체적 혜택]
"전화 대기 없이, 실시간 예약, 자동 할인까지"
[CTA Button]
"지금 시작하기 →"
[Hero Image]
스마트폰으로 예약하는 모습
### 2️⃣ Problem Section (공감대 형성)
---
"이런 경험, 해보셨나요?"
❌ 전화 예약하려다 15분 대기
❌ 원하는 시간대는 항상 만석
❌ 가격 비교는 불가능
❌ 취소하려면 또 전화
"매주 테니스 치고 싶은데,
예약이 너무 번거로워 포기하신 적 있으시죠?"
### 3️⃣ Agitation Section (문제 심화)
---
[통계로 문제 심화]
"직장인 73%가 운동 부족"
"운동 포기 이유 1위: 번거로운 예약(42%)"
[감정 자극]
"주말마다 '이번엔 꼭 운동해야지' 다짐하지만,
복잡한 예약 과정에 지쳐 결국 포기하고 있지 않나요?"
### 4️⃣ Solution Section (해결책 제시)
---
"3초 예약 시스템"
[Step 1] 📍 위치 선택
가까운 코트 자동 추천
[Step 2] 📅 시간 선택
실시간 예약 가능 시간 확인
[Step 3] 💳 결제 완료
원터치 결제, 자동 할인 적용
"복잡한 과정은 우리가 해결했습니다"
### 5️⃣ Benefits Section (구체적 혜택)
---
[시간 절약]
⏰ 평균 15분 → 3초
"매주 1시간 절약"
[비용 절감]
💰 자동 할인 적용
"평균 30% 저렴"
[편의성]
📱 언제 어디서나
"지하철에서도 예약 가능"
### 6️⃣ Social Proof Section (신뢰 구축)
---
[숫자로 증명]
"5,000명이 매주 사용 중"
"월 10,000건 예약 처리"
"평균 평점 4.8/5.0"
[고객 후기]
"김OO (37세, 직장인)"
"퇴근길 지하철에서 예약 완료!
주말 운동이 규칙적으로 바뀌었어요"
"박OO (29세, 프리랜서)"
"평일 낮 할인으로 30% 절약!
시간도 자유롭고 가격도 저렴해요"
### 7️⃣ CTA Section (행동 유도)
---
[긴급성 생성]
"🎁 지금 가입하면 첫 예약 30% 할인"
"⏰ 이번 주말 예약 마감 임박"
[3단계 CTA]
1. "무료로 시작하기" (부담 제거)
2. "1분 만에 가입" (간편함 강조)
3. "첫 예약 30% 할인" (즉각 혜택)
[보증]
"예약 수수료 없음"
"언제든 취소 가능"
```
### 3. 가치 제안 캔버스 (Value Proposition Canvas)
```markdown
## Value Proposition
### Customer Jobs (고객이 해결하려는 일)
- 주말 운동 계획
- 건강 관리
- 스트레스 해소
- 사회적 교류
### Pain Relievers (고통 해결)
- 전화 대기 → 즉시 예약
- 불확실성 → 실시간 확인
- 비싼 가격 → 자동 할인
- 복잡한 과정 → 3단계 간소화
### Gain Creators (이익 창출)
- 시간 절약 (주당 1시간)
- 비용 절감 (30% 할인)
- 규칙적 운동 습관
- 운동 仲間 찾기
```
### 4. 메시지 A/B 테스트 제안
```markdown
## A/B Testing Suggestions
### Headline Variations
A: "테니스 코트 예약, 이제 3초면 충분합니다"
B: "매주 테니스 치고 싶다면? 앱으로 3초 예약"
C: "전화 대기는 그만, 실시간 코트 예약"
### CTA Variations
A: "지금 시작하기"
B: "무료로 예약하기"
C: "30% 할인받기"
### Value Prop Variations
A: "시간 절약" 중심
B: "비용 절감" 중심
C: "편의성" 중심
```
### 5. 채널별 메시지 최적화
```markdown
## Channel-Specific Messages
### Instagram Ad (비주얼 중심)
[Image: 테니스 치는 행복한 모습]
"주말 테니스, 3초 예약 ✨"
#테니스 #주말운동 #코트예약
### Google Ads (검색 의도 명확)
"테니스 코트 예약 | 실시간 예약 | 30% 할인"
"전화 대기 없이 바로 예약. 지금 시작하기"
### Email (스토리텔링)
Subject: "김대리님, 이번 주말 테니스 어떠세요?"
"매번 예약 때문에 포기하셨다면..."
[Full story + CTA]
### 카톡 채널 (친근한 톤)
"테니스 예약 때문에 스트레스 받으셨죠? 😅
이제 카톡하듯 쉽게 예약하세요!"
```
---
## Output Files
### 생성될 파일들:
1. **`docs/appkit/sales-landing.md`**
- 전체 랜딩 페이지 구조
- 섹션별 메시지
- CTA 전략
2. **`docs/appkit/value-proposition.md`**
- 핵심 가치 제안
- Pain-Gain 매트릭스
- 차별화 포인트
3. **`docs/appkit/landing-page.html`** (선택사항)
- 실제 HTML 랜딩 페이지
- `.specify/templates/sales-landing-template.html` 템플릿 기반으로 생성
---
## Template Reference
### 랜딩 페이지 HTML 템플릿
랜딩 페이지를 실제 HTML로 만들 때는 아래 템플릿을 참고하세요:
```
.specify/templates/sales-landing-template.html
```
**템플릿 특징**:
- SEO 최적화 (Open Graph, Twitter Card, JSON-LD 구조화 데이터)
- 반응형 디자인 (모바일 우선)
- 모던한 UI/UX (Noto Sans KR 폰트, 부드러운 애니메이션)
- 섹션 구성: Hero → Problem → Solution → Benefits → Social Proof → FAQ → CTA
- CSS 변수 기반 테마 시스템 (Primary: #7C3AED)
**사용법**:
1. 템플릿을 복사하여 새 파일 생성
2. 세일즈 메시지에 맞게 텍스트 수정
3. 브랜드 컬러와 이미지 교체
4. CTA 링크 및 폼 연결
---
## Integration Points
### 다른 명령어와의 연계:
- **From `/appkit.customer`**: 페르소나별 Pain Points
- **From `/appkit.spec`**: 핵심 기능과 혜택
- **To `/appkit.mvp`**: 검증할 핵심 가치
- **To `/appkit.design`**: 사용자 온보딩 플로우
---
## Examples
### Example 1: B2C 서비스
```bash
$ /appkit.sales
📢 Sales Landing Generated
Framework: PAS (Problem-Agitate-Solution)
Hero: "3초 예약 혁명"
Problem: 복잡한 예약 과정
Agitate: 73% 운동 포기
Solution: 원터치 시스템
Proof: 5,000명 사용 중
CTA: "지금 30% 할인"
✅ Generated sales-landing.md
✅ Generated value-proposition.md
```
### Example 2: 특정 페르소나 타겟
```bash
$ /appkit.sales "price-sensitive students"
📢 Student-Focused Message
Hero: "학생 90% 할인"
Problem: 비싼 코트 가격
Solution: 그룹 예약 할인
Proof: "서울대 테니스 동아리 공식 앱"
CTA: "학생증 인증하고 90% 할인"
✅ Updated sales-landing.md
```
---
## Key Principles
### 세일즈 메시지 원칙:
1. **Features ❌ Benefits ✅**: "실시간 예약"이 아닌 "대기 시간 제로"
2. **You, not We**: "당신은" 중심, "우리는" 최소화
3. **Specific Numbers**: "많이"가 아닌 "73%"
4. **Emotional + Rational**: 감정 자극 + 논리적 근거
5. **Clear Next Step**: 모호한 CTA는 전환율 킬러
---
## Tips
### 고전환율 랜딩 페이지:
1. **Above the Fold**: 스크롤 없이 핵심 가치 전달
2. **One Message**: 한 페이지, 하나의 메시지
3. **Social Proof**: 숫자 > 로고 > 후기 순으로 배치
4. **Urgency**: "지금" 행동해야 할 이유
5. **Risk Reversal**: 무료 체험, 환불 보장
### 카피라이팅 공식:
- **Headline**: 혜택 + 숫자 + 시간
- **CTA**: 동사 + 혜택 + 긴급성
- **Testimonial**: 이름 + 나이 + 직업 + 구체적 결과
---
## Next Steps
### 이 명령어 실행 후:
**📍 다음 단계: Step 5 - `/appkit.mvp`** (MVP 범위 정의)
- 세일즈 메시지에서 약속한 핵심 가치만 구현
- 최소한의 기능으로 시장 검증
---
## Version
- **Version**: 1.0.0
- **Created**: 2025-11-19
- **Philosophy**: "Sell the hole, not the drill"

430
.claude/commands/appkit.spec.md
View File

@@ -1,430 +0,0 @@
---
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
```

454
.claude/commands/appkit.ui.md Normal file
View File

@@ -0,0 +1,454 @@
---
description: 화면설계서 - 라우터, 화면 목록, UI 컴포넌트 정의
---
## User Input
```text
$ARGUMENTS
```
User input can be empty (전체) or specific feature/screen name.
## Overview
**논리적 사고 5단계 워크플로우**:
```
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트) ← YOU ARE HERE
4. /appkit.policy → 정책설계서 (비즈니스 규칙)
5. /appkit.visualize → 목업 생성 (HTML 프로토타입)
```
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works`
## Purpose
라우터 구조, 탭 네비게이션, 화면 목록, UI 컴포넌트를 체계적으로 정의합니다.
개발자가 바로 구현할 수 있는 수준의 상세 화면 명세를 작성합니다.
---
## Pre-requisite
- `/appkit.new`로 서비스 컨셉이 정의되어 있어야 함
- `concept.md` 파일이 존재해야 함
---
## Usage
```bash
/appkit.ui # 전체 UI 설계 (router.md + main.md)
/appkit.ui router # 라우터 구조만
/appkit.ui main # 메인 구조만
/appkit.ui "채팅" # 특정 화면 상세
```
---
## Execution Flow
### 1. 기존 기획 읽기
Read files from `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/`:
- `concept.md` - 서비스 컨셉
- `mvp-scope.md` - MVP 범위
### 2. UI 설계 대화
**Step 1: 전체 구조 제시**
```markdown
## UI 설계 초안
### 라우터 구조
```
/ # 기본 탭
├── /[tab1] # 탭1
│ └── /:id # 상세
├── /[tab2] # 탭2
│ └── /:id # 상세
└── /settings # 설정
```
### 탭 구조
| # | 탭 | 아이콘 | 경로 | 뱃지 |
|---|-----|------|-----|------|
| 1 | [탭1] | [아이콘] | `/[경로]` | [조건] |
| 2 | [탭2] | [아이콘] | `/[경로]` | [조건] |
---
이 구조가 맞나요? 수정할 부분이 있나요?
```
**Step 2: 사용자 피드백**
- "좋아", "Yes" → 상세 문서 생성
- 수정 요청 → 업데이트 후 재제시
### 3. 생성할 문서들
#### 3-1. router.md (라우터 & UI 목록)
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/router.md`
**템플릿**: `.specify/templates/ui-router.md` 참조
```markdown
# [서비스명] - Router & UI 목록
## 라우터 구조
```
/ # 기본 = [메인탭]
├── /[tab1] # 탭1 (목록)
│ └── /:id # 상세
├── /[tab2] # 탭2 (목록)
│ └── /:id # 상세
├── /[tab3] # 탭3 (메인 액션)
├── /[tab4] # 탭4
└── /settings # 설정
```
---
## 탭 구조
### 하단 탭바 (Bottom Tab)
| # | 탭 | 아이콘 | 경로 | 뱃지 |
|---|-----|------|-----|------|
| 1 | [탭명] | [아이콘] | `/[경로]` | [조건] |
| 2 | [탭명] | [아이콘] | `/[경로]` | [조건] |
### 탭바 레이아웃
```
┌─────────────────────────────────────────────────┐
│ │
│ [아이콘] [아이콘] [아이콘] [아이콘] [아이콘] │
│ 탭1 탭2 탭3 탭4 탭5 │
└─────────────────────────────────────────────────┘
```
---
## 화면 목록
### 1. [탭명] 탭
| 항목 | 내용 |
|-----|------|
| 경로 | `/[경로]` |
| 탭바 | [탭] (활성) |
| 역할 | [역할 설명] |
#### 컴포넌트
| ID | 유형 | 이름 | 설명 |
|----|-----|-----|------|
| `[id]-header` | Header | 상단 헤더 | [설명] |
| `[id]-list` | List | 목록 | [설명] |
| `[id]-item` | Card | 아이템 | [설명] |
#### 팝업/모달
| ID | 유형 | 트리거 | 설명 |
|----|-----|-------|------|
| `popup-[name]` | Modal | [트리거] | [설명] |
---
### 2. [화면명] 상세
| 항목 | 내용 |
|-----|------|
| 경로 | `/[경로]/:id` |
| 진입 | [어디서] (Push) |
#### 컴포넌트
| ID | 유형 | 이름 | 설명 |
|----|-----|-----|------|
| `detail-header` | Header | 헤더 | [설명] |
| `detail-content` | Display | 컨텐츠 | [설명] |
---
## 전역 컴포넌트
### 상단 헤더 (Global Header)
```
┌─────────────────────────────────────────────────┐
│ [로고] [상태 표시] ⚙️ │
└─────────────────────────────────────────────────┘
```
### 전역 팝업
| ID | 유형 | 트리거 | 설명 |
|----|-----|-------|------|
| `global-network-error` | Modal | 네트워크 오류 | 재시도/취소 |
| `global-session-expired` | Modal | 세션 만료 | 재로그인 |
---
## 네비게이션 플로우
### 기본 플로우
```
[앱 실행]
│
└─→ [메인 탭] (기본)
│
├─→ [액션] → [상세 화면]
│
└─→ [다른 탭으로 이동]
```
---
## URL 스킴
### 딥링크
| 경로 | 설명 |
|-----|------|
| `[scheme]://` | 앱 실행 |
| `[scheme]://[path]` | 특정 화면 |
---
## 요약 통계
| 카테고리 | 개수 |
|---------|-----|
| 탭 화면 | N개 |
| 상세 화면 | N개 |
| 바텀시트 | N개 |
| 팝업/모달 | N개 |
| **총 UI 요소** | **N개** |
```
#### 3-2. main.md (메인 구조)
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/main.md`
**템플릿**: `.specify/templates/ui-main.md` 참조
```markdown
# [서비스명] - 메인 구조
## 화면 개요
| 항목 | 내용 |
|-----|------|
| 서비스명 | [서비스명] |
| UI 컨셉 | [UI 컨셉] |
| 탭 수 | N개 |
| 메인 액션 | [메인 액션 설명] |
---
## 탭 구조
### 탭 비교 (레퍼런스)
| 위치 | [레퍼런스 앱] | [우리 앱] | 역할 |
|-----|--------------|---------|------|
| 1 | [탭] | [탭] | [역할] |
| 2 | [탭] | [탭] | [역할] |
### 탭바 레이아웃
```
┌─────────────────────────────────────────────────┐
│ [각 탭 아이콘과 라벨] │
└─────────────────────────────────────────────────┘
```
---
## 상단 헤더
### 기본 구조
```
┌─────────────────────────────────────────────────┐
│ [로고] [상태 표시] ⚙️ │
└─────────────────────────────────────────────────┘
```
### 헤더 요소
| 요소 | 위치 | 설명 | 액션 |
|-----|-----|------|-----|
| 로고 | 좌측 | [설명] | [액션] |
| [상태] | 우측 | [설명] | [액션] |
| 설정 | 우측 끝 | 설정 아이콘 | 설정 화면 |
---
## 탭별 개요
### 1탭: [탭명]
```
┌─────────────────────────────────────┐
│ [화면 레이아웃 ASCII Art] │
│ │
│ │
├─────────────────────────────────────┤
│ [탭바] │
└─────────────────────────────────────┘
```
**상세 문서:** [해당 문서 링크]
---
## 네비게이션 구조
### 탭 내비게이션 (Bottom Tab)
```
[앱 실행]
│
├─ 탭1
│ └─ 상세 (push)
│
├─ 탭2
│ └─ 상세 (push)
│
└─ 탭3 ← 기본 시작 탭
```
---
## 테마 및 스타일
### 컬러 테마
| 모드 | 배경 | 텍스트 | 포인트 |
|-----|-----|-------|-------|
| 기본 | #[색상] | #[색상] | #[색상] |
| 다크 | #[색상] | #[색상] | #[색상] |
### 탭바 스타일
```css
.tab-bar {
background: #[색상];
height: 56px;
}
```
---
## 데이터 요구사항
### API 명세
```
GET /api/[endpoint]
```
```typescript
interface [Response] {
[field]: [type];
}
```
---
## MVP 구현 범위
### Phase 1 (필수)
- [ ] [항목 1]
- [ ] [항목 2]
### Phase 2
- [ ] [항목 1]
- [ ] [항목 2]
```
---
### 4. 완료 리포트
```
✅ 화면설계서 작성 완료!
📁 생성된 파일:
- ui/works/router.md
- ui/works/main.md
📊 요약:
- 탭 화면: N개
- 상세 화면: N개
- 컴포넌트: N개
📝 다음 단계:
**Step 4 - 정책설계서 (/appkit.policy)**
/appkit.policy
**Step 5 - HTML 목업 (/appkit.visualize)**
/appkit.visualize home
/appkit.visualize all
📍 현재 위치: Step 3/5 완료
```
---
## 화면설계 원칙
### Do's
- ✅ **라우터 명확화**: 모든 화면의 경로와 계층 구조 정의
- ✅ **컴포넌트 ID**: 재사용 가능한 ID 체계 사용
- ✅ **상태 고려**: 각 화면의 Empty, Loading, Error 상태
- ✅ **네비게이션 흐름**: 화면 간 이동 경로 명시
- ✅ **ASCII Art**: 레이아웃을 시각적으로 표현
### Don'ts
- ❌ **경로 누락**: 라우터에 없는 화면 금지
- ❌ **ID 중복**: 컴포넌트 ID 중복 금지
- ❌ **모호한 설명**: "적절히", "필요시" 지양
---
## Example
```
$ /appkit.ui
📱 UI 설계서 작성
라우터 구조:
/
├── /friends
│ └── /:id
├── /chat
│ └── /:id
├── /home (기본)
├── /shop
└── /more
탭 구조:
1. 👩 친구
2. 💬 채팅
3. 🏠 홈 (센터)
4. 🛒 쇼핑
5. ••• 더보기
✅ router.md 생성 완료
✅ main.md 생성 완료
```

484
.claude/commands/appkit.visualize.md Normal file
View File

@@ -0,0 +1,484 @@
---
description: 목업 생성 - HTML 기반 라이브 프로토타입 UI 생성
---
## User Input
```text
$ARGUMENTS
```
User input should be a screen name (e.g., "home", "chat", "booking") or "all" for all screens.
## Overview
**논리적 사고 5단계 워크플로우**:
```
1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?)
2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지
3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트)
4. /appkit.policy → 정책설계서 (비즈니스 규칙)
5. /appkit.visualize → 목업 생성 (HTML 프로토타입) ← YOU ARE HERE
```
**출력 디렉토리**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/mockup`
## Purpose
router.md와 policy 문서를 기반으로 실제 동작하는 HTML 목업을 생성합니다.
브라우저에서 바로 확인할 수 있는 라이브 프로토타입입니다.
---
## Pre-requisite
- `/appkit.ui`로 화면설계가 되어 있어야 함
- `router.md` 파일이 존재해야 함
---
## Usage
```bash
/appkit.visualize home # 홈 화면 목업
/appkit.visualize chat # 채팅 화면 목업
/appkit.visualize all # 전체 화면 목업
/appkit.visualize "예약 상세" # 특정 화면 목업
```
---
## Execution Flow
### 1. 기존 기획 읽기
Read files from `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/`:
- `router.md` - 라우터 및 UI 목록
- `main.md` - 메인 구조
- `policies/*.md` - 정책 문서
### 2. 목업 생성 대화
**Step 1: 화면 확인**
```markdown
## 목업 생성
router.md에서 확인된 화면 목록:
| 화면 | 경로 | 생성 여부 |
|-----|------|----------|
| home | `/` | ⬜ |
| chat-list | `/chat` | ⬜ |
| chat-room | `/chat/:id` | ⬜ |
| shop | `/shop` | ⬜ |
어떤 화면을 생성할까요?
```
**Step 2: 사용자 선택**
- 특정 화면명 → 해당 화면만 생성
- "all", "전체" → 모든 화면 생성
### 3. HTML 목업 파일 생성
#### 3-1. 기본 구조
**File**: `/Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/mockup/[screen].html`
**템플릿**: `.specify/templates/mockup-base.html` 참조
```html
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>[화면명] - [서비스명]</title>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;500;600;700;800&display=swap" rel="stylesheet">
<link rel="stylesheet" href="styles.css">
</head>
<body>
<div class="app">
<!-- Header -->
<header class="header" id="[screen]-header">
<!-- 헤더 컴포넌트 -->
</header>
<!-- Main Content -->
<main class="content" id="[screen]-content">
<!-- 메인 콘텐츠 -->
</main>
<!-- Tab Bar -->
<nav class="tab-bar">
<!-- 탭바 -->
</nav>
</div>
<!-- Overlay -->
<div class="overlay" id="overlay" onclick="closeAll()"></div>
<!-- Modals/Popups -->
<!-- 모달/팝업 -->
<script src="scripts.js"></script>
<script>
// 화면별 스크립트
</script>
</body>
</html>
```
#### 3-2. 공통 스타일시트 (styles.css)
```css
/* Reset & Base */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
:root {
/* Colors */
--bg-primary: #0D0D1A;
--bg-secondary: #1A1A2E;
--bg-card: #252538;
--text-primary: #FFFFFF;
--text-secondary: #9999AA;
--accent-primary: #6C5CE7;
--accent-secondary: #45B7D1;
--accent-pink: #FF6B9D;
--accent-gold: #FFD93D;
--danger: #FF6B6B;
--success: #4ECB71;
/* Sizing */
--header-height: 56px;
--tab-height: 64px;
--safe-area-bottom: env(safe-area-inset-bottom, 0px);
}
body {
font-family: 'Noto Sans KR', sans-serif;
background: var(--bg-primary);
color: var(--text-primary);
min-height: 100vh;
overflow-x: hidden;
}
/* App Container */
.app {
max-width: 430px;
margin: 0 auto;
min-height: 100vh;
position: relative;
background: var(--bg-primary);
}
/* Header */
.header {
position: fixed;
top: 0;
left: 50%;
transform: translateX(-50%);
width: 100%;
max-width: 430px;
background: var(--bg-primary);
padding: 12px 16px;
z-index: 100;
}
/* Tab Bar */
.tab-bar {
position: fixed;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 100%;
max-width: 430px;
background: var(--bg-primary);
display: flex;
justify-content: space-around;
padding: 8px 0;
padding-bottom: calc(8px + var(--safe-area-bottom));
border-top: 1px solid #2D2D3A;
z-index: 100;
}
.tab-item {
display: flex;
flex-direction: column;
align-items: center;
padding: 8px 16px;
color: var(--text-secondary);
text-decoration: none;
position: relative;
}
.tab-item.active {
color: var(--text-primary);
}
.tab-icon {
font-size: 20px;
margin-bottom: 4px;
}
.tab-label {
font-size: 10px;
}
.tab-badge {
position: absolute;
top: 0;
right: 8px;
background: var(--danger);
color: white;
font-size: 10px;
padding: 2px 6px;
border-radius: 10px;
min-width: 16px;
text-align: center;
}
/* Content Area */
.content {
padding-top: var(--header-height);
padding-bottom: calc(var(--tab-height) + var(--safe-area-bottom));
min-height: 100vh;
}
/* Cards */
.card {
background: var(--bg-card);
border-radius: 16px;
padding: 16px;
margin: 12px 16px;
}
/* Buttons */
.btn {
display: inline-flex;
align-items: center;
justify-content: center;
padding: 12px 24px;
border-radius: 12px;
font-weight: 600;
cursor: pointer;
transition: all 0.2s;
border: none;
}
.btn-primary {
background: var(--accent-primary);
color: white;
}
.btn-secondary {
background: var(--bg-card);
color: var(--text-primary);
}
/* Modal */
.modal {
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%) scale(0.9);
background: var(--bg-secondary);
border-radius: 20px;
padding: 24px;
text-align: center;
z-index: 1001;
opacity: 0;
visibility: hidden;
transition: all 0.3s;
max-width: 320px;
width: 90%;
}
.modal.active {
opacity: 1;
visibility: visible;
transform: translate(-50%, -50%) scale(1);
}
/* Overlay */
.overlay {
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
background: rgba(0,0,0,0.7);
z-index: 1000;
opacity: 0;
visibility: hidden;
transition: all 0.3s;
}
.overlay.active {
opacity: 1;
visibility: visible;
}
/* Toast */
.toast {
position: fixed;
bottom: calc(var(--tab-height) + 20px + var(--safe-area-bottom));
left: 50%;
transform: translateX(-50%) translateY(100px);
background: var(--bg-card);
padding: 12px 24px;
border-radius: 12px;
opacity: 0;
transition: all 0.3s;
z-index: 1002;
}
.toast.active {
opacity: 1;
transform: translateX(-50%) translateY(0);
}
```
#### 3-3. 공통 스크립트 (scripts.js)
```javascript
// Modal Functions
function showModal(id) {
document.getElementById('overlay').classList.add('active');
document.getElementById(id).classList.add('active');
}
function closeAll() {
document.getElementById('overlay').classList.remove('active');
document.querySelectorAll('.modal, .bottom-sheet').forEach(el => {
el.classList.remove('active');
});
}
// Toast Function
function showToast(message, duration = 2000) {
const toast = document.getElementById('toast');
if (toast) {
toast.textContent = message;
toast.classList.add('active');
setTimeout(() => {
toast.classList.remove('active');
}, duration);
}
}
// Tab Badge Update
function updateBadge(tabId, count) {
const badge = document.querySelector(`#${tabId} .tab-badge`);
if (badge) {
badge.textContent = count;
badge.style.display = count > 0 ? 'block' : 'none';
}
}
```
---
### 4. 화면별 목업 생성
각 화면에 대해 router.md의 컴포넌트 정보를 기반으로 HTML 생성:
1. **헤더 영역**: `[screen]-header` 컴포넌트들
2. **메인 콘텐츠**: `[screen]-content` 내 컴포넌트들
3. **탭바**: 전역 탭바 (현재 탭 active 표시)
4. **팝업/모달**: `popup-*`, `bs-*` 컴포넌트들
### 5. 완료 리포트
```
✅ 목업 생성 완료!
📁 생성된 파일:
- mockup/home.html
- mockup/chat.html
- mockup/styles.css
- mockup/scripts.js
🌐 브라우저에서 확인:
file:///Users/.../ui/works/mockup/home.html
📊 생성 요약:
- HTML 파일: N개
- 컴포넌트: N개
- 모달/팝업: N개
📝 참고:
- 각 화면은 상호 링크되어 있습니다
- 팝업은 JavaScript로 동작합니다
- 정책 문서와 연결된 UI 요소에는 정책 ID 주석이 포함되어 있습니다
📍 현재 위치: Step 5/5 완료!
```
---
## 목업 생성 원칙
### Do's
- ✅ **router.md 기반**: 모든 컴포넌트 ID와 구조 준수
- ✅ **정책 연결**: UI에 적용되는 정책 ID 주석 추가
- ✅ **상호 링크**: 화면 간 네비게이션 동작
- ✅ **상태 표시**: Empty, Loading, Error 상태 시뮬레이션
- ✅ **반응형**: 모바일 퍼스트 (max-width: 430px)
### Don'ts
- ❌ **과도한 디자인**: 와이어프레임 수준 유지
- ❌ **하드코딩**: 데이터는 의미있는 샘플로
- ❌ **누락**: router.md에 정의된 컴포넌트 누락 금지
---
## 정책 연결 주석 예시
```html
<!-- [MN-001] 채팅권 잔액 표시 -->
<div class="token-badge">
<span>💬</span>
<span>127</span>
</div>
<!-- [GM-002] 예약 가능 시간: 24시간 전까지만 -->
<button class="btn-primary" disabled>
예약 마감
</button>
```
---
## Example
```
$ /appkit.visualize home
🎨 목업 생성: home
router.md에서 컴포넌트 확인:
- home-header (Header)
- home-stats (Card)
- home-quick-status (Display)
- tab-bar (TabBar)
- popup-new-message (Modal)
- popup-life-stage (Modal)
정책 적용:
- [MN-001] 채팅권 잔액 표시 → header
- [GM-001] 모드 전환 → header
✅ home.html 생성 완료
✅ styles.css 업데이트
✅ scripts.js 업데이트
🌐 file:///Users/.../ui/works/mockup/home.html
```