aiwf/docs/EXAMPLES.ko.md

AI Workflow Framework for Claude Code with multi-language support (Korean/English)

# AIWF 실제 사용 예제 및 활용 사례

이 문서는 다양한 개발 시나리오에서 AIWF 프레임워크를 활용하는 방법을 보여주는 실용적인 예제와 활용 사례를 제공합니다.

[한국어](EXAMPLES.ko.md) | [English](EXAMPLES.md)

## 목차

1. [새 프로젝트 시작하기](#새-프로젝트-시작하기)
2. [기능 개발 워크플로](#기능-개발-워크플로)
3. [팀 협업 시나리오](#팀-협업-시나리오)
4. [성능 최적화](#성능-최적화)
5. [대규모 코드베이스 관리](#대규모-코드베이스-관리)
6. [CI/CD 통합](#cicd-통합)
7. [다국어 프로젝트](#다국어-프로젝트)
8. [긴급 디버깅](#긴급-디버깅)

---

## 새 프로젝트 시작하기

### 시나리오: 이커머스 플랫폼 개발

Claude Code로 새로운 이커머스 플랫폼 프로젝트를 시작합니다.

#### 1단계: 프로젝트 초기화

```bash
# 프로젝트 디렉토리 생성
mkdir my-ecommerce
cd my-ecommerce

# AIWF 설치
aiwf install

# AIWF로 프로젝트 초기화
/project:aiwf:initialize
```

#### 2단계: 프로젝트 비전 정의

```bash
/project:aiwf:aiwf_create_prd "이커머스 플랫폼" "AI 기반 추천 시스템을 갖춘 현대적인 이커머스 솔루션"
```

#### 3단계: 첫 마일스톤 계획

```bash
/project:aiwf:aiwf_create_milestone_plan "MVP 핵심 기능"
```

**Claude Code가 다음을 정의해줍니다:**
- 사용자 인증 시스템
- 상품 카탈로그
- 장바구니
- 주문 관리
- 결제 통합

#### 4단계: 스프린트 생성

```bash
/project:aiwf:create_sprints_from_milestone M01
```

**결과:** 3개의 스프린트 생성
- S01: 인증 및 사용자 관리
- S02: 상품 카탈로그 및 검색
- S03: 장바구니 및 결제

#### 5단계: 개발 시작

```bash
# 시스템 설계를 위해 아키텍트 페르소나로 전환
/project:aiwf:ai_persona:architect

# 전체 아키텍처 설계
"이커머스 플랫폼의 전체 아키텍처를 설계해주세요"

# 인증을 위한 기능 생성
/project:aiwf:aiwf_create_general_task "사용자 인증 시스템"
# 반환: FL001

# Git 브랜치 생성
git checkout -b feature/FL001-user-authentication

# 적절한 페르소나로 코딩 시작
/project:aiwf:ai_persona:developer
```

---

## 기능 개발 워크플로

### 시나리오: 실시간 알림 구현

#### 1단계: 기능 항목 생성

```bash
/project:aiwf:aiwf_create_general_task "실시간 알림 시스템"
# 반환: FL002

# 상세한 기능 명세 생성
/project:aiwf:feature_spec FL002
```

#### 2단계: 설계 단계

```bash
# 아키텍트 페르소나 사용
/project:aiwf:ai_persona:architect

"WebSocket을 사용한 확장 가능한 실시간 알림 시스템을 설계해주세요"
```

#### 3단계: 구현

```bash
# 기능 브랜치 생성
git checkout -b feature/FL002-realtime-notifications

# 균형 잡힌 컨텍스트 압축으로 구현
/project:aiwf:compress_context:balanced

# 구현 시작
"알림을 위한 WebSocket 서버를 구현해주세요"
```

#### 4단계: 테스트 및 디버깅

```bash
# 디버거 페르소나로 전환
/project:aiwf:ai_persona:debugger

"WebSocket 구현에서 연결이 끊어지는 문제를 디버깅해주세요"

# 테스트 실행
npm test

# 테스트 태스크 생성
/project:aiwf:create_task "알림 시스템을 위한 통합 테스트 작성"
```

#### 5단계: 코드 리뷰

```bash
# 리뷰어 페르소나로 전환
/project:aiwf:ai_persona:reviewer

"알림 시스템 구현의 보안성과 성능을 검토해주세요"

# 리뷰 피드백 반영
/project:aiwf:do_task T15_S02
```

#### 6단계: 문서화

```bash
# 문서 작성자 페르소나로 전환
/project:aiwf:ai_persona:documenter

"알림 엔드포인트를 위한 API 문서를 작성해주세요"

# 기능 변경 로그 생성
# Feature changelog 명령어가 제거됨 - 대신 aiwf_project_review 사용
```

#### 7단계: 기능 완료

```bash
# 기능 참조와 함께 커밋
git add .
git commit -m "feat(FL002): 실시간 알림 시스템 구현"

# Pull Request 생성
gh pr create --title "[FL002] 실시간 알림 시스템" \
  --body "WebSocket 기반 실시간 알림 구현"

# 기능 상태 업데이트
# Feature status 명령어가 제거됨 - 대신 aiwf_smart_complete 사용
```

---

## 팀 협업 시나리오

### 시나리오: 마이크로서비스를 작업하는 분산 팀

#### 팀 워크플로 설정

```bash
# 팀 리더가 프로젝트 구조 생성
/project:aiwf:initialize

# CLAUDE.md에 팀 규칙 정의
cat > CLAUDE.md << 'EOF'
# 팀 규칙

## 커밋 메시지 형식
- feat(FLXXX): 새로운 기능
- fix(FLXXX): 버그 수정
- docs(FLXXX): 문서
- test(FLXXX): 테스트
- refactor(FLXXX): 코드 리팩토링

## 코드 리뷰 프로세스
1. 모든 PR은 2명의 승인 필요
2. CI/CD 파이프라인 통과 필수
3. 테스트 포함 필수
4. 문서 업데이트 필수

## 페르소나 사용법
- 아키텍트: 시스템 설계 결정
- 개발자: 구현
- 리뷰어: PR 검토
- 문서 작성자: API 문서
EOF
```

#### 병렬 개발

**개발자 A: 인증 서비스**
```bash
# 기능 생성
/project:aiwf:aiwf_create_general_task "인증 마이크로서비스"
# FL003

# 인증 서비스 작업
cd services/auth
/project:aiwf:ai_persona:developer
git checkout -b feature/FL003-auth-service
```

**개발자 B: 상품 서비스**
```bash
# 기능 생성
/project:aiwf:aiwf_create_general_task "상품 카탈로그 마이크로서비스"
# FL004

# 상품 서비스 작업
cd services/products
/project:aiwf:ai_persona:developer
git checkout -b feature/FL004-product-service
```

#### 일일 동기화

```bash
# 팀 상태 리포트 생성
/project:aiwf:team_status_report

# 모든 활성 기능 확인
/project:aiwf:list_features --status=in_progress

# 스프린트 진행 상황 검토
/project:aiwf:sprint_status S02
```

#### 코드 리뷰 프로세스

```bash
# 리뷰어가 페르소나 전환
/project:aiwf:ai_persona:reviewer

# 특정 PR 검토
gh pr checkout 42
/project:aiwf:code_review --pr=42

# 리뷰 댓글 추가
gh pr review 42 --comment -b "인증 실패에 대한 오류 처리를 추가해주세요"
```

---

## 성능 최적화

### 시나리오: 느린 API 엔드포인트 최적화

#### 1단계: 성능 프로파일링

```bash
# 최적화 페르소나로 전환
/project:aiwf:ai_persona:optimizer

# 성능 태스크 생성
/project:aiwf:create_task "/api/search 엔드포인트 성능 최적화"
```

#### 2단계: 현재 성능 벤치마크

```javascript
// benchmark-search.js
import { PerformanceBenchmark } from '@aiwf/performance';

const benchmark = new PerformanceBenchmark({
  iterations: 100,
  memoryProfiling: true
});

const searchBenchmark = {
  name: '검색 API 벤치마크',
  tests: [{
    name: '복합 검색 쿼리',
    fn: async () => {
      await fetch('/api/search?q=laptop&filters=price:100-1000');
    }
  }]
};

const baseline = await benchmark.run(searchBenchmark);
await benchmark.saveReport('./baseline-performance.json');
```

#### 3단계: 메모리 프로파일러로 분석

```javascript
// memory-analysis.js
import { MemoryProfiler } from '@aiwf/memory';

const profiler = new MemoryProfiler({
  heapThreshold: 100 * 1024 * 1024 // 100MB
});

profiler.startProfiling();

// 검색 작업 실행
for (let i = 0; i < 1000; i++) {
  await performSearch('테스트 쿼리');
}

const report = profiler.generateReport();
const suggestions = profiler.getOptimizationSuggestions();

console.log('메모리 최적화 제안:', suggestions);
```

#### 4단계: 최적화 구현

```bash
# 최적화 페르소나로 제안 받기
"이 검색 구현을 분석하고 최적화 방안을 제안해주세요"

# 캐싱 구현
/project:aiwf:implement_caching search-results
```

#### 5단계: 개선 사항 검증

```javascript
// 성능 비교
const optimized = await benchmark.run(searchBenchmark);
const regression = benchmark.detectPerformanceRegression(optimized, baseline);

if (regression.hasRegression) {
  console.error('성능 저하 감지!');
} else {
  console.log(`성능이 ${regression.improvement}% 향상되었습니다`);
}
```

---

## 대규모 코드베이스 관리

### 시나리오: 10만 라인 이상의 레거시 시스템 작업

#### 1단계: 초기 분석

```bash
# 개요를 위한 적극적 압축 사용
/project:aiwf:compress_context:aggressive

# 프로젝트 구조 파악
"이 코드베이스의 전체 아키텍처를 분석해주세요"
```

#### 2단계: 현대화 계획 수립

```bash
# 현대화를 위한 마일스톤 생성
/project:aiwf:aiwf_create_milestone_plan "레거시 시스템 현대화"

# 기능별로 세분화
/project:aiwf:aiwf_create_general_task "데이터베이스 마이그레이션"      # T001
/project:aiwf:aiwf_create_general_task "API 현대화"                 # T002
/project:aiwf:aiwf_create_general_task "프론트엔드 리팩토링"          # T003
```

#### 3단계: 점진적 리팩토링

```bash
# 특정 모듈에 균형 잡힌 압축 사용
/project:aiwf:compress_context:balanced

# 한 번에 하나의 모듈에 집중
"사용자 관리 모듈을 현대적인 패턴으로 리팩토링해주세요"
```

#### 4단계: 진행 상황 추적

```javascript
// progress-tracker.js
import { FeatureLedger } from '@aiwf/features';

const ledger = new FeatureLedger();
await ledger.init();

// 현대화 리포트 생성
const features = await ledger.searchFeatures({
  tags: ['modernization'],
  dateRange: {
    start: '2024-01-01',
    end: '2024-12-31'
  }
});

features.forEach(feature => {
  console.log(`${feature.id}: ${feature.name} - ${feature.progress}%`);
});
```

---

## CI/CD 통합

### 시나리오: 자동화된 품질 게이트

#### 1단계: GitHub Actions 설정

```yaml
# .github/workflows/aiwf-quality.yml
name: AIWF 품질 검사

on:
  pull_request:
    branches: [ main ]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Node.js 설정
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    
    - name: AIWF 설치
      run: |
        npm install -g aiwf
        aiwf install --ci
    
    - name: 성능 벤치마크 실행
      run: |
        node scripts/run-benchmarks.js
        
    - name: 기능 완료 상태 확인
      run: |
        aiwf check-feature-status ${{ github.event.pull_request.title }}
        
    - name: 리포트 생성
      run: |
        aiwf generate-ci-report
        
    - name: PR에 댓글 달기
      uses: actions/github-script@v6
      with:
        script: |
          const report = require('./aiwf-ci-report.json');
          github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: `## AIWF 품질 리포트\n\n${report.summary}`
          });
```

#### 2단계: Pre-commit 훅

```bash
# 훅 설치
/project:aiwf:install_git_hooks

# 커스텀 pre-commit 훅
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash

# 기능 참조 확인
feature_id=$(git diff --cached --name-only | xargs grep -l "FL[0-9]\{3\}" | head -1)

if [ -z "$feature_id" ]; then
  echo "경고: 변경사항에서 기능 참조를 찾을 수 없습니다"
  echo "코드나 커밋 메시지에 기능 ID (FLXXX)를 추가하세요"
fi

# 빠른 테스트 실행
npm run test:quick

# 코드 품질 검사
aiwf code-quality-check
EOF

chmod +x .git/hooks/pre-commit
```

---

## 다국어 프로젝트

### 시나리오: 국제 고객을 둔 한국 팀

#### 1단계: 이중 언어 환경 설정

```bash
# 한국어를 주 언어로 AIWF 설치
aiwf-lang set ko

# 이중 언어 문서 구조 생성
mkdir -p docs/{ko,en}
```

#### 2단계: 한국어로 팀 커뮤니케이션

```bash
# 한국어 명령어 사용
/프로젝트:aiwf:초기화

# 한국어 태스크 생성
/프로젝트:aiwf:태스크_생성 "사용자 인증 시스템 구현"

# 한국어 커밋 메시지
git commit -m "기능(FL001): JWT 토큰 생성 구현"
```

#### 3단계: 영어로 고객 문서

```bash
# 문서 작성자 페르소나로 전환
/project:aiwf:ai_persona:documenter

# 한국어 코드베이스에서 영어 API 문서 생성
"한국어 코드베이스에서 영어 API 문서를 생성해주세요"

# 이중 언어 기능 요약 생성
/project:aiwf:feature_summary FL001 --lang=en,ko
```

#### 4단계: 자동화된 번역 워크플로

```javascript
// bilingual-docs.js
import { DocumentProcessor } from '@aiwf/utils';

async function generateBilingualDocs() {
  const processor = new DocumentProcessor();
  
  // 한국어 문서 처리
  const koreanDocs = await processor.loadDirectory('./docs/ko');
  
  // 영어 버전 생성
  for (const doc of koreanDocs) {
    const englishVersion = await processor.translate(doc, 'ko', 'en');
    await processor.save(`./docs/en/${doc.name}`, englishVersion);
  }
}
```

---

## 긴급 디버깅

### 시나리오: 새벽 3시 프로덕션 이슈

#### 1단계: 빠른 컨텍스트 로딩

```bash
# 속도를 위한 적극적 압축 사용
/project:aiwf:compress_context:aggressive

# 중요한 파일만 로드
"결제 처리 모듈과 최근 오류 로그만 로드해주세요"
```

#### 2단계: 신속한 진단

```bash
# 디버거 페르소나로 전환
/project:aiwf:ai_persona:debugger

# 오류 분석
"이 스택 트레이스를 분석하고 근본 원인을 찾아주세요"

# 최근 변경사항 확인
git log --oneline -10 -- src/payments/
```

#### 3단계: 응급 수정

```bash
# 핫픽스 브랜치 생성
git checkout -b hotfix/payment-processing-error

# 검증과 함께 빠른 수정
"결제 프로세서의 null 포인터 예외를 적절한 검증으로 수정해주세요"

# 수정 테스트
npm run test:payments
```

#### 4단계: 배포 및 문서화

```bash
# 명확한 메시지로 커밋
git commit -m "hotfix: 결제 프로세서의 null 포인터 수정

- 결제 방법에 대한 null 검사 추가
- 방어적 프로그래밍 추가
- 엣지 케이스에 대한 단위 테스트 추가

Fixes #456"

# 긴급 PR 생성
gh pr create --title "HOTFIX: 결제 처리 오류" \
  --body "프로덕션 이슈에 대한 긴급 수정" \
  --label "hotfix,urgent"

# 사고 문서화
/project:aiwf:create_incident_report "결제 처리 실패"
```

#### 5단계: 사후 분석

```bash
# 분석을 위해 아키텍트 페르소나로 전환
/project:aiwf:ai_persona:architect

"이 사고를 분석하고 유사한 문제를 방지하기 위한 아키텍처 개선사항을 제안해주세요"

# 개선 태스크 생성
/project:aiwf:create_task "결제 처리 안전장치 구현"
```

---

## 모범 사례 요약

### 1. 페르소나 사용 패턴
```bash
설계 → Architect (아키텍트)
코딩 → Developer (개발자)
디버깅 → Debugger (디버거)
리뷰 → Reviewer (리뷰어)
문서화 → Documenter (문서 작성자)
최적화 → Optimizer (최적화)
```

### 2. 압축 모드 선택
```bash
개요/탐색 → Aggressive (적극적)
일반 개발 → Balanced (균형)
중요/디버깅 → Conservative (보수적)
```

### 3. 기능-Git 워크플로
```bash
기능 → 브랜치 → 커밋 → PR → 병합 → 완료
FL001 → feature/FL001-desc → feat(FL001): msg → PR#42 → main → ✓
```

### 4. 토큰 관리
- 정기적으로 사용량 모니터링
- 사전에 압축 사용
- 불필요한 파일 제외
- 주요 태스크 간 컨텍스트 정리

### 5. 팀 협업
- 일관된 커밋 형식
- 정기적인 상태 업데이트
- 명확한 기능 소유권
- 문서화된 규칙

---

## 결론

이러한 예제들은 실제 시나리오에서 AIWF의 유연성과 강력함을 보여줍니다. 성공의 핵심은:

1. **상황에 맞는 도구**: 적절한 페르소나와 압축 모드 사용
2. **일관된 워크플로**: 확립된 패턴 따르기
3. **명확한 소통**: 기능 참조와 구조화된 커밋 사용
4. **사전 관리**: 토큰, 성능, 진행 상황 모니터링
5. **팀 정렬**: 규칙 문서화 및 공유

더 많은 예제와 커뮤니티 기여를 보려면 [GitHub 저장소](https://github.com/moonklabs/aiwf/tree/main/examples)를 방문하세요.