orchestry-mcp/USAGE_GUIDE.md

Orchestry MCP Server for multi-session task management

# BMAD Task Manager 사용 가이드

## 🚀 빠른 시작

### 1. 설치
```bash
npm install
```

### 2. 서버 빌드
```bash
cd server && npm run build && cd ..
```

### 3. 실행

#### 🎯 권장 방법 (Serena 스타일)
```bash
# 통합 실행 + 브라우저 자동 열기
./bmad

# MCP 모드 (LLM 연동용)
./bmad mcp

# 서비스 중지
./stop.sh
```

#### 기타 실행 방법
```bash
# Web UI + API 서버 실행 (수동)
./start.sh

# 모든 서비스 + 브라우저 자동 열기
./start-all.sh

# MCP 서버만 실행
./start-mcp.sh

# 개별 실행
cd server && npm run dev:web  # API 서버
cd server && npm run dev:mcp  # MCP 서버 (stdio)
cd server && npm run dev:unified  # 통합 모드
cd web && npm run dev         # Web UI
```

### 4. 접속
- Web UI: http://localhost:3000
- API Server: http://localhost:3001/api
- WebSocket: ws://localhost:3001

## 🤖 LLM(Claude) 사용법

### MCP 도구 사용 예시

#### 1. 프로젝트 생성
```
create_project("신규 이커머스 플랫폼", "고객 경험 개선을 위한 통합 프로젝트")
```

#### 2. Business 목표 설정
```
create_business(projectId, {
  title: "고객 유지율 30% 향상",
  description: "고객 이탈을 줄이고 재구매율을 높이는 비즈니스 목표",
  objectives: [
    "월간 이탈률 5% 이하 달성",
    "평균 구매 주기 단축",
    "고객 생애 가치(LTV) 향상"
  ],
  kpis: [
    {name: "월간 활성 사용자", target: "100,000", unit: "명"},
    {name: "재구매율", target: "40%", unit: "%"}
  ]
})
```

#### 3. Mission 정의
```
create_mission(businessId, {
  title: "로열티 프로그램 구축",
  description: "포인트 및 등급 기반 로열티 시스템",
  priority: "high",
  successCriteria: [
    "프로그램 가입자 10,000명",
    "월간 포인트 사용률 60%",
    "VIP 등급 전환율 15%"
  ],
  deliverables: [
    "포인트 적립/사용 시스템",
    "등급별 혜택 매트릭스",
    "로열티 대시보드"
  ]
})
```

#### 4. Approach 전략
```
create_approach(missionId, {
  title: "게이미피케이션 기반 로열티",
  methodology: "포인트, 뱃지, 리더보드를 활용한 게임화 전략",
  resources: [
    {type: "human", name: "백엔드 개발자", quantity: 2},
    {type: "human", name: "프론트엔드 개발자", quantity: 2},
    {type: "technical", name: "Redis 캐시 서버"},
    {type: "technical", name: "포인트 관리 DB"}
  ],
  risks: [
    {
      description: "복잡한 포인트 정책으로 인한 사용자 혼란",
      impact: "medium",
      probability: "medium",
      mitigation: "단순하고 명확한 포인트 정책 수립"
    }
  ]
})
```

#### 5. Deployment 태스크
```
create_deployment(approachId, {
  title: "Redis 기반 포인트 캐시 시스템 구축",
  description: "실시간 포인트 조회 및 업데이트를 위한 캐시 레이어",
  status: "todo",
  estimatedHours: 24,
  checklist: [
    {text: "Redis 클러스터 구성", completed: false},
    {text: "포인트 캐시 로직 구현", completed: false},
    {text: "동기화 메커니즘 구현", completed: false},
    {text: "성능 테스트", completed: false}
  ],
  tags: ["backend", "infrastructure", "redis"]
})
```

#### 6. 상태 업데이트
```
update_deployment_status(deploymentId, "in_progress")
```

#### 7. 전체 보기
```
get_bmad_hierarchy(projectId)  // BMAD 트리 구조
get_board(projectId)           // 칸반 보드 상태
```

## 📊 Web UI 기능

### 1. 칸반 보드
- **드래그 앤 드롭**: 태스크를 드래그하여 상태 변경
- **상태 컬럼**: Backlog → Todo → In Progress → Review → Done
- **실시간 업데이트**: WebSocket을 통한 즉시 반영

### 2. BMAD 계층 트리
- **4단계 구조**: Business > Mission > Approach > Deployment
- **확장/축소**: 각 노드를 클릭하여 하위 항목 표시
- **색상 코딩**: 각 단계별 고유 색상으로 구분
- **통계 표시**: 각 레벨별 항목 수 표시

### 3. 태스크 카드
- **상세 정보**: 제목, 설명, 마감일, 담당자
- **체크리스트**: 세부 작업 진행률 표시
- **태그**: 카테고리 및 라벨 관리
- **우선순위**: Critical/High/Medium/Low 표시

## 🔧 고급 기능

### 문서 연결
```
link_document(entityId, "mission", {
  type: "prd",
  title: "로열티 프로그램 PRD",
  content: "## 개요\n### 목적\n..."
})
```

### 검색
```
search_tasks({
  query: "redis",
  status: "in_progress",
  tags: ["backend"]
})
```

## 📝 BMAD 방법론 핵심

1. **Business (왜?)**: 비즈니스 목표와 KPI
2. **Mission (무엇을?)**: 구체적 미션과 성공 기준
3. **Approach (어떻게?)**: 전략과 방법론
4. **Deployment (실행)**: 실제 실행 태스크

각 단계는 상위 단계의 목표를 달성하기 위한 구체화 과정입니다.

## 🎯 팀 협업 시나리오

### 시나리오 1: 신규 기능 개발
1. PM이 Business 목표 설정
2. 팀 리드가 Mission 정의
3. 아키텍트가 Approach 설계
4. 개발자가 Deployment 태스크 실행

### 시나리오 2: 분기 계획
1. 경영진이 Business 목표 제시
2. 각 팀이 Mission 제안
3. 기술 검토 후 Approach 확정
4. 스프린트별 Deployment 배분

## 🚨 문제 해결

### MCP 서버 연결 안 됨
```bash
# 서버 재시작
cd server && npm run dev
```

### Web UI 접속 안 됨
```bash
# 포트 확인
lsof -i :3001
# 프로세스 종료 후 재시작
```

### 데이터베이스 초기화
```bash
# DB 파일 삭제
rm server/bmad.db
# 서버 재시작하면 자동 생성
```

## 📚 추가 자료

- [BMAD Method 상세 설명](./docs/bmad-method.md)
- [API 문서](./docs/api.md)
- [MCP 도구 레퍼런스](./docs/mcp-tools.md)