Claude Code Ultraplan 완전 정복: `/ultraplan`로 계획을 원격 서버에 위임하고 터미널을 되찾는 법
"AI가 복잡한 계획을 짜는 동안 나는 뭘 해야 하지?" 대규모 리팩토링이나 DB 마이그레이션을 시작할 때마다 이 질문이 따라붙습니다. AI 에이전트가 수십 개의 파일을 분석하고 계획을 수립하는 동안, 터미널은 그 작업에 묶여 있고 개발자는 옆에서 기다릴 수밖에 없습니다.
사실 이 기능은 공식 출시 전에 먼저 외부에 알려졌습니다. 2026년 3월 31일, npm 패키지 @anthropic-ai/claude-code v2.1.88에 59.8MB의 소스맵 파일이 실수로 포함되어 1,884개의 TypeScript 소스 파일이 노출된 사고가 있었습니다. 그 유출본에서 발견된 미출시 기능 중 하나가 바로 Claude Code Ultraplan이었고, Anthropic은 유출된 기능 가운데 이것을 가장 먼저 공식 출시(Research Preview)했습니다. Claude Code v2.1.91 이상에서 /ultraplan 명령어로 사용할 수 있습니다.
이 글을 읽고 나면 /ultraplan 명령을 현재 진행 중인 프로젝트에 바로 적용하고, 계획 수립이 진행되는 동안 터미널에서 다른 작업을 병행하는 워크플로를 갖출 수 있습니다.
핵심 개념
Ultraplan이 기존 /plan과 다른 점
Claude Code의 기존 /plan 명령은 로컬 터미널 세션 안에서 계획을 수립합니다. 세션이 완료될 때까지 같은 터미널에서 다른 작업을 하기 어렵습니다. Ultraplan은 이 구조를 바꿉니다. 계획 단계 자체를 Anthropic 원격 서버로 분리해서, 로컬 터미널이 계획 수립에 묶이지 않도록 합니다.
계획-실행 분리(Plan-Execute Separation): AI 에이전트가 계획을 수립하는 단계와 실제 코드를 변경하는 단계를 물리적으로 분리하는 아키텍처 패턴. 별도의 계획 단계를 갖춘 에이전트가 즉시 실행 방식보다 더 안정적인 결과를 내는 경향이 있으며, Anthropic이 Claude Code의 핵심 차별화 전략으로 밀고 있는 방향입니다.
Ultraplan 동작 흐름:
| 단계 | 위치 | 설명 |
|---|---|---|
| 1. 명령 입력 | 로컬 터미널 | /ultraplan [프롬프트] 입력 후 세션이 원격으로 넘어감 |
| 2. 계획 수립 | Anthropic 원격 서버 | Claude Opus 4.6이 격리된 환경에서 분석 및 계획 |
| 3. 계획 검토 | 브라우저 (claude.ai) | 섹션별 인라인 코멘트, 이모지 반응으로 수정 요청 |
| 4. 실행 결정 | 선택 가능 | 로컬 터미널 주입 또는 원격 직접 실행 |
원격 서버는 GitHub 연동을 통해 프로젝트 코드에 접근합니다. 클라우드 컨테이너가 저장소를 체크아웃해야 파일 구조와 의존성을 분석할 수 있기 때문에, GitHub 연동이 단순한 계정 연결이 아니라 기술적으로 필수 조건입니다. 로컬 전용 저장소에서는 /plan을 사용하는 것이 적합합니다.
3가지 호출 방식
방식 1 — 직접 명령어 (권장)
/ultraplan 모노리식 Express 앱을 NestJS 모듈 구조로 전환하는 계획을 세워줘명령을 입력하면 터미널에 아래와 같은 응답이 나타나고, 이후 로컬 터미널은 자유롭게 사용할 수 있습니다.
⠸ Ultraplan 세션 시작 중...
✓ 원격 컨테이너 연결됨
✓ 저장소 컨텍스트 로드 중...
계획 수립이 진행되는 동안 로컬 터미널을 자유롭게 사용할 수 있습니다.
완료되면 claude.ai에서 계획서를 확인하세요.방식 2 — /plan 에스컬레이션
로컬에서 /plan으로 시작했다가 작업 규모가 크다고 판단되면 클라우드 정교화 옵션을 선택할 수 있습니다.
/plan 현재 모놀리스 구조를 마이크로서비스로 분리하는 방법을 알려줘
# → 계획 수립 중 옵션 프롬프트 표시:
# [1] 로컬에서 계속 수립
# [2] Ultraplan으로 전환 (원격 정교화)방식 3 — 일반 프롬프트 내 키워드 (확인 필요)
일부 문서에서 일반 프롬프트에 "ultraplan"을 포함하면 자동으로 원격 세션이 트리거된다고 설명하는데, 이 동작은 Claude Code 버전 및 환경에 따라 다르게 작동할 수 있습니다. 일관된 결과를 원한다면 방식 1의 /ultraplan 직접 명령을 사용하는 것이 안전합니다.
계획 승인 후 실행 경로
계획 검토가 끝나면 4가지 경로를 선택할 수 있습니다.
| 경로 | 설명 | 적합한 상황 |
|---|---|---|
Implement here |
현재 터미널 세션에 계획 주입 | 바로 실행에 착수하고 싶을 때 |
Start new session |
새 세션에서 계획을 컨텍스트로 시작 | 깔끔한 실행 환경을 원할 때 |
Cancel |
계획을 파일로만 저장 | 나중에 참고하거나 팀과 공유할 때 |
Cloud execute |
원격에서 직접 실행 후 PR 자동 생성 | CI/CD 흐름에 통합하고 싶을 때 |
실전 적용
예시 1: 대규모 리팩토링 계획 수립
50개 이상의 라우터 파일이 존재하는 Express 모노리스를 NestJS 모듈 구조로 전환하는 작업입니다. 의존성 분석, 모듈 분리 순서, 단계별 마이그레이션 전략이 모두 필요한 복잡한 작업입니다.
/ultraplan 모노리식 Express 앱을 NestJS 모듈 구조로 전환하는 계획을 세워줘.
현재 src/ 디렉토리에 50개 이상의 라우터 파일이 있고,
공통 미들웨어가 전역으로 적용되어 있어.
각 라우터를 NestJS 모듈로 분리하는 순서와 마이그레이션 전략을 포함해줘.계획이 완료된 뒤 브라우저에서 열리는 계획서에는 아래 항목들이 구조화되어 표시됩니다.
| 검토 항목 | 설명 |
|---|---|
| 의존성 분석 결과 | 어떤 라우터가 어떤 공통 모듈에 의존하는지 |
| 모듈 분리 순서 | 사이드 이펙트를 최소화하는 작업 순서 |
| 마이그레이션 단계 | 단계별 체크포인트와 롤백 기준 |
| 예상 리스크 | 공통 미들웨어 이전 시 주의할 점 |
원격 계획 수립이 진행되는 동안, 로컬에서는 다른 브랜치의 버그 픽스나 테스트를 계속 진행할 수 있습니다. 계획이 완료되면 브라우저 알림을 통해 안내됩니다.
예시 2: DB 스키마 마이그레이션 설계
DB 마이그레이션은 롤백 전략까지 포함해야 하기 때문에 계획 수립에 가장 공을 들여야 하는 작업 유형 중 하나입니다.
/ultraplan PostgreSQL users 테이블에 멀티 테넌시 지원을 추가하려고 해.
현재 schema.sql을 분석해서, 기존 데이터를 유지하면서
tenant_id 컬럼을 추가하는 마이그레이션 플랜을 작성해줘.
롤백 전략도 포함해줘.backfill: 기존 레코드에 새로 추가된 컬럼의 값을 일괄 채워 넣는 작업. 대규모 테이블에서는 성능 영향이 크기 때문에 별도의 배치 처리 전략이 필요합니다.
Ultraplan이 이 시나리오에서 수립하는 계획의 흐름은 다음과 같습니다.
- 기존 스키마 분석 (FK, 인덱스, 연관 테이블 파악)
- 변경 영향 범위 확정
- 마이그레이션 쿼리 단계별 설계
- 기존 데이터 백필(backfill) 전략 수립
- 롤백 쿼리 및 트리거 포인트 정의
계획서 각 단계에 인라인 코멘트로 "backfill 배치 사이즈 기준은 무엇인가요?"처럼 구체적인 질문을 남기면, Ultraplan이 해당 섹션을 보강한 수정안을 제시합니다.
예시 3: API 아키텍처 의사결정
단일 정답 없이 여러 선택지가 동등하게 유효한 아키텍처 결정 시나리오에서 Ultraplan이 특히 효과적입니다.
/ultraplan 현재 REST API 서버를 확장해야 하는데,
REST 유지 / gRPC 전환 / GraphQL 도입 / 혼합 아키텍처 중
어떤 방향이 적합한지 트레이드오프 분석과 함께 계획을 세워줘.
현재 클라이언트는 모바일 앱과 내부 대시보드야.gRPC: Google이 개발한 고성능 원격 프로시저 호출 프레임워크. Protocol Buffers를 직렬화 형식으로 사용해 REST보다 낮은 지연과 강한 타입 안전성을 제공합니다. 주로 서비스 간 내부 통신에 적합합니다.
이 유형의 요청에서 Ultraplan은 단순히 하나를 추천하는 대신, 각 선택지의 장단점과 현재 클라이언트 구성(모바일 앱 + 내부 대시보드)에 맞는 적용 맥락을 구조화된 표로 제시합니다. 팀 리뷰나 아키텍처 결정 문서로 그대로 활용할 수 있습니다.
장단점 분석
장점
| 항목 | 내용 |
|---|---|
| 터미널 비차단 | 계획 수립 중에도 로컬에서 독립적인 작업 가능 |
| 강력한 모델 | 원격에서 Claude Opus 4.6을 전용으로 장시간 사용 |
| 구조화된 리뷰 UX | 인라인 코멘트, 이모지 반응, 사이드바 아웃라인으로 세밀한 검토 가능 |
| 추가 비용 없음 | /plan과 동일한 토큰·구독 제한 적용 |
| SWE-bench 성능 | Claude Code 72.7% (OpenAI Codex 69.1% 상회, Claude Code 전체 기준) |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 최소 버전 요구 | v2.1.91 이상 필수 | claude --version 확인 후 업데이트 |
| GitHub 연동 필수 | 원격 컨테이너가 코드에 접근하려면 저장소 연결 필요 | 로컬 전용 작업은 /plan 사용 |
| 웹 계정 필요 | Pro/Max/Team/Enterprise 플랜 요구 | 플랜 확인 후 적용 |
| 플랫폼 제한 | Bedrock, Vertex AI, Foundry 환경에서 사용 불가 | 해당 환경에서는 /plan 대안 사용 |
| Remote Control 충돌 | Remote Control 활성화 시 Ultraplan 시작과 함께 연결 해제 | 사용 전 Remote Control 상태 확인 |
| Research Preview | 기능과 동작 방식이 피드백에 따라 변경될 수 있음 | 릴리즈 노트 정기 확인 권장 |
| 오프라인 환경 | 인터넷 연결 없는 환경에서 사용 불가 | 폐쇄망 환경에서는 로컬 /plan 활용 |
실무에서 자주 보이는 패턴
- 모든 작업에 Ultraplan을 적용하는 경우 — 단일 파일 수정이나 접근법이 명확한 간단한 작업에는 로컬
/plan또는 직접 구현이 더 빠릅니다. Ultraplan은 여러 파일에 걸친 복잡한 작업이나 아키텍처 선택지가 여러 개인 의사결정 시나리오에서 진가를 발휘합니다. - 계획 검토 없이 바로
Implement here를 선택하는 경우 — 원격에서 수립된 계획이라도 브라우저에서 섹션별로 검토하고 인라인 코멘트로 수정을 요청하는 과정을 거치는 것이 최종 결과 품질을 높이는 데 도움이 됩니다. - 처리 시간을 과도하게 기대하는 경우 — 원격 계획 수립 소요 시간은 작업 복잡도와 서버 상황에 따라 달라집니다. Research Preview 단계이므로 예측 가능한 처리 시간 범위를 단정하기 어렵습니다.
마치며
Ultraplan을 사용하면 복잡한 작업의 계획 단계가 진행되는 동안에도 로컬 터미널로 다른 작업을 병행할 수 있어, 하루 안에 처리할 수 있는 작업의 양과 품질이 모두 달라집니다.
지금 바로 시작해볼 수 있는 3단계:
- 버전 확인 및 업데이트 —
claude --version으로 v2.1.91 이상인지 확인하고, 필요하다면pnpm add -g @anthropic-ai/claude-code@latest로 업데이트한 뒤 GitHub 연동 상태도 점검하면 좋습니다. - 첫 Ultraplan 실행 — 현재 진행 중인 프로젝트에서 가장 복잡한 리팩토링 작업 하나를 골라
/ultraplan [작업 설명]을 실행해보시면 됩니다. 계획이 수립되는 동안 다른 브랜치에서 별도 작업을 진행해보면 비차단 방식의 효과를 체감할 수 있습니다. - 브라우저 검토 활용 — 계획이 완료되면
claude.ai에서 계획서를 열어 각 섹션에 인라인 코멘트를 남겨보시면 됩니다. 이 리뷰 과정이 계획의 완성도를 어떻게 높이는지 직접 확인할 수 있습니다.
Research Preview 단계이므로, 팀 프로젝트나 프로덕션 적용 전에 개인 프로젝트에서 먼저 검증해보는 것을 권장합니다. 문제가 발생하거나 피드백이 있다면 Anthropic Discord 또는 Claude Code GitHub Issues를 통해 리포트할 수 있습니다.
참고 자료
- Plan in the cloud with ultraplan | Claude Code 공식 문서
- Claude Code's Ultraplan Bridges the Gap Between Planning and Execution | DevOps.com
- Claude Code Ultraplan: Cloud Planning to Free Your Terminal | claudefa.st
- Claude Code's new Ultraplan feature moves task planning to the cloud | The Decoder
- Claude Code Ultra Plan vs Local Plan Mode | MindStudio
- How to Use Claude Code Ultra Plan: Requirements, Token Costs | MindStudio
- Everything in Claude Code's Leaked Source: KAIROS, ULTRAPLAN, Buddy and More | techsy.io
- ULTRAPLAN & KAIROS | DeepWiki
- Claude Code Ultraplan Launched: I Just Tested It | Medium
- Inside Claude Code's leaked source | The New Stack
- 클로드 코드 Ultraplan, 계획 단계를 클라우드로 분리한 이유 | 디지털포커스