Claude Code Ultraplan으로 클라우드에서 대규모 리팩터링 돌리기
claude code ultraplan 한 줄 요약
Claude Code Ultraplan은 CLI에서
/ultraplan으로 시작하고, 플랜 초안은 Claude Code on the web 세션에서 다듬는 흐름이에요. 개인 구독 기준 Pro나 Max면 바로 시도할 수 있고, GitHub 저장소 접근은 GitHub App이나/web-setup둘 중 하나로 잡아야 해요. 다만 2026-04 기준 Research Preview라서 stream timeout, 결과 소실, stale snapshot 같은 함정은 먼저 막아두는 편이 낫더라고요.
30분 가까이 플랜을 돌리는 동안 터미널이 비어 있는 경험, 처음엔 좀 이상하더라고요. 보통 plan mode는 화면을 붙잡고 있어야 하니까요. 근데 Claude Code Ultraplan은 그 병목을 클라우드 쪽으로 빼는 구조예요. CLI에서 플랜만 떼어 웹 세션으로 보내니까, 터미널을 붙잡고 있을 일이 줄어들더라고요.
여기서 많이 막히는 건 기능 설명이 아니에요. GitHub 연결을 왜 요구하는지, Pro로도 버틸 수 있는지, 플랜 도는 동안 로컬에서 고친 파일이 왜 반영 안 되는지 같은 실전 문제죠. 2026-04 기준 공식 문서를 다시 보면 시작 조건은 생각보다 단순한데, 삽질 포인트는 따로 있더라고요. 버전 체크, GitHub 접근 방식, 미커밋 변경, Remote Control 충돌 같은 것들요.
브라우저 리뷰 화면이 편하다고 무조건 좋은 것도 아니에요. 승인 UI가 안 뜨거나, 세션이 길어지다 출력이 날아가거나, 스냅샷이 오래된 상태로 남는 이슈도 있어요. 파일 여러 개가 엮인 리팩터링이나 마이그레이션이면 차이가 크고, 반대로 한두 파일 수정이면 시간만 더 들 수 있죠.
아래 순서를 한 번 따라 하면 바로 켤 수 있고, 왜 굳이 로컬 plan mode를 계속 쓰는지도 같은 흐름에서 보여요. 실제로는 claude --version, git status, /ultraplan, /tasks 이 네 군데만 제대로 봐도 삽질 절반은 줄어들어요.
Ultraplan은 결국 어디서 돌고 어디서 리뷰하나
Ultraplan은 plan mode를 새로 만든 기능이라기보다, 플랜 짜는 구간만 클라우드 웹 세션으로 넘기는 흐름에 가까워요. 어디서 시작하고 어디서 검토하는지부터 잡아야 덜 꼬여요. 굳이 브라우저까지 가야 하나 싶죠?
결론부터 보면 시작은 CLI, 리뷰는 웹 세션이에요. 2026-04 기준 Anthropic 공식 문서는 Claude Code 사용 환경을 CLI, Desktop, VS Code, JetBrains, Web, Mobile, 그리고 Chrome·Slack·CI/CD(배포 파이프라인) 연동까지 넓게 잡고 있지만, Ultraplan 문서는 시작 지점을 CLI, 리뷰 지점을 웹 세션 기준으로 못 박아둬요. 이 차이를 먼저 알고 들어가면 헤매는 시간이 줄어요.
| 사용 환경 | Claude Code에서 하는 일 | Ultraplan과의 연결 |
|---|---|---|
| CLI | 명령 입력, plan mode, /tasks 확인 |
시작 지점 |
| Web | 클라우드 세션 실행, diff 리뷰, PR 생성 | 플랜 리뷰와 원격 실행 지점 |
| Desktop | 일반 Claude Code 작업, 병렬 세션, 시각적 리뷰 | Ultraplan 전용 시작점으로 문서화되진 않았어요 |
| VS Code | 에디터 안에서 파일 맥락과 diff 보기 | 주변 작업 환경 |
| JetBrains | IntelliJ, PyCharm 계열에서 Claude Code 쓰기 | 주변 작업 환경 |
| Mobile | 클라우드 세션 모니터링, 원격 작업 확인 | 보조 확인용 |
| Chrome / Slack / CI/CD | 브라우저 조작, 팀 채널, 자동화 파이프라인 연동 | 직접적인 Ultraplan 시작점은 아니에요 |
브라우저 세션 자체가 아직 낯설면 Claude Code on the Web 사용법: 브라우저에서 돌리는 AI 코딩 에이전트부터 먼저 보고 오는 편이 덜 헷갈려요. Ultraplan도 결국 그 웹 인프라 위에서 플랜을 다듬는 흐름이거든요.
claude code ultraplan 켜기 전에 체크할 것
여긴 기능 설명보다 사전 조건이 더 중요해요. 세팅이 하나라도 비면 /ultraplan이 아예 안 뜨거나, 떠도 중간에 막힐 수 있어요. GitHub 하나만 있다고 다 풀리진 않아요. 버전, 요금제, 로그인 경로까지 같이 걸려요.
최신 조건은 Ultraplan 공식 문서와 Claude 요금제 페이지 기준으로 보는 게 가장 빨라요. 커뮤니티 글은 빠르긴 한데, 연구 미리보기 기능은 며칠 사이에도 조건이 바뀌더라고요.
체크리스트부터 짧게 보면 이래요.
claude --version이v2.1.91이상인가 (권장v2.1.101+)- 작업 대상이 GitHub 저장소인가
- GitHub 접근을 GitHub App 또는
/web-setup으로 잡았는가 - 개인 구독이면 Pro 또는 Max인가
- Bedrock, Vertex, Foundry 경로로 로그인한 세션은 아닌가
- 미커밋 변경이 너무 많지 않은가
요금은 개인 기준으로 이렇게 보면 돼요.
| 항목 | 2026-04 기준 공식 가격 |
|---|---|
| Pro | 연간 환산 월 17달러, 월간 결제 20달러 |
| Max 5x | 월 100달러 |
| Max 20x | 월 200달러 |
Pro도 진입 자체는 돼요. 다만 Claude와 Claude Code 사용량이 같이 묶여서 계산되기 때문에, 큰 리팩터링 플랜을 여러 번 돌리면 사용량 한도에 먼저 닿을 수 있어요. 그래서 대형 작업은 Max 쪽이 덜 빡빡하고, 작은 작업은 로컬 plan mode로 빼는 식이 현실적이더라고요.
버전도 한 번 체크하세요. v2.1.91에서 /ultraplan 자체는 열려요. v2.1.101부터는 원격 세션 기능이 기본 cloud environment를 자동으로 만들어 줘서, 브라우저에서 환경부터 잡는 옛날 절차가 필요 없어요. 예전 글처럼 직접 잡으라는 설명이 남아 있으면 그건 한 템포 지난 정보일 가능성이 커요.
처음 설치부터 다시 보고 싶으면 Claude Code 사용법: 설치부터 첫 실행까지 5분 가이드 쪽이 바로 이어져요. 여기서 버전 확인까지만 끝내고 돌아오면 돼요.
Ultraplan 첫 실행 워크플로
처음 한 번만 순서를 맞추면 흐름은 단순해요. 버전 확인하고, 커밋 상태 정리하고, /ultraplan으로 보내고, 브라우저에서 리뷰한 뒤 어디서 실행할지 고르면 끝나요. 이걸 미커밋 상태로 바로 돌릴 건 아니죠?
먼저 작업트리부터 정리해요. 클라우드 세션은 저장소를 새로 clone한 상태(fresh clone)로 뜨기 때문에, 내 로컬에서만 바뀐 파일은 플랜이 못 봐요.
# 버전과 작업트리 상태 먼저 보기
claude --version
git status --short
# 스냅샷을 맞추고 싶으면 먼저 커밋하고 푸시
git add .
git commit -m "prep: snapshot before ultraplan"
git push origin HEAD
그다음 Claude Code 세션 안에서 /ultraplan을 던져요. 프롬프트는 설명보다 스펙에 가깝게 쓰는 편이 나아요.
/ultraplan
Express 5.x와 PostgreSQL 14를 쓰는 서비스예요.
src/auth/ 아래만 보고 JWT 마이그레이션 플랜을 짜줘.
기존 세션 쿠키 호환은 유지해야 해요.
영향 파일, 테스트 위치, 롤백 포인트를 같이 적어줘.
흐름은 보통 이렇게 가요.
- CLI에
◇ ultraplan상태가 보이고 브라우저 링크가 떠요. - 웹 세션에서 섹션별 코멘트나 이모지 반응으로 플랜을 다듬어요.
- 다 됐으면 웹에서 실행 위치를 골라요.
- 브라우저 실행이면 그대로 클라우드에서 구현하고 PR까지 이어져요.
- 터미널로 되돌리면
Implement here,Start new session,Cancel셋 중 하나를 고를 수 있어요. - 세션을 놓쳤으면
/tasks로 다시 열어보면 돼요.
Cancel이 은근 쓸모 있어요. 지금 당장 실행은 안 하고 플랜 파일만 저장해 두고 싶을 때 좋거든요. 나중에 다시 실험하기도 편하죠. Start new session을 고르면 claude --resume 명령을 같이 띄워줘요. 원래 대화를 버린 건 아니라는 뜻이에요.
세션 흐름을 보는 감각은 Claude Code Monitor 도구로 배포 로그 실시간 추적하기에서 다룬 장시간 작업 모니터링 느낌이랑 꽤 비슷해요. Ultraplan도 결국 백그라운드 태스크 하나로 보는 편이 덜 복잡해요.
자주 터지는 함정 4가지와 회피법
여기부터가 실전이에요. 기능 자체보다 함정 회피를 먼저 알면 비용도 덜 쓰고 멘탈도 덜 깎여요. 왜 멀쩡해 보이는데 승인 버튼이 안 뜨냐고요?
2026-04 기준 커뮤니티와 GitHub 이슈를 모아보면 많이 반복되는 문제는 네 가지로 압축돼요.
| 함정 | 증상 | 먼저 할 일 |
|---|---|---|
| Stream idle timeout | 브라우저에서 스피너만 돌고 승인 UI가 안 떠요 | 프롬프트 범위를 줄이고, WSL2면 재현 여부를 따로 체크 |
| 장시간 세션 종료 후 결과 소실 | 오래 기다렸는데 결과가 남지 않아요 | 범위를 잘게 나누고, 결과가 뜨면 바로 저장 경로 확보 |
| Plan mode 위반 | 승인 뒤 플랜 파일이 아니라 소스 파일부터 건드려요 | 바로 중단하고 플랜만 저장한 뒤 새 세션에서 다시 실행 |
| Stale snapshot | 로컬에서 방금 고친 내용이 플랜에 안 보여요 | 커밋·푸시 후 다시 시작 |
이 중 stale snapshot은 구조 문제에 가까워요. 공식 웹 문서도 클라우드 세션이 새로 clone한 상태로 시작한다고 적어두고 있어서, 로컬에서만 바뀐 파일은 원격 플랜이 모르는 게 정상이에요. 그래서 Ultraplan 직전 git status가 제일 중요해요.
Remote Control 충돌도 자주 헷갈려요. 공식 Ultraplan 문서에는 Remote Control이 켜져 있으면 Ultraplan 시작 시 끊긴다고 나와 있어요. 둘 다 claude.ai/code 인터페이스를 잡아먹기 때문이죠. 이 흐름을 이미 쓰고 있다면 Claude Code Remote Control 사용법: 폰에서 이어받고 VPS에서 돌리기를 먼저 보고 충돌 지점을 정리하는 편이 나아요.
회피 팁을 짧게 적으면 이래요.
- 프롬프트는 넓은 요청보다 좁은 스펙으로 써요
- 미커밋 변경은 최대한 줄여요
- 플랜이 보이면 바로 읽고, 바로 저장 경로를 챙겨요
- 승인 직후 동작이 이상하면 새 세션에서 다시 붙여요
claude code ultraplan vs 로컬 plan mode
Ultraplan이 늘 더 좋은 건 아니에요. plan mode를 클라우드로 옮기면서 검토 표면이 좋아진 거지, 작은 작업까지 다 보내면 오히려 돌아가요. 한 파일 rename하는데 굳이 웹 세션까지 띄울까요?
rename 하나면 로컬 plan mode가 빨라요. 웹 세션은 파일 범위가 넓어질수록 값어치가 올라오고, 그 전엔 오히려 시작 비용만 더 내는 셈이에요. 선택 기준은 생각보다 단순해요.
| 항목 | 로컬 plan mode | Ultraplan |
|---|---|---|
| 시작 속도 | 빠름 | 웹 세션 여는 시간이 들어가요 |
| 검토 방식 | 터미널 중심 | 브라우저에서 섹션별 코멘트 가능 |
| 터미널 점유 | 계속 잡고 있어요 | 플랜 작성 중엔 터미널이 비어요 |
| GitHub 필요 | 아니에요 | 필요해요 |
| 클라우드 의존 | 낮음 | 높아요 |
| 잘 맞는 작업 | 소규모 수정, 범위가 명확한 변경 | 대규모 리팩터링, 마이그레이션, 리뷰가 필요한 플랜 |
| 안 맞는 작업 | 거의 없음 | 한 줄 수정, 영향 파일이 1~2개인 작업 |
체감 기준도 이 정도예요.
- 영향 파일이 적고 내가 이미 구조를 알고 있다: 로컬 plan mode가 더 빨라요
- 파일 범위가 넓고, 리뷰 코멘트를 섹션별로 남기고 싶다: Ultraplan이 편해요
- 로컬 환경 의존이 강하다: 로컬 plan mode 쪽이 덜 위험해요
- 플랜 짜는 동안 다른 작업을 병행하고 싶다: Ultraplan 쪽 손이 덜 가요
노트북 덮어도 계속 돌아가는 장시간 작업 감각은 Claude Code 루틴 실전 가이드: PR 리뷰·배포 검증을 노트북 꺼도 돌리는 법과 결이 비슷해요. 근데 Ultraplan은 실행보다 플랜 리뷰가 중심이라, “백그라운드에서 오래 돌린다”보다 “플랜을 웹에서 더 잘 본다”에 초점을 맞추는 편이 맞아요.
자주 묻는 질문
Q1: Ultraplan이 로컬 plan mode랑 뭐가 달라요?
A: 로컬 plan mode는 지금 열어둔 세션 안에서 플랜을 짜고 바로 이어가는 흐름이에요. Ultraplan은 그 플랜 구간을 웹 세션으로 넘겨서 브라우저에서 코멘트 달고, 다시 클라우드나 터미널 쪽으로 실행 위치를 고르는 방식이죠. 더 똑똑하다기보다 워크플로가 달라요.
Q2: GitHub 연동이 왜 필요해요? GitLab만 쓰면 안 되나요?
A: 공식 문서 기준 Ultraplan은 Claude Code 계정과 GitHub 저장소 접근을 요구해요. GitHub 접근은 GitHub App이나 /web-setup 둘 중 하나로 잡을 수 있어요. 저장소가 GitLab에만 있고 GitHub 쪽 연결이 없다면 시작 조건을 못 맞춘다고 보는 게 맞아요.
Q3: Pro 요금제로도 쓸 수 있어요?
A: 개인 기준으로는 가능해요. 공식 가격 페이지상 Pro는 Claude Code를 웹과 터미널에서 둘 다 쓸 수 있어요. 근데 사용량이 Claude 본체와 묶여서 계산되니까, 긴 플랜 작업을 연속으로 돌릴 땐 Max보다 먼저 한도에 닿기 쉬워요.
Q4: 오래 돌리다 보면 결과가 사라질 수도 있어요?
A: 2026-04 기준 GitHub 이슈에는 장시간 세션 뒤 출력이 남지 않았다는 사례가 있어요. 그래서 범위를 좁게 끊고, 결과가 보이면 바로 검토하거나 저장 경로를 챙기는 식으로 움직이는 편이 안전해요. 큰 작업 하나를 통으로 던지기보다 두세 단계로 쪼개는 게 낫더라고요.
Q5: Bedrock이나 Vertex, Foundry에서도 Ultraplan을 쓸 수 있어요?
A: 공식 Ultraplan 문서는 아니라고 적고 있어요. 이 기능은 Anthropic 클라우드 인프라에서 돌아가서 Bedrock, Vertex, Foundry 경로에선 열리지 않아요. 그 환경을 써야 한다면 로컬 plan mode 쪽이 현실적인 대안이에요.
