Claude Code Ultraplan 완벽 가이드 - 터미널은 자유롭게, 계획은 클라우드에서

들어가며

복잡한 기능을 Claude Code에게 맡기면 한 가지 불편함이 있었습니다. 계획 수립에 5~10분이 걸리는데, 그 동안 터미널을 쓸 수 없다는 것입니다. "auth 서비스를 JWT로 마이그레이션해줘"라고 요청하면, Claude가 코드베이스를 탐색하고 계획을 세우는 동안 그냥 기다려야 했습니다.

그래서 실무에서는 계획 수립은 건너뛰고 바로 구현을 시키거나, 아예 다른 터미널을 열어 작업하는 패턴이 생겼습니다. 하지만 복잡한 리팩토링이나 아키텍처 변경은 계획 없이 시작하면 반드시 뒤엎게 됩니다.

2026년 4월, Anthropic이 이 문제를 정면으로 해결한 기능을 출시했습니다. Ultraplan — 계획 수립을 클라우드로 옮겨서 터미널을 자유롭게 쓸 수 있게 하고, 브라우저에서 계획을 리뷰하고, 실행 위치까지 선택할 수 있는 기능입니다.

이 글에서는 Ultraplan의 동작 원리, 실전 사용법, 그리고 기존 Plan Mode와의 차이를 실무 관점에서 정리합니다.

1. Ultraplan이란?

Ultraplan은 로컬 CLI에서 시작한 계획 작업을 Claude Code on the Web(클라우드)으로 넘겨서, 백그라운드에서 계획을 수립하는 기능입니다.

항목	기존 Plan Mode	Ultraplan
실행 위치	로컬 터미널	클라우드 (Anthropic 서버)
터미널 점유	계획 완료까지 차단	터미널 즉시 해방
리뷰 방식	터미널에서 텍스트로	브라우저에서 인라인 코멘트
에이전트 구조	단일 에이전트	멀티 에이전트 (탐색 3 + 비평 1)
실행 선택	로컬만	클라우드 또는 로컬 선택
협업	불가	인라인 코멘트, 이모지 리액션

핵심 가치

• Targeted Feedback: 계획 전체가 아닌 개별 섹션에 코멘트
• Hands-off Drafting: 계획 생성 중 터미널에서 다른 작업 가능
• Flexible Execution: 클라우드에서 바로 실행하거나 터미널로 가져와서 실행

2. 멀티 에이전트 아키텍처

Ultraplan이 기존 Plan Mode와 근본적으로 다른 점은 멀티 에이전트 구조입니다.

# Ultraplan 멀티 에이전트 구조

┌─────────────────────────────────────────────┐
│              Ultraplan Engine                │
├─────────┬─────────┬─────────┬───────────────┤
│ 탐색 #1  │ 탐색 #2  │ 탐색 #3  │  비평 에이전트  │
│ (접근A)  │ (접근B)  │ (접근C)  │  (보안/일관성) │
│  병렬    │  병렬    │  병렬    │  순차 (마지막)  │
└─────────┴─────────┴─────────┴───────────────┘
      ↓                              ↓
  각자 독립적으로             보안 결함, 아키텍처
  코드베이스 탐색 →           일관성, 잠재적 회귀
  서로 다른 접근법 제안        오류를 검토

• 탐색 에이전트 3개: 코드베이스를 독립적으로 탐색하며 서로 다른 접근법을 제안합니다. 병렬로 작동하므로 단일 에이전트보다 다양한 관점을 빠르게 수집합니다.
• 비평 에이전트 1개: 탐색 에이전트들의 결과를 종합하여 보안 결함, 아키텍처 일관성, 잠재적 회귀 오류를 검토합니다.

단일 모델이 처음부터 끝까지 순차적으로 분석하는 것이 아니라, 전문화된 에이전트 그룹이 분업하는 구조입니다.

3. 사용 방법

3-1. 시작하기

Ultraplan을 시작하는 방법은 3가지입니다:

# 방법 1: /ultraplan 명령어
/ultraplan migrate the auth service from sessions to JWTs

# 방법 2: 프롬프트에 'ultraplan' 키워드 포함
이 프로젝트의 인증 시스템을 JWT로 전환하는 계획을 ultraplan으로 세워줘

# 방법 3: 로컬 Plan에서 전환
# Plan Mode에서 계획 승인 다이얼로그에서
# "No, refine with Ultraplan on Claude Code on the web" 선택

3-2. 상태 표시

클라우드에서 계획이 진행되는 동안 CLI에 상태 표시가 나타납니다:

상태	의미
◇ ultraplan	Claude가 코드베이스를 탐색하고 계획을 작성 중
◇ ultraplan needs your input	Claude가 명확히 할 질문이 있음 → 브라우저에서 응답
◆ ultraplan ready	계획 완료 → 브라우저에서 리뷰 가능

# 상세 상태 확인
/tasks
# → ultraplan 항목 선택 → 세션 링크, 에이전트 활동, 중단 옵션 표시

3-3. 브라우저에서 계획 리뷰

◆ ultraplan ready 상태가 되면 세션 링크를 열어 claude.ai에서 계획을 리뷰합니다.

• 인라인 코멘트: 특정 구간을 하이라이트하고 코멘트를 남기면 Claude가 해당 부분만 수정
• 이모지 리액션: 섹션별로 승인(👍) 또는 우려(⚠️) 표시
• 아웃라인 사이드바: DB 스키마 변경, API 엔드포인트, 단위 테스트 등 섹션 간 빠른 이동

코멘트를 남기면 Claude가 계획을 수정하고 업데이트된 버전을 제시합니다. 만족할 때까지 반복할 수 있습니다.

4. 실행 옵션

계획이 확정되면 실행 위치를 선택합니다.

옵션 A: 클라우드에서 실행

# 브라우저에서 "Approve Claude's plan and start coding" 선택
# → 같은 클라우드 세션에서 바로 구현 시작
# → 완료 후 diff 리뷰 → PR 생성까지 웹에서 처리
# → 터미널에는 확인 메시지만 표시

코드 구현부터 PR 생성까지 클라우드에서 끝낼 수 있어, 터미널을 전혀 건드리지 않아도 됩니다.

옵션 B: 터미널로 가져와서 실행

# 브라우저에서 "Approve plan and teleport back to terminal" 선택
# → 터미널에 "Ultraplan approved" 다이얼로그 표시

# 3가지 선택지:
# 1. Implement here - 현재 대화에 계획 주입, 이어서 구현
# 2. Start new session - 대화 초기화 후 계획만으로 새 세션 시작
# 3. Cancel - 계획을 파일로 저장, 나중에 실행

로컬 환경의 도구(Docker, DB, 테스트 서버)에 직접 접근해야 할 때 유용합니다.

5. 실전 활용 시나리오

시나리오 1: 대규모 리팩토링

/ultraplan 주문 서비스의 모놀리스를 MSA로 분리하는 계획을 세워줘.
현재 OrderService, PaymentService, ShippingService가 하나의 모듈에 있고,
이벤트 기반으로 분리하고 싶어. Kafka 사용.

3개 탐색 에이전트가 각각 다른 분리 전략(도메인 기준 / 데이터 기준 / 트래픽 기준)을 제안하고, 비평 에이전트가 데이터 정합성과 트랜잭션 문제를 검토합니다.

시나리오 2: 기술 마이그레이션

/ultraplan Spring Boot 3에서 4로 마이그레이션.
Jakarta EE, Virtual Threads 전환, deprecated API 교체 포함.

시나리오 3: 보안 감사 + 수정 계획

/ultraplan 현재 프로젝트의 보안 취약점을 분석하고 수정 계획을 세워줘.
OWASP Top 10 기준, 특히 인증/인가와 SQL Injection 중심으로.

6. 요구사항 및 제한사항

요구사항

항목	조건
Claude Code 버전	v2.1.91 이상
웹 계정	Claude Code on the Web 계정 필요
저장소	GitHub 리포지토리 필요
인프라	Anthropic 클라우드 전용 (Bedrock/Vertex/Foundry 불가)

제한사항

• Research Preview 상태 — 동작과 기능이 피드백에 따라 변경될 수 있습니다
• Remote Control과 동시 사용 불가 — 둘 다 claude.ai/code 인터페이스를 사용하므로 하나만 연결 가능
• AWS Bedrock, Google Vertex, MS Foundry에서 사용 불가 — Anthropic 클라우드 인프라 전용
• 클라우드 세션은 계정의 기본 cloud environment에서 실행됩니다

7. Ultraplan vs 기존 Plan Mode vs 일반 프롬프트

상황	추천 방식
단순 기능 추가, 버그 수정	일반 프롬프트 (계획 불필요)
중간 복잡도 작업 (파일 5개 미만)	Plan Mode (/plan)
대규모 리팩토링, 아키텍처 변경	Ultraplan
팀 리뷰가 필요한 설계 작업	Ultraplan (인라인 코멘트 활용)
로컬 환경 접근이 필수인 작업	Ultraplan → 터미널로 전송
PR까지 자동화하고 싶을 때	Ultraplan → 클라우드 실행

8. 버전 확인 및 업데이트

# 현재 버전 확인
claude --version

# 업데이트 (v2.1.91 이상 필요)
npm update -g @anthropic-ai/claude-code

# Ultraplan 사용 시작
claude
/ultraplan 인증 시스템을 OAuth2 + JWT로 전환하는 계획을 세워줘

마치며

Ultraplan은 Claude Code의 가장 큰 약점이었던 "계획 수립 중 터미널 차단" 문제를 정면으로 해결했습니다.

특히 멀티 에이전트 구조(탐색 3 + 비평 1)는 단일 에이전트가 놓치기 쉬운 보안 결함이나 아키텍처 불일치를 잡아내는 데 효과적입니다. 브라우저 기반 인라인 코멘트는 "이 부분만 수정해줘"라는 정밀한 피드백을 가능하게 합니다.

아직 Research Preview 단계이므로 변경 가능성이 있지만, 계획과 실행을 분리하는 패턴 자체는 AI 코딩 에이전트의 미래 방향을 보여줍니다. 복잡한 리팩토링이나 아키텍처 변경을 앞두고 있다면, /ultraplan 한 줄로 시작해보시길 추천합니다.