Oh my Opencode 3.0 Guide

Oh-My-OpenCode 3.0 완벽 가이드

새로운 오케스트레이션 시스템과 에이전트 아키텍처 이해하기

---

📋 목차

1. 개요

2. v3.0의 핵심 철학

3. 새롭게 추가된 에이전트

   • Prometheus (플래너)

   • Atlas (마스터 오케스트레이터)

   • Metis (플랜 컨설턴트)

   • Momus (플랜 리뷰어)

4. Sisyphus vs Atlas 비교

5. 새로운 워크플로우

6. Category & Skill 시스템

7. 설정 가이드

8. 사용 시나리오별 권장 방식

---

개요

Oh-My-OpenCode v3.0은 에이전트 배포 및 관리 방식을 근본적으로 변화시킨 메이저 업데이트입니다. 정적인 에이전트 정의에서 벗어나 동적이고 지능적인 오케스트레이션 생태계로 전환되었습니다.

주요 변경사항

영역	v2.x	v3.0
에이전트 구조	하드코딩된 에이전트	Category + Skill 동적 조합
계획/실행	혼합	완전 분리 (Prometheus/Atlas)
작업 검증	수동	자동화된 검증 루프
상태 관리	세션 기반	boulder.json 영속 상태
학습	없음	누적 학습 (Notepads)

---

v3.0의 핵심 철학

"계획과 실행의 분리" (Separation of Planning and Execution)

전통적인 AI 에이전트의 문제점:

• 컨텍스트 오염: 계획과 실행이 섞이면서 목표 상실

• 목표 이탈 (Cognitive Drift): 작업 중 요구사항 망각

• AI Slop: 저품질 코드 생산

• 검증 부재: 완료 여부 확인 불가

Oh-My-OpenCode v3.0의 해결책:

┌─────────────────────────────────────────────────────────┐
│                    Planning Phase                        │
│  Prometheus (전략가) - 코드를 절대 작성하지 않음          │
│  → 인터뷰 → 분석 → 완벽한 계획 수립                      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
                    .sisyphus/plans/*.md
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Execution Phase                        │
│  Atlas (실행자) - 계획만 실행                            │
│  → 위임 → 검증 → 재시도 → 완료까지 무한 반복             │
└─────────────────────────────────────────────────────────┘

---

새롭게 추가된 에이전트

🔥 Prometheus (플래너)

그리스 신화에서 인류에게 불을 전해준 타이탄. 전략과 선견지명의 상징.

역할

• 순수 전략가: 코드를 절대 작성하지 않음

• 인터뷰어: 사용자와 대화하며 요구사항 명확화

• 리서처: 코드베이스 분석 (explore/librarian 활용)

제약사항

• READ-ONLY: .sisyphus/ 디렉토리 내 마크다운 파일만 생성/수정 가능

• 코드 파일 직접 수정 불가

• 시스템 명령어 실행 불가

워크플로우

1. 사용자 요청 접수
       ↓
2. 명확화 질문 (인터뷰)
       ↓
3. 코드베이스 리서치 (explore/librarian 호출)
       ↓
4. Metis 상담 (필수)
       ↓
5. 계획 초안 작성
       ↓
6. [선택] Momus 검증 (High Accuracy Mode)
       ↓
7. 최종 계획 저장 → .sisyphus/plans/{name}.md

사용법

# 방법 1: Tab 키로 모드 전환
Tab → Prometheus 모드 진입

# 방법 2: @plan 명령어
@plan "인증 시스템을 NextAuth로 리팩토링하고 싶어"

출력 예시

<!-- .sisyphus/plans/auth-refactoring.md -->

# Auth Refactoring Plan

## Overview
현재 세션 기반 인증을 NextAuth.js로 마이그레이션

## Tasks
- [ ] Task 1: NextAuth 패키지 설치 및 설정
- [ ] Task 2: 기존 auth 모듈 백업
- [ ] Task 3: NextAuth provider 구현
- [ ] Task 4: 세션 마이그레이션 스크립트 작성
- [ ] Task 5: 테스트 및 검증

## Acceptance Criteria
- 모든 기존 사용자 세션 유지
- OAuth 로그인 지원 (Google, GitHub)
- 기존 API 호환성 유지

## Guardrails
- 프로덕션 DB 직접 수정 금지
- 단계별 롤백 가능해야 함

---

⚡ Atlas (마스터 오케스트레이터)

그리스 신화에서 하늘을 어깨에 짊어진 타이탄. 무거운 짐을 끝까지 지탱하는 인내의 상징.

역할

• 계획 실행 전문가: Prometheus가 만든 계획을 실행

• 태스크 위임자: 각 작업에 최적의 에이전트/카테고리 배정

• 품질 관리자: 모든 단계 검증, 실패 시 자동 재시도

핵심 기능

기능	설명
Right Tool, Right Job	Category + Skill 조합으로 최적 에이전트 배치
Relentless Verification	계획 대비 결과 집요하게 검증
Auto-Resume	실패 시 자동 재시도
Cost Optimization	프로바이더별 토큰 사용 최적화
Accumulated Wisdom	작업별 학습 내용 누적 저장

상태 관리

// .sisyphus/boulder.json
{
  "active_plan": ".sisyphus/plans/auth-refactoring.md",
  "started_at": "2026-01-26T10:30:00.000Z",
  "session_ids": ["ses_abc123"],
  "plan_name": "auth-refactoring",
  "current_task": 2,
  "completed_tasks": [1],
  "learnings": ".sisyphus/notepads/auth-refactoring/"
}

누적 학습 (Notepads)

.sisyphus/notepads/auth-refactoring/
├── learnings.md      # 성공한 패턴, 컨벤션
├── decisions.md      # 아키텍처 결정 사항
└── issues.md         # 발견된 문제 및 해결책

사용법

# Prometheus 계획 완료 후
/start-work

⚠️ 주의: /start-work 없이 Atlas를 직접 호출하면 예측 불가능한 동작 발생

---

🦉 Metis (플랜 컨설턴트)

그리스 신화에서 지혜와 깊은 사고의 여신. 제우스의 첫 번째 아내.

역할

• 숨겨진 의도 파악: 사용자가 말하지 않은 진짜 니즈 발견

• AI 과잉 엔지니어링 방지: 불필요한 복잡성 제거

• 모호함 제거: 애매한 요구사항 명확화

특징

• Prometheus 계획 생성 전 필수 상담

• "사용자가 원하는 것" vs "사용자가 말한 것" 구분

• 실패 가능성이 높은 지점 사전 식별

상담 예시

[Metis 분석]

🔍 숨겨진 의도 발견:
- 사용자가 "빠른 로그인"을 원한다고 했지만, 실제로는 "소셜 로그인 추가"가 목적

⚠️ AI 실패 가능성:
- 기존 세션 스토어와의 충돌 가능성
- OAuth 콜백 URL 설정 누락 위험

💡 권장사항:
- Task 분리: "설정" → "구현" → "마이그레이션" → "검증"
- 롤백 계획 필수 포함

---

👁️ Momus (플랜 리뷰어)

그리스 신화에서 비판과 풍자의 신. 완벽함을 추구하며 결점을 찾아냄.

역할

• 고정밀 검증 (High Accuracy Mode)

• 계획이 완벽해질 때까지 거부 및 수정 요구

• 최종 품질 게이트키퍼

검증 기준

항목	검증 내용
Clarity	모든 태스크가 명확하고 구체적인가?
Completeness	누락된 단계가 없는가?
Verifiability	각 태스크의 완료 기준이 측정 가능한가?
Feasibility	기술적으로 실현 가능한가?
Safety	위험 요소가 적절히 관리되는가?

워크플로우

Prometheus 계획 제출
       ↓
Momus 검토
       ↓
    ┌──────┴──────┐
    │             │
  OKAY        REJECTED
    │             │
    ↓             ↓
  실행 진행    Prometheus
              재수정 후
              재제출

선택적 사용

• 기본: 비활성화

• 활성화: 사용자가 "high accuracy" 요청 시

---

Sisyphus vs Atlas 비교

개요 비교

구분	Sisyphus	Atlas
정체성	Primary Orchestrator	Master Orchestrator
기본 모델	Claude Opus 4.5	Claude Opus 4.5 (또는 Sonnet)
활성화	기본 / ulw 키워드	/start-work 명령어
계획 필요	❌ 선택적	✅ 필수
작동 방식	계획 + 실행 통합	실행만 (계획은 Prometheus)
상태 저장	세션 내	boulder.json 영속
누적 학습	❌	✅ Notepads
자동 재시도	제한적	✅ 완전 자동화

역할 비교

🪨 Sisyphus (시시포스)

"만능 팀장" - 계획도 하고 실행도 하는 올라운더

특징:
- 즉흥적 작업 가능
- 빠른 응답
- 유연한 접근
- 단일 세션 내 완결

적합한 작업:
✅ 빠른 버그 수정
✅ 간단한 기능 추가
✅ 코드 리뷰
✅ 질문 응답
✅ 탐색적 작업

⚡ Atlas (아틀라스)

"전문 프로젝트 매니저" - 계획된 작업만 정밀하게 실행

특징:
- 사전 계획 필수
- 체계적 검증
- 상태 영속성
- 학습 누적

적합한 작업:
✅ 대규모 리팩토링
✅ 새 기능 구현
✅ 마이그레이션 프로젝트
✅ 멀티파일 변경
✅ 품질 중요 작업

워크플로우 비교

Sisyphus 단독 (기존 방식)

👤 "로그인 기능 만들어줘 ulw"
            │
            ▼
    ┌───────────────┐
    │   Sisyphus    │
    │  ┌─────────┐  │
    │  │ 분석    │  │
    │  │   ↓     │  │
    │  │ 계획    │  │
    │  │   ↓     │  │
    │  │ 실행    │  │
    │  │   ↓     │  │
    │  │ 검증    │  │
    │  └─────────┘  │
    └───────────────┘
            │
            ▼
         완료 ✅

장점: 빠름, 간편함 단점: 복잡한 작업에서 품질 저하 가능

Prometheus + Atlas (v3.0 방식)

👤 "인증 시스템 리팩토링해줘"
            │
            ▼
    ┌───────────────────────────────────┐
    │         Planning Phase            │
    │  ┌─────────────────────────────┐  │
    │  │ 🔥 Prometheus               │  │
    │  │    ↓ 인터뷰                 │  │
    │  │ 🦉 Metis (상담)             │  │
    │  │    ↓                        │  │
    │  │ 👁️ Momus (검증, 선택적)     │  │
    │  └─────────────────────────────┘  │
    └───────────────────────────────────┘
            │
            ▼
    .sisyphus/plans/auth.md
            │
            ▼
    /start-work
            │
            ▼
    ┌───────────────────────────────────┐
    │        Execution Phase            │
    │  ┌─────────────────────────────┐  │
    │  │ ⚡ Atlas                     │  │
    │  │    ↓                        │  │
    │  │ Task 1 → Junior → 검증     │  │
    │  │    ↓                        │  │
    │  │ Task 2 → Junior → 검증     │  │
    │  │    ↓                        │  │
    │  │ Task N → Junior → 검증     │  │
    │  └─────────────────────────────┘  │
    └───────────────────────────────────┘
            │
            ▼
         완료 ✅

장점: 높은 품질, 추적 가능, 재개 가능 단점: 초기 설정 시간 필요

비용 효율성

방식	토큰 사용 패턴
Sisyphus	Opus 4.5 단일 모델 집중 사용
Atlas	작업별 최적 모델 분산 사용

Atlas 비용 최적화 예시:

• 오케스트레이션: Sonnet (저비용)

• 일상 태스크: GLM 4.7 (무료/저비용)

• 빠른 수정: Haiku 4.5 (최저비용)

• 복잡한 로직: GPT 5.2 (고성능)

---

새로운 워크플로우

Planning Triad (계획 삼인방)

         ┌─────────────────┐
         │   👤 User       │
         └────────┬────────┘
                  │ 요청
                  ▼
         ┌─────────────────┐
         │ 🔥 Prometheus   │◄──────┐
         │   (Planner)     │       │
         └────────┬────────┘       │
                  │                │
                  ▼                │
         ┌─────────────────┐       │
         │ 🦉 Metis        │       │
         │  (Consultant)   │───────┤ 피드백
         └────────┬────────┘       │
                  │                │
                  ▼                │
         ┌─────────────────┐       │
         │ 👁️ Momus        │       │
         │   (Reviewer)    │───────┘
         └────────┬────────┘
                  │ OKAY
                  ▼
         ┌─────────────────┐
         │ 📄 Plan File    │
         │ .sisyphus/plans │
         └─────────────────┘

Execution Flow (실행 흐름)

    /start-work
         │
         ▼
┌─────────────────────┐
│   ⚡ Atlas           │
│   (Orchestrator)    │
└──────────┬──────────┘
           │
     ┌─────┴─────┬─────────┬─────────┐
     ▼           ▼         ▼         ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Oracle  │ │Frontend │ │ Explore │ │Librarian│
│(Debug)  │ │  (UI)   │ │ (Grep)  │ │ (Docs)  │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
     │           │           │           │
     └─────┬─────┴─────┬─────┴─────┬─────┘
           │           │           │
           ▼           ▼           ▼
     ┌─────────────────────────────────┐
     │    .sisyphus/notepads/          │
     │    (Accumulated Wisdom)         │
     └─────────────────────────────────┘

---

Category & Skill 시스템

개념

v3.0에서는 하드코딩된 에이전트 대신 Category + Skill 조합으로 동적 에이전트를 생성합니다.

구성요소	역할	예시
Category	"어떤 종류의 작업인가?"	visual-engineering, quick, business-logic
Skill	"어떤 전문지식이 필요한가?"	frontend-ui-ux, git-master, playwright

기존 vs 신규 비교

기존 (v2.x)	신규 (v3.0)
frontend-ui-ux-engineer (고정)	category="visual-engineering" + skills=["frontend-ui-ux"]
모델 고정 (Gemini 3 Pro)	카테고리별 최적 모델 자동 선택
확장 불가	커스텀 카테고리/스킬 추가 가능

사용 예시

// Git 작업 전문 에이전트 생성
delegate_task(
  category="quick",
  skills=["git-master"],
  prompt="현재 변경사항 커밋해줘"
)

// UI 작업 전문 에이전트 생성
delegate_task(
  category="visual-engineering",
  skills=["frontend-ui-ux"],
  prompt="대시보드에 반응형 차트 추가해줘"
)

// 커스텀 조합
delegate_task(
  category="unity-game-dev",
  skills=["unity-master"],
  prompt="플레이어 이동 시스템 구현해줘"
)

커스텀 Category 정의

// .opencode/oh-my-opencode.json
{
  "categories": {
    "korean-writer": {
      "model": "google/gemini-3-flash",
      "temperature": 0.5,
      "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone."
    },
    "unity-game-dev": {
      "model": "openai/gpt-5.2",
      "temperature": 0.3,
      "prompt_append": "You are a Unity game development expert..."
    }
  }
}

---

설정 가이드

기본 설정

// ~/.config/opencode/oh-my-opencode.json
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  "sisyphus_agent": {
    "disabled": false,
    "planner_enabled": true,
    "replace_plan": true
  },
  
  "agents": {
    "atlas": {
      "model": "anthropic/claude-sonnet-4-5",
      "variant": "max"
    },
    "prometheus": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}

비용 최적화 설정

{
  "agents": {
    "atlas": {
      "model": "anthropic/claude-sonnet-4-5"
    },
    "librarian": {
      "model": "zai-coding-plan/glm-4.7"
    },
    "explore": {
      "model": "opencode/gpt-5-nano"
    }
  },
  "categories": {
    "quick": {
      "model": "opencode/gpt-5-nano"
    },
    "unspecified-low": {
      "model": "zai-coding-plan/glm-4.7"
    }
  }
}

Hook 설정

{
  "disabled_hooks": [
    // "start-work",           // 실행 트리거 비활성화
    // "prometheus-md-only"    // Prometheus 쓰기 제한 해제 (비권장)
  ]
}

---

사용 시나리오별 권장 방식

의사결정 플로우차트

작업 유형 판단
     │
     ├─ 빠른 수정 / 간단한 작업?
     │       │
     │       └─ YES → Sisyphus (일반 프롬프트)
     │
     ├─ 컨텍스트 설명이 귀찮은 복잡한 작업?
     │       │
     │       └─ YES → Sisyphus + "ulw" 키워드
     │
     └─ 정밀한 실행 & 검증이 필요?
             │
             └─ YES → Prometheus (@plan) → Atlas (/start-work)

시나리오별 가이드

시나리오	권장 방식	명령어
오타 수정	Sisyphus	"line 42 오타 고쳐줘"
간단한 버그 수정	Sisyphus	"로그인 버튼 안 눌리는 거 고쳐줘"
새 API 엔드포인트 추가	Sisyphus + ulw	"유저 프로필 API 추가해줘 ulw"
인증 시스템 리팩토링	Prometheus + Atlas	@plan → /start-work
DB 스키마 마이그레이션	Prometheus + Atlas	@plan → /start-work
대규모 코드 정리	Prometheus + Atlas	@plan → /start-work

Best Practices

1. 계획에 충분한 시간 투자

   • Prometheus 인터뷰에 성의껏 답변

   • 계획이 완벽할수록 실행이 빠름

2. Single Plan Principle

   • 아무리 큰 작업도 하나의 계획 파일에 포함

   • 컨텍스트 분산 방지

3. 중단 후 재개

   • Atlas는 boulder.json으로 상태 추적

   • 중단 후 /start-work로 이어서 진행

4. High Accuracy Mode

   • 중요한 프로덕션 작업에는 Momus 검증 활성화

   • "high accuracy로 검증해줘" 요청

---

참고 자료

• Oh-My-OpenCode GitHub

• 공식 문서 - Orchestration Guide

• 공식 문서 - Understanding Orchestration System

• Discord 커뮤니티

---

📅 문서 작성일: 2026-01-26 📦 기준 버전: oh-my-opencode v3.0.1