@restnfeel/agentc-starter-kit/docs/task-master-guide.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# Task Master 워크플로우 가이드

AgentC Starter Kit과 Task Master를 결합한 체계적인 웹사이트 개발 가이드

## 📋 목차

- [Task Master 소개](#task-master-소개)
- [초기 설정](#초기-설정)
- [PRD 기반 프로젝트 생성](#prd-기반-프로젝트-생성)
- [개발 워크플로우](#개발-워크플로우)
- [고급 기능](#고급-기능)
- [베스트 프랙티스](#베스트-프랙티스)
- [문제 해결](#문제-해결)

## 🎯 Task Master 소개

Task Master는 AI 기반 프로젝트 관리 시스템으로, PRD(Product Requirements Document)를 분석하여 체계적인 개발 태스크를 생성하고 관리합니다.

### 핵심 장점

1. **AI 기반 태스크 생성**: PRD를 분석하여 자동으로 구조화된 태스크 생성
2. **복잡도 분석**: 각 태스크의 난이도를 분석하여 적절한 분해 제안
3. **의존성 관리**: 태스크 간 의존성을 자동으로 관리
4. **실시간 진행 추적**: 프로젝트 진행률을 실시간으로 모니터링
5. **변경사항 반영**: 요구사항 변경 시 관련 태스크 자동 업데이트

## 🚀 초기 설정

### 1. Task Master 설치

```bash
# 전역 설치 (권장)
npm install -g task-master-ai

# 또는 프로젝트별 설치
npm install task-master-ai
npx task-master-ai --version
```

### 2. 프로젝트 초기화

```bash
# 새 프로젝트 디렉토리 생성
mkdir customer-website
cd customer-website

# Task Master 초기화
task-master init --name="Customer Website" --description="고객사 웹사이트 프로젝트" --yes
```

### 3. 프로젝트 환경 설정

```bash
# Next.js 프로젝트 생성
npx create-next-app@latest customer-website --typescript --tailwind --app
cd customer-website

# AgentC 모듈 설치
npm install @restnfeel/agentc-starter-kit
npm install @supabase/supabase-js prisma @prisma/client

# 환경 변수 설정
cp .env.example .env.local
# .env.local 파일에 Supabase 정보 입력
```

### 4. Supabase 프로젝트 설정

1. **Supabase 콘솔에서 새 프로젝트 생성**

   - [Supabase Dashboard](https://supabase.com/dashboard) 접속
   - "New Project" 클릭
   - 프로젝트 이름, 데이터베이스 비밀번호 설정
   - 리전 선택 (Asia Pacific - Seoul 권장)

2. **프로젝트 정보 복사**

   - Settings > API에서 URL과 anon key 복사
   - Settings > Database에서 Connection string 복사

3. **환경 변수 설정** (`.env.local`)

   ```env
   DATABASE_URL="postgresql://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:5432/postgres"
   SUPABASE_URL="https://[PROJECT-REF].supabase.co"
   SUPABASE_ANON_KEY="your-supabase-anon-key"
   NEXTAUTH_SECRET="your-nextauth-secret"
   ```

4. **데이터베이스 스키마 적용**
   ```bash
   # Prisma 스키마를 Supabase에 적용
   npx prisma db push
   npx prisma generate
   ```

### 5. AI 모델 설정

```bash
# 대화형 설정 (권장)
task-master models --setup

# 또는 빠른 설정
task-master models --set-main="anthropic/claude-3-5-sonnet-20241022" \
                   --set-research="anthropic/claude-3-5-sonnet-20241022" \
                   --set-fallback="openai/gpt-4o"
```

### 6. 환경 변수 설정

**.env 파일 생성:**

```env
# AI 모델 API 키 (사용하는 것만 설정)
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
PERPLEXITY_API_KEY=your_perplexity_key

# 기타 설정
LOG_LEVEL=info
```

## 📝 PRD 기반 프로젝트 생성

### 1. PRD 문서 작성

**scripts/prd.txt 생성:**

```text
# [프로젝트명] 웹사이트

## 프로젝트 개요
- 회사명: [회사명]
- 업종: [업종]
- 웹사이트 유형: [비즈니스/이커머스/포트폴리오/블로그]
- 주요 목표: [프로젝트의 핵심 목표]

## 타겟 사용자
- 주요 타겟: [주요 사용자층]
- 사용자 페르소나: [구체적인 사용자 특성]

## 페이지 구성
### 홈페이지
- Hero Section: [메인 메시지]
- About Section: [회사/서비스 소개]
- Features/Services: [주요 서비스나 특징]
- Portfolio/Case Studies: [실적이나 사례]
- Testimonials: [고객 후기]
- Contact Section: [연락처 및 CTA]

### 추가 페이지
- [필요한 추가 페이지들 나열]

## 기능 요구사항
### 필수 기능
- [반드시 구현해야 할 기능들]

### 선택 기능
- [우선순위가 낮은 기능들]

## 기술 스택
- 프레임워크: Next.js 14 + TypeScript
- 스타일링: Tailwind CSS
- 기반 시스템: AgentC Starter Kit
- 추가 기술: [필요한 추가 기술스택]

## 디자인 요구사항
### 브랜딩
- 주요 컬러: [브랜드 컬러]
- 폰트: [선호하는 폰트 스타일]
- 톤앤매너: [브랜드 톤앤매너]

### UI/UX
- 디자인 스타일: [모던/클래식/미니멀 등]
- 반응형 디자인: 필수
- 접근성: [접근성 요구사항]

## 성능 요구사항
- 페이지 로딩 속도: LCP < 2.5초
- SEO 최적화: 필수
- 모바일 최적화: 필수

## 특별 요구사항
- [고객별 특수 요구사항]
- [통합이 필요한 서드파티 서비스]
- [규정 준수 요구사항]

## 출시 일정
- 개발 기간: [예상 개발 기간]
- 주요 마일스톤: [중요한 일정들]
```

### 2. 태스크 생성

```bash
# PRD 파싱하여 태스크 생성
task-master parse-prd scripts/prd.txt --num-tasks=12 --research

# 생성된 태스크 확인
task-master list
```

### 3. 복잡도 분석

```bash
# 태스크 복잡도 분석
task-master analyze-complexity --research --threshold=6

# 분석 결과 확인
task-master complexity-report
```

## 🔄 개발 워크플로우

### 1. 작업 시작 패턴

```bash
# 현재 상황 확인
task-master list

# 다음 작업할 태스크 확인
task-master next

# 특정 태스크 상세 정보
task-master show <task-id>
```

### 2. 태스크 분해

```bash
# 복잡한 태스크 분해 (복잡도 6 이상)
task-master expand --id=1 --research --force

# 모든 태스크 일괄 분해
task-master expand --all --research --num=5
```

### 3. 개발 진행

```bash
# 작업 시작
task-master set-status --id=1.1 --status=in-progress

# [실제 구현 작업]

# 진행상황 업데이트
task-master update-subtask --id=1.1 --prompt="구현 진행상황:
- [완료된 작업들]
- [발견한 이슈들]
- [다음 단계 계획]"

# 작업 완료
task-master set-status --id=1.1 --status=done
```

### 4. 변경사항 관리

```bash
# 새 요구사항 추가
task-master add-task --prompt="[새로운 요구사항 설명]" --research --priority=high

# 기존 태스크 업데이트
task-master update-task --id=5 --prompt="[변경사항 설명]" --research

# 여러 태스크 일괄 업데이트
task-master update --from=8 --prompt="[전반적인 변경사항]" --research
```

## 🚀 고급 기능

### 1. 의존성 관리

```bash
# 의존성 추가
task-master add-dependency --id=5 --depends-on=3

# 의존성 제거
task-master remove-dependency --id=5 --depends-on=3

# 의존성 검증
task-master validate-dependencies

# 의존성 문제 자동 수정
task-master fix-dependencies
```

### 2. 태스크 조작

```bash
# 태스크 이동
task-master move-task --from=5 --to=3

# 서브태스크를 독립 태스크로 변환
task-master remove-subtask --id=3.2 --convert

# 기존 태스크를 서브태스크로 변환
task-master add-subtask --parent=3 --task-id=8

# 서브태스크 일괄 삭제
task-master clear-subtasks --id=3
```

### 3. 파일 관리

```bash
# 개별 태스크 파일 생성
task-master generate

# 커스텀 출력 디렉토리
task-master generate --output=./custom-tasks/
```

## 💡 베스트 프랙티스

### 1. PRD 작성 요령

- **구체적인 요구사항**: 모호한 표현보다는 구체적인 기능 명세
- **우선순위 명시**: 필수/선택 기능을 명확히 구분
- **기술적 제약사항**: 특정 기술이나 서비스 사용 요구사항 명시
- **성능 기준**: 구체적인 성능 목표 설정

### 2. 태스크 관리 전략

- **적절한 태스크 수**: 10-15개 메인 태스크가 적절
- **복잡도 임계값**: 6 이상에서 태스크 분해 고려
- **정기적인 업데이트**: 구현 중 발견사항을 즉시 기록
- **의존성 설정**: 순서가 중요한 작업은 의존성 명시

### 3. AI 모델 활용

- **Research 모드**: 복잡한 기능이나 새로운 기술 도입 시 활용
- **적절한 모델 선택**:
  - Main: 일반적인 태스크 생성/업데이트
  - Research: 심화 분석이 필요한 작업
  - Fallback: 메인 모델 실패 시 대안

### 4. 워크플로우 패턴

```bash
# 매일 작업 시작 시
task-master next                    # 다음 작업 확인
task-master show <id>              # 작업 상세 확인

# 구현 중
task-master update-subtask --id=<id> --prompt="진행상황"

# 작업 완료 시
task-master set-status --id=<id> --status=done
task-master next                    # 다음 작업 확인
```

## 🔧 문제 해결

### 1. 일반적인 문제

**Task Master 명령어가 작동하지 않을 때:**

```bash
# 설치 확인
npm list -g task-master-ai

# 재설치
npm uninstall -g task-master-ai
npm install -g task-master-ai

# 권한 문제 (macOS/Linux)
sudo npm install -g task-master-ai
```

**AI 모델 호출 실패:**

```bash
# API 키 확인
cat .env | grep API_KEY

# 모델 설정 확인
task-master models

# 다른 모델로 변경
task-master models --set-main="openai/gpt-4o"
```

### 2. 태스크 관련 문제

**태스크가 너무 많이 생성됨:**

```bash
# 태스크 제거
task-master remove-task --id=<id> --yes

# 새로 생성 (더 적은 수로)
task-master parse-prd scripts/prd.txt --num-tasks=8
```

**의존성 순환 오류:**

```bash
# 의존성 검증 및 수정
task-master validate-dependencies
task-master fix-dependencies
```

### 3. 성능 최적화

**응답 속도 개선:**

```bash
# 로그 레벨 조정
echo "LOG_LEVEL=error" >> .env

# 간단한 모델 사용
task-master models --set-main="openai/gpt-4o-mini"
```

## 📚 추가 자료

- [AgentC Starter Kit 문서](../README.md)
- [AI 빠른 구현 가이드](ai-quick-reference.md)
- [구현 예제 모음](examples.md)
- [API 레퍼런스](api-reference.md)

## 🤝 지원

문제가 발생하거나 개선사항이 있다면:

- GitHub Issues: [프로젝트 저장소]
- 이메일: support@agentc.dev
- Discord: [커뮤니티 링크]

---

_이 가이드를 통해 Task Master와 AgentC Starter Kit을 효과적으로 활용하여 고품질 웹사이트를 빠르게 구현할 수 있습니다._