appkit/.claude/commands/appkit.merge.md

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

/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. 용어 통일성

## 용어 충돌 발견

❌ **Spec에서**: "페르소나 설정"
❌ **Customer에서**: "캐릭터 프로필"
❌ **MVP에서**: "인물 정보"

✅ **통일 제안**:
→ 표준 용어: "페르소나"
→ 모든 문서에 일관되게 적용

B. 기능 중복 확인

## 중복 기능 발견

❌ **001-persona/spec.md**:
- 이미지 생성 기능 언급

❌ **002-content/spec.md**:
- 이미지 생성 기능 중복 설명

✅ **통합 제안**:
→ 002-content에서 통합 관리
→ 001-persona는 002-content 참조

C. 고객 가치 일관성

## 가치 제안 충돌

❌ **Spec**: "100명 자동 관리"
❌ **Customer**: "15시간 → 1시간 시간 절약"
❌ **Sales**: "월 1억 수익"

✅ **핵심 가치 통일**:
→ Primary Value: "시간 절약 (15시간 → 1시간)"
→ Secondary Value: "확장성 (100명 관리)"
→ Ultimate Goal: "월 1억 수익 달성"

3. MVP 범위 기반 우선순위 조정

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

# 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

# 고객 여정 - 기능 매핑

*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. 충돌 해결

충돌 패턴 식별:

## 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: 기본 통합

$ /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: 특정 영역 집중

$ /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는 맥락을 놓친다. 사람이 통합하라."