oh-my-claudecode (OMC) 완전 가이드

oh-my-claudecode (OMC) 완전 정복 가이드

버전: v4.6.0 기준 | 최종 업데이트: 2026-03-04
Claude Code를 500% 활용하기 위한 실전 가이드.
"도구가 아니라 무기다 (A weapon, not a tool)"

---

목차

1. OMC가 필요한 이유
2. 설치 및 초기 설정
3. 핵심 개념: 에이전트 오케스트레이션
4. 실행 모드 완전 정리
5. 30종 에이전트 카탈로그
6. 매직 키워드 & 스킬 레퍼런스
7. 메모리 시스템 활용
8. MCP 도구 심층 활용
9. 멀티 AI 오케스트레이션 (Claude + Gemini + Codex)
10. 실전 시나리오별 워크플로우
11. Hook 시스템 이해하기
12. 비용 최적화 전략
13. 알림 시스템 설정
14. 환경 변수 & 설정 레퍼런스
15. 트러블슈팅
16. 빠른 참조 카드

---

1. OMC가 필요한 이유

일반 Claude Code의 한계

Claude Code는 강력하지만 기본 상태에서는 한 번에 하나씩 작업합니다. 대규모 기능을 구현할 때 다음과 같은 문제가 생깁니다.

[일반 Claude Code]

사용자: "회원가입/로그인/프로필 수정 기능 전부 만들어줘"

Claude: (혼자서 순차적으로...)
  → 회원가입 구현 중...  (10분)
  → 로그인 구현 중...    (8분)
  → 프로필 구현 중...    (7분)
  → 총 25분 소요, 중간에 컨텍스트 잃어버림

OMC가 있으면

[OMC Claude Code]

사용자: "ralph: 회원가입/로그인/프로필 수정 기능 전부 만들어줘"

Claude (지휘자):
  ├── executor #1 → 회원가입 API 구현  ─┐
  ├── executor #2 → 로그인 API 구현    ─┼─ (동시에!)
  ├── executor #3 → 프로필 API 구현   ─┘
  ├── test-engineer → 테스트 코드 작성
  └── verifier → "모두 완료됐는지 확인"

  → 총 8분 소요, verifier가 완료 보증

OMC가 주는 핵심 가치

가치	설명	체감 효과
속도	독립적인 작업 병렬 처리	3~5배 빠름
완성도	verifier가 완료 보증	"다 됐다" 믿을 수 있음
비용	작업 난이도별 모델 자동 선택	30~50% 절감
품질	전문 에이전트 역할 분리	코드 품질 향상
지속성	ralph 모드로 완료까지 반복	중간에 포기 없음

---

2. 설치 및 초기 설정

설치 (2단계)

Step 1: 플러그인 설치

Claude Code 터미널에서 실행:

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

Step 2: 초기 설정

/oh-my-claudecode:omc-setup

설정 마법사가 다음을 자동 구성합니다.

• ~/.claude/CLAUDE.md — OMC 지시문 (에이전트/스킬 정의)
• ~/.claude/settings.json — 플러그인 등록, HUD, 환경변수
• Hook 시스템 활성화

설치 확인

/omc-doctor

출력 예시:

OMC Health Check
✓ Plugin installed: v4.6.0
✓ CLAUDE.md configured
✓ Hooks active (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse)
✓ Team mode: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
✓ HUD statusline active

settings.json 기본 구조

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/hud/omc-hud.mjs"
  },
  "enabledPlugins": {
    "oh-my-claudecode@omc": true
  }
}

프로젝트 첫 시작

새 프로젝트에 들어가면 항상 이것부터:

/deepinit

OMC가 프로젝트 구조를 분석하고 AGENTS.md 계층 문서를 자동 생성합니다.

실행 결과:
  AGENTS.md              ← 루트 문서 (전체 구조, 기술 스택)
  src/AGENTS.md          ← 소스 디렉토리 문서
  src/app/AGENTS.md      ← App Router 라우팅 문서
  src/components/AGENTS.md ← 컴포넌트 문서

---

3. 핵심 개념: 에이전트 오케스트레이션

아키텍처 구조

┌──────────────────────────────────────────────────────────┐
│  사용자 (VSCode / 터미널)                                  │
└───────────────────────────┬──────────────────────────────┘
                            │ 프롬프트
                            ▼
┌──────────────────────────────────────────────────────────┐
│  Claude Code + OMC 플러그인                                │
│                                                           │
│  Hook 시스템            CLAUDE.md 지시문                  │
│  (자동 트리거/키워드 감지)  (에이전트/스킬/동작 정의)        │
│                ↓                    ↓                     │
│  ┌─────────────────────────────────────────┐             │
│  │         오케스트레이션 엔진              │             │
│  │                                         │             │
│  │  ┌──────────┐  ┌──────────┐  ┌──────┐  │             │
│  │  │ explore  │  │executor  │  │verify│  │             │
│  │  │ (haiku)  │  │(sonnet)  │  │(son) │  │             │
│  │  └──────────┘  └──────────┘  └──────┘  │             │
│  │         병렬 또는 순차 실행              │             │
│  └─────────────────────────────────────────┘             │
│                                                           │
│  MCP 도구            메모리             상태              │
│  (LSP, AST, REPL)   (notepad)         (.omc/)            │
└──────────────────────────────────────────────────────────┘

모델 라우팅: 비용 최적화의 핵심

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

haiku  (저비용, 빠름)
  → 파일 탐색, 구조 분석, 문서 작성, 간단한 검색
  → 예: explore, writer 에이전트

sonnet (중간 비용, 균형)
  → 일반 구현, 테스트, 디버깅, 리팩토링
  → 예: executor, test-engineer, debugger 에이전트

opus   (고비용, 최고 성능)
  → 아키텍처 설계, 복잡한 분석, 종합 리뷰, 비판적 검토
  → 예: architect, code-reviewer, critic 에이전트

실제로 이렇게 동작합니다:

사용자: "autopilot: 인증 시스템 만들어줘"

OMC 내부:
  1. explore    (haiku)  → 현재 코드 구조 파악
  2. planner    (opus)   → 구현 계획 수립
  3. architect  (opus)   → 인터페이스 설계
  4. executor   (sonnet) × 3 → 병렬 구현
  5. test-engineer (sonnet) → 테스트 작성
  6. verifier   (sonnet) → 완료 검증

파일 구조

~/.claude/
├── CLAUDE.md              ← OMC 핵심 지시문
├── settings.json          ← 설정 파일
└── plugins/cache/omc/     ← 플러그인 소스

프로젝트/
├── .omc/
│   ├── state/             ← 실행 모드 상태
│   ├── notepad.md         ← 영구 메모 (컨텍스트 압축에도 유지)
│   ├── project-memory.json ← 프로젝트 메모리
│   ├── plans/             ← 계획 문서
│   ├── prd.json           ← PRD (v4.6.0 ralph 자동 생성)
│   └── logs/              ← 실행 로그
├── AGENTS.md              ← AI용 프로젝트 문서 (deepinit 생성)
└── src/AGENTS.md

---

4. 실행 모드 완전 정리

모드 강도 스펙트럼

낮음 ◄────────────────────────────────────────────► 높음
     대화    plan   autopilot   ralph   team ralph
     (단일)  (계획)  (자율실행)  (무한)  (팀+무한)

Autopilot — 완전 자율 실행

복잡한 단일 기능 구현에 최적. 계획부터 검증까지 자동.

트리거 키워드: autopilot:, build me, I want a

사용자: "autopilot: 할일 목록(Todo) 앱 페이지 만들어줘"

Phase 1 — 확장 (Expansion)
  "할일 목록"을 구체적 요구사항으로 확장
  → 할일 추가/삭제/완료 토글, 로컬 상태 관리, 반응형 UI

Phase 2 — 계획 (Planning)
  planner 에이전트가 작업 분해
  → Todo 타입 정의 → TodoItem 컴포넌트 → TodoList → 페이지 통합

Phase 3 — 실행 (Execution)
  executor 에이전트들 병렬 구현
  → src/types/todo.ts 생성
  → src/components/TodoItem.tsx 생성
  → src/components/TodoList.tsx 생성
  → src/app/todos/page.tsx 수정

Phase 4 — QA
  qa-tester 가 빌드/린트/테스트 실행
  → npm run build → 통과
  → npm run lint  → 통과

Phase 5 — 검증 (Verification)
  verifier 에이전트가 요구사항 체크리스트 확인
  → ✓ 할일 추가 기능
  → ✓ 삭제 기능
  → ✓ 완료 토글
  → "완료 확인됨"

Ralph — 끝까지 멈추지 않는 모드

v4.6.0부터 Ralph는 자동으로 prd.json을 생성합니다. 모든 수용 기준이 통과할 때까지 반복합니다.

트리거 키워드: ralph:, don't stop, must complete

사용자: "ralph: 이 앱에 JWT 인증 시스템 전체 구현해줘"

자동 생성: .omc/prd.json
  {
    "title": "JWT 인증 시스템",
    "acceptance_criteria": [
      "회원가입 API (/api/auth/register) 동작",
      "로그인 API (/api/auth/login) JWT 발급",
      "보호된 라우트에서 토큰 검증",
      "리프레시 토큰 갱신",
      "모든 에러 케이스 핸들링"
    ]
  }

Iteration 1: 기본 구조 + 회원가입 구현
Iteration 2: 로그인 + JWT 발급 구현
Iteration 3: 미들웨어 + 토큰 검증 구현
Iteration 4: 리프레시 토큰 구현
Iteration 5: verifier 검증 → "에러 핸들링 미흡"
Iteration 6: 에러 핸들링 전체 보강
Iteration 7: verifier 검증 → "모든 기준 통과" → 완료

PRD 없이 시작하려면: "ralph --no-prd: 로그인 기능 만들어줘"

Ultrawork — 최대 병렬 실행

5개 이상의 에이전트를 동시에 투입. 독립적인 작업 대량 처리에 최적.

트리거 키워드: ultrawork, ulw

사용자: "ulw: 이 5개 API 엔드포인트 전부 구현해줘
        (users, posts, comments, likes, notifications)"

동시 실행:
  executor #1 → /api/users 구현    ─┐
  executor #2 → /api/posts 구현    ─┤
  executor #3 → /api/comments 구현 ─┤ 병렬
  executor #4 → /api/likes 구현    ─┤
  executor #5 → /api/notifications ─┘

총 소요 시간 ≈ 단일 작업 시간 × 1.2 (병렬 오버헤드 포함)

Ecomode — 토큰 효율 최대화

비용이 중요할 때. 가능한 한 저렴한 모델 우선 사용.

트리거 키워드: eco

사용자: "eco: 린트 에러 전부 수정해줘"

→ haiku 모델로 먼저 시도
→ haiku가 해결 못하면 sonnet으로 에스컬레이션
→ opus는 절대적으로 필요한 경우에만 사용
→ 예상 비용 절감: 30~50%

Team — 네이티브 팀 협업

Claude Code 네이티브 팀 기능을 활용한 조율 방식.

트리거 키워드: team

사용자: "team 3:executor 모든 컴포넌트 테스트 코드 작성"

→ executor 에이전트 3개가 팀으로 조율하며 작업
→ 실시간 메시지로 작업 상태 공유
→ 공유 태스크 리스트에서 각자 작업 픽업

파이프라인:
  team-plan → team-prd → team-exec → team-verify → team-fix

Deep Interview — 막연한 아이디어 명확화

v4.6.0 신기능. 실행 전 소크라테스식 질문으로 모호함을 제거합니다.

트리거 키워드: /deep-interview

사용자: "/deep-interview '대시보드 만들어줘'"

OMC가 수학적 모호성 점수를 계산하고 질문 생성:

Q1: "어떤 종류의 데이터를 보여주는 대시보드인가요?
    (a) 사용자 분석  (b) 매출 현황  (c) 시스템 모니터링  (d) 기타"

Q2: "실시간 업데이트가 필요한가요?"

Q3: "대상 사용자는 누구인가요? 기술적 지식 수준은?"

→ 명확성 점수가 임계값 이상이 되면 실행 시작
→ 애매한 요구사항으로 인한 재작업 방지

사용 시점: 요구사항이 추상적이거나 규모가 큰 작업 전

Plan — 전략적 계획 수립

실행 전 계획을 먼저 세우고 승인을 받는 방식.

트리거 키워드: plan this:, plan the

사용자: "plan this: 결제 시스템 연동"

→ 현재 코드 분석 (explore)
→ 구현 계획 상세 작성
→ 계획을 사용자에게 제시 → 승인 요청

출력 예시:
  구현 계획: 결제 시스템 연동

  Step 1: 환경 변수 설정 (5분)
    - .env에 STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY 추가

  Step 2: Stripe SDK 설치 및 클라이언트 설정 (10분)
    - npm install @stripe/stripe-js stripe
    - src/lib/stripe.ts 생성

  Step 3: 결제 API 라우트 구현 (20분)
    - POST /api/checkout → Stripe 세션 생성
    - GET /api/checkout/success → 결제 확인

  Step 4: 프론트엔드 결제 버튼 구현 (15분)
    - src/components/CheckoutButton.tsx 생성

  Step 5: 웹훅 처리 (15분)
    - POST /api/webhooks/stripe → 결제 완료 처리

  이 계획으로 진행할까요?

Ralplan — 합의 기반 계획

Planner, Architect, Critic 세 에이전트가 합의에 이를 때까지 반복 검토.

트리거 키워드: ralplan, consensus plan

사용자: "ralplan: 멀티테넌트 SaaS 아키텍처 설계해줘"

Round 1:
  planner   → 초안 작성 (마이크로서비스 제안)
  architect → 검토: "데이터 격리 방식 명시 필요"
  critic    → 비판: "배포 복잡성 과소평가됨"

Round 2:
  planner   → 수정안 (모놀리스 + 모듈식)
  architect → 수정: "테넌트별 스키마 격리 추가"
  critic    → "허용 가능, 스케일링 계획 보강 필요"

Round 3:
  합의 도달 → 최종 아키텍처 문서 생성

옵션: "ralplan --deliberate: ..." 
  → 사전 위험 분석 + 확장된 테스트 계획 포함

모드별 추천 상황

작업	추천 모드	이유
버그 1개	일반 대화	단순, 빠름
컴포넌트 1개 추가	plan → 직접 구현	계획 후 실행
기능 1개 (여러 파일)	autopilot:	자동 계획~검증
대규모 기능	ralph:	완료까지 반복
풀스택 프로젝트	team + ralph:	팀 + 무한반복
여러 파일 리팩토링	ulw	병렬 처리
아키텍처 설계	ralplan:	전문가 합의
막연한 아이디어	/deep-interview	명확화 먼저
비용 절감	eco:	저렴한 모델 우선

---

5. 30종 에이전트 카탈로그

빌드 & 분석 에이전트

에이전트	모델	핵심 역할	실전 사용 예시
explore	haiku	코드 탐색, 파일/심볼 매핑	"이 프로젝트에서 인증 관련 파일 찾아줘"
analyst	opus	요구사항 분석, 수용 기준 정의	"이 기능의 엣지케이스 모두 정리해줘"
planner	opus	작업 순서 계획, 실행 계획 수립	"마이그레이션을 어떤 순서로 해야 해?"
architect	opus	시스템 설계, 인터페이스 정의	"확장 가능한 API 구조 설계해줘"
debugger	sonnet	근본 원인 분석, 회귀 분리	"이 TypeError가 왜 나는지 추적해줘"
executor	sonnet	코드 구현, 리팩토링	"이 함수 TypeScript로 변환해줘"
deep-executor	opus	복잡한 자율 구현	대규모, 다파일 구현 작업
verifier	sonnet	완료 증거 수집, 검증	"정말 모든 기능이 동작하는지 확인해줘"

리뷰 에이전트

에이전트	모델	핵심 역할	실전 사용 예시
quality-reviewer	sonnet	로직 결함, 안티패턴, 성능 이슈	코드 품질 점검
security-reviewer	sonnet	보안 취약점, 인증/인가, SQL 인젝션	배포 전 보안 감사
code-reviewer	opus	종합 리뷰, API 계약, 하위호환성	PR 최종 리뷰

리뷰 에이전트 직접 호출 예시:

"review code"       → code-reviewer 에이전트 실행
"security review"   → security-reviewer 에이전트 실행

도메인 전문가 에이전트

에이전트	모델	핵심 역할	실전 사용 예시
test-engineer	sonnet	테스트 전략, 커버리지, TDD	"이 함수 단위 테스트 작성해줘"
build-fixer	sonnet	빌드/타입 에러 수정	"타입 에러 전부 고쳐줘"
designer	sonnet	UI/UX 설계, 컴포넌트 디자인	"이 폼 UX 개선해줘"
writer	haiku	기술 문서, README, 주석	"이 API 문서 작성해줘"
qa-tester	sonnet	런타임 검증, E2E 테스트	"실제로 실행해서 테스트해봐"
scientist	sonnet	데이터/통계 분석	"이 로그 데이터 패턴 분석해줘"
document-specialist	sonnet	외부 공식 문서 조회	"Next.js 15 공식 문서 확인해줘"
git-master	sonnet	Git 작업, 커밋 관리, 브랜치 전략	"커밋 정리하고 PR 설명 작성해줘"
code-simplifier	opus	코드 단순화, 중복 제거, 정리	"이 복잡한 로직 단순화해줘"

조율 에이전트

에이전트	모델	핵심 역할	실전 사용 예시
critic	opus	계획/설계 비판적 검토, 약점 발견	"이 아키텍처 계획에 문제점 찾아줘"

---

6. 매직 키워드 & 스킬 레퍼런스

매직 키워드 전체 목록

프롬프트에 이 키워드를 포함하면 자동으로 해당 모드가 활성화됩니다.

키워드	실행 모드	실제 사용 예시
autopilot:	완전 자율 실행	"autopilot: 검색 기능 추가해줘"
build me	완전 자율 실행	"build me a REST API"
ralph:	완료까지 반복	"ralph: 인증 시스템 전체 구현"
don't stop	완료까지 반복	"don't stop until all tests pass"
ulw	최대 병렬	"ulw 이 10개 컴포넌트 전부 리팩토링"
ultrawork	최대 병렬	"ultrawork: API 5개 동시 구현"
eco	토큰 효율	"eco: 린트 에러 전부 수정"
plan this:	계획 수립	"plan this: 결제 시스템 연동"
ralplan	합의 기반 계획	"ralplan: DB 스키마 설계"
team	팀 협업	"team 3:executor 테스트 작성"
analyze	분석/디버깅	"analyze: 이 메모리 누수 원인"
debug	분석/디버깅	"debug: 이 API가 500 에러 내는 이유"
review code	코드 리뷰	"review code"
security review	보안 리뷰	"security review"
fix build	빌드 수정	"fix build"
type errors	타입 에러 수정	"fix all type errors"
tdd	테스트 주도 개발	"tdd: 로그인 기능"

슬래시 명령어 전체 목록

직접 타이핑하는 명령어들:

핵심 워크플로우

/deepinit              → 프로젝트 AGENTS.md 계층 문서 자동 생성
/deep-interview        → 소크라테스식 요구사항 명확화 (v4.6.0)
/autopilot             → 자율 실행 모드
/ralph                 → 반복 완료 모드
/ultrawork             → 최대 병렬 모드
/team                  → 네이티브 팀 협업
/plan                  → 계획 수립
/ralplan               → 합의 기반 계획
/analyze               → 분석/디버깅

코드 품질

/code-review           → 종합 코드 리뷰 (opus)
/security-review       → 보안 취약점 점검
/build-fix             → 빌드 에러 수정
/tdd                   → 테스트 주도 개발
/sciomc                → 과학적 데이터 분석 (병렬 scientist)

멀티 AI

/omc-teams             → tmux 기반 외부 AI 워커 (Codex, Gemini)
/ccg                   → 3모델 동시 활용 (Claude+Codex+Gemini)

유틸리티

/note [내용]           → 메모 저장
/cancel                → 현재 모드 취소
/cancel --force        → 모든 상태 초기화
/trace                 → 에이전트 실행 타임라인
/hud                   → HUD 상태바 설정
/learner               → 현재 세션에서 재사용 패턴 추출
/skill                 → 로컬 커스텀 스킬 관리
/configure-notifications → 알림 설정
/omc-setup             → OMC 재설정
/omc-doctor            → 설치 진단
/omc-help              → 도움말

---

7. 메모리 시스템 활용

컨텍스트가 압축되어도 중요한 정보가 사라지지 않게 하는 것이 핵심입니다.

메모리 종류 비교

종류	위치	수명	용도
Priority Context	.omc/notepad.md	영구	프로젝트 핵심 규칙
Working Memory	.omc/notepad.md	7일	임시 작업 메모
Manual	.omc/notepad.md	영구	수동 관리 항목
Project Memory	.omc/project-memory.json	영구	기술 스택, 컨벤션
Auto Memory	~/.claude/projects/*/memory/	영구	세션 간 자동 학습

Notepad 활용법

# 영구 기억 (컨텍스트 압축에도 유지)
<remember priority>
이 프로젝트는 반드시 bun 사용 (npm, yarn 금지)
TypeScript strict mode 항상 활성화
Tailwind CSS만 사용, styled-components 금지
</remember>

# 7일간 기억 (작업 중 메모)
<remember>
오늘 발견한 버그: UserContext가 SSR에서 hydration 오류 발생
원인: useLayoutEffect 사용 → useEffect로 교체 필요
</remember>

/note 명령어 활용

/note API 엔드포인트 목록:
  POST /api/auth/register  → 회원가입
  POST /api/auth/login     → 로그인
  DELETE /api/auth/logout  → 로그아웃
  GET /api/users/me        → 내 정보 조회

Project Memory 설정

.omc/project-memory.json을 직접 편집하거나 OMC에게 요청:

"project_memory_add_directive 도구를 사용해서:
  directive: '항상 Server Components 우선 사용, Client Components는 최소화'
  priority: 'high'"

권장 project-memory.json 구조:

{
  "techStack": "Next.js 15, React 19, TypeScript 5.4, Tailwind v4",
  "runtime": "bun",
  "build": "bun run dev / bun run build",
  "conventions": "App Router, Server Components 기본, Zustand 상태관리",
  "structure": "src/app/ 라우팅, src/components/ 컴포넌트, src/lib/ 유틸",
  "testing": "vitest + testing-library",
  "directives": [
    { "directive": "TypeScript strict mode 항상 사용", "priority": "high" },
    { "directive": "컴포넌트는 반드시 타입 정의 포함", "priority": "high" },
    { "directive": "console.log 대신 logger 사용", "priority": "medium" }
  ]
}

실전: 컨텍스트 압축 대비하기

긴 작업 중간에 컨텍스트가 압축되어도 중요한 정보가 유지되게:

# 작업 시작 시
<remember priority>
현재 작업: 결제 시스템 연동
완료된 것: Stripe SDK 설치, /api/checkout 라우트 생성
다음 작업: 웹훅 처리 (/api/webhooks/stripe)
주의사항: Stripe webhook 시크릿은 STRIPE_WEBHOOK_SECRET 환경변수
</remember>

---

8. MCP 도구 심층 활용

LSP (Language Server Protocol) 도구

IDE 수준의 코드 이해를 Claude에게 부여합니다.

타입 정보 확인

사용자: "이 파일의 UserProfile 컴포넌트 props 타입 보여줘"

→ lsp_hover 실행
→ 출력: UserProfile의 props 인터페이스 전체 표시

심볼 참조 추적

사용자: "useAuth 훅이 어디서 쓰이고 있어?"

→ lsp_find_references 실행
→ 출력:
  src/app/dashboard/page.tsx:12
  src/app/profile/page.tsx:8
  src/components/Header.tsx:23
  총 3개 파일, 3개 참조

프로젝트 전체 에러 확인

사용자: "프로젝트 전체에 타입 에러 있어?"

→ lsp_diagnostics_directory 실행
→ 출력:
  src/lib/api.ts:45 - Type 'string | undefined' is not assignable to type 'string'
  src/components/Form.tsx:12 - Property 'onSubmit' is missing
  총 2개 에러 발견

전체 심볼 이름 변경

사용자: "getUserInfo 함수를 fetchUserProfile로 이름 바꿔줘 (전체 파일)"

→ lsp_rename 실행
→ 모든 파일에서 참조까지 동시에 변경됨

LSP 도구 전체 목록

도구	기능
lsp_hover	심볼의 타입/문서 정보
lsp_goto_definition	정의 위치로 이동
lsp_find_references	모든 참조 검색
lsp_document_symbols	파일 내 심볼 목록
lsp_workspace_symbols	워크스페이스 심볼 검색
lsp_diagnostics	파일 에러/경고 확인
lsp_diagnostics_directory	프로젝트 전체 에러 확인
lsp_rename	심볼 전체 이름 변경
lsp_code_actions	리팩토링/퀵픽스 제안

AST Grep — 구조적 코드 검색/치환

텍스트 검색이 아닌 구문 구조 기반 검색. 훨씬 정확합니다.

패턴 검색

# 모든 console.log 찾기
ast_grep_search: pattern="console.log($MSG)"

# 모든 useState 사용처 찾기
ast_grep_search: pattern="useState($INIT)"

# 특정 컴포넌트 사용 찾기
ast_grep_search: pattern="<Button $$$PROPS />"

# async/await 없는 fetch 호출 찾기
ast_grep_search: pattern="fetch($URL)"

패턴 치환 (전체 파일 일괄 적용)

# console.log → logger.info 전체 교체
ast_grep_replace:
  pattern: "console.log($MSG)"
  replace: "logger.info($MSG)"

# React.FC → 직접 함수 타입으로 변경
ast_grep_replace:
  pattern: "const $NAME: React.FC<$PROPS>"
  replace: "function $NAME($PROPS: $PROPS)"

Python REPL — 데이터 분석

세션 간 변수가 유지되는 영속적 Python 환경.

# CSV 데이터 분석
action: "execute"
code: """
import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv('data/users.csv')
print(df.describe())
print(f"\n활성 사용자 수: {df[df['active'] == True].shape[0]}")
"""

# 분석 결과를 다음 호출에서도 사용 가능 (변수 유지됨)
action: "execute"
code: "df.groupby('region')['revenue'].sum().plot(kind='bar')"

---

9. 멀티 AI 오케스트레이션

Claude, Gemini, Codex를 동시에 활용하는 OMC의 고급 기능.

/omc-teams — tmux 기반 외부 AI 워커

실제 Gemini CLI, Codex CLI 프로세스를 tmux 패널에서 실행.

요구사항: tmux 설치 필요

# Codex에게 코드 리뷰 요청
/omc-teams 1:codex 이 PR 코드 리뷰해줘

# Gemini에게 UI 디자인 검토 요청 (1M 컨텍스트 활용)
/omc-teams 1:gemini 전체 codebase의 UI/UX 일관성 검토해줘

# Claude 워커 2개 병렬 실행
/omc-teams 2:claude 각자 다른 모듈 구현해줘

각 AI의 강점

AI	강점	추천 작업
Claude	지휘/종합/복잡한 추론	오케스트레이션, 아키텍처
Gemini	1M 컨텍스트, UI/UX	대규모 코드베이스 분석, 디자인 검토
Codex	코드 분석, 보안	아키텍처 검증, 보안 리뷰

/ccg — 3모델 동시 활용

사용자: "/ccg 이 인증 시스템 전체 리뷰해줘"

내부 실행:
  Codex    → 백엔드 보안, 알고리즘 분석
  Gemini   → 프론트엔드 UX, 전체 코드베이스 일관성
     ↓            ↓
  Claude   → 두 결과 종합 → 최종 리뷰 보고서 생성

Rate Limit 자동 대기

OMC는 Claude Code의 rate limit을 자동으로 처리합니다.

# 상태 확인 및 안내
omc wait

# 자동 재개 데몬 활성화 (tmux 필요)
omc wait --start

# 데몬 비활성화
omc wait --stop

---

10. 실전 시나리오별 워크플로우

시나리오 1: 새 프로젝트 킥오프

# 1단계: 프로젝트 문서화
/deepinit

# 2단계: 아키텍처 합의
ralplan: 전체 시스템 아키텍처 설계해줘 (기술 스택: Next.js 15, PostgreSQL, Redis)

# 3단계: 핵심 요구사항 명확화
/deep-interview '소셜 로그인이 있는 SaaS 앱'

# 4단계: 팀으로 구현
team ralph: 기본 CRUD 기능 전체 구현해줘

시나리오 2: 기능 추가

# 요구사항이 명확할 때
autopilot: 이메일 알림 기능 추가해줘
  (가입 환영, 비밀번호 재설정, 주문 확인 이메일)

# 요구사항이 모호할 때
/deep-interview '알림 기능 추가'
→ 명확화 후 →
autopilot: [명확해진 요구사항]으로 구현해줘

시나리오 3: 레거시 코드 리팩토링

# 1단계: 현황 파악
"analyze: 이 코드베이스의 기술 부채 파악해줘"

# 2단계: 계획
"plan this: JavaScript → TypeScript 마이그레이션"

# 3단계: 병렬 실행
"ulw: 이 15개 파일 전부 TypeScript로 변환해줘"

# 4단계: 검증
"review code"
"fix build"

시나리오 4: 버그 추적 및 수정

# 에러 메시지를 그대로 붙여넣기
"analyze: 
  Error: Cannot read property 'user' of undefined
  at AuthMiddleware (middleware.ts:45)
  at Layer.handle [as handle_request]"

→ debugger 에이전트가:
  1. 스택 트레이스 분석
  2. AuthMiddleware 코드 확인
  3. 근본 원인 파악: user 객체가 초기화 전에 접근됨
  4. 수정 방안 제시

# 수정
"fix build" 또는 직접 수정 지시

시나리오 5: 배포 전 코드 리뷰

# 전체 리뷰 파이프라인
"review code"          → 로직, 안티패턴, 성능
"security review"      → 보안 취약점 점검
"/sciomc 성능 분석"    → 데이터 분석 (선택)

# 발견된 문제 일괄 수정
"ralph: 코드 리뷰에서 발견된 모든 문제 수정해줘"

시나리오 6: TDD 개발

# 테스트 먼저, 구현 나중
"tdd: 사용자 인증 서비스 개발해줘"

→ test-engineer 에이전트:
  1. 테스트 케이스 목록 작성
  2. 실패하는 테스트 작성 (Red)
  3. executor에게 구현 위임
  4. 테스트 통과 확인 (Green)
  5. 리팩토링 (Refactor)
  6. 반복

시나리오 7: 데이터 분석 작업

# 로그 데이터 분석
"/sciomc 이 CSV 파일 분석해줘:
  - 사용자 행동 패턴
  - 이탈 원인 분석
  - 매출 기여도 높은 기능"

→ 여러 scientist 에이전트 병렬 실행
→ Python REPL로 pandas/matplotlib 분석
→ 종합 보고서 생성

시나리오 8: Git 작업 자동화

# 커밋 정리
"git-master에게 위임: 지금까지 변경된 파일들 의미있는 단위로 커밋 정리해줘"

# PR 준비
"git-master: 이 변경사항 PR 설명 작성해줘 (한국어, 변경 이유/내용/테스트 방법 포함)"

# 브랜치 전략
"git-master: feature/auth-system 브랜치에서 작업하고 main에 squash merge 준비해줘"

---

11. Hook 시스템 이해하기

Hook이란?

Claude Code의 특정 이벤트에 자동으로 실행되는 스크립트입니다. OMC는 이를 통해 컨텍스트를 주입하고 스킬을 자동 트리거합니다.

Hook 타이밍

세션 시작 ──────────► SessionStart hook
                       "OMC 초기화, notepad/project-memory 로드,
                        현재 실행 모드 상태 복구"

프롬프트 제출 ─────► UserPromptSubmit hook
                       "매직 키워드 감지, 스킬 자동 매핑,
                        컨텍스트 주입"

도구 사용 전 ──────► PreToolUse hook
                       "병렬 읽기 권장 힌트,
                        관련 파일 사전 로드 제안"

도구 사용 후 ──────► PostToolUse hook
                       "결과 검증, 후속 조치 제안,
                        에러 감지 시 자동 수정 제안"

대화 중 나오는 메시지 해석

<system-reminder>hook success: Success</system-reminder>
→ 정상 작동 중, 무시하고 진행

<system-reminder>hook additional context: 
  병렬 파일 읽기를 사용하면 성능이 향상됩니다.
</system-reminder>
→ 유용한 힌트, 참고하여 적용

<system-reminder>[MAGIC KEYWORD: ralph detected]</system-reminder>
→ ralph 모드 자동 활성화됨

<system-reminder>The boulder never stops rolling</system-reminder>
→ ralph/ultrawork 활성 상태, 계속 실행 중

Hook 비활성화 (필요한 경우)

# 전체 비활성화
export DISABLE_OMC=1

# 특정 hook만 건너뛰기
export OMC_SKIP_HOOKS=PreToolUse,PostToolUse

---

12. 비용 최적화 전략

모델별 비용 비교

haiku   ─── 기준 비용 1x   (가장 저렴)
sonnet  ─── 기준 비용 5x   (중간)
opus    ─── 기준 비용 15x  (가장 비쌈)

비용 절감 전략

전략 1: Ecomode 적극 활용

# 단순한 작업은 무조건 eco
"eco: 모든 파일에서 불필요한 console.log 제거"
"eco: import 정리해줘"
"eco: 주석 번역해줘 (영어 → 한국어)"

전략 2: 작업 복잡도에 맞는 모드 선택

버그 1개 → 직접 대화 (불필요한 에이전트 호출 없음)
컴포넌트 1개 → 직접 대화
여러 파일 → autopilot 또는 ulw
대규모 기능 → ralph (내부적으로 최적 모델 선택)

전략 3: /note로 반복 탐색 방지

# 자주 쓰는 정보를 미리 저장해두면
# 매번 explore 에이전트 호출 비용 절감
/note 
  Auth 관련 파일:
  - src/lib/auth.ts (JWT 유틸)
  - src/middleware.ts (토큰 검증)
  - src/app/api/auth/ (API 라우트)

전략 4: deepinit으로 탐색 비용 선투자

# 처음에 한 번만 투자
/deepinit

# 이후 explore 에이전트가 AGENTS.md를 참조하여
# 불필요한 파일 탐색 최소화

전략 5: modelAliases 설정 (v4.6.0)

// settings.json에 추가
{
  "modelAliases": {
    "opus": "claude-sonnet-4-5",    // opus 대신 sonnet 사용
    "sonnet": "claude-haiku-4-5"   // sonnet 대신 haiku 사용
  }
}

HUD로 비용 모니터링

HUD 상태바에서 실시간으로 토큰 사용량 확인:

OMC [ralph] | agents: 3 | tokens: 45.2k | est. cost: $0.23

---

13. 알림 시스템 설정

장시간 실행되는 작업(ralph, autopilot)이 완료되면 알림을 받을 수 있습니다.

지원 플랫폼

/configure-notifications

실행 후 플랫폼 선택:

Telegram

OMC_TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxxxxxxxxxxxxxxxxxx
OMC_TELEGRAM_CHAT_ID=123456789

Discord

OMC_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/yyy

Slack

OMC_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx

파일 출력

OMC_NOTIFY_FILE=/tmp/omc-notifications.log

알림이 오는 시점

이벤트	설명
세션 시작	작업이 시작됨
세션 종료	작업이 완료됨
질문 대기	Claude가 답변 대기 중
에이전트 생성	전문 에이전트 투입됨
유휴 상태	작업 없이 대기 중

알림 비활성화:

export OMC_NOTIFY=0

---

14. 환경 변수 & 설정 레퍼런스

핵심 환경 변수

변수	기본값	설명
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	1	Team 모드 활성화 (필수)
DISABLE_OMC	미설정	모든 OMC hook 비활성화
OMC_SKIP_HOOKS	미설정	특정 hook 건너뛰기 (쉼표 구분)
OMC_NOTIFY	활성	0이면 알림 비활성화
OMC_TEAM_NO_RC	미설정	RC 파일 로딩 명시적 비활성화 (v4.6.0)

settings.json 전체 구조

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/hud/omc-hud.mjs"
  },
  "enabledPlugins": {
    "oh-my-claudecode@omc": true
  },
  "modelAliases": {
    "opus": "claude-opus-4-5",
    "sonnet": "claude-sonnet-4-5",
    "haiku": "claude-haiku-4-5-20251001"
  },
  "extraKnownMarketplaces": {
    "omc": {
      "source": {
        "source": "git",
        "url": "https://github.com/Yeachan-Heo/oh-my-claudecode.git"
      }
    }
  }
}

플러그인 업데이트

/plugin marketplace update omc

---

15. 트러블슈팅

자주 발생하는 문제

문제 상황	해결 방법
hook이 작동 안 함	/omc-doctor 실행 후 안내 따르기
매직 키워드가 트리거 안 됨	/oh-my-claudecode:스킬명 으로 직접 실행
Team 모드 에러	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수 확인
상태가 꼬임	/cancel --force 로 전체 초기화
ralph가 멈추지 않음	/cancel 또는 대화에서 "중단해줘"
플러그인 업데이트 필요	/plugin marketplace update omc
처음부터 재설정	/omc-setup 재실행
보안 관련 경고 (v4.6.0)	CLI 경로 신뢰 설정 확인, OMC_TEAM_NO_RC 설정 검토

진단 명령어

/omc-doctor        → 설치 상태 종합 진단
/trace             → 에이전트 실행 타임라인 확인
/cancel --force    → 모든 활성 모드 강제 종료 + 상태 파일 삭제
/omc-setup         → 재설정 마법사

실행 중인 모드 취소

/cancel              → 현재 활성 모드 정상 취소
/cancel --force      → 모든 상태 파일 삭제 + 전체 초기화

대화에서:
"stop"
"중단해줘"
"잠깐 멈춰"

v4.6.0 보안 변경사항

• CLI 경로 신뢰 검증이 강화됨. 바이너리 경로가 검증된 절대 경로로 고정됨.
• OMC_TEAM_NO_RC 환경변수로 RC 파일 로딩을 명시적으로 비활성화 가능.
• 일시적 실패 재시도 + watchdog done.json 파싱 복구 기능 추가.

---

16. 빠른 참조 카드

┌──────────────────────────────────────────────────────────┐
│              OMC 빠른 참조 카드 (v4.6.0)                  │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  처음 시작                                                │
│    /deepinit              프로젝트 문서화                  │
│    /deep-interview '아이디어'  요구사항 명확화 (신기능)    │
│    /omc-doctor            설치 진단                       │
│                                                           │
│  계획                                                     │
│    plan this: [기능]      계획 수립 후 승인                │
│    ralplan: [기능]        전문가 합의 기반 계획             │
│                                                           │
│  실행 (강도 순)                                           │
│    autopilot: [지시]      자율 실행 (계획~검증 자동)       │
│    ralph: [지시]          완료까지 반복 (PRD 자동 생성)    │
│    ulw [지시]             최대 병렬 실행                   │
│    team N:agent [지시]    N개 에이전트 팀 협업             │
│    eco: [지시]            토큰 절약 모드                   │
│                                                           │
│  분석 & 리뷰                                              │
│    analyze: [문제]        디버깅/원인 분석                 │
│    review code            종합 코드 리뷰                   │
│    security review        보안 취약점 점검                 │
│    fix build              빌드/타입 에러 수정              │
│    tdd: [기능]            테스트 주도 개발                 │
│                                                           │
│  멀티 AI                                                  │
│    /omc-teams N:ai [지시] Codex/Gemini 병렬 활용          │
│    /ccg [지시]            3모델 동시 분석                  │
│                                                           │
│  유틸리티                                                 │
│    /note [내용]           메모 저장                        │
│    <remember>...</remember>   7일 기억                    │
│    <remember priority>...</remember>  영구 기억           │
│    /cancel                현재 모드 취소                   │
│    /cancel --force        전체 초기화                      │
│    /trace                 실행 타임라인                    │
│    /learner               패턴 추출 및 재사용              │
│                                                           │
│  강도: 대화 < plan < autopilot < ralph < team ralph       │
│  비용: haiku < sonnet << opus                             │
│                                                           │
│  GitHub: github.com/Yeachan-Heo/oh-my-claudecode         │
└──────────────────────────────────────────────────────────┘

---

부록: 에이전트 직접 호출

슬래시 명령어 대신 에이전트를 직접 지명해서 호출할 수도 있습니다.

# 특정 에이전트에게 직접 위임
"explore 에이전트: src/app 디렉토리 구조 전체 매핑해줘"
"architect 에이전트: 현재 인증 시스템 UML 다이어그램 그려줘"
"security-reviewer 에이전트: 이 파일만 보안 점검해줘"
"writer 에이전트: 이 함수들 JSDoc 주석 전부 작성해줘"
"git-master 에이전트: conventional commits 형식으로 커밋해줘"

부록: /learner — 패턴 학습 및 재사용

세션에서 효과적이었던 문제 해결 패턴을 추출하고 커스텀 스킬로 저장:

# 세션 후 패턴 추출
/learner

→ "이번 세션에서 다음 패턴이 효과적이었습니다:
   1. 타입 에러 수정: lsp_diagnostics → 일괄 수정 → 재검증
   2. API 구현: architect → executor × 3 (병렬) → test-engineer

   이를 커스텀 스킬로 저장할까요?"

# 저장 후 다음에 바로 사용
/skill run api-implementation-pattern

---

이 가이드는 oh-my-claudecode v4.6.0 기준으로 작성되었습니다.
공식 저장소: https://github.com/Yeachan-Heo/oh-my-claudecode
공식 사이트: https://yeachan-heo.github.io/oh-my-claudecode-website/