Part 5. Oh My Bridge — 플러그인 구성과 작동 방식

oh-my-bridge는 Claude Code 워크플로우에 외부 LLM(GPT-5.3-codex)을 통합하는 Claude Code 플러그인이다.

MCP Server → SubAgent → Hook → Skill → Plugin 레이어를 쌓아 Codex CLI(GPT-5.3-codex)를 Claude Code 워크플로우에 통합한다.

현재 구조의 핵심은 Skill 기반 라우팅이다. Claude가 작업 의도를 분류하고, 복잡한 코드 생성은 Codex MCP를 직접 호출하고, 단순 수정은 Claude 네이티브 편집을 그대로 진행한다. 초기에는 PreToolUse 훅으로 Edit/Write를 가로채는 방식을 시도했으나 UX 문제(deny가 Error로 렌더링)와 의도 기반 라우팅의 필요성으로 Skill 기반으로 전환했다.

소스 코드: github.com/Bongseop-Kim/oh-my-bridge

1. 플러그인 디렉토리 구조

oh-my-bridge/
├── .claude-plugin/
│   └── plugin.json                    플러그인 메타데이터
├── .mcp.json                          MCP 서버 등록 설정
├── agents/
│   └── codex-generator.md             SubAgent 정의
├── hooks/
│   ├── hooks.json                     Hook 이벤트 바인딩
│   ├── log-codex-usage.sh             JSONL 사용량 로깅
│   └── codex-fallback.sh              장애 감지 + fallback 주입
├── skills/
│   ├── oh-my-bridge/
│   │   └── SKILL.md                   라우팅 규칙 (code-routing skill)
│   └── subagent-driven-development/
│       ├── SKILL.md                   워크플로우 오버라이드
│       └── implementer-prompt.md      위임 프롬프트 템플릿
└── setup.sh                           스킬 배포 헬퍼

2. 전체 실행 흐름

단일 흐름: Skill 기반 라우팅

사용자 요청
  → Claude가 oh-my-bridge 라우팅 규칙 판단
      → 복잡한 코드 생성·로직 구현
          → mcp__codex 호출
          → Codex CLI(GPT-5.3-codex)가 파일 직접 생성/수정
          → PostToolUse Hook 자동 트리거
              → log-codex-usage.sh: JSONL 로그 기록
              → codex-fallback.sh: 에러 감지 → additionalContext 주입
      → 단순 수정·설정·오타
          → Claude 네이티브 Edit/Write

Plan mode 실행 시

Plan mode → ExitPlanMode
  → routing pass: 단계별 작업에 대해 라우팅 기준 검토
  → 복잡한 코드 생성 단계 → Codex 라우팅
  → 단순 수정 단계 → Claude 네이티브

3. 레이어별 구성

3.1 MCP Server — .mcp.json

Codex CLI의 내장 mcp-server 모드를 활용하여 Claude Code에 네이티브 도구로 등록한다.

{
  "codex": {
    "type": "stdio",
    "command": "codex",
    "args": ["-m", "gpt-5.3-codex", "mcp-server"]
  }
}

/plugin install 후 Claude Code 세션에서 /mcp를 실행하면:

plugin:oh-my-bridge:codex · ✔ connected

실제 도구명: mcp__plugin_oh-my-bridge_codex__codex

3.2 SubAgent — agents/codex-generator.md

haiku가 오케스트레이터를 맡아 CLI 명령을 조합하고 결과를 검증한다. 실제 코드 생성은 Codex CLI → GPT-5.3-codex가 처리한다.

프론트매터:

name: codex-generator
description: 코드 생성, 보일러플레이트, 테스트 생성 시 사용
tools: Bash, Read, Write
model: haiku
maxTurns: 10
permissionMode: acceptEdits

워크플로우 (4단계):

1. 프롬프트 조합 — 7-Section 위임 프롬프트를 태스크 설명으로부터 구성
2. Codex CLI 실행

   codex -q -a full-auto --writable-roots "$(pwd)" "{prompt}"

   • -q: quiet 모드 (인터랙티브 UI 억제)
   • -a full-auto: GPT가 자율적으로 파일 생성/수정
   • --writable-roots: 쓰기 가능 경로를 현재 프로젝트로 한정
3. 결과 검증 — 파일 존재 확인, 문법 검사 (node --check, python -m py_compile 등)
4. 결과 반환 — 생성/수정된 파일 목록, 검증 결과, 에러 발생 시 상세 정보

실패 시 SubAgent는 자체 수정이나 재시도를 하지 않고 부모 세션에 에러를 보고한다. 재시도는 codex-fallback.sh의 additionalContext를 읽은 Claude가 결정한다.

3.3 Skill — skills/

skills/oh-my-bridge/SKILL.md — 라우팅 규칙 (code-routing skill):

Claude가 작업을 시작하기 전 이 Skill을 트리거하여 Codex로 라우팅할지 결정한다.

라우팅 판단 기준:

• 로직 유무: 새 함수, 알고리즘, 비즈니스 로직 구현 → Codex
• 복잡도: 여러 파일에 걸친 변경, 새 모듈 생성 → Codex
• 파일 유형: 설정 파일(.json, .yaml), 마크다운, lock 파일 → Claude 네이티브
• 단순 수정: 오타, TODO 추가, 주석 삽입 → Claude 네이티브

skills/subagent-driven-development/SKILL.md — 오버라이드 워크플로우:

Superpowers의 subagent-driven-development 스킬을 오버라이드한다. Implementer를 codex-generator SubAgent로 교체하고, Spec Reviewer / Code Quality Reviewer는 원본 그대로 유지한다.

1. Implementer: codex-generator SubAgent 디스패치
   - 7-Section 위임 포맷 사용 (implementer-prompt.md)
   - 실패 시 fallback hook 지시에 따라 Claude 네이티브 Implementer로 재시도
   - 권장: git worktree 격리 후 실행

2. Spec Reviewer: 원본 그대로

3. Code Quality Reviewer: 원본 그대로

implementer-prompt.md — 위임 프롬프트 템플릿:

7-Section 포맷을 정의한다. Stateless 설계 특성상 각 호출에 전체 컨텍스트를 포함해야 하며, 재시도 시 이전 시도 내용과 에러를 함께 넣는다.

1. TASK: {원자적, 구체적 목표 한 문장}
2. EXPECTED OUTCOME: {성공 기준}
3. CONTEXT: {현재 상태, 관련 파일 경로/스니펫, 배경}
4. CONSTRAINTS: {기술 제약, 기존 패턴, 변경 불가 항목}
5. MUST DO: {필수 요건}
6. MUST NOT DO: {금지 행동}
7. OUTPUT FORMAT: {출력 형식}

Stateless 재시도 시 CONTEXT 섹션에 이전 시도 기록을 포함한다. 최대 3회 시도 후 부모 세션으로 에스컬레이션한다.

3.4 Hook — hooks/

훅은 PostToolUse 로깅과 fallback만 담당한다. PreToolUse 인터셉션(Edit/Write 가로채기)은 제거했다.

hooks/hooks.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "mcp__plugin_oh-my-bridge_codex__.*",
      "hooks": [
        {"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/log-codex-usage.sh"},
        {"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/codex-fallback.sh"}
      ]
    }]
  }
}

log-codex-usage.sh — PostToolUse JSONL 사용량 로깅:

Codex MCP 호출 후 ~/.claude/logs/codex-usage.log에 추가한다.

{
  "timestamp": "2026-02-28T08:59:54Z",
  "tool": "mcp__plugin_oh-my-bridge_codex__codex",
  "status": "success",
  "exit_code": "",
  "error": ""
}

codex-fallback.sh — PostToolUse 장애 감지 + fallback 주입:

Codex 응답에서 .error 필드 또는 비정상 exit_code를 감지하면 additionalContext를 출력한다.

{"additionalContext": "⚠️ Codex 호출 실패. 동일 태스크를 codex-generator SubAgent 대신 Claude 네이티브 SubAgent로 재실행하라."}

성공 시 아무것도 출력하지 않으며 Claude Code가 정상적으로 진행한다. 훅은 감지 역할만 담당하고, 실제 fallback 전환은 additionalContext를 읽은 Claude가 결정한다.

4. 설치

Phase 1–2: 플러그인 설치

/plugin install /path/to/oh-my-bridge
# 또는 마켓플레이스에서
/plugin install oh-my-bridge

자동으로 처리되는 항목:

• .mcp.json → mcp__plugin_oh-my-bridge_codex__codex 도구 등록
• agents/codex-generator.md → SubAgent 자동 등록 (플러그인 agents/ 자동 스캔)
• hooks/hooks.json → PostToolUse 훅 바인딩 (${CLAUDE_PLUGIN_ROOT} = 플러그인 캐시 경로)

Phase 3: 스킬 배포 (Superpowers 필요)

/plugin install은 skills/를 ~/.claude/skills/에 복사하지 않는다. 수동 배포가 필요하다.

# setup.sh로 자동 배포 (code-routing skill + subagent-driven-development 오버라이드)
./setup.sh

# 되돌리기
./setup.sh --undo

또는 수동:

# code-routing skill
mkdir -p ~/.claude/skills/oh-my-bridge
cp skills/oh-my-bridge/SKILL.md ~/.claude/skills/oh-my-bridge/

# subagent-driven-development 오버라이드 (Superpowers 있는 경우)
mkdir -p ~/.claude/skills/subagent-driven-development
cp skills/subagent-driven-development/SKILL.md ~/.claude/skills/subagent-driven-development/
cp skills/subagent-driven-development/implementer-prompt.md ~/.claude/skills/subagent-driven-development/

Superpowers의 개인 스킬 우선 매칭에 의해 ~/.claude/skills/subagent-driven-development/가 원본보다 먼저 로드된다.

5. 동작 확인

MCP 서버 연결

Claude Code 세션에서 /mcp 실행:

plugin:oh-my-bridge:codex · ✔ connected

disconnected면 Codex CLI 설치(codex --version) 또는 인증(codex /status) 확인.

SubAgent 등록

/agents 실행:

oh-my-bridge:codex-generator · haiku

Skill 라우팅 확인

head -6 ~/.claude/skills/oh-my-bridge/SKILL.md
# "oh-my-bridge routing" 텍스트가 나오면 정상

라우팅 동작 확인: 코드 생성 요청 시 Claude가 mcp__plugin_oh-my-bridge_codex__codex를 호출하는지 세션 로그에서 확인한다.

Hook 로그

Codex MCP 호출 후:

cat ~/.claude/logs/codex-usage.log
tail -5 ~/.claude/logs/codex-usage.log | jq .

# 에러만 필터
jq 'select(.status == "error")' ~/.claude/logs/codex-usage.log

E2E 흐름 확인

새 함수 hello()를 /tmp/hello-bridge.js에 구현해줘

정상 실행 시 Claude가 mcp__plugin_oh-my-bridge_codex__codex를 호출하고, Codex가 파일을 직접 생성한다. Hook 로그에 해당 호출이 기록되어야 한다.

6. 통제 수단

7. 안정성 설계

full-auto 모드 리스크 완화

codex -a full-auto는 GPT가 파일을 자율적으로 수정한다. 의도치 않은 덮어쓰기를 방지하기 위해 git worktree 격리를 권장한다.

# Implementer 실행 전 worktree 생성
git worktree add .worktrees/codex-impl -b feat/codex-impl-{task-id}
cd .worktrees/codex-impl

# 리뷰 통과 후 머지
git checkout main
git merge feat/codex-impl-{task-id}
git worktree remove .worktrees/codex-impl

Superpowers의 using-git-worktrees 스킬을 활용하면 이 과정을 자동화할 수 있다. implementer-prompt.md에 worktree 격리 절차가 템플릿으로 포함되어 있다.

Stateless 재시도 프로토콜

Codex CLI 각 호출은 독립적이므로, 재시도 시 이전 시도 내용 전체를 컨텍스트에 포함한다:

Attempt 1 → 실패
  ↓
Attempt 2 (원래 태스크 + Attempt 1 시도 내용 + 에러 상세)
  ↓
Attempt 3 (전체 히스토리)
  ↓
부모 세션 에스컬레이션

시리즈

• Part 1. Oh My Bridge: Claude Code 멀티 LLM 오케스트레이션 전략 — oh-my-bridge 배경, 대안 탐색, 전체 구조
• Part 2. Inside Superpowers — 스킬 시스템 동작 원리, SubAgent 패턴 상세
• Part 3. Inside Oh My Opencode — 설계 패턴 레퍼런스, 멀티 에이전트 오케스트레이션, 도구 혁신
• Part 4. Inside Oh My Claudecode — 훅 기반 인터셉션, 에이전트 티어, autopilot 파이프라인
• Part 5. Oh My Bridge: 플러그인 구성과 작동 방식 — Skill 기반 라우팅, MCP + SubAgent 구성, 안정성 설계