Claude Code를 제대로 쓰려면 이 두 가지가 필요하다

AI 코딩 보조 도구를 쓰다 보면 한 가지 한계에 부딪힌다.

Claude Code는 분명 강력한데, 기본 상태에서는 하나씩 답해주는 수준에 머문다.

여러 파일을 동시에 다루거나, 복잡한 시스템을 설계하거나, 버그의 원인을 추적할 때는 여전히 손이 많이 간다.

 

이 글은 Unreal Engine GAS(Gameplay Ability System) 프로젝트를 진행하면서 Claude Code 환경을 어떻게 확장했는지 기록한 Dev Log다. 설치법 나열이 아니라, 왜 이 도구가 필요했고, 실제로 어떻게 썼는지에 집중한다.

---

문제: Claude Code 기본 상태의 한계

프로젝트에는 캐릭터(Ares, Chan, Drakhar, Merci)마다 어빌리티가 있고, 공용 AttributeSet과 DamageExecCalc가 얽혀 있다. Sound V2 브랜치 작업을 시작하자 이런 상황이 예상된다.

• Wwise PostEvent 호출 타이밍을 물어보면 학습 데이터 기준의 오래된 답변이 돌아온다.
• 4개 캐릭터 어빌리티를 동시에 수정해야 하는데 AI는 하나씩 순차 처리한다.
• 멀티플레이어 RPC 버그를 추적하려면 코드를 일일이 읽어주며 설명해야 한다.

해결책은 두 가지였다.

---

해결 1. oh-my-claudecode — AI를 팀으로 만드는 도구

oh-my-claudecode는 Claude Code 위에 올라가는 멀티에이전트 오케스트레이션 레이어다. 쉽게 말하면, Claude 혼자 일하던 것을 역할이 나뉜 팀으로 바꿔준다.

 

설치

npm install -g oh-my-claudecode

Claude Code를 재시작하면 /oh-my-claudecode: 커맨드가 활성화된다. 정상 설치 확인:

setup omc

---

핵심 기능 3가지

① Team 모드 : 여러 에이전트가 작업을 나눠 병렬 처리한다.

/team 4:executor "각 캐릭터 어빌리티 폴더 리팩토링:
- Agent 1: Ares (Berserk, ChargeDash, SwordAura)
- Agent 2: Chan (BullRush, ShieldGuard, ShieldSlam, WarCry)
- Agent 3: Drakhar (DraconicFury, Earthquake, Flight, WingRush)
- Agent 4: Merci (EagleEye, MultiShot, SmokeArrow)"

4개 캐릭터를 순서대로 처리하던 것을 동시에 진행한다.

 

② Trace : 버그의 원인을 경쟁 가설 방식으로 추적한다. 멀티플레이어 RPC 문제처럼 재현이 어려운 버그에 특히 유용하다.

/oh-my-claudecode:trace
GS_GA_Chan_ShieldGuard가 클라이언트에서만 발동 안 됨.
서버-클라이언트 RPC 흐름을 추적해줘

 

③ Architect : Opus 모델을 사용해 시스템 설계를 검토한다. 코드를 짜기 전에 구조를 먼저 잡고 싶을 때 쓴다.

/oh-my-claudecode:architect
Sound V2에서 Wwise Event를 GameplayAbility 생명주기에 바인딩하는
아키텍처를 제안해줘. GS_GameplayAbility 베이스 클래스 기준으로.

---

주요 에이전트 역할 분담

에이전트	용도	모델
architect	시스템 설계 검토	Opus (읽기전용)
executor	실제 코드 구현	Sonnet
debugger	루트 원인 분석	Sonnet
trace	증거 기반 버그 추적	Sonnet
code-reviewer	PR 전 코드 리뷰	Opus
explore	코드베이스 빠른 탐색	Haiku

• /oh-my-claudecode:architect (Opus): 새 시스템 설계, 아키텍처 결정 전 검토 — Large 작업 승인 전 단계
• /oh-my-claudecode:trace (Sonnet): 멀티플레이어/DS 재현 어려운 버그 가설 기반 추적
• /oh-my-claudecode:code-reviewer (Opus): PR 전 GAS/Replication 전체 리뷰
• /team N:executor: 여러 캐릭터 어빌리티 동시 수정 등 병렬 작업
• use context7: 최신 UE API / Wwise 공식 문서 실시간 참조

---

 

해결 2. Context7 MCP — AI에게 최신 문서를 실시간 제공

MCP(Model Context Protocol) 는 AI에게 외부 도구나 데이터를 연결하는 표준 프로토콜이다. Context7은 그 중에서도 라이브러리 공식 문서를 실시간으로 가져와 AI에게 제공하는 MCP 서버다.

Unreal Engine GAS API나 Wwise 연동 방법을 물어보면 Claude는 학습 시점 기준의 답을 준다. Context7을 연결하면 최신 공식 문서를 직접 참조한다.

설치

C:\Users\<사용자명>\.claude\settings.json에 아래 블록을 추가한다.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "type": "stdio"
    }
  }
}

Claude Code를 재시작하면 적용된다.

---

사용법

질문 끝에 use context7을 붙이기만 하면 된다.

AbilitySystemComponent의 GetGameplayEffectCount 사용법 알려줘 use context7

Wwise와 Unreal Engine 5 연동 시 PostEvent 호출 타이밍 use context7

UGameplayAbility에서 CommitAbility 실패 처리 패턴 use context7

 

---

Team 모드 활성화 — psmux 설치

/team 명령어를 쓰려면 프로세스 멀티플렉서인 psmux가 필요하다.

npm install -g psmux

---

설치 확인:

where psmux
# C:\Users\CHA\AppData\Roaming\npm\psmux.cmd

이후 /team N:에이전트종류 "작업" 형식으로 사용한다. N은 병렬로 실행할 에이전트 수다.

---

Serena MCP는 왜 설치 안 했나

Serena(oraios/serena)는 LSP 기반 심볼 탐색과 심볼 단위 코드 편집을 제공하는 MCP 서버다. 기능은 강력하지만 이 환경에서는 이미 커버가 된다.

기능	이미 있는 도구
심볼 정의 이동	oh-my-claudecode lsp_goto_definition
참조 탐색	lsp_find_references
심볼 목록	lsp_document_symbols
심볼 이름 변경	lsp_rename
파일 탐색/검색	Claude Code 기본 Glob, Grep

게다가 Unreal Engine C++ 프로젝트는 clangd 연동을 위해 compile_commands.json을 별도로 생성해야 하고, Claude Code 최신 버전에서 Serena 도구가 노출되지 않는 호환 이슈도 보고된 바 있다.

이미 있는 도구가 같은 문제를 해결하고 있다면, 추가 도구는 복잡도만 높인다.

---

상황별 조합 정리

상황	추천
새 어빌리티 설계	architect → executor → verifier
멀티플레이어 버그	trace → debugger
PR 전 코드 품질	code-reviewer
여러 파일 동시 수정	/team N:executor
최신 Unreal API 참조	질문 + use context7
Sound 시스템 설계	architect + use context7

 

---

마치며

설치 자체는 간단하다. npm install 두 번과 JSON 한 줄이 전부다. 중요한 건 어떤 상황에 어떤 도구를 쓰는지 아는 것이다. Unreal Engine GAS처럼 구조가 복잡한 프로젝트일수록, AI를 단일 어시스턴트로 쓰는 것과 역할이 나뉜 팀으로 쓰는 것의 차이가 크게 체감된다.

---

참고

• oh-my-claudecode: https://github.com/Yeachan-Heo/oh-my-claudecode
• Context7 MCP: https://github.com/upstash/context7

GitHub - Yeachan-Heo/oh-my-claudecode: Teams-first Multi-agent orchestration for Claude Code

GitHub - upstash/context7: Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors