# Sisyphus 오케스트레이터 및 전문 에이전트

> 원문 출처: https://goddaehee.tistory.com/485

## Sisyphus 오케스트레이터

### 이름의 유래

**Sisyphus (시시포스)**는 그리스 신화에 나오는 인물로, 끊임없이 바위를 산 위로 밀어 올리는 영원한 노동을 하는 것으로 유명합니다.

oh-my-opencode의 Sisyphus는 이 신화에서 영감을 받아:
- **끈기**: 작업을 완료할 때까지 절대 포기하지 않음
- **반복**: Todo 항목이 모두 완료될 때까지 계속
- **목표 지향**: 정상에 도달(작업 완료)하는 것이 목표

### 역할 및 책임

#### 1. 작업 분석 및 분해

```
사용자 요청: "사용자 인증 시스템을 구현해줘"

Sisyphus 분석:
┌─────────────────────────────────────────┐
│ 작업 분해                                │
├─────────────────────────────────────────┤
│ 1. 아키텍처 설계                         │
│    → @Oracle에게 위임                    │
│                                         │
│ 2. 프론트엔드 컴포넌트                   │
│    - 로그인 폼                          │
│    - 회원가입 폼                        │
│    - 프로필 페이지                      │
│    → @Frontend에게 위임                 │
│                                         │
│ 3. 백엔드 API                           │
│    - /auth/login                        │
│    - /auth/register                     │
│    - /auth/logout                       │
│    → @Oracle에게 위임                   │
│                                         │
│ 4. 문서화                               │
│    - API 문서                           │
│    - 사용자 가이드                      │
│    → @Document-Writer에게 위임          │
└─────────────────────────────────────────┘
```

#### 2. 공격적 위임 (Aggressive Delegation)

**전통적 AI의 문제**:
```
AI: "인증 시스템을 구현하겠습니다"
AI: [혼자 모든 작업 시도]
AI: "프론트엔드 80% 완료, 나머지는 직접 하세요"
```

**Sisyphus의 접근**:
```
Sisyphus: "작업을 분석하고 전문가에게 위임하겠습니다"

[병렬 실행]
├─ @Oracle: 아키텍처 설계
├─ @Frontend: UI 구현
├─ @Librarian: 보안 best practices 검색
└─ @Document-Writer: 문서 준비

Sisyphus: [결과 수집 및 통합]
Sisyphus: "모든 작업 100% 완료"
```

#### 3. Todo 지속 강제 (Todo Continuation Enforcer)

**동작 방식**:
```python
class TodoContinuationEnforcer:
    def enforce(self):
        while not self.all_todos_completed():
            pending_todos = self.get_pending_todos()

            for todo in pending_todos:
                if todo.status == "pending":
                    agent = self.select_best_agent(todo)
                    result = agent.execute(todo)

                    if result.completed:
                        todo.status = "completed"
                    else:
                        # 실패해도 다시 시도
                        self.retry_queue.add(todo)

            # 완료 확인
            if self.all_todos_completed():
                return "SUCCESS"
            else:
                # 계속 진행
                continue
```

**실제 예시**:
```
Todo List:
✅ 1. 프로젝트 구조 분석
✅ 2. 아키텍처 설계
✅ 3. 데이터베이스 스키마
🔄 4. API 엔드포인트 구현 (진행 중)
⏳ 5. 프론트엔드 컴포넌트
⏳ 6. 테스트 작성
⏳ 7. 문서화

Sisyphus: "아직 3개 작업 미완료, 계속 진행..."

[시간 경과]

✅ 1. 프로젝트 구조 분석
✅ 2. 아키텍처 설계
✅ 3. 데이터베이스 스키마
✅ 4. API 엔드포인트 구현
✅ 5. 프론트엔드 컴포넌트
✅ 6. 테스트 작성
✅ 7. 문서화

Sisyphus: "모든 작업 완료! ✓"
```

#### 4. 결과 통합

여러 에이전트의 작업 결과를 일관성 있게 통합:

```
@Oracle 결과:
  - 인증 아키텍처 문서
  - API 설계

@Frontend 결과:
  - Login.tsx
  - Register.tsx
  - Profile.tsx

@Document-Writer 결과:
  - API.md
  - USER_GUIDE.md

Sisyphus 통합:
  ├─ 일관성 검증
  ├─ 중복 제거
  ├─ 연결 확인
  └─ 최종 프로젝트 구조 생성
```

### Sisyphus 설정

#### 기본 설정

```json
{
  "agents": {
    "Sisyphus": {
      "model": "anthropic/claude-opus-4-5",
      "temperature": 0.3,
      "max_tokens": 8000,
      "thinking_budget": 32000,
      "mode": "sync",
      "capabilities": {
        "task_delegation": true,
        "result_integration": true,
        "todo_enforcement": true,
        "context_management": true
      },
      "delegation_strategy": "aggressive",
      "completion_threshold": 1.0
    }
  }
}
```

**주요 설정 항목**:
- **thinking_budget**: 32K 토큰의 확장된 사고
- **mode**: `sync` - 동기 실행으로 조율
- **delegation_strategy**: `aggressive` - 적극적인 위임
- **completion_threshold**: 1.0 - 100% 완료 요구

## 전문 에이전트 팀

### 1. Oracle - 아키텍처 전문가

**역할**: 시스템 설계, 코드 리뷰, 디버깅

**모델**: `openai/gpt-5.2-medium`

**전문 분야**:
- 시스템 아키텍처 설계
- 디자인 패턴 적용
- 코드 구조 개선
- 복잡한 버그 분석
- 성능 최적화 전략

**사용 시나리오**:
```
@Oracle 이 마이크로서비스 아키텍처를 검토해줘

@Oracle 이 버그의 근본 원인을 찾아줘

@Oracle 이 시스템의 확장성을 개선하려면?
```

**실행 모드**: `sync` (동기) - 신중한 분석 필요

**예시 출력**:
```markdown
# Architecture Review

## Current Structure
- Monolithic architecture
- Single database
- Synchronous communication

## Identified Issues
1. Tight coupling between modules
2. Single point of failure
3. Scalability limitations

## Recommended Architecture
```mermaid
graph TD
    A[API Gateway] --> B[Auth Service]
    A --> C[User Service]
    A --> D[Product Service]
    B --> E[Auth DB]
    C --> F[User DB]
    D --> G[Product DB]
```

## Migration Strategy
1. Extract Auth service first
2. Implement API Gateway
3. Migrate remaining services
4. Add message queue for async communication

## Estimated Effort
- Phase 1: 2 weeks
- Phase 2: 1 week
- Phase 3: 3 weeks
- Total: 6 weeks
```

### 2. Librarian - 문서 연구 전문가

**역할**: 문서 검색, API 참조, Best Practices

**모델**: `google/gemini-3-flash` (또는 GLM-4.7)

**전문 분야**:
- 공식 문서 검색
- 라이브러리 사용법
- Best Practices 조사
- 코드 예제 찾기
- 최신 기술 동향

**사용 시나리오**:
```
@Librarian React Query의 최신 사용법을 찾아줘

@Librarian PostgreSQL 인덱싱 best practices는?

@Librarian TypeScript 5.0의 새로운 기능은?
```

**실행 모드**: `async` (비동기) - 빠른 검색

**예시 출력**:
```markdown
# React Query Best Practices (2026)

## Installation
\`\`\`bash
npm install @tanstack/react-query@latest
\`\`\`

## Basic Setup
\`\`\`typescript
// main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 minutes
      cacheTime: 1000 * 60 * 10, // 10 minutes
    },
  },
})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
    </QueryClientProvider>
  )
}
\`\`\`

## Best Practices
1. **Query Keys**: Use array format for hierarchical caching
2. **Stale Time**: Set appropriate stale times
3. **Error Handling**: Implement global error boundaries
4. **Optimistic Updates**: Use for better UX

## Sources
- Official Docs: https://tanstack.com/query/latest
- GitHub: https://github.com/TanStack/query
```

### 3. Explore - 코드베이스 탐색 전문가

**역할**: 빠른 코드 검색, 패턴 찾기

**모델**: `xai/grok-code` 또는 `google/gemini-3-flash`

**전문 분야**:
- 파일 검색
- 코드 패턴 찾기
- 의존성 분석
- 사용되지 않는 코드 식별
- 중복 코드 탐지

**사용 시나리오**:
```
@Explore API 호출하는 모든 코드를 찾아줘

@Explore useState를 사용하는 컴포넌트 목록

@Explore 사용되지 않는 유틸리티 함수는?
```

**실행 모드**: `async` (비동기) - 빠른 탐색

**예시 출력**:
```markdown
# Search Results: API Calls

## High Relevance (8 files)

### src/services/api.ts
\`\`\`typescript
Line 15: export const fetchUsers = () => api.get('/users')
Line 23: export const fetchPosts = () => api.get('/posts')
Line 31: export const createPost = (data) => api.post('/posts', data)
\`\`\`

### src/hooks/useUser.ts
\`\`\`typescript
Line 8: const { data } = useQuery('users', fetchUsers)
\`\`\`

### src/components/UserList.tsx
\`\`\`typescript
Line 12: const users = await fetchUsers()
\`\`\`

## Medium Relevance (5 files)
- src/utils/apiClient.ts
- src/contexts/ApiContext.tsx
...

## Statistics
- Total API calls found: 47
- Unique endpoints: 12
- GET requests: 28
- POST requests: 12
- PUT requests: 5
- DELETE requests: 2
```

### 4. Frontend UI/UX Engineer - 프론트엔드 전문가

**역할**: UI 컴포넌트 개발, 반응형 디자인

**모델**: `google/gemini-3-pro`

**전문 분야**:
- React/Vue/Angular 컴포넌트
- CSS 스타일링
- 반응형 디자인
- 접근성 (a11y)
- 사용자 경험 최적화

**사용 시나리오**:
```
@Frontend 모던한 로그인 페이지를 만들어줘

@Frontend 이 컴포넌트를 반응형으로 만들어줘

@Frontend 다크모드를 추가해줘
```

**실행 모드**: `async` (비동기) - 독립적 작업

**예시 출력**:
```typescript
// src/components/LoginForm.tsx
import { useState } from 'react'
import { useNavigate } from 'react-router-dom'

interface LoginFormProps {
  onSubmit: (email: string, password: string) => Promise<void>
}

export function LoginForm({ onSubmit }: LoginFormProps) {
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  const [isLoading, setIsLoading] = useState(false)
  const [error, setError] = useState('')
  const navigate = useNavigate()

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    setIsLoading(true)
    setError('')

    try {
      await onSubmit(email, password)
      navigate('/dashboard')
    } catch (err) {
      setError('Invalid email or password')
    } finally {
      setIsLoading(false)
    }
  }

  return (
    <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-blue-50 to-indigo-100">
      <div className="max-w-md w-full space-y-8 p-10 bg-white rounded-xl shadow-lg">
        <div className="text-center">
          <h2 className="text-3xl font-bold text-gray-900">
            Sign in to your account
          </h2>
          <p className="mt-2 text-sm text-gray-600">
            Enter your credentials to access your account
          </p>
        </div>

        <form className="mt-8 space-y-6" onSubmit={handleSubmit}>
          {error && (
            <div className="rounded-md bg-red-50 p-4">
              <p className="text-sm text-red-800">{error}</p>
            </div>
          )}

          <div className="space-y-4">
            <div>
              <label htmlFor="email" className="sr-only">
                Email address
              </label>
              <input
                id="email"
                name="email"
                type="email"
                autoComplete="email"
                required
                value={email}
                onChange={(e) => setEmail(e.target.value)}
                className="appearance-none relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 rounded-lg focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
                placeholder="Email address"
              />
            </div>

            <div>
              <label htmlFor="password" className="sr-only">
                Password
              </label>
              <input
                id="password"
                name="password"
                type="password"
                autoComplete="current-password"
                required
                value={password}
                onChange={(e) => setPassword(e.target.value)}
                className="appearance-none relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 rounded-lg focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
                placeholder="Password"
              />
            </div>
          </div>

          <div>
            <button
              type="submit"
              disabled={isLoading}
              className="group relative w-full flex justify-center py-2 px-4 border border-transparent text-sm font-medium rounded-lg text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
            >
              {isLoading ? 'Signing in...' : 'Sign in'}
            </button>
          </div>
        </form>
      </div>
    </div>
  )
}
```

### 5. Document-Writer - 문서 작성 전문가

**역할**: 기술 문서 작성

**모델**: `google/gemini-3-flash`

**전문 분야**:
- API 문서
- README 작성
- 사용자 가이드
- 코드 주석
- 튜토리얼

**사용 시나리오**:
```
@Document-Writer 이 API의 문서를 작성해줘

@Document-Writer README를 업데이트해줘

@Document-Writer 사용자 가이드를 만들어줘
```

**실행 모드**: `async` (비동기) - 독립적 작업

**예시 출력**:
```markdown
# API Documentation

## Authentication Endpoints

### POST /auth/login

Authenticates a user and returns an access token.

**Request Body**
\`\`\`json
{
  "email": "user@example.com",
  "password": "securePassword123"
}
\`\`\`

**Response (200 OK)**
\`\`\`json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "123",
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}
\`\`\`

**Error Responses**

401 Unauthorized
\`\`\`json
{
  "success": false,
  "error": "Invalid credentials"
}
\`\`\`

**Example Usage**

\`\`\`javascript
const response = await fetch('/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securePassword123',
  }),
})

const data = await response.json()
console.log(data.data.token)
\`\`\`
```

### 6. Multimodal-Looker - 멀티모달 분석 전문가

**역할**: 이미지, PDF 분석

**모델**: `google/gemini-3-flash`

**전문 분야**:
- 이미지 분석
- 스크린샷 이해
- PDF 파싱
- 다이어그램 해석
- UI 디자인 분석

**사용 시나리오**:
```
@Multimodal-Looker 이 디자인 목업을 분석해줘

@Multimodal-Looker 이 에러 스크린샷을 봐줘

@Multimodal-Looker 이 PDF의 내용을 요약해줘
```

**실행 모드**: `async` (비동기) - 독립적 분석

## 에이전트 협업 예시

### 복잡한 작업의 흐름

```
사용자: "전자상거래 사이트를 만들어줘 ultrawork"

Sisyphus: [작업 분석 및 분해]

[Phase 1: 설계]
@Oracle → 시스템 아키텍처 설계
@Librarian → E-commerce best practices 검색

[Phase 2: 구현 (병렬)]
├─ @Frontend → 상품 목록 페이지
├─ @Frontend → 장바구니 컴포넌트
├─ @Frontend → 결제 페이지
└─ @Oracle → 백엔드 API

[Phase 3: 문서화]
@Document-Writer → API 문서, 사용자 가이드

[Phase 4: 통합]
Sisyphus → 모든 결과 통합 및 검증

결과: 완전한 전자상거래 사이트 ✅
```

## 다음 단계

1. [ultrawork 사용법](./02-05-ultrawork-usage.md)
2. [문제 해결](./02-06-troubleshooting.md)
3. [비용 최적화](./03-01-cost-optimization.md)

---

**이전**: [oh-my-opencode 설치](./02-02-oh-my-opencode-installation.md)
**다음**: [ultrawork 사용법](./02-05-ultrawork-usage.md)