[AI] 5. Claude Code 병렬 처리로 효율 극대화하기 - cmux, worktree, omc 병렬 처리하기 (.omc/handoffs, .omc/shared_memory.json)

1. [AI] Claude Code 병렬 처리로 효율 극대화하기 - git worktree 기본 개념

2. [AI] Claude Code 병렬 처리로 효율 극대화하기 (claude --worktree)

3. [AI] Claude Code 병렬 처리로 효율 극대화하기 - tmux 활용하기

4. [AI] Claude Code 병렬 처리로 효율 극대화하기 - cmux 활용하기

5. Claude Code 병렬 처리로 효율 극대화하기 - cmux, worktree, omc 병렬 처리하기 (.omc/handoffs, .omc/shared_memory.json)

 

Ghostty 기반의 AI 전용 터미널 cmux, Claude Code의 --worktree 기능, 그리고 oh-my-claudecode(omc) 플러그인의 데이터 동기화 메커니즘을 결합하여, 완벽히 독립된 가상 환경에서 여러 AI 에이전트가 소통하며 협업하는 파이프라인 구축 방법을 정리

1. 핵심 아키텍처 개요

이 시스템은 메인 에이전트가 컨텍스트를 쪼개어 하위 에이전트들에게 분배하고, 각 하위 에이전트들은 독립된 워크트리에서 작업하면서도 공유 메모리를 통해 실시간으로 상태를 동기화하는 구조

• cmux: 화면 분할 및 에이전트 상태 시각화
• Git Worktree: 하나의 레포지토리 내에서 브랜치 충돌 없는 독립된 소스코드 공간 제공
• OMC Handoffs & Shared Memory: 분리된 에이전트 간의 컨텍스트 파이프라인 및 상태 동기화

2. 디렉토리 구조 설계

프로젝트 루트에 에이전트 간의 소통을 위한 메타데이터 공간을 확보해야 함. .claude/worktrees는 Claude Code가 자동으로 관리하는 영역.

my-project/ (Main Repository)
├── .omc/
│   ├── handoffs/          # 에이전트 간 주고받는 Task 카드 / 결과물 (JSON 또는 MD)
│   └── shared_memory.json # Shared Memory API가 참조할 글로벌 상태 저장소
└── .claude/worktrees/     # Claude Code가 자동 생성/삭제하는 격리된 워크트리 공간
    ├── task-auth-xyz/     # 에이전트 A의 독립 작업 공간
    └── task-ui-abc/       # 에이전트 B의 독립 작업 공간

3. Step-by-Step 워크플로우

Step 1. 마스터 컨트롤러(Orchestrator) 세팅

1. cmux 터미널을 실행하고 메인 프로젝트 디렉토리로 이동.
2. 첫 번째 패널에서 전체 요구사항을 분석할 마스터 Claude 세션을 오픈.
3. Bash

   claude
   

4. 마스터에게 전체 요구사항(예: "인증 모듈 추가 및 관련 UI 컴포넌트 개발")을 입력하고, 서브 태스크 스펙을 쪼개어 .omc/handoffs/task-auth.json과 task-ui.json 형태로 저장하도록 지시.

Step 2. cmux 패널 분할 및 독립 워크트리 실행

1. Cmd + D(세로 분할)를 눌러 패널을 필요한 만큼 쪼갬.
2. 분할된 각 패널에서 Claude Code의 --worktree 플래그를 사용해 에이전트들을 실행.

   # 좌측 패널 (에이전트 A - Auth 담당)
   claude --worktree
   
   # 우측 패널 (에이전트 B - UI 담당)
   claude --worktree
   

💡 --worktree 플래그의 장점 Claude Code가 내부적으로 git worktree를 자동 생성하여 독립된 브랜치와 디렉토리를 격리시킴. 작업이 끝나고 exit로 세션을 종료할 때, 변경 사항이 없다면 파일 찌꺼기를 남기지 않고 워크트리를 자동으로 청소(Clean up)해 주기 때문에 매우 깔끔함.

Step 3. .omc/handoffs/ 기반 컨텍스트 할당

분할된 패널의 각 에이전트에게 마스터가 남겨둔 핸드오프 카드를 읽고 작업을 시작하라고 프롬프트를 줌.

• 에이전트 A 패널: ".omc/handoffs/task-auth.json을 읽고 인증 로직을 구현해줘."
• 에이전트 B 패널: ".omc/handoffs/task-ui.json을 읽고 UI 컴포넌트를 구현해줘."

omc 를 사용하는 이유?

단순히 사람이 메모장을 저장하는 폴더가 아님. omc 플러그인은 Claude Code가 실행될 때 프로젝트 루트의 .omc/ 디렉토리를 MCP(Model Context Protocol) 시스템 프롬프트의 최우선 컨텍스트 경로로 강제 주입

• 자동 탐색 및 로딩 (Auto-discovery): --worktree로 띄워진 서브 에이전트들은 구동되자마자 프로젝트의 상위 레벨에 있는 .omc/handoffs/를 알아서 스캔함. 사용자가 *"태스크 카드 읽어봐"*라고 말하지 않아도, omc 환경의 Claude는 이미 본인에게 할당된 JSON 스펙을 파악하고 세션을 시작함.
• 구조화된 인터페이스 가이드: omc는 핸드오프 카드를 쓸 때 일정한 템플릿(작업 목표, 변경 범위, 제약 조건, 의존성 ID 등)을 강제함. 이를 통해 에이전트 간에 컨텍스트가 누수되는 것을 막아줌.

omc - Shared Memory API의 핵심: '파일'이 아닌 '도구(Tool)'의 공유

가장 오해하기 쉬운 부분이 shared_memory.json임. 단순히 파일 시스템에 텍스트를 적어두면, 에이전트들은 본인이 cat 명령어로 읽기 전까지는 상대방이 무슨 짓을 했는지 알 수 없음.

omc가 제공하는 Shared Memory API는 Claude에게 '전역 락(Lock) 및 상태 조회가 가능한 MCP Tool'을 제공하는 개념임.

• 이벤트 기반 인터랙션: 에이전트 A가 Shared Memory API Tool을 호출해 데이터를 업데이트하는 순간, omc 백그라운드 프로세스가 활성화되어 있는 다른 cmux 패널(에이전트 B)에게 알림이나 컨텍스트 갱신 신호를 보냄.
• 동시성 제어 (Concurrency Control): 여러 에이전트가 동시에 하나의 공유 자원에 접근할 때 파일이 깨지지 않도록 API 레벨에서 데이터 정합성을 보장해 줌.

Step 4. Shared Memory API를 통한 실시간 동기화

독립된 워크트리에 있는 에이전트들은 서로의 실시간 코드 변경을 직접 볼 수 없음. 이때 전역 공유 파일인 shared_memory.json을 데이터 버스로 활용해야 함.

• 동작 매커니즘: 각 에이전트에게 "핵심 마일스톤(예: API 스펙 확정, 데이터 모델 정의 완료)을 달성할 때마다 .omc/shared_memory.json에 상태를 업데이트하고, 주기적으로 이 파일을 읽어 다른 패널의 상황을 인지하라"고 지시(또는 시스템 프롬프트 주입)함.
• 예시 시나리오:
  1. 에이전트 A가 User 데이터 모델 설계를 마치고 공유 메모리에 {"auth_model": "ready", "fields": [...]}를 기록.
  2. 우측 패널의 에이전트 B는 공유 메모리의 변화를 감지하고, 확정된 스펙에 맞춰 LoginView.swift 소스코드를 작성.

4. 작업 생산성을 높이는 cmux 핵심 단축키 팁

여러 패널에서 에이전트가 동시에 연산을 수행할 때 화면을 제어하기 위한 필수 단축키 정리.

• Cmd + D : 터미널 세로 분할 (좌/우)
• Cmd + Shift + D : 터미널 가로 분할 (위/아래)
• Cmd + Option + 방향키 : 분할된 패널(에이전트) 간 포커스 이동
• Cmd + Shift + [ / ] : 상단 탭(Surface) 간 이동
• Cmd + W : 작업이 완료된 에이전트 패널 닫기

요약 및 결론

cmux와 Claude Code --worktree 조합은 Git 컨플릭트라는 리스크를 원천 차단하면서 멀티 에이전트 환경을 구축할 수 있는 가장 우아한 방법임. 여기에 omc 스타일의 Handoffs & Shared Memory 개념을 얹어주면 에이전트 간의 단절을 막고 유기적인 협업이 가능해짐. 대규모 리팩토링이나 기능 동시 개발 시 적극적으로 도입을 권장