TRENDSHIFT 딥다이브 · 2026-04-02 분석

oh-my-claudecode 딥다이브
— Claude Code를 "AI 개발팀"으로 확장하는 멀티에이전트 오케스트레이션

매직 키워드 하나로 복잡한 멀티에이전트 파이프라인이 자동 실행됩니다. oh-my-claudecode는 19개 전문 에이전트, 40개 워크플로우 스킬, tmux 기반 병렬 실행을 갖춘 Claude Code 전용 오케스트레이션 프레임워크입니다. 한국인 개발자 허예찬(Yeachan Heo)이 만든 프로젝트로, 11개 언어 문서를 지원합니다. (저장소: Yeachan-Heo/oh-my-claudecode · ⭐28,652 · TypeScript · MIT)

프로젝트 한줄 요약
왜 주목받는가
기술 스택 전체 지도
아키텍처 심화 분석
디렉토리 구조 해부
학습 포인트 (기술별)
하드웨어 / 시스템 요구사항
직접 해볼 수 있는 실습 과제
관련 기술 심화 학습 로드맵
핵심 키워드 사전
참고 링크

1프로젝트 한줄 요약

oh-my-claudecode가 정확히 무엇을 하는 물건인가

oh-my-claudecode(OMC)는 Claude Code를 위한 팀 기반 멀티에이전트 오케스트레이션 프레임워크입니다. 19개 전문 에이전트를 조율하여 복잡한 개발 작업을 자동화하고, tmux 기반으로 병렬 에이전트를 실행하는 플러그인 시스템입니다.

항목	내용
GitHub	Yeachan-Heo/oh-my-claudecode
스타	⭐ 28,652 (2026-06-04 기준, .md의 13.9k에서 급증)
언어	TypeScript (Node.js 20+)
npm 패키지	oh-my-claude-sisyphus
라이선스	MIT

한 컷 비유

"Claude Code 한 명에게 '전문 팀 전체'를 붙여주는 마법 키워드 시스템"

Claude Code 혼자 일하면 뛰어난 개발자 1명입니다. autopilot: build a REST API라고 입력하는 순간, 설계자·실행자·검증자·코드 리뷰어가 tmux 창 여러 개에 동시에 나타나 협업합니다.

핵심은 "Convention over Configuration" 철학입니다. 복잡한 설정 없이 autopilot, ralph, team 같은 매직 키워드만 알면 됩니다.

2왜 주목받는가

트렌딩 이유와 경쟁 제품 대비 장점

2026년 들어 Claude Code가 터미널 기반 코딩 도구의 대세가 되면서, 그 위에 올리는 "오케스트레이션 레이어"에 대한 수요가 급증했습니다. OMC는 이 흐름의 한가운데에 있습니다.

기존 방식의 한계

단일 Claude Code 세션의 병목

복잡한 기능을 혼자 구현할 때 Claude Code 단일 세션은 컨텍스트 한계에 부딪힙니다. 여러 파일, 여러 작업을 병렬로 처리하지 못하고, 역할 분리 없이 코드 작성과 검토를 같은 에이전트가 담당합니다.

OMC의 해법

팀 파이프라인 + 병렬 에이전트

plan → PRD → exec → verify → fix의 스테이지 파이프라인으로 작업을 분리합니다. tmux 패인에서 최대 6개 에이전트가 동시에 실행되고, 작성자-검토자 분리로 코드 품질을 높입니다.

비교 대상	oh-my-claudecode 장점
순수 Claude Code	19개 전문 에이전트 자동 라우팅, 멀티에이전트 팀 파이프라인
Cursor / Windsurf	터미널 네이티브, tmux 기반 병렬 실행, CLI 파워유저 친화
GitHub Copilot Workspace	오픈소스, 커스텀 스킬 시스템, 자체 상태관리
obra/superpowers	팀 오케스트레이션에 집중, 더 정교한 파이프라인 스테이지 관리
LangGraph 등 범용 프레임워크	Claude Code에 특화, 플러그인 한 줄 설치, 별도 서버 불필요

3기술 스택 전체 지도

TypeScript 코어 + tmux 실행 환경

┌─────────────────────────────────────────────────┐ │ TypeScript (ES2022) │ │ Node.js >= 20.0.0 │ ├─────────────────────────────────────────────────┤ │ @anthropic-ai/claude-agent-sdk │ MCP SDK │ │ (에이전트 생성) │ (도구 통신) │ ├─────────────────────────────────────────────────┤ │ Commander.js │ Zod │ better-sqlite3 │ │ (CLI 파싱) │ (스키마) │ (로컬 상태 DB) │ └─────────────────────────────────────────────────┘

기술	역할	상세
TypeScript	메인 언어	ES2022 타겟, strict 모드, NodeNext 모듈
Claude Agent SDK	에이전트 생성·위임	@anthropic-ai/claude-agent-sdk ^0.1.0
MCP SDK	도구 통신 프로토콜	@modelcontextprotocol/sdk ^1.26.0
better-sqlite3	로컬 상태 저장소	세션 데이터, 분석 결과 영속화
tmux	멀티에이전트 세션 관리	각 워커를 별도 tmux 패인에서 실행
esbuild	번들러	TypeScript → JavaScript 빌드
Vitest	유닛/통합 테스트	UI 모드 지원, Jest 호환

4아키텍처 심화 분석

매직 키워드 라우터와 5가지 핵심 패턴

┌──────────────────────────────────────────────────────────────┐ │ 사용자 입력 (터미널) │ │ "autopilot: build a REST API" / "/team 3:executor fix bug" │ └───────────────────────┬──────────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 매직 키워드 라우터 │ │ autopilot │ ralph │ ulw(ultrawork) │ team │ deep-interview │ └───────────────────────┬──────────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 오케스트레이션 엔진 │ │ Team Pipeline: plan → PRD → exec → verify → fix → complete │ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ 모델 라우팅 │ │ 병렬 디스패치 │ │ 상태 머신 관리 │ │ │ │ Haiku↔Opus │ │ max 6 agents │ │ .omc/state/ │ │ │ └──────────────┘ └──────────────┘ └─────────────────┘ │ └──────────────────────────┬───────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 19개 전문 에이전트 풀 │ │ explorer · analyst · planner · architect · executor │ │ code-reviewer · security-reviewer · performance-review │ │ debugger · test-engineer · designer · writer │ └──────────────────────────┬───────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 실행 인프라 │ │ tmux 세션 관리 · git worktree 격리 · MCP 도구 서버 │ │ better-sqlite3 로컬 상태 DB · Discord/Slack 알림 시스템 │ └──────────────────────────────────────────────────────────────┘

핵심 설계 패턴

1. 매직 키워드 패턴 (Keyword-Triggered Workflow)

"Convention over Configuration" 철학. 사용자 입력에서 특정 키워드를 감지하면 워크플로우가 자동 활성화됩니다.

키워드	스킬	동작
`autopilot`	$autopilot	완전 자율 실행 파이프라인
`ralph`	$ralph	끈기 모드 — verify/fix 무한 루프
`ulw`	$ultrawork	최대 병렬성
`team`	$team	정식 팀 파이프라인 (plan→PRD→exec→verify→fix)
`deep-interview`	$deep-interview	소크라틱 요구사항 정제
`ccg`	$ccg	Codex + Gemini 합성

2. 스테이지 파이프라인 패턴 (Staged Pipeline)

각 스테이지는 명확한 완료 조건을 가지고 순차 실행됩니다:

[team-plan] → [team-prd] → [team-exec] → [team-verify] → [team-fix] ↑ │ └──────────────┘ (max N회 반복 후 실패)

3. 지능형 모델 라우팅 (Smart Model Routing)

작업 복잡도에 따라 자동으로 모델을 선택합니다:

단순 작업 (파일 이름 변경, 포맷팅) → Haiku (빠르고 저렴) 중간 작업 (코드 리뷰, 테스트 작성) → Sonnet (균형) 복잡 작업 (아키텍처 설계, 디버깅) → Opus (최고 품질)

4. 작성자-검토자 분리 (Writer/Reviewer Separation)

같은 에이전트가 코드를 작성하고 검토하지 않습니다. 반드시 별도 에이전트가 리뷰합니다:

executor (작성) → code-reviewer (검토) → executor (수정) security-reviewer performance-reviewer

5. 상태 머신 기반 영속성 (State Machine Persistence)

모든 오케스트레이션 상태가 .omc/ 디렉토리에 저장됩니다. 세션이 중단되어도 마지막 스테이지에서 재개 가능합니다.

.omc/ ├── state/ # 현재 모드 상태 (JSON) ├── plans/ # 계획 문서 (PRD, 테스트 스펙) ├── sessions/ # 세션 기록 (*.json) ├── notepad.md # 세션 메모 └── project-memory.json # 크로스 세션 지식

5디렉토리 구조 해부

src/team/이 프로젝트의 심장부

oh-my-claudecode/ ├── .claude-plugin/ # Claude Code 플러그인 매니페스트 ├── .mcp.json # MCP 서버 설정 ├── agents/ # 19개 에이전트 역할 정의 (마크다운) │ ├── architect.md # 시스템 설계 전문가 │ ├── executor.md # 실행 전문가 │ ├── debugger.md # 디버깅 전문가 │ ├── code-reviewer.md # 코드 리뷰어 │ └── ... (15개 더) │ ├── skills/ # 40개 워크플로우 스킬 (각각 폴더) │ ├── autopilot/ # 자율 실행 모드 │ ├── ralph/ # 끈기 모드 (verify/fix 루프) │ ├── ultrawork/ # 최대 병렬 모드 │ ├── team/ # 팀 파이프라인 │ ├── deep-interview/ # 소크라틱 인터뷰 │ ├── hud/ # 실시간 모니터링 HUD │ └── ... (34개 더) │ ├── src/ # TypeScript 소스 코드 │ ├── index.ts # 엔트리 포인트 │ ├── team/ # 팀 오케스트레이션 코어 (60개 파일!) │ │ ├── runtime.ts # 팀 런타임 v1 │ │ ├── runtime-v2.ts # 팀 런타임 v2 │ │ ├── phase-controller.ts # 파이프라인 스테이지 관리 │ │ ├── role-router.ts # 역할 기반 라우팅 │ │ ├── dispatch-queue.ts # 작업 큐 │ │ ├── tmux-session.ts # tmux 세션 관리 │ │ ├── tmux-comm.ts # tmux IPC 통신 │ │ ├── git-worktree.ts # 워크트리 격리 │ │ ├── merge-coordinator.ts # 병합 조율 │ │ ├── heartbeat.ts # 에이전트 생존 확인 │ │ └── ... (50개 더) │ ├── cli/ · commands/ · config/ · hooks/ │ ├── hud/ # 실시간 상태 표시 │ ├── mcp/ # MCP 서버/도구 구현 │ ├── notifications/ # Discord/Slack/Telegram 알림 │ └── autoresearch/ # 자율 연구 모듈 │ ├── CLAUDE.md # Claude Code 설정 (핵심!) ├── AGENTS.md # 에이전트 카탈로그 정의 └── package.json + tsconfig.json + vitest.config.ts

주목할 디렉토리

src/team/ (60개 파일) — 프로젝트의 심장부

팀 오케스트레이션의 모든 로직이 여기에 있습니다. phase-controller.ts, dispatch-queue.ts, worker-bootstrap.ts 등이 파이프라인의 핵심입니다. agents/ 19개 마크다운 파일은 Claude가 읽고 해당 역할로 동작하게 하는 "직무 기술서"입니다.

6학습 포인트 (기술별)

이 레포에서 무엇을 배울 수 있는가

A. 멀티에이전트 오케스트레이션

에이전트 역할을 마크다운으로 정의하는 "에이전트-as-프롬프트" 패턴
스테이지 파이프라인 (plan → PRD → exec → verify → fix)으로 복잡한 작업을 분할하는 방법
최대 6개 에이전트 병렬 실행 + 결과 병합 전략

B. Claude Code 플러그인 시스템

.claude-plugin/ 매니페스트 구조
Claude Code에 스킬, 훅, MCP 도구를 추가하는 방법
매직 키워드로 스킬을 트리거하는 패턴

C. MCP (Model Context Protocol)

@modelcontextprotocol/sdk를 사용한 MCP 서버 구축. Claude Code와 외부 도구 사이의 통신 프로토콜. src/mcp/ 디렉토리의 도구 구현 패턴을 학습할 수 있습니다.

D. tmux 기반 프로세스 관리

Node.js에서 tmux 세션을 프로그래밍적으로 생성/관리하는 방법. 여러 Claude 프로세스를 동시에 실행하고 통신하는 IPC 패턴. src/team/tmux-session.ts와 tmux-comm.ts의 세션 관리 로직을 분석하세요.

E. Git Worktree 활용

git worktree를 사용해 에이전트별 독립 작업 공간을 만드는 패턴. 여러 에이전트가 동시에 같은 레포의 다른 부분을 수정할 때의 충돌 해소 방법.

F. 상태 관리와 영속성

better-sqlite3를 사용한 로컬 상태 영속화. .omc/ 디렉토리의 파일 기반 상태 관리. 세션 중단 후 재개하는 체크포인트 패턴.

7하드웨어 / 시스템 요구사항

Claude Max 구독 또는 API 키 필요

요구사항	최소	권장
Node.js	>= 20.0.0	최신 LTS (22.x)
Claude Code CLI	설치 필수	최신 버전
구독	Claude Pro 또는 API 키	Claude Max (팀 기능 위해)
tmux	설치 필수 (팀/병렬 기능)	tmux 3.x+
OS	macOS / Linux	macOS
RAM	8GB	16GB+ (다수 에이전트 병렬 시)

# 방법 1: Claude Code 플러그인으로 설치
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

# 방법 2: npm 글로벌 설치
npm i -g oh-my-claude-sisyphus@latest

# Teams 기능 활성화 (~/.claude/settings.json)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

8직접 해볼 수 있는 실습 과제

난이도별 실습

LEVEL 1 · 초급

autopilot으로 간단한 앱 만들기 ⏱ 30분

oh-my-claudecode 설치 후 아래 명령어를 입력해보세요. autopilot이 어떤 순서로 작업하는지, 어떤 에이전트가 활성화되는지 HUD로 확인합니다.

autopilot: build a simple TODO CLI app in TypeScript

LEVEL 2 · 중급

Team 파이프라인으로 REST API 만들기 ⏱ 1시간

plan → PRD → exec → verify → fix 각 스테이지가 어떻게 전환되는지 추적하세요. .omc/plans/ 폴더에 생성되는 PRD 문서를 분석합니다.

/team 3:executor "Build a REST API with Express.js for managing books"

LEVEL 3 · 중급

커스텀 에이전트 역할 정의 ⏱ 1~2시간

agents/ 디렉토리의 기존 에이전트 정의 파일을 읽고, 같은 형식으로 agents/korean-docs-writer.md 같은 커스텀 에이전트를 작성하여 팀 모드에서 호출되는지 테스트해보세요.