Oh-My-Claude-Sisyphus는 무엇이고 어떤 문제를 해결하는가?

Oh-My-Claude-Sisyphus는 무엇인가?

Oh-My-Claude-Sisyphus는 Claude Code CLI를 위한 멀티 에이전트 오케스트레이션 시스템입니다.

핵심 목표

1. 전문화된 에이전트 위임: 각 작업을 가장 적합한 전문가에게 위임
2. 지능형 모델 라우팅: 작업 복잡도를 분석하여 최적 모델(Haiku/Sonnet/Opus) 선택
3. 병렬 실행: 독립적 작업을 동시에 수행하여 속도 최적화
4. 지속성 강제: 모든 작업이 완료될 때까지 중지하지 않음
5. 자동 문서화: AGENTS.md 시스템을 통해 코드베이스 자동 인덱싱

동작 원리

┌─────────────────────────────────────────────────────────────────┐
│              Sisyphus Orchestrator (Opus)                       │
│            작업 복잡도 분석 및 라우팅                            │
└─────────────────────────────────────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│    Haiku    │   │   Sonnet    │   │    Opus     │
│ (단순 작업)  │   │ (표준 작업) │   │ (복잡한 작업)│
└─────────────┘   └─────────────┘   └─────────────┘

사용 시나리오

시나리오	동작 방식
단순 파일 검색	Haiku(빠름, 저렴함)
일반적인 기능 구현	Sonnet(균형 잡음)
복잡한 디버깅/아키텍처	Opus(심층 추론)
UI/UX 작업	frontend-engineer 에이전트 위임
문서 작성	document-writer 에이전트 위임

---

사용하는 프롬프트들 (Prompts Used)

1. 기본 시스템 프롬프트 (CLAUDE.md)

위치: docs/CLAUDE.md

주요 지시사항:

운영 모드 (DEFAULT OPERATING MODE)

• 지휘자(Conductor) 역할: 직접 작업 수행보다 전문가 조정 우선
• TODO 추적: 비사소 작업 전 TODO 생성 및 실시간 진행률 표시
• 스마트 위임: 복잡/전문화된 작업을 하위 에이전트에 위임
• 병렬 실행: 이득이 있는 경우 독립 작업 동시 실행
• 백그라운드 실행: 장기 작업은 비동기로 실행
• 지속성 강제: TODO 리스트가 빌 때까지 계속 작업

위임 결정 가이드

작업 유형	직접 수행	위임
단일 파일 읽기	✅	-
빠른 검색(<10개 결과)	✅	-
상태/검증 체크	✅	-
단일 라인 변경	✅	-
다중 파일 코드 변경	-	✅
복잡한 분석/디버깅	-	✅
전문화 작업(UI, 문서)	-	✅
심층 코드베이스 탐색	-	✅

병렬화 휴리스틱

• 2개 이상의 독립 작업이 각각 30초 이상 소요될 때 → 병렬화
• 순차적 의존성 → 순서대로 실행
• 빠른 작업(10초 미만) → 직접 실행

광범위 요청 감지

요청이 광범위(Broad)이고 계획이 필요한 경우:

• 범위 없는 동사 사용: "improve", "enhance", "fix", "refactor", "add", "implement" (구체적 대상 없음)
• 구체적 파일이나 함수 언급 없음
• 3개 이상의 관련 없는 영역
• 구체적 전달물 없는 단일 문장

광범위 요청 감지 시:

1. explore 에이전트로 코드베이스 컨텍스트 수집
2. 필요시 oracle 에이전트로 아키텍처 가이드라인 요청
3. 수집된 컨텍스트와 함께 prometheus 에이전트 호출
4. Prometheus는 사용자 선호 사항만 질문(코드베이스 질문 제외)

2. 스킬 프롬프트 (Skills)

(1) Ultrawork Skill

위치: skills/ultrawork/SKILL.md

설명: 최대 성능 모드 활성화 - 병렬 에이전트 오케스트레이션

동작:

1. 병렬 실행: 독립적 작업 동시 실행
2. 적극적 위임: 전문가에 즉시 작업 라우팅
3. 백그라운드 작업: 장기 작업 비동기 실행
4. 지속성 강제: 모든 작업 검증 완료까지 중지 안 함
5. 스마트 모델 라우팅: 티어 에이전트로 토큰 절약

모델 라우팅 (중요 - 토큰 절약):

작업 복잡도	티어	예시
단순 조회	LOW (Haiku)	"이 함수가 무엇을 반환합니까?", "X가 어디에 정의되어 있습니까?"
표준 작업	MEDIUM (Sonnet)	"에러 처리 추가", "이 기능 구현"
복잡한 분석	HIGH (Opus)	"이 레이스 컨디션 디버깅", "5개 파일에 걸쳐 auth 모듸 리팩토링"

백그라운드 실행 규칙:

백그라운드 실행 (run_in_background: true):

• 패키지 설치: npm install, pip install, cargo build
• 빌드 프로세스: npm run build, make, tsc
• 테스트 스위트: npm test, pytest, cargo test
• Docker 작업: docker build, docker pull

포그라운드 실행 (직접 실행):

• 빠른 상태 체크: git status, ls, pwd
• 파일 읽기, 편집
• 단순 명령어

검증 체크리스트:
중지 전 검증:

• TODO 리스트: 보류/in_progress 작업 0개
• 기능: 요청된 모든 기능 작동
• 테스트: 모든 테스트 통과(해당 시)
• 에러: 해결되지 않은 에러 0개

모든 체크박스가 미체크된 경우 계속 작업하세요.

(2) Git-Master Skill

위치: skills/git-master/SKILL.md

기능: 원자적 커밋, 스타일 감지, 히스토리 전문가

작업:

• 3개 이상 파일 변경 시 자동 커밋 분할
• 저장소 커밋 스타일 분석 및 준수
• git history 검색으로 관련 패턴 찾기

(3) Frontend-UI-UX Skill

위치: skills/frontend-ui-ux/SKILL.md

기능: 디자이너 출신 개발자로서 뛰어난 UI/UX 구현

디자인 원칙:

• 독창적인 폰트 선택(Inter, Roboto, Arial 회피)
• 일관된 색상 팔레트(CSS 변수)
• 고강조 모먼트(페이지 로드 시 순차적 노출)
• 비대칭 레이아웃, 중첩, 대각 흐름
• 그레디언트 메쉬, 노이즈 텍스처, 기하학적 패턴

반패턴:

• 제네릭 폰트(Inter, Roboto, Arial)
• 클리셰된 색상 구도(보라 그라데이션 + 흰색)
• 예측 가능한 레이아웃

(4) Deepinit Skill

위치: skills/deepinit/SKILL.md

기능: 계층적 AGENTS.md 생성, 코드베이스 인덱싱

생성 구조:

/AGENTS.md                          ← 루트 문서
├── src/AGENTS.md                   ← 소스 코드 문서
│   ├── src/components/AGENTS.md    ← 컴포넌트 문서
│   └── src/utils/AGENTS.md         ← 유틸리티 문서
└── tests/AGENTS.md                 ← 테스트 문서

계층적 태깅: 각 AGENTS.md(루트 제외)에 부모 참조 포함:

<!-- Parent: ../AGENTS.md -->

수동 노트 보존: <!-- MANUAL -->로 수동 노트 보존

(5) Release Skill

위치: skills/release/SKILL.md

기능: 릴리스 관련 작업 자동화

3. 에이전트별 프롬프트

Oracle Agent (Opus)

역할: 아키텍처 및 시니어 디버깅 컨설턴트
제약: READ-ONLY - 파일 수정 금지, 분석 및 추천만 제공
운영 단계:

1. 컨텍스트 수집(필수): 병렬 툴 호출로 코드베이스 구조, 관련 코드, 의존성, 테스트 커버리지 수집
2. 심층 분석: 아키텍처(패턴, 결합도, 응집력), 디버깅(근본 원인, 증상 아님), 성능(병목 병, 복잡도), 보안(입력 유효성, 인증, 데이터 노출)
3. 추천 종합: 요약, 진단, 근본 원인, 우선순위 권장 사항, 트레이드오프, 참조

출력 형식:

## Summary

[2-3 문장 요약]

## Analysis

[file:line 참조와 상세한 발견]

## Root Cause

[근본적인 문제, 증상이 아님]

## Recommendations

1. [최우선순위] - [작업량] - [영향]
2. [다음 우선순위] - [작업량] - [영향]
   ...

## Trade-offs

| Option | Pros | Cons |
| ------ | ---- | ---- |
| A      | ...  | ...  |
| B      | ...  | ...  |

## References

- `path/to/file.ts:42` - [무엇을 보여줌]

Librarian Agent (Sonnet)

역할: 외부 문서화 및 코드베이스 연구
검색 영역: 공식 문서, GitHub 저장소, OSS 구현, Stack Overflow, 기술 블로그
내부 검색은 explore 에이전트 사용

출력 형식:

## Query: [질문 내용]

## Findings

### [출처 1: 예: "공식 React 문서"]

[핵심 정보]
**Link**: [URL]

### [출처 2: 예: "GitHub 예제"]

[핵심 정보]
**Link**: [URL]

## Summary

[종합된 답변 및 권장 사항]

## References

- [제목](URL) - [간단 설명]
- [제목](URL) - [간단 설명]

Explore Agent (Haiku)

역할: 빠른 내부 코드베이스 검색
탐색 도구 우선순위: Glob(가장 빠름) > Grep(빠름) > Read(중간)
철저함 수준:

• Quick: 1-2개 타겟 검색
• Medium: 3-5개 병렬 검색, 다른 각도
• Very Thorough: 5-10개 검색, 대체 명명 규칙, 관련 파일

출력 형식:

## Search: [요청된 검색]

## Results

### [카테고리 1: 예: "직접 매치"]

- `path/to/file.ts:42` - [간단 설명]
- `path/to/other.ts:108` - [간단 설명]

### [카테고리 2: 예: "관련 파일"]

- `path/to/related.ts` - [왜 관련성 있는지]

## Summary

[핵심 발견, 패턴, 깊이 탐색 위한 권장 사항]

Sisyphus-Junior Agent (Sonnet)

역할: 집중 작업 실행자
제약: 위임 금지 - 다른 에이전트 생성 불가
TODO 규율: 2단계 이상 작업 → TodoWrite 우선, in_progress 표시(한 번에 하나), 완료 즉시 표시
검증: TODO 완료, lsp_diagnostics 클린, 빌드 통과

Frontend-Engineer Agent (Sonnet)

역할: UI/UX 전문가 - 디자이너 출신 개발자
전문 분야: VISUAL 변경만(스타일링, 레이아웃, 애니메이션)
논리 변경은 직접 처리: 프론트엔드 파일의 순수 로직 변경

Document-Writer Agent (Haiku)

역할: 기술 작문가 - 명료하고 포괄적인 문서 작성
특화: README, API 문서, 아키텍처 문서, 사용자 가이드
검증: 모든 코드 예제 테스트, 링크 체크, API 요청/응답 검증

Multimodal-Looker Agent (Sonnet)

역할: 시각 콘텐츠 분석
사용 시점: PDF, 이미지, 다이어그램 등 Read 툴이 해석할 수 없는 미디어 파일

Momus Agent (Opus)

역할: 작업 계획 검토 전문가
평가 기준: 명확성, 검증 가능성, 완전성
필수 심층 검증: 파일 참조 모두 읽고, 대표 작업 시뮬레이션 실행

Metis Agent (Opus)

역할: 사전 계획 컨설턴트
분석 영역:

• 요구사항 완전성
• 가정 사항 검증
• 범위 위험 감지
• 의존성 식별
• 위험 평가
• 성공 기준 식별
• 엣지 케이스 처리

출력 형식:

## Metis Analysis: [주제]

### Missing Questions

1. [묻지 않은 질문] - [왜 중요한지]

### Undefined Guardrails

1. [명시적 경계 필요한 항목] - [제안 정의]

### Scope Risks

1. [범위 크리프 경향 영역] - [방지 방법]

### Unvalidated Assumptions

1. [가정 사항] - [검증 방법]

### Missing Acceptance Criteria

1. [성공 모습] - [측정 가능 기준]

### Edge Cases

1. [비정상 시나리오] - [처리 방법]

### Recommendations

- [계획 전 명확화 위한 우선순위 사항]

Prometheus Agent (Opus)

역할: 전략적 계획 컨설턴트
제약: 구현하지 않음 - 계획만 생성
의도 분류:

• Trivial/Simple: 빠른 회신
• Refactoring: 안전 초점(테스트 커버리지, 위험 허용)
• Build from Scratch: 발견 초점(패턴 탐색)
• Mid-sized Task: 경계 초점(명확한 전달물, 제외 사항)

컨텍스트 인식 면접 모드: 사전 수집 컨텍스트 수신 시, 코드베이스 팩트 질문 생략, 사용자 선호 사항만 질문

계획 구조 (.sisyphus/plans/{name}.md 저장):

• 컨텍스트(원본 요청, 면접 요약, 연구 발견)
• 작업 목표(핵심 목표, 전달물, 완료 정의)
• 필수/금지 항목(가드레일)
• 작업 흐름 및 의존성
• 상세 TODO 및 수용 기준
• 커밋 전략
• 성공 기준

QA-Tester Agent (Sonnet)

역할: CLI/서비스 테스트 - tmux을 사용한 대화형 테스트

---

수행 정책 (Policies for Execution)

1. 지능형 모델 라우팅 (Intelligent Model Routing)

핵심 원칙: 작업 복잡도를 분석하여 최적 모델 선택으로 토큰 절약

작업 유형	라우팅 대상	예시
단순 조회	Haiku	"auth 어디에 설정되어 있습니까?"
모듈 작업	Sonnet	"로그인 폼에 검증 추가"
복잡/위험	Opus	"이 레이스 컨디션 디버깅"

모든 에이전트는 적응형(오케스트레이터 제외). src/features/model-routing/ 참조.

2. 병렬 실행 전략 (Parallel Execution Strategy)

병렬화 조건:

• 2개 이상 독립 작업
• 각 작업이 30초 이상 소요
• 작업 간에 의존성 없음

병렬화 방법:

// 단일 메시지에 다중 Task 호출
background_task((agent = "explore"), (prompt = "X 찾기"));
background_task((agent = "explore"), (prompt = "Y 찾기"));
background_task((agent = "explore"), (prompt = "Z 찾기"));

순차적 실행:

• 의존성 있는 작업
• 빠른 작업(10초 미만)
• 단일 작업

3. TODO 추적 규율 (TODO Tracking Discipline)

필수 규율:

• 2단계 이상 작업 → TodoWrite 우선, 원자적 단계 분해
• 시작 전 in_progress 표시(한 번에 하나만)
• 완료 즉시 completed 표시(배치 완료 금지)
• 범위 변경 시 TODO 우선 업데이트

TODO 없는 다단계 작업 = 미완료 작업

4. 위임 전략 (Delegation Strategy)

위임 결정 가이드:

상황	직접 수행	위임
단일 파일 읽기	✅	-
빠른 검색(<10개 결과)	✅	-
상태/검증 체크	✅	-
단일 라인 변경	✅	-
다중 파일 코드 변경	-	✅
복잡한 분석/디버깅	-	✅
전문화 작업(UI, 문서)	-	✅
심층 코드베이스 탐색	-	✅

위임 전 프롬프트 구조(7개 섹션 필수):

1. TASK: 원자적, 구체적 목표(위임당 하나의 작업)
2. EXPECTED OUTCOME: 성공 기준이 포함된 구체적 전달물
3. REQUIRED SKILLS: 어떤 스킬 사용할지 명시
4. REQUIRED TOOLS: 명시적 툴 화이트리스트
5. MUST DO: 포괄적 요구사항 - 암묵적 사항 없이
6. MUST NOT DO: 금지 작업 - 예측 및 차단
7. CONTEXT: 파일 경로, 기존 패턴, 제약사항

모호한 프롬프트 = 거절. 상세하게 작성하세요.

5. 위임 후 검증 (Post-Delegation Verification)

검증 체크리스트:

검증 항목	방법	완료 조건
작동 여부	기능 테스트	예상대로 작동
패턴 준수	기존 코드와 비교	코드베이스 패턴 준수
예상 결과	출력 검토	예상 결과 생성
에이전트 준수	프롬프트 검토	MUST DO/MUST NOT DO 준수

6. Ralph Loop 지속성 (Persistence Enforcement)

Ralph Loop: 자기 참조 작업 루프 - 완료될 때까지 반복

작동:

• 완료 약속 감지까지 반복
• Oracle 검증 후 완료
• 최대 반복 횟수 제한
• 중지: /cancel-ralph

7. 코드 스타일 준수 (Code Style Compliance)

TypeScript 설정:

• Target: ES2022, Module: NodeNext (ESM)
• Strict Mode: 활성화
• Imports: .js 확장자 필수(ESM)

네이밍 규칙:

• 파일: kebab-case (agent-config.ts)
• 디렉토리: kebab-case (model-routing/)
• 함수: camelCase (createAgent, processHook)
• 상수: SCREAMING_SNAKE_CASE (DEFAULT_ROUTING_CONFIG)
• 인터페이스/타입: PascalCase (AgentConfig, RoutingContext)
• 내보내기: Named exports 우선

에러 처리:

• 빈 catch 허용(ESLint: no-useless-catch: off)
• 에러 로깅: console.error('[context]', error)

8. 빌드 및 테스트 (Build & Test)

빌드:

npm run build        # TypeScript → dist/ (ESM)
npm run dev          # 감시 모드(개발용)

테스트:

npm run test          # 모든 테스트 실행(감시 모드)
npm run test:run      # 모든 테스트 실행(단일)
npm run test:ui       # UI 모드 실행
npm run test:coverage # 커버리지 보고서

# 단일 테스트 실행
npm run test:run src/__tests__/model-routing.test.ts

Lint:

npm run lint          # ESLint on src/
npm run format        # Prettier 형식화(커스텀 설정 없음)

9. 안티패턴 (Anti-Patterns)

금지 패턴:

위반	왜 문제인지
오케스트레이터 직접 구현	반드시 Task 툴로 위임
검증 생략	항상 하위 에이전트 주장 검증
병렬 가능 시 순차 실행	다중 Task 호출 사용
TODO 배치 완료	완료 즉시 표시(사용자 가시성 저하)
거대 커밋	3개 이상 파일 = 2개 이상 커밋
자기보고 신뢰	자체 툴 호출로 검증

10. 금지 작업 (Forbidden Actions)

금지:

작업	이유
as any 타입 억제	타입 안전성 저하
@ts-ignore, @ts-expect-error	타입 에러 은폐
요청 없는 커밋	사용자 동의 없음
추론 없는 코드 추측	파일 먼저 읽기
손상된 상태로 중지	실패 후 복원 필수
테스트 삭제로 "통과"	회피 - 고쳐야 함
숏건 디버깅	랜덤 변경 추정

11. 실패 복구 (Failure Recovery)

실패 후 절차:

1. 근본 원인 수정(증상 아님)
2. 모든 수정 후 재검증
3. 샷건 디버깅(랜덤 변경 회피) 금지

3회 연속 실패 후:

1. 모든 작업 즉시 중지
2. 마지막 작업 상태로 복원(git checkout/실행 취소)
3. 시도 사항 및 실패 기록
4. 전체 컨텍스트로 Oracle 상담
5. Oracle 해결 불가 시 → 사용자에게 물어보기

금지:

• 손상된 상태로 코드 방치
• 실패한 테스트 삭제로 "통과"
• 회피 없는 계속 시도

12. 완료 증거 요구사항 (Completion Evidence)

작업 완료 필수 조건:

• 모든 계획된 TODO 항목 완료 표시
• 변경된 파일에서 lsp_diagnostics 클린
• 빌드 명령어 존재 시 종료 코드 0
• 테스트 존재 시 통과(기존 실패 명시적 표기)
• 사용자 원시 요청 완전히 해결

증거 없음 = 작업 미완료

---

스킬 활성화 (Skill Activation)

자동 감지

신호	자동 활성화
"끝날 때까지 중지 안 함" / "완료 필수"	+ ralph-loop
UI/컴포넌트/스타일링 작업	+ frontend-ui-ux
"ultrawork" / "최대 속도" / "병렬"	+ ultrawork
다중 파일 git 변경	+ git-master
"계획해" / 전략적 토의	prometheus
"코드베이스 인덱싱" / "AGENTS.md 생성" / "구조 문서화"	deepinit

수동 슬래시 명령

명령어	설명
/ultrawork <task>	최대 성능 모드 - 모든 것 병렬화
/deepsearch <query>	철저한 코드베이스 검색
/deepinit [path]	계층적 AGENTS.md로 코드베이스 인덱싱
/analyze <target>	심층 분석 및 조사
/plan <description>	Prometheus로 계획 세션 시작
/review [plan-path]	Momus로 계획 검토
/prometheus <task>	면접 워크플로 전략적 계획
/ralph-loop <task>	작업 완료까지 자기 참조 루프
/cancel-ralph	활성 Ralph Loop 취소

---

요약 (Summary)

이 프로젝트는:

1. Claude Code CLI를 위한 멀티 에이전트 오케스트레이션 시스템
2. 지능형 모델 라우팅으로 토큰 효율화
3. 12개 전문화 에이전트와 5개 내장 스킬
4. 병렬 실행과 지속성 강제로 생산성 극대화
5. GitHub에서 oh-my-opencode에서 영감을 얻어 제작

핵심 철학:

• "The boulder never stops." (바위는 결코 멈추지 않는다.)
• 모든 작업이 완료될 때까지 지속
• 전문가에게 위임, 스스로 직접 구현하지 않음
• 모든 주장을 검증, 맹목하게 신뢰하지 않음