oh-my-claudecode (OMC)

[!tldr] 한줄 요약 OMC는 28+ 에이전트와 40+ 스킬을 마크다운 프롬프트로 정의하고, 훅 기반 오케스트레이션으로 조합하는 Claude Code 플러그인이다. 마크다운이 곧 프로그래밍 언어가 되는 "Prompt-as-Code" 패러다임을 구현한다.

핵심 내용

프로젝트 구조

OMC 플러그인은 6개의 핵심 디렉토리로 구성된다:

oh-my-claudecode/
├── agents/          ← 에이전트 프롬프트 (마크다운)
├── skills/          ← 스킬 워크플로우 (SKILL.md)
├── hooks/           ← 이벤트 핸들러 (hooks.json + JS)
├── scripts/         ← 키워드 감지 등 런타임 스크립트
├── src/             ← TypeScript 소스 (MCP 서버, 훅 로직)
└── .claude-plugin/
    └── plugin.json  ← 플러그인 등록 (skills, mcpServers)

graph TB
    Plugin[plugin.json<br/>플러그인 등록] --> Skills[skills/<br/>40+ 워크플로우]
    Plugin --> MCP[.mcp.json<br/>3개 MCP 서버]
    Plugin --> Hooks[hooks/<br/>9개 이벤트 바인딩]

    Hooks --> KD[keyword-detector.mjs<br/>키워드 자동 감지]
    Hooks --> SI[skill-injector.mjs<br/>스킬 프롬프트 주입]
    Hooks --> PM[persistent-mode.cjs<br/>모드 지속성]

    Skills --> Agents[agents/<br/>28+ 에이전트 프롬프트]
    MCP --> T[t: LSP/AST/REPL/상태]
    MCP --> X[x: OpenAI Codex]
    MCP --> G[g: Google Gemini]

에이전트 프롬프트 패턴

에이전트는 .md 파일로 정의되며, 11개 섹션의 XML 구조를 사용한다:

5가지 핵심 프롬프트 엔지니어링 패턴:

1. 역할 경계(Role Boundary) — architect는 READ-ONLY (disallowedTools: Write, Edit), executor는 쓰기 전용
2. 존재 이유(Why_This_Matters) — "왜 이 에이전트가 필요한지" 명시해서 역할 이탈 방지
3. 대조 예시(Contrastive Examples) — Good/Bad를 나란히 보여줘서 경계선을 학습
4. 실패 모드(Failure Modes) — "하지 말아야 할 것"을 명시적으로 나열
5. 도구 권한 제어(Tool Permission) — 모델 티어(haiku/sonnet/opus)에 따라 접근 가능한 도구 차등

오케스트레이션 메커니즘

사용자 입력이 에이전트 실행으로 이어지는 5단계 흐름:

flowchart LR
    Input[사용자 입력] --> KD[keyword-detector<br/>정규식 매칭]
    KD -->|MAGIC KEYWORD 주입| Skill[Skill 도구<br/>SKILL.md 로딩]
    Skill --> Steps[Steps 실행<br/>에이전트 호출]
    Steps --> State[상태 파일<br/>.omc/state/]
    State -->|Stop 훅 체크| Loop{계속?}
    Loop -->|Yes| Steps
    Loop -->|No| Done[완료]

스킬 구조

스킬은 skills/{name}/SKILL.md 형태로 존재하며, 5가지 유형으로 분류된다:

SKILL.md는 이중 독자(Dual Audience) 설계:

• YAML frontmatter → 플러그인 시스템이 파싱 (스킬 등록)
• XML 태그 (<Steps>, <Use_When>) → Claude가 읽음 (실행 로직)
• 마크다운 본문 → 사람이 읽음 (설정 참조)

마크다운 안의 XML — 프롬프트 엔지니어링

SKILL.md에서 XML 태그를 사용하는 이유:

1. 경계 명확성 — <Use_When>...</Use_When>은 열림/닫힘이 명시적. 마크다운 헤딩은 어디서 끝나는지 모호
2. Claude 최적화 — Anthropic이 공식 권장하는 기법. Claude는 XML 태그를 구조화된 지시의 구분자로 인식하도록 학습됨
3. 의미 전달 — <Failure_Modes_To_Avoid>처럼 태그 이름 자체가 의도를 전달
4. 복잡도 기반 선택 — 워크플로우 스킬(복잡)은 XML, 유틸리티 스킬(단순)은 순수 마크다운

Prompt-as-Code 패러다임

OMC의 가장 흥미로운 특징은 마크다운이 프로그래밍 언어 역할을 한다는 점이다. LLM이 런타임이 되어 자연어 지시를 실행한다:

전통적 코드와의 결정적 차이: 모호성이 허용된다. "Run independent tasks in parallel"이라고만 써도 Claude가 맥락을 보고 어떤 태스크가 독립적인지 판단해서 실행한다. 이것이 장점(프로그래밍 지식 없이 워크플로우 정의 가능)이자 단점(실행 결과가 비결정적)이다.

1950s: 기계어    → 하드웨어가 직접 실행
1970s: C 언어    → 컴파일러가 기계어로 변환
1990s: Python   → 인터프리터가 바이트코드로 변환
2020s: 마크다운  → LLM이 의미를 이해하고 도구를 호출

예시

autopilot — 워크플로우 오케스트레이터의 실행 흐름

사용자: "autopilot REST API for bookstore with CRUD"
  ↓
keyword-detector: "autopilot" 감지 → [MAGIC KEYWORD: autopilot]
  ↓
SKILL.md 로딩 → Phase 0~5 순차 실행:
  Phase 0: analyst(opus) + architect(opus) → spec.md
  Phase 1: architect(opus) → plan.md, critic(opus) → 검증
  Phase 2: executor(haiku/sonnet/opus) → 구현 (병렬)
  Phase 3: ultraqa → 빌드/린트/테스트 (최대 5회 반복)
  Phase 4: architect + security-reviewer + code-reviewer (병렬 검증)
  Phase 5: 상태 파일 정리

analyze — 에이전트 단축 스킬

---
name: analyze
---
<Steps>
1. Identify the analysis type
2. Gather relevant context
3. Route to analyzer:
   - Preferred: ask_codex(agent_role="architect")   ← MCP 우선
   - Fallback: Task(architect, opus)                ← 에이전트 대체
4. Return structured findings
</Steps>
Task: {{ARGUMENTS}}   ← 사용자 입력이 여기로 전달

참고 자료

• oh-my-claudecode GitHub
• Claude Code Plugins 문서
• Anthropic Prompt Engineering — XML Tags

관련 노트

• MCP(Model Context Protocol)
• Claude Code Agent 동작 방식
• Claude Code Skill
• Claude Code Plugin
• Best Practices