이전 글(Codex 플러그인 실무 워크플로우)에서 플러그인 사용법은 다뤘으니, 여기서는 “주력 도구로 뭘 고를까” 관점만 본다.

출발점 — “커서가 더 좋다”는 오해

내가 Claude Code를 그렇게 권해도, 내 주변 사람들은 한동안 “커서가 더 좋다”며 Cursor를 놓지 않았다. 이유를 들여다보면 대부분 같은 오해 위에 서 있다.

• “커서에서 쓰는 Sonnet/Opus나 Claude Code에서 쓰는 거나 똑같은 모델 아니냐” — 모델 가중치는 같다. 하지만 같은 모델이라도 어떤 하네스(컨텍스트 주입, 툴 정의, 메모리, 후크)에 얹히느냐에 따라 결과물이 갈린다. 하네스 개념이 없으면 이 차이 자체가 안 보인다.
• “커서는 여러 모델을 고를 수 있으니 Claude 모델만 쓰는 것보다 우월하다” — 모델 선택지 수가 곧 에이전트 성능은 아니다. 모델을 바꿔 끼우는 것과, 하네스를 그 모델에 맞게 깎는 것은 다른 레이어의 일이다.

근본 원인은 하나다. 모델 자체를 에이전트라고 생각하는 것. 컨텍스트 엔지니어링이라는 레이어가 있다는 걸 모르면, 도구 비교가 “어느 모델이 더 똑똑한가”로 납작해진다. 실제로 결과를 가르는 건 그 위에 얹힌 하네스인데도.

그래서 하네스를 의식하기 시작한 사람들은 IDE 안의 어시스턴트에서 CLI 기반 에이전트로 넘어간다. 그리고 그 종착지에서 다시 Claude Code와 Codex로 갈린다. 질문이 “Cursor냐 아니냐”에서 “클코냐 코덱스냐”로 바뀌는 지점이다.

먼저 짚을 것 — 두 도구는 한쪽 방향으로만 공식 연동된다

이게 의사결정에 생각보다 크게 작용한다. 2026년 6월 현재:

• Codex → Claude Code (공식 O): OpenAI가 openai/codex-plugin-cc를 2026년 3월 30일에 공식 배포했다. Claude Code 세션 안에서 슬래시 커맨드로 Codex에 리뷰·위임을 던질 수 있다. MCP 서버 방식이고, 로컬 codex 바이너리와 config.toml, 기존 MCP·샌드박스 설정을 그대로 상속한다.
• Claude Code → Codex (공식 X): 반대로 Codex 세션 안에서 Claude Code를 공식 플러그인으로 붙이는 경로는 없다. 커뮤니티가 만든 비공식 “Claude plugin for Codex”가 있을 뿐이고, Codex가 Claude Code 마켓플레이스를 자동 미러링하다가 ${CLAUDE_PLUGIN_ROOT} 치환을 못 해서 MCP 핸드셰이크가 깨지는 이슈도 보고돼 있다(openai/codex#19372).

즉 Claude Code를 허브로 두면 Codex를 정식으로 흡수할 수 있지만, 반대는 매끄럽지 않다. 내가 클코를 주력에 두는 첫 번째 실무적 이유가 이거다. 두 모델을 다 쓰고 싶다면 허브는 클코가 유리하다.

모델 성능 — 벤치마크는 워크로드에 따라 갈린다

수치만 보면 한쪽 압승이 아니다. 출시일과 코딩 벤치마크를 정리하면:

해석:

• 레포 단위 이슈 해결(모듈 경계를 넘는 멀티스텝 패치)은 Opus 4.8이 SWE-Bench Pro에서 10%p 이상 앞선다.
• 터미널 주도 에이전틱 코딩은 GPT-5.5가 Terminal-Bench 2.1에서 앞선다.

한 가지 함정은 이 “터미널 강세”가 실제 사용 환경과 꼭 일치하지 않는다는 점이다. Terminal-Bench는 말 그대로 터미널 구동을 가정한 벤치마크지만, 정작 Codex를 쓰는 경우 상당수는 CLI가 아니라 Codex 데스크톱(GUI)으로 들어온다. CLI보다 GUI가 익숙한 사용자가 그만큼 많다는 뜻이고, 그러면 벤치마크가 측정한 강점이 실사용에선 그대로 안 살아날 수 있다.

벤치마크 수치는 모두 서드파티 측정치이고 측정 환경에 따라 흔들린다. 절대 점수보다 “내 워크로드가 레포 전반 리팩터링이냐, 터미널 자동화냐” 그리고 “나는 CLI로 굴리나, GUI로 굴리나”가 더 현실적인 판단 기준이다.

멀티 에이전트 / 서브에이전트 — 구조가 다르다

오케스트레이션을 어떻게 하느냐가 실제 사용감을 가른다.

Claude Code

• Subagents: 커스텀 프롬프트·툴·격리를 가진 재사용 에이전트 설정. 메인 세션이 워커로 호출한다.
• Agent Teams (2026-02-05, Research Preview): 리드 에이전트가 전문 서브에이전트에게 병렬 위임. split-pane 모드를 켜면 각 팀원이 자기 pane을 갖고, 터미널에 따라 tmux / iTerm2를 자동 감지해 분할한다.
• Agent View (2026-05-11, Research Preview): tmux 바둑판을 직접 깔지 않고도 여러 세션을 단일 리스트 대시보드 한 화면에서 관리. 클코 프로세스 상태를 직접 읽어 테이블로 반영한다.

Codex

• Subagents: explorer(읽기 전용 분석) / worker(읽기-쓰기 실행) / default(범용) 3가지 역할. 사용자가 명시적으로 요청할 때만 spawn하고, 최대 6개까지 동시 실행한다.
• 설정은 config.toml의 [agents] 섹션에서: max_threads = 6(동시 스레드), max_depth = 1(중첩 깊이), job_max_runtime_seconds = 300. 모든 결과가 모일 때까지 기다렸다가 한 번에 통합 응답을 준다.

차이를 한 줄로: 클코는 “팀/뷰”라는 UI 레이어까지 얹어 다중 세션 관찰성을 챙겼고, 코덱스는 config 기반으로 빡세게 통제되는 병렬 워커에 가깝다. 여러 세션을 띄워놓고 상태를 눈으로 훑어야 하는 1인 멀티트랙 작업엔 클코의 Agent View가, 정해진 작업을 정확히 N개로 쪼개 돌리는 데는 코덱스의 명시적 서브에이전트가 손에 붙는다.

tmux 바둑판 에이전트 뷰 — 직접 깔 것인가, 내장을 쓸 것인가

여러 에이전트를 동시에 띄워놓고 바둑판으로 보는 방식엔 두 갈래가 있다.

1. 직접 tmux 그리드: 세션마다 pane을 나눠 한 탭에 깔아두는 고전적 방법. 완전한 제어권을 갖지만 상태 추적은 수동이다.
2. 클코 내장: Agent Teams의 split-pane(tmux/iTerm2 자동 감지) 또는 Agent View의 단일 대시보드.

내 결론은 둘은 대체재가 아니라 보완재다. 자유도가 필요하고 비표준 프로세스까지 한 화면에 묶고 싶으면 직접 tmux가 낫고, “지금 어느 세션이 입력을 기다리는가”를 빠르게 보려면 Agent View가 낫다. 코덱스에는 이 관찰성 레이어가 클코만큼 정돈돼 있지 않아서, 코덱스로 다중 인스턴스를 CLI에서 굴리려면 결국 tmux를 직접 까는 쪽이 된다.

하네스 엔지니어링 관점

모델 점수보다 오래 가는 차이는 하네스(컨텍스트 주입, 툴 정의, 메모리, 후크, 플러그인)다.

• Claude Code: CLAUDE.md + 스킬 + 플러그인 + 후크로 하네스를 세밀하게 조립할 수 있다. Codex 플러그인의 review gate(Stop Hook으로 응답마다 자동 리뷰)처럼, 하네스에 다른 모델을 끼워 넣는 것도 가능하다.
• Codex: config.toml 중심으로 에이전트·샌드박스·스레드를 통제한다. 설정이 코드화돼 있어 재현성과 팀 공유가 깔끔하다.

방향성이 다르다. 클코는 확장성과 조립, 코덱스는 선언적 통제와 재현성 쪽이다. 하네스를 직접 깎아 쓰는 걸 즐기면 클코, 설정을 못 박아 안정적으로 돌리고 싶으면 코덱스가 손에 맞는다.

비용

API 단가는 입력 동일, 출력은 Opus가 약간 싸다. 다만 나처럼 Claude Max + ChatGPT Plus 구독으로 쓰면 토큰 단가보다 플랜 한도와 사용량 소진 속도가 체감 비용을 좌우한다. 특히 클코에서 Codex review gate를 켜면 Claude↔Codex 루프가 길어져 양쪽 사용량이 동시에 빠진다(이전 글에서 경고한 그대로다).

정리 — 누가 뭘 주력으로 둬야 하나

• Claude Code 주력이 맞는 사람: 레포 전반을 넘나드는 리팩터링·마이그레이션이 잦고, 여러 세션 관찰성과 하네스 커스터마이징을 중시하고, 두 모델을 한 허브에서 섞고 싶은 경우. (= 내 케이스)
• Codex 주력이 맞는 사람: 터미널 주도 자동화 비중이 크거나 반대로 GUI 워크플로가 편하고, 선언적 config로 재현성 있게 묶고 싶고, GPT 계열 모델 성향이 손에 맞는 경우.

핵심은 공식 연동이 단방향(Codex→클코)이라, 두 모델을 다 쓸 거면 허브는 클코가 유리하다는 점이다. 한쪽만 깔끔하게 쓸 거라면 워크로드(레포 단위냐 터미널 단위냐)로 고르면 된다. 벤치마크 1~2점 차이로 고를 문제가 아니다.

Sources:

• openai/codex-plugin-cc (GitHub)
• Introducing Codex Plugin for Claude Code (OpenAI Developer Community)
• Codex auto-mirrors Claude Code marketplaces — MCP handshake issue (openai/codex#19372)
• Subagents — Codex (OpenAI Developers)
• Orchestrate teams of Claude Code sessions (Claude Code Docs)
• Claude Opus 4.8 vs GPT-5.5: Benchmarks & Pricing (DataCamp)
• Claude Opus 4.8 Pricing (CloudZero)
• GPT-5.5 Pricing (apidog)

리서치 프리뷰 단계지만 Pro/Max 사용자라면 바로 켜볼 수 있다. 직접 며칠 써보고 한계까지 같이 정리한다.

이게 푸는 문제, 못 푸는 문제

푸는 문제

• 책상에서 시작한 세션을 외출 중에 폰으로 이어가기
• 회의실 노트북 옆에서 폰으로 메시지 한 줄 던지기
• 로컬 MCP, CLAUDE.md, .env 같은 환경을 그대로 들고 가기

못 푸는 문제

• 노트북 끄고 출근하기 → 로컬 프로세스 죽으면 끝
• 인터랙티브 picker가 필요한 명령 (/mcp, /plugin, /resume) 원격 조작
• API 키만 가진 환경에서 쓰기 → claude.ai OAuth 로그인 필수

클라우드에서 통째로 돌리고 싶으면 그건 Claude Code on the web 영역이다. Remote Control은 어디까지나 내 머신을 원격 조종하는 채널이다.

작동 원리 — Outbound Polling

핵심은 inbound 포트를 열지 않는다는 점이다.

내 노트북                       Anthropic API                 폰 / 브라우저
   │                                 │                              │
   │  outbound HTTPS (polling)       │                              │
   ├────────────────────────────────►│                              │
   │                                 │◄─────────────────────────────┤
   │                                 │     메시지 입력              │
   │◄────────────────────────────────┤                              │
   │   작업 지시 수신                │                              │
   │                                 │                              │
   │  결과 push                      │                              │
   ├────────────────────────────────►├─────────────────────────────►│

내 머신이 Anthropic API에 폴링하면서 일감을 받아간다. 방화벽 뚫을 필요 없고, 포트포워딩도 없고, ngrok도 없다. TLS 위에서 짧은 수명의 자격증명이 목적별로 따로 발급된다.

활성화 조건

API 키로 Claude Code 쓰던 환경이라면 한 번은 claude auth login으로 claude.ai OAuth 로그인 거쳐야 한다.

시작 방법 — 세 가지 모드

1. 서버 모드 (병렬 세션 가능)

claude remote-control

터미널이 서버 모드로 대기 상태에 들어간다. 세션 URL이 표시되고, 스페이스바를 누르면 QR 코드가 토글된다. 폰 카메라로 QR 찍으면 Claude 앱에서 바로 열린다.

주요 플래그:

런타임에 w 키 누르면 same-dir ↔ worktree 전환 가능하다.

2. 인터랙티브 + 원격 동시

claude --remote-control
# 또는 짧게
claude --rc

평소처럼 터미널에서 채팅하면서 동시에 원격에서도 같은 세션에 접속 가능한 모드다. 책상에 앉아서 일하다가 자리 비울 때 폰으로 이어받는 시나리오에 어울린다.

claude --remote-control "My Project"

이름 인자도 받는다.

3. 진행 중인 세션에 붙이기

이미 세션에 들어와 있는 상태라면 슬래시 명령으로 변환 가능하다.

/remote-control
/rc My Project

기존 대화 히스토리를 그대로 가져간다. 단, 이 방식은 --verbose, --sandbox, --no-sandbox 플래그를 못 받는다.

4. VS Code 확장 (v2.1.79 이상)

VS Code 프롬프트 박스에서 /remote-control 또는 /rc. 배너에 상태가 뜨고, Open in browser로 바로 이동할 수 있다. CLI와 달리 이름 인자나 QR 코드는 지원 안 한다.

모든 세션에 자동으로 켜기

/config

→ Enable Remote Control for all sessions = true.

이렇게 하면 매 인터랙티브 세션이 자동으로 원격 세션 1개씩 등록한다. Desktop 앱은 Settings → Claude Code → Enable remote control by default에서도 토글 가능하다.

클라이언트 매트릭스

세션 목록에서 원격 세션은 컴퓨터 아이콘 + 초록 점으로 표시된다.

폰에 앱이 없다면 세션 안에서 /mobile 치면 다운로드 QR이 뜬다.

로컬 환경이 그대로 따라가는가

이게 클라우드 실행과의 결정적 차이다.

회사 보안 정책이 빡세서 코드가 클라우드 컨테이너로 못 나가는 환경이라면 Remote Control이 거의 유일한 외부 조작 옵션이다.

tmux와 결합 — 실무 영속 세팅

claude remote-control은 터미널 프로세스가 죽으면 끝난다. 외출하면서 노트북 ssh로 접속해서 다시 띄울 수도 있지만 매번 번거롭다. tmux로 영속화해두면 깔끔하다.

# 세션 시작
tmux new -s rc
cd ~/projects/my-app
claude remote-control --name "my-app" --spawn worktree

# Ctrl-b d 로 detach
# 노트북 닫지 않고 외출

# 돌아와서 attach
tmux attach -t rc

ssh로 자기 머신에 들어가서 attach 하는 흐름까지 갖춰두면 모바일에서 세션 끊겼을 때 복구가 빠르다. 세션 명명은 --name 일관되게 쓰는 게 낫다 — 휴대폰 세션 목록에서 헷갈리는 게 의외로 큰 마찰이다.

토큰을 아끼면서 긴 세션을 끌고 가는 노하우는 Claude Code 토큰 절약 실전 가이드에 따로 정리해뒀다. 원격에서 폰으로 끄적이는 메시지가 의외로 컨텍스트를 빠르게 갉아먹기 때문에, /compact나 /clear를 원격에서도 쓸 수 있다는 점을 적극 활용하는 게 좋다.

다른 원격 접근법과의 비교

고르는 기준

• 진행 중인 작업을 폰으로 잠깐 이어가려는 거면 → Remote Control
• 노트북도 안 켜고 클라우드에서 돌리고 싶다 → Claude Code on the web
• SSH 키랑 DDNS 다 갖췄고 자유도가 필요하다 → SSH + tmux

Claude Code 에이전트 협력사와 일하기에서 다뤘던 멀티 에이전트 구성을 원격에서 조종하고 싶을 때는 Remote Control + --spawn worktree가 짝이 맞는다. 서브에이전트 워크트리들이 충돌하지 않게 분리되니까.

한계와 함정

솔직하게 정리한다.

1. 로컬 프로세스 죽으면 끝

터미널 닫거나 노트북 셧다운하면 세션 종료. sleep은 괜찮지만 셧다운/터미널 종료는 회복 불가다. tmux로 백업 띄워두는 게 사실상 필수.

2. 약 10분 네트워크 타임아웃

머신이 깨어 있는데 네트워크만 약 10분 이상 끊기면 프로세스가 알아서 종료된다. 카페에서 노트북 두고 나갔는데 와이파이 끊긴 시나리오에서 당한다. 다시 claude remote-control로 재시작 필요.

3. 인터랙티브 picker 명령 로컬 전용

MCP 서버 새로 붙이거나 플러그인 설치하는 작업은 폰에서 못 한다. 외출 중 환경 재구성은 안 된다는 뜻이다.

4. Ultraplan 시작하면 끊긴다

ultraplan 세션을 시작하는 순간 Remote Control 연결이 끊긴다. claude.ai/code 인터페이스를 둘이 동시에 못 쓰는 구조 때문이다. 외출 중 ultraplan 띄울 거면 미리 결정해야 한다.

5. 모바일 키보드의 현실

폰에서 긴 프롬프트 작성은 솔직히 고역이다. 짧은 지시(“계속 진행”, “이쪽으로 가지 마”, “리뷰 결과 정리해줘”) 위주로 굴리고, 본격 작업은 데스크탑에서 한다. 음성 입력이 의외로 쓸 만하지만 코드 토큰 인식은 여전히 거칠다.

6. 한 프로세스당 원격 세션 1개

서버 모드(claude remote-control)가 아닌 일반 모드(claude --rc)에서는 프로세스당 원격 세션 1개로 제한된다. 한 머신에서 여러 프로젝트를 병렬로 원격 조작하려면 서버 모드를 쓰거나 프로세스를 여러 개 띄워야 한다.

7. Team/Enterprise 기본 OFF

회사 계정이면 관리자가 admin settings에서 토글 켜기 전엔 못 쓴다. 데이터 보존 정책에 따라 토글 자체가 회색 처리되어 있을 수도 있다.

실무 워크플로우 예시

시나리오 A: 외출 전 활성화

# 출근 전 책상에서
cd ~/projects/my-shop
tmux new -s rc-shop
claude remote-control --name "shop-prod-fix" --spawn worktree

# Ctrl-b d 로 detach
# 노트북 그대로 두고 외근

지하철에서 폰으로 claude.ai/code 열어서 “어제 그 결제 버그 재현 테스트 작성해줘” 한 줄. 회사 도착해서 결과 확인.

시나리오 B: 회의 중 백그라운드 지시

회의실에서 노트북으로 발표하면서 폰으로 “방금 받은 피드백대로 인보이스 PDF 레이아웃 수정 시작해줘”를 메시지 하나로 던지기. 회의 끝나고 노트북 돌아오면 diff가 준비돼 있다.

시나리오 C: 침대에서 마무리

저녁에 침대에서 폰으로 “오늘 PR 리뷰 코멘트 다 반영했나 확인하고, 안 됐으면 정리해서 알려줘”. 결과 보고 OK면 푸시 알림 켜놓고 잠들기 (/config → Push when Claude decides, v2.1.110 이상 필요).

정리

Remote Control은 로컬 세션을 다른 기기로 연장하는 채널이다. 클라우드 실행 대안이 아니라, 내 머신에 묶여 있던 Claude Code를 시공간적으로 자유롭게 만드는 기능에 가깝다.

리서치 프리뷰라 깔끔하지 않은 부분이 있다. GitHub 이슈 트래커에 서버 모드 worktree 관련 버그도 올라와 있다 (#45975). 핵심 기능은 충분히 쓸 만하지만, 로컬 프로세스가 죽으면 끝이라는 본질적 제약은 인지하고 들어가야 한다.

출처

• Claude Code Remote Control 공식 문서 — 모든 플래그/명령/제약 1차 확인
• docs.anthropic.com Remote Control 미러 — 동일 문서로 리다이렉트
• Claude Code Desktop 공식 문서 — Desktop 앱의 Dispatch/Code 탭 역할 확인
• How to Control Claude Code from Your Phone — wmedia.es — 서버 모드 동작 교차 확인
• GitHub Issue #45975 — Server mode session creation 400 — 알려진 버그 참조

하네스 엔지니어링이 뭔가

공식 정의: Agent = Model + Harness. HashiCorp 창업자 Mitchell Hashimoto가 2026년 2월에 정의했다.

모델(Claude, GPT-4)은 내가 바꿀 수 없다. 하네스(Harness)는 그 모델을 감싸는 모든 것이다.

• CLAUDE.md — 시스템 프롬프트 + 프로젝트 컨텍스트
• 에이전트 정의 파일 — 역할, 허용 도구, 모델 선택 (~/.claude/agents/architect.md 같은 것들)
• 스킬 파일 — 워크플로우 자동화, 참조 문서
• 툴 권한 설정 — 어떤 도구를 허용/차단할지
• 피드백 루프 — 훅(TaskCompleted, TeammateIdle), 회의록 자동 누적
• 실행 환경 — tmux 분할, worktree 격리

이걸 의도적으로 설계하는 게 하네스 엔지니어링이다.

프롬프트 엔지니어링 → 컨텍스트 엔지니어링 → 하네스 엔지니어링 순으로 개념이 진화했다. 프롬프트 하나 잘 쓰는 게 아니라, 모델이 작동하는 환경 전체를 구조화하는 방향으로.

자주 보이는 오해: 하네스 엔지니어링을 에이전트 팀 구성이랑 같은 걸로 본다. 용어는 최신인데 이해가 에이전트 팀 하나에 멈춰 있는 경우다. Agent Teams(TeamCreate)는 하네스를 구현하는 방법 중 하나다. 단일 Claude Code 세션의 CLAUDE.md 하나만 잘 설계해도 하네스 엔지니어링이다. 팀 없이도 성립한다.

Agent Teams는 하네스 엔지니어링에서 분산 실행 레이어를 담당한다. 역할 분리, 컨텍스트 격리, 파일 소유권 매트릭스가 실제로 여러 에이전트 실행에 투영되는 모습이다.

Agent Teams란

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 한 줄 켜면 활성화되는 실험적 기능이다. lead 세션 하나가 PM/Architect/Dev/QA 같은 teammate들을 spawn해서 분업시킨다. 각 teammate는 독립된 Claude Code 세션이고 자기 컨텍스트 윈도우를 따로 가진다. 하네스 엔지니어링 관점에서 보면, 각 teammate 파일(~/.claude/agents/*.md)이 하네스 정의고, TeamCreate가 그 하네스를 여러 개 동시에 실행하는 방식이다.

업무용 노트북에선 보안 정책상 WSL2를 못 쓴다. 대안으로 psmux를 쓴다. Rust로 짠 Windows 네이티브 tmux로, ConPTY를 직접 다루고 .tmux.conf를 그대로 읽는다. Claude Code agent teams를 공식 지원해서 psmux 세션 안에서 lead를 띄우면 teammate가 알아서 별도 pane에 spawn된다. 결과적으로 macOS·WSL2·psmux 세 환경에서 운영 경험 차이가 거의 없다.

회사 팀 인력 모델과 왜 닮았나 — 하네스 설계 관점

회사에서 여러 사이트를 동시에 운영하면서 PM·아키텍트·BE/FE 개발자·DBA·인프라·QA·보안 같은 역할을 나눠 굴리는데, agent teams 구조가 그 인력 모델이랑 묘하게 비슷하다. 우연이 아니다. 역할 정의와 책임 격리 — 이게 인간 팀 설계에서 차용한 하네스 설계 원칙이다.

그래서 검증해봤다. Anthropic이 공식 문서에서 “회사 조직처럼 만들었다”고 직접 명시한 적은 없다. 그 표현은 안 나온다. 하지만 채택한 메커니즘 자체가 인간 팀에서 차용한 것들이다.

• Lateral peer communication: teammate끼리 직접 메시지 (lead 거치지 않음)
• Role specialization: subagent definition으로 역할별 특화
• Shared workspace: 파일 시스템 + shared task list
• Task claiming with file locking: sprint 티켓 잡듯 race condition 방지
• Orchestrator-led coordination: lead가 작업 분배, teammate는 자가 클레임

Anthropic이 자체적으로 진행한 실험도 같은 방향이다. 16개 에이전트로 Rust 기반 C 컴파일러를 처음부터 작성해서 Linux 6.9 커널까지 컴파일하는 데 성공했다. 단일 에이전트 워크플로로는 안 되는 규모다.

내가 회사 팀 굴리는 방식과 비슷한 모양으로 동작하는 게 단순 우연은 아니다.

왼쪽 메인 세션이 lead. 오른쪽 5개 pane이 architect / backend / frontend / pm / qa. 개인 게임 프로젝트(SpaceCat) M2 Week 1 킥오프 — 각자 자기 도메인 의견을 동시에 분석하는 중이다.

일반 subagent 호출이랑 뭐가 다른가

가장 큰 차이는 컨텍스트가 따로 흐른다는 거다. 5명이 동시에 작업해도 lead의 메인 컨텍스트는 깔끔하게 유지된다.

직접 굴려본 장점

개인 게임 프로젝트(SpaceCat — Phaser 기반 HTML5 게임)의 M2 Week 1 킥오프를 5인 팀으로 굴려봤다. Architect는 씬 골격·ServiceLocator·EventBus 설계, Backend는 Firebase 서비스 레이어, Frontend는 CatRenderer 14종 visual switch, PM은 characters.json·일정 cut line, QA는 DoD·회귀 테스트 전략. Lead가 5명을 동시 spawn하고 각자 자기 도메인 관점에서 의견을 분석하게 했다.

장점은 네 가지였다.

컨텍스트 격리. PM은 스코프와 일정만, Architect는 설계 패턴만, BE는 데이터/서비스 레이어만, FE는 렌더링·전환 로직만 본다. 각자 자기 도메인 외 잡음이 없다.

파일 소유권 분리. Architect가 첫 단계에서 파일 소유권 매트릭스를 박는다. 씬 골격은 Architect, Firebase 어댑터는 BE, CatRenderer는 FE 식으로 명확히 갈리니까 동시 작업해도 충돌이 안 났다.

한 화면 모니터링. tmux split으로 5개 pane이 동시에 깜박이는 게 보인다. 어디가 막혔는지, 누가 끝났는지 즉시 파악 가능하다. Architect가 “Phaser Registry vs 별도 GameStateService” 같은 결정 분기를 띄우면 lead가 바로 받아서 판단한다.

메인 컨텍스트 클린. lead는 “Architect 분석 완료”, “BE 서비스 레이어 초안”, “FE 렌더러 14종 매핑”, “PM 일정 cut line”, “QA DoD 초안” 정도만 본다. 각 teammate의 토큰짜리 작업 로그가 lead 컨텍스트로 흘러들지 않는다.

회사 업무 코드베이스에서도 같은 패턴으로 굴려봤다. 솔직히 아직 매끄럽지 않다. Task 완료 마킹이 가끔 누락되고, lead가 teammate 진행을 못 따라잡아서 다시 물어봐야 할 때가 있다. 최적화도 덜 됐다 — 같은 작업을 일반 subagent로 했을 때보다 토큰을 좀 더 쓴다. 그래도 컨텍스트 격리와 책임 분리에서 오는 이점이 단점을 충분히 누른다. 실험 단계라는 점만 감안하면 회사 실무에 붙여도 굴러간다.

함정과 단점

장점만 적으면 광고다. 실제로 겪은 단점도 똑같이 적는다.

특히 두 번째 함정 — 자연어로 “팀 만들어”라고 하면 lead가 의도는 받아들이지만 실제로 TeamCreate 도구를 안 부르고 그냥 일반 subagent 4번 순차 호출로 처리하는 경우가 있다. 도구 이름을 명시적으로 박아야 한다.

토큰을 적게 쓰면서 굴리는 패턴

5배 컨텍스트는 무조건 정해진 값이 아니다. 다음만 지키면 단일 세션 대비 1.5~2배 수준으로 끝낼 수 있다. 결과 품질 향상까지 고려하면 비용 손해는 아니다.

• 작업에 필요한 인원만 띄운다. 풀세트 13명을 매번 부르면 의미 없다. 작업 성격에 맞춰 3~5명으로 끊는다.
• Teammate 모델을 작업 난이도에 맞춘다. Architect만 Opus, 나머지는 Sonnet 또는 Haiku. /config의 default teammate model 설정 또는 spawn 프롬프트에서 직접 지정한다.
• Read-only 에이전트는 도구를 제한한다. PM/Architect는 Write/Edit 없이 Read/Grep만 줘도 충분하다. 불필요한 도구 호출이 줄어든다.
• Architect 단계에서 파일 소유권을 분명히 나눈다. 재작업이 없으면 컨텍스트도 부풀지 않는다.
• 작업 크기를 작게 자른다. 한 teammate가 5~6개 task로 끝나는 정도면 컨텍스트 윈도우가 안 터진다.
• 단순 작업엔 일반 subagent로 끊는다. 팀 모드는 진짜 분업 가치가 있을 때만.

요약하면 사람 적게, 모델 가볍게, 도구 좁게, 작업 잘게. 이 네 가지가 토큰 청구서를 결정한다.

“잘 써보인다”는 메타 효과 — 인정한다

5개 pane에서 PM/Architect/Dev/QA가 각자 다른 작업으로 깜박이고 있는 화면은 솔직히 멋있어 보인다. 카페에서 옆자리 사람이 흘끔거리는 정도의 비주얼이다.

근데 그게 다였으면 안 쓴다. 실제로 결과 품질이 올라가니까 쓰는 거다. 책임 영역이 분리되고 컨텍스트가 격리되니까 한 명한테 다 시키는 것보다 누락이 적다. Architect가 만든 파일 소유권 매트릭스는 한 사람짜리 세션에서는 잘 안 만들어지는 산출물이다.

시각 효과 자체가 목표는 아니다. 결과 품질을 위해 분업하다 보니 부수적으로 화면이 보기 좋아진 거다.

5명은 워밍업, 진짜는 13인 조직도

블로그 같은 작은 프로젝트는 5명 MVP 팀(PM/Architect/BE/FE/QA)으로 충분하다. 하지만 회사 실무 코드베이스는 도메인이 더 잘게 쪼개진다. 영역별 특화 에이전트를 추가하면 각자가 자기 도메인 전문 지식으로 답한다.

내가 회사 실무에서 쓰는 풀세트 조직도다.

각 에이전트는 ~/.claude/agents/{role}.md 하나로 정의된다. YAML frontmatter에 name, description, tools, model 박고 시스템 프롬프트에 책임/금지사항 적으면 끝이다. 한번 만들면 모든 프로젝트에서 재사용된다. 이 파일 하나가 하네스 정의 단위다. 모델이 뭘 알고 뭘 모르는지, 어디까지 건드릴 수 있는지가 이 파일로 결정된다.

특화의 의미는 그 도메인 외 잡음이 안 들어온다는 거다. 보안 에이전트는 OWASP 체크리스트 기준으로만 본다. DBA 에이전트는 N+1, 인덱스 누락, 트랜잭션 격리 수준만 본다. 풀스택 단일 에이전트는 이 모든 걸 동시에 봐야 해서 정작 중요한 사각지대를 놓친다.

어떤 작업에 어떤 구성?

작업 성격에 따라 lead한테 구성을 지시한다. 사람 늘리는 게 능사는 아니다.

작업 시작 전에 “이번 작업에 누구 누구 붙여” 라고 lead한테 명시한다. 그러지 않으면 lead가 임의로 풀세트를 띄울 수 있다.

단순 작업엔 쓰지 마라

오해 방지. 모든 작업을 팀으로 굴리면 안 된다.

• 타이포 수정 — 일반 Claude Code 한 명으로 충분
• 라이브러리 1줄 업그레이드 — 팀 띄우는 오버헤드가 작업 자체보다 큼
• 테스트 1개 추가 — subagent 한 명 호출이 빠름
• README 업데이트 — 팀 모드 자체가 낭비

기준은 단순하다. 풀스택 분업이 자연스럽게 떠오르는 작업일 때만 팀을 띄운다. 한 사람이 머릿속에서 다 처리할 수 있는 크기면 단일 세션이 정답이다.

토큰 5배는 진짜 5배다. 가볍게 보면 안 된다.

마무리

하네스 엔지니어링은 모델을 고르는 게 아니라 모델이 작동하는 환경을 설계하는 일이다. Agent Teams는 그 환경을 여러 역할로 분산시키는 방식이다.

협력업체 메타포는 여전히 잘 맞는다. 대표한테만 발주하고 나머지는 알아서 분업한다. 다만 외주사 고를 때처럼 작업 크기와 구성을 가려서 발주해야 한다. 풀세트 팀을 매번 띄우는 게 능사가 아니라는 점, 에이전트 파일(역할 정의)을 잘 짜는 것 자체가 하네스 엔지니어링이라는 점, 이 둘만 기억하면 단일 세션으로 만드는 결과보다 누락이 적다.

출처

• Claude Code Agent Teams 공식 문서
• Claude Code Subagents
• Run agents in parallel — 비교 가이드
• How Anthropic teams use Claude Code
• Building a C compiler with a team of parallel Claudes — Anthropic Engineering
• Mitchell Hashimoto — Harness Engineering (원 개념 정의)
• psmux — Windows native tmux (GitHub)

이게 뭔지 한 줄 요약

Claude Code 세션 안에서 슬래시 커맨드로 Codex를 호출하는 플러그인이다. 리뷰, 디버깅 위임, 배경 작업 등을 Codex에 던지고 Claude는 오케스트레이션에 집중한다.

설치

# Claude Code 세션 내에서
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

OpenAI 계정(ChatGPT Free 포함)이나 API 키가 있으면 된다. Codex CLI가 없으면 /codex:setup 단계에서 자동으로 설치 여부를 물어본다.

명령어 정리

/codex:review

현재 변경사항에 대한 표준 코드 리뷰. 커밋되지 않은 diff, 브랜치 diff, 특정 파일 범위를 대상으로 쓸 수 있다. 읽기 전용이라 코드에 손대지 않는다.

시간이 좀 걸리는 리뷰라면 백그라운드로 돌리는 게 낫다:

/codex:review --background

/codex:adversarial-review

일반 리뷰가 아니다. “뭔가 문제가 있다고 가정하고 찾아내라”는 방식의 악마의 변호인 분석이다. 설계 결정에 의문을 던지고, 실패 케이스를 파고들고, 더 단순하거나 안전한 접근이 있었는지를 따진다.

기능 완성 직후 Self-QA 용도로 쓰기 좋다. 읽기 전용.

/codex:rescue

커맨드 중 유일하게 코드 변경이 가능한 명령이다. 특정 태스크를 Codex에 위임하고 실제 작업을 시킨다.

/codex:rescue investigate why the tests started failing
/codex:rescue fix the failing test with the smallest safe patch
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
/codex:rescue --background investigate the regression
/codex:resume  # 직전 rescue 스레드 이어받기
/codex:rescue --fresh  # 새 스레드로 시작

--model 옵션으로 빠른 작업에는 경량 모델을 쓸 수 있다. 단순 반복 수정, 테스트 수정, 린트 수정 같은 작업을 싸게 돌리는 용도다.

/codex:status / /codex:cancel

백그라운드로 돌린 rescue나 review 작업 상태 확인 및 취소.

/codex:status   # 진행 중인 작업 확인
/codex:cancel   # 취소

/codex:result

완료된 작업의 결과 확인. Codex 세션 ID도 함께 반환해서, 터미널에서 직접 codex resume <session-id>로 그 세션에 접속할 수도 있다.

/codex:setup

설치 상태 확인, 리뷰 게이트 활성화/비활성화.

/codex:setup --enable-review-gate
/codex:setup --disable-review-gate

백그라운드 워크플로우

실무에서 가장 유용하게 쓰는 패턴이다.

1. Claude가 기능 구현 중
2. 구현 완료 후 --background로 review나 rescue 실행
3. Claude는 다음 태스크로 넘어감
4. 잠시 후 /codex:status → /codex:result로 결과 수령

무거운 리뷰를 기다리면서 멈추지 않아도 된다. 컨텍스트 낭비가 없다.

Review Gate

/codex:setup --enable-review-gate

활성화하면 Claude가 응답을 끝낼 때마다 Stop Hook이 트리거되어 Codex가 해당 응답을 자동으로 리뷰한다. 문제가 발견되면 Claude가 멈추기 전에 다시 돌아가서 수정한다.

주의: Claude↔Codex 루프가 길게 이어질 수 있어서 사용량이 빠르게 소진된다. 세션을 모니터링할 수 있을 때만 켜는 게 맞다.

실무 워크플로우 예시

일반적인 기능 개발

[Claude] 요구사항 분석 → 구현 계획 수립 → 코드 작성
[실행] /codex:review --background
[Claude] 다음 태스크로 진행
[나중에] /codex:result → 리뷰 결과 반영

테스트 실패 디버깅

[CI에서 테스트 실패 확인]
/codex:rescue investigate why the tests started failing
/codex:status (기다리는 동안 다른 작업)
/codex:result → 원인 분석 결과 확인
/codex:rescue --resume apply the top fix from the last run

PR 직전 최종 검증

/codex:adversarial-review
→ 결과 보고 위험 지점 수정
/codex:review
→ 최종 확인 후 PR

Claude Code 단독 vs Codex 연동 — 팩트 기반 비교

정리하면: Claude가 오케스트레이터, Codex가 전문가 호출 구조다. Codex를 붙인다고 Claude가 약해지는 게 아니라, 사각지대를 다른 모델이 채우는 방식이다.

리뷰 편향 제거가 핵심 이유다. 같은 모델이 짜고 리뷰하면 같은 실수를 반복해서 못 잡는다.

이커머스 / 웹 SI · 운영 업무 적용

이커머스 운영

• 장바구니/결제 로직 변경 시: /codex:adversarial-review로 엣지케이스(중복 주문, 재고 경쟁, 쿠폰 조합) 집중 공략
• 프로모션 코드 긴급 배포: --background로 리뷰 돌리고 다른 긴급 수정 병행
• 구버전 레거시 정산 코드: /codex:rescue 위임으로 Claude 컨텍스트 낭비 없이 정리

웹 SI 프로젝트

• 마감 전 납품 점검: PR 직전 adversarial-review로 클라이언트 피드백 전에 미리 걸러내기
• 외주 코드 인수인계: 받은 코드베이스에 review 돌려서 품질 리포트 빠르게 뽑기
• 반복 수정 요청 대응: 단순 레이아웃/스타일 수정은 --model gpt-5.4-mini로 비용 절감

공통

팀 작업이 아닌 1인 개발이거나 리뷰어가 없는 프로젝트에서 셀프 리뷰의 한계를 메우는 용도가 가장 실용적이다.

팁 모음

• 모델 기본값 설정: 프로젝트 루트에 .codex/config.toml 두면 매번 --model 안 써도 된다
• review gate는 집중 작업 시에만: 세션 감시 안 되는 상태에서 켜면 사용량 폭탄
• rescue는 작게 위임: 범위가 넓으면 결과 병합이 복잡해진다. 태스크 단위를 작게 잘라서 던지는 게 낫다
• result에서 session-id 챙기기: codex resume <id>로 터미널에서 바로 이어받을 수 있어서 디버깅 심화 때 유용하다

Sources:

• GitHub - openai/codex-plugin-cc
• Introducing Codex Plugin for Claude Code - OpenAI Developer Community

조작법

PC

• ← → 또는 A D — 좌우 이동
• Space / ↑ / W — 점프 (벽에 붙은 상태에서 자동 벽 점프)

모바일 (한 손 조작)

작은 드래그에도 즉각 반응하도록 x^0.4 곡선 적용. 손 크기와 무관하게 45px 드래그면 최대 속도다.

발판 종류

• 빌딩 옥상 — 기본 발판. 측면에 붙으면 벽 점프 가능
• 새 — 이동형 발판. 밟으면 슈퍼 점프 (+속도)
• 구름 — 일회성 발판. 한 번 밟으면 흩어짐. 머리로는 통과
• 비행기 — 장애물. 위에서 밟으면 슈퍼 점프, 측면 충돌 시 추락 (1500m+)

고도별 환경 변화

3000m를 넘으면 배경에 별이 깜박이기 시작한다.

전체 화면으로 플레이 →

프로토타입에서 검증한 것들

v0.1부터 v0.10b까지 총 11번의 이터레이션을 거쳤다. 핵심 결정 사항들:

시점: 백뷰 의사 3D, 자동 상승 러너 등 여러 방향을 시도했지만 결국 사이드뷰 Doodle Jump 계열로 확정. 고양이가 화면을 가로지르며 올라가는 게 직관적이고 재미있었다.

모바일 조작: 가장 오래 걸린 부분. 떼는 순간 점프, 탭=점프+드래그=이동 분리, 슬라이드 점프 등을 다 거절하고 마리오식 가변 점프 + 드래그 X 속도 방식으로 확정했다. 손가락 하나로 높이와 방향을 동시에 조절할 수 있다.

발판 배치: 초반에는 완전 랜덤 배치였는데, 위로 올라가다가 머리를 박거나 발판이 한쪽으로 몰리는 문제가 있었다. 이전 발판 위치를 추적해서 65% 확률로 반대편에 배치하는 지그재그 알고리즘을 넣었더니 자연스럽게 해결됐다.

다음 단계

이 프로토타입은 코어 게임필 검증용이다. v1.0에서는 Phaser 3 + TypeScript로 전환하고, 픽셀 아트 캐릭터 자산, 새 7종 차별화, 우박·번개 날씨 이벤트, BGM/SFX를 붙일 예정이다. 최종 목표는 App Store + Play Store 출시.

왜 튜토리얼이 필요했나

1.0.0에는 튜토리얼이 없었다. 스테이지 1~4가 사실상 가이드 역할을 하니까 충분하다고 생각했다.

틀렸다. 지인들한테 플레이해보라고 했더니 생각보다 많은 사람이 어렵다고 했다. 나한테는 당연한 규칙인데 처음 보는 사람한테는 전혀 당연하지 않았다. 색이 누적된다는 것, 한 번 지나간 칸은 다시 못 간다는 것, 별에 도달할 때 색이 정확해야 한다는 것 — 이걸 텍스트 없이 전달해야 한다.

튜토리얼 설계 원칙

텍스트 설명은 안 쓰기로 했다. 글로벌 출시 기준이기도 하고, 팝업 읽는 유저는 드물다.

대신 고정 레벨 3단계로 규칙을 하나씩 가르친다.

Tutorial 1: 2×3, 빨강 구슬 하나 → 빨강 별
            → 색이 누적된다는 것을 가르침

Tutorial 2: 2×3, 빨강 → 빨강★ → 파랑 → 보라★
            → 두 색을 섞으면 새 색이 된다는 것

Tutorial 3: 3×3, 빨강 → 빨강★ → 파랑 → 보라★ → 흰 → 라벤더★
            → 세 가지 색 혼합, 흰색의 역할

세 레벨 전부 같은 뱀형(snake) 경로 패턴을 쓴다. 경로 모양 자체가 일관되어야 규칙 학습에 집중할 수 있다.

고정 레벨 생성

랜덤 생성과 별도로 generateTutorialLevel(n: 1 | 2 | 3)을 PuzzleGenerator.ts에 추가했다. 튜토리얼은 절차적 생성이 아니라 하드코딩.

export function generateTutorialLevel(n: 1 | 2 | 3): LevelData {
  if (n === 1) {
    // 2×3  path: (0,0)→(0,1)→(0,2)→(1,2)→(1,1)→(1,0)
    // R marble at start, r★ target at end
    const grid = makeBlankGrid(2, 3);
    grid[0][0].type = 'R'; grid[0][0].source = SOURCE_MAP['R'];
    grid[1][0].type = 'r'; grid[1][0].target = TARGET_MAP['r'];
    return {
      name: 'Tutorial 1', rows: 2, cols: 3,
      grid,
      events: ['R', 'r'],
      solutionPath: [
        {row:0,col:0},{row:0,col:1},{row:0,col:2},
        {row:1,col:2},{row:1,col:1},{row:1,col:0},
      ],
    };
  }
  // ... Tutorial 2, 3 동일 패턴
}

온보딩 오버레이

튜토리얼 레벨 시작 전에 한 번만 보여주는 오버레이를 넣었다. “손가락으로 드래그해서 경로를 그리세요” 류의 최소한의 조작 안내.

localStorage로 표시 여부를 기록한다. 한 번 보면 다시 안 뜬다.

this.tutorialPending = !localStorage.getItem('tutorialSeen');
if (!localStorage.getItem('onboardingSeen')) this.onboardingVisible = true;

버전이 올라갈 때(마이너 버전 기준) 기존 유저에게도 한 번 더 보여주도록 처리했다. 업데이트로 튜토리얼이 바뀌었을 수도 있으니까.

// 버전 변경 감지 시 seen 플래그 초기화
localStorage.removeItem('tutorialSeen');
localStorage.removeItem('onboardingSeen');

힌트 애니메이션 개선

기존 힌트는 스테이지 1~4에서 경로 전체를 한 번에 보여줬다. 이걸 두 가지로 나눴다.

• auto-hint: 드래그 시작 전에 경로 전체를 pulse로 표시 (sin 파형으로 밝기 변조)
• 버튼 힌트: 경로를 start → end로 순차 애니메이션 후 페이드아웃

const elapsed = this.animTimer - this.hintAnimStart;
const drawProgress = Math.min(1, elapsed / this.HINT_ANIM_DURATION);

드래그를 시작하는 순간 auto-hint가 사라진다. 자연스럽게 손을 뗀다.

1.1.0 앱스토어 업데이트

위 튜토리얼 시스템을 올린 게 1.1.0이다. 리뷰 통과, 앱스토어에 올라가 있다.

1.1.1: 세로모드 고정 + UX 다듬기

1.1.0 올리고 나서 바로 발견한 문제들을 수정해서 1.1.1을 만들었다. 지금 심사 대기 중이다.

세로모드 고정

가로로 돌리면 레이아웃이 깨진다. 처음부터 세로 전용 게임인데 이걸 강제하지 않았다.

Info.plist에서 지원 방향을 세로만 남겼다.

<key>UISupportedInterfaceOrientations</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
</array>
<key>UISupportedInterfaceOrientations~ipad</key>
<array>
  <string>UIInterfaceOrientationPortrait</string>
  <string>UIInterfaceOrientationPortraitUpsideDown</string>
</array>
<key>UIRequiresFullScreen</key>
<true/>

iPad는 UpsideDown도 허용했다. 홈 버튼 없는 iPad에서 UpsideDown이 없으면 리젝 사유가 될 수 있다.

배너 광고 개선

기존 배너가 스플래시(로딩) 화면에서도 뜨는 문제가 있었다. startBanner를 별도로 분리해서 게임 화면에 진입한 후에만 배너가 로드되도록 수정했다.

로드 실패 시 재시도 로직도 추가했다. 최대 3회, 지수 백오프는 아니고 그냥 단순 재시도.

private retryCount = 0;
private readonly MAX_RETRY = 3;

async onBannerFailedToLoad() {
  if (this.retryCount < this.MAX_RETRY) {
    this.retryCount++;
    await this.showBanner();
  }
}

튜토리얼 UX 다듬기

• 튜토리얼 진행 중 하단 버튼(힌트, 설정 등) 숨김. 튜토리얼 중에 설정 열 이유가 없다.
• 게임 화면에서 “Tutorial” 버튼 제거. 설정 패널 안에 Help + Tutorial을 같은 row 2컬럼으로 정리.
• 힌트 카운트다운(3-2-1) 진행 중 힌트 버튼 재입력 방지. 연속 탭하면 카운트다운이 꼬였다.

지금 상태와 다음 계획

1.1.1이 통과되면 당분간 iOS 업데이트는 없다. 다음 목표는 안드로이드 출시다.

안드로이드는 1.1.1 기준으로 빌드한다. Capacitor가 코드 공유를 해주기는 하는데 AdMob App ID, RevenueCat 설정, 스토어 스크린샷은 전부 따로 준비해야 한다. 그 과정을 다음 편에 쓸 예정이다.

리젝 사유

Apple이 준 사유는 Guideline 5.1.2 — Legal — Privacy — Data Use and Sharing이었다.

요약하면 이렇다:

ATT(App Tracking Transparency) 권한 요청이 광고 SDK 초기화보다 먼저 이뤄져야 한다.

내 코드는 ATT 요청을 JavaScript(WebView) 레벨에서 처리하고 있었다. 문제는 AdMob 네이티브 SDK가 WebView보다 먼저 초기화될 수 있다는 것. 타이밍이 보장이 안 된다.

Apple 가이드라인은 명확하다. 광고 SDK가 뜨기 전에 ATT가 먼저여야 한다.

원인

AdManager.ts에 이런 코드가 있었다.

async initialize() {
  await this.requestTrackingAuthorization(); // JS 레벨 ATT
  await AdMob.initialize({ testingDevices: [] });
}

JS에서 ATT를 요청하고, 그 다음 AdMob을 초기화하는 흐름이다. 얼핏 보면 맞아 보이는데 문제가 있다.

Capacitor WebView가 뜨는 시점에 이미 네이티브 AdMob SDK가 초기화를 시작할 수 있다. JS는 WebView가 완전히 로드된 다음에야 실행된다. 순서가 꼬인다.

해결

네이티브 레벨에서 처리해야 한다. AppDelegate.swift에 직접 넣었다.

import AppTrackingTransparency

func applicationDidBecomeActive(_ application: UIApplication) {
    if #available(iOS 14, *) {
        ATTrackingManager.requestTrackingAuthorization { status in
            // 결과와 무관하게 AdMob은 이후에 초기화됨
        }
    }
}

applicationDidBecomeActive는 앱이 포그라운드로 올라오는 시점에 호출된다. WebView 로드나 AdMob 초기화보다 먼저 실행된다. 이게 Google이 공식 권장하는 방식이다.

Info.plist에 NSUserTrackingUsageDescription은 이미 있었으니 그대로 뒀다.

JS 쪽 ATT 로직은 삭제하지 않고 상태 확인만 하도록 남겼다. 네이티브가 이미 처리했으니 중복 요청은 안 된다.

재제출 프로세스

빌드 번호 올리기

같은 버전으로 재제출하려면 빌드 번호를 올려야 한다.

Xcode → TARGETS → App → General → Identity

• Version: 1.0 유지
• Build: 1 → 2

그다음 Product → Archive → Distribute App.

Review Notes 작성

재제출할 때 Review Notes를 꼭 썼다. 심사관한테 뭘 수정했는지 설명하는 칸이다. 안 써도 되지만 쓰는 게 낫다.

The App Tracking Transparency permission dialog appears immediately
when the app becomes active for the first time, before any ads are loaded.

Implementation: ATT is requested in applicationDidBecomeActive in
AppDelegate.swift using ATTrackingManager.requestTrackingAuthorization,
before the AdMob SDK initialization.

기술적으로 정확하게 쓴다. 심사관도 사람이고, 무엇을 수정했는지 명확히 알면 통과가 빠르다.

심사 통과

재제출 후 약 24시간 만에 통과됐다.

리젝 받고 원인 파악해서 수정하고 재제출까지 하루도 안 걸렸다. Apple이 리젝 사유를 구체적으로 알려주기 때문에 방향은 명확하다. 겁먹을 필요 없다. 틀리면 수정하면 된다.

심사 통과 후: isTesting 제거

심사 중에는 AdManager.ts에 isTesting: true가 세 군데 있었다. 심사관한테 테스트 배너 보이면 안 되니까 켜뒀던 거다.

통과하자마자 전부 제거하고 Build 3으로 다시 올렸다.

// 제거 전
await AdMob.showBanner({
  adId: BANNER_ID,
  isTesting: true, // ← 이거
});

// 제거 후
await AdMob.showBanner({
  adId: BANNER_ID,
});

실제 광고가 붙기 시작한 건 이 버전부터다.

게임 컨셉

모든 칸을 한 붓으로 방문하되, 색 구슬을 지나면 붓 색이 누적되고 별 칸에 정확한 혼합색으로 도달해야 클리어하는 퍼즐 게임이다. 색은 물감처럼 더하기만 되고 빼지지 않는다. 경로의 순서가 곧 퍼즐의 해답이다.

단순한 규칙인데 생각보다 퍼즐 깊이가 나왔다. colorpath.html 하나짜리 파일에서 게임의 핵심 루프를 확인했다.

마이그레이션 결정

프로토타입이 동작하자마자 구조적인 문제가 보였다. 1,100줄짜리 IIFE 안에 색 시스템, 레벨 생성, 렌더링, 입력 처리가 전부 섞여 있었다. 모바일 앱으로 출시하려면 어차피 손봐야 하는 부분이었다.

선택지는 두 가지였다.

1. 바닐라 JS 구조 유지, Capacitor만 씌우기
2. Phaser 3 + TypeScript로 재작성

첫 번째가 공수는 적다. 하지만 Canvas 2D를 직접 다루는 코드가 이미 복잡해진 상태에서 더 키우는 건 나중에 더 힘들어진다는 걸 경험으로 알고 있었다. Phaser를 선택했다.

구조 설계

마이그레이션 전에 기능 단위로 파일을 나눴다.

Phaser를 쓰면서도 실제 그리기는 Canvas 2D로 직접 한다. Phaser의 display list에 CanvasDrawer 오브젝트를 올려두고, render 단계에서 Canvas context를 받아 직접 드로잉하는 방식이다. Phaser 내장 게임 오브젝트 대신 Canvas API를 그대로 쓰는 이유는 프로토타입에서 작성한 드로잉 코드를 최대한 재활용하기 위해서다.

절차적 레벨 생성

레벨을 하드코딩하지 않고 전부 생성한다. 핵심은 두 가지다.

해밀턴 경로 생성: Warnsdorff 휴리스틱으로 모든 칸을 한 번씩 방문하는 경로를 찾는다. 실패하면 DFS 백트래킹으로 폴백한다.

부분집합 체인: 다중 별 스테이지에서 각 별의 목표 색이 체인을 이뤄야 한다. {r} ⊂ {r,y} ⊂ {r,y,b} 같은 구조. 색은 누적만 되기 때문에 순서가 잘못된 별 조합은 수학적으로 클리어 불가다. 생성 단계에서 이를 강제한다.

스테이지가 올라갈수록 그리드가 커지고, 별 개수가 늘고, 장애물이 추가된다. 장애물은 체커보드 패리티와 연결성 제약을 통과해야만 배치된다. 그렇지 않으면 해밀턴 경로 자체가 불가능한 그리드가 나온다.

결과

colorpath.html은 레거시로 남겨두고 건드리지 않는다. Phaser 앱은 app/ 폴더에 분리되어 있다. 마이그레이션 후 기능은 동일하지만 코드가 다룰 수 있는 단위로 쪼개졌다. 다음 단계는 이걸 실제 iOS 앱으로 패키징하는 것이었다.

Capacitor 셋업

설정 자체는 단순하다.

npm install @capacitor/core @capacitor/cli @capacitor/ios
npx cap init
npx cap add ios

capacitor.config.ts에 번들 ID와 웹 디렉토리만 지정하면 된다.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.hsc.colorpath',
  appName: 'Painting Star',
  webDir: 'dist',
  ios: {
    contentInset: 'always',
  },
};

이후 워크플로우는 항상 같다.

npm run build
npx cap sync ios
npx cap open ios   # Xcode 열림

cap sync가 dist/를 iOS 프로젝트 안으로 복사하고 플러그인도 업데이트한다. 코드 바꿀 때마다 이 세 줄을 실행해야 한다는 게 처음엔 불편했는데 금방 익숙해졌다.

번들 ID 문제

처음엔 번들 ID를 com.hsc.colorpath로 설정했다. 그런데 앱 이름이 ‘Painting Star’인데 번들 ID가 colorpath면 나중에 관리가 꼬일 것 같아서 com.hsc.paintingstar로 바꿨다.

번들 ID를 바꾸면 건드려야 하는 곳이 여러 군데다.

• capacitor.config.ts의 appId
• Xcode의 Signing & Capabilities → Bundle Identifier
• Info.plist의 CFBundleIdentifier
• AdMob, RevenueCat 같은 서드파티 설정

특히 AdMob Info.plist에 박혀 있는 GADApplicationIdentifier를 놓치면 광고 초기화할 때 크래시가 난다. 체크리스트 없이 감으로 바꾸다가 한 번 놓쳤다.

화면 크기 적응

Phaser를 초기화할 때 고정 해상도(420×740)로 시작했다. 웹에서는 CSS scale로 맞추면 되지만, 실제 기기에서는 노치와 홈 인디케이터 영역을 고려해야 한다.

Safe Area를 무시하면 버튼이 홈 인디케이터에 걸린다. WKWebView의 viewport-fit=cover와 CSS env(safe-area-inset-*) 변수를 조합해서 캔버스 레이아웃을 잡았다.

결국 고정 해상도를 버리고 window.innerWidth / window.innerHeight로 동적 계산하는 방식으로 전환했다. Phaser 게임 크기를 기기 화면에 맞게 초기화하고, 내부 UI 좌표도 전부 비율로 계산한다. 작업량이 늘어났지만 어차피 해야 하는 작업이었다.

스플래시 스크린

Capacitor에는 스플래시 스크린 플러그인이 있다. 2732×2732 png를 준비해서 Assets.xcassets에 넣으면 된다.

문제는 Xcode가 스플래시 이미지를 세 장 요구한다는 것이다 — 1x, 2x, 3x. 결국 같은 이미지를 세 벌 준비했다. 앱 심사 전에 스플래시 이미지를 제거하는 방향으로 정리했다. 앱 로딩이 빠르면 스플래시가 굳이 필요 없다.

실제 기기 테스트

시뮬레이터와 실제 기기는 다르다. 시뮬레이터에서 멀쩡하게 돌던 게 실제 폰에서 다르게 보이는 경우가 여러 번 있었다.

가장 크게 달랐던 건 터치 응답이다. 시뮬레이터에서는 마우스 클릭으로 테스트하니까 실제 손가락 드래그의 느낌을 알 수 없다. 경로 그리기가 핵심 인터랙션인 게임이라 실기 테스트가 필수였다. 드래그 감도와 판정 범위를 실기에서 여러 번 수정했다.

Xcode에서 실기 빌드하려면 Apple Developer Program($99/년) 가입이 필요하다. 가입 전에는 7일짜리 무료 프로비저닝으로 본인 기기에만 설치할 수 있다. 개발 중에는 이걸로 충분하다.

AdMob 배너와 레이아웃 충돌

배너 광고가 화면 하단에 붙으면 게임 버튼과 겹친다. AdMob은 배너 크기를 비동기로 알려주는데, BannerAdPluginEvents.SizeChanged 이벤트로 높이를 받아서 CSS 변수로 박아두는 방식을 썼다.

AdMob.addListener(BannerAdPluginEvents.SizeChanged, (info: { height: number }) => {
  document.documentElement.style.setProperty('--banner-height', `${info.height}px`);
});

게임 캔버스는 --banner-height만큼 위쪽으로 올라간다. 배너가 없을 때(광고 제거 구매자)는 변수를 0으로 세팅하면 레이아웃이 원래대로 돌아온다. 단순한 방법인데 깔끔하게 동작했다.

결과

Capacitor는 웹 기술 스택을 그대로 유지하면서 네이티브 앱을 만들 수 있는 가장 마찰 없는 방법이다. 플러그인 에코시스템도 충분하고, iOS/Android 동시 타겟도 코드베이스 하나로 커버된다.

다음 단계는 이 앱에 광고와 인앱결제를 붙이는 것이었다.

AdMob 설정

@capacitor-community/admob 플러그인을 썼다. 배너, 전면광고, 보상형 광고 세 가지를 연동했다.

보상형 광고는 강제 노출이 아니라 사용자가 원할 때 보는 방식이라 거부감이 덜하다. 힌트와 재생성 버튼에 gold 테두리와 ▶ 배지를 붙여서 광고가 필요하다는 걸 미리 알려줬다.

ATT 권한 처리

iOS 14부터 광고 추적 동의(ATT)를 받지 않으면 개인화 광고를 못 쓴다. AdMob 초기화 전에 반드시 요청해야 한다. 순서가 틀리면 ATT 팝업이 뜨지 않거나 무효 처리된다.

const { status } = await AppTrackingTransparency.getStatus();
if (status === 'notDetermined') {
  await AppTrackingTransparency.requestPermission();
}
await AdMob.initialize({});

capacitor-plugin-app-tracking-transparency 플러그인이 필요하고, Info.plist에 NSUserTrackingUsageDescription 키도 추가해야 한다. 이걸 빠뜨리면 App Store 심사에서 리젝된다.

isTesting 플래그

개발 중에는 isTesting: true를 써야 한다. 실제 광고를 클릭해서 수익을 발생시키면 AdMob 정책 위반이다.

const options: BannerAdOptions = {
  adId: AD_IDS.banner,
  adSize: BannerAdSize.ADAPTIVE_BANNER,
  position: BannerAdPosition.BOTTOM_CENTER,
  isTesting: true, // AdMob 승인 전까지 유지
};

AdMob 계정 승인은 앱 출시 후 트래픽이 발생해야 이루어진다. 출시 전에는 테스트 광고만 볼 수 있다.

RevenueCat 연동

StoreKit을 직접 다루지 않고 RevenueCat을 쓰기로 한 이유는 간단하다. 구매 복원, 영수증 검증, 기기 간 동기화를 처음부터 직접 구현하는 게 생각보다 복잡하다. RevenueCat이 이걸 대신 해준다.

API 키 혼동

RevenueCat에는 API 키가 두 종류 있다. App Store Connect API 키(SubscriptionKey_*.p8)와 RevenueCat 자체 SDK 키(appl_*). 처음에 이 둘을 혼동해서 시간을 날렸다.

• App Store Connect API 키: RevenueCat 대시보드에서 앱 구성 시 등록. 인앱결제 상품 정보를 App Store에서 가져오는 데 쓰인다.
• RevenueCat SDK 키: 앱 코드에 박는 키. Purchases.configure()에 넣는 appl_ 로 시작하는 문자열.

App Store Connect에서 키를 만들 때는 In-App Purchase 유형으로 만들어야 한다. 일반 API 키(AuthKey_*.p8)와 파일 이름 형식이 다르다. SubscriptionKey_XXXXXXXX.p8이면 맞는 키다.

Sandbox 테스트 불통

인앱결제를 연동하고 실기 테스트를 해봤는데 “상품을 찾을 수 없습니다”가 계속 떴다. 로그를 보면 RevenueCat은 연결되는데 상품 목록이 비어있다.

원인을 찾는 데 시간이 걸렸다. App Store Connect에서 인앱결제 상품 상태가 READY_TO_SUBMIT인 상태에서는 Sandbox StoreKit이 상품을 반환하지 않는다는 게 핵심이었다. 앱을 App Store Connect에 한 번 업로드해야 상품 상태가 WAITING_FOR_REVIEW로 바뀌고 그때부터 Sandbox 테스트가 가능하다.

즉, 실제로 앱을 심사 제출하기 전까지는 인앱결제 Sandbox 테스트가 안 된다. 출시 전에 결제 플로우를 완전히 검증할 수 없다는 뜻이다.

구매 복원

RevenueCat은 restorePurchases()를 제공한다. Apple ID 단위로 구매 이력을 서버에서 조회해서 복원한다. 기기를 바꾸거나 앱을 재설치해도 복원된다.

const info = await Purchases.restorePurchases();
const entitlement = info.entitlements.active['remove_ads'];
if (entitlement) {
  localStorage.setItem('adsRemoved', 'true');
}

localStorage는 캐시 역할만 한다. 진실의 원천은 RevenueCat 서버(Apple ID 기반)다. 앱 시작 시 getCustomerInfo()를 호출해서 동기화한다.

광고 전략 설계

처음엔 전면광고 위주로 설계했다가 Rewarded Ad 중심으로 바꿨다. 이유는 세 가지다.

1. 전면광고는 타이밍이 나쁘면 사용자 경험을 깎는다
2. Rewarded Ad는 사용자가 선택한다 — 거부감이 다르다
3. 힌트/재생성 같은 “편의 기능”과 궁합이 잘 맞는다

adsRemoved 구매자는 전부 무제한 무료다. 광고 없이 플레이하고 싶은 사람은 한 번 구매하면 된다.

결과

AdMob + RevenueCat 조합은 무료 게임 수익화의 사실상 표준이다. 각각 독립적으로 초기화되고 간섭이 없다. Sandbox 테스트 제약은 불편하지만, 이건 Apple의 정책이라 어쩔 수 없다. 실제 결제 동작 확인은 앱 승인 후로 미뤘다.