agentic-harness

참고자료 · Claude Code

Claude Code /ultraplan — 클라우드에서 계획을 돌리고 터미널은 비워 둡니다

Claude Code 의 /ultraplan 슬래시 명령은 기존 로컬 plan mode 와 다른 새로운 작동 방식을 도입합니다. 계획 수립 단계를 Anthropic 의 클라우드 인프라에서 수행해서, 계획이 작성되는 동안 로컬 터미널은 다른 작업에 자유롭게 쓸 수 있습니다. 이 페이지는 Anthropic 공식 문서를 1차 출처로 해서 ultraplan 의 동작 방식, 요구 조건, 실행 경로, 운영 팁을 정리합니다.

Claude Code — Ultraplan 공식 문서 ↗Claude Code Changelog ↗Anthropic Opus 4.6 — Agent Teams ↗Claude Support — Using Claude Code with Pro/Max ↗

1. 무엇인가 — 한 문단 요약

Ultraplan 은 Claude Code 의 슬래시 명령으로, 사용자가 요청한 작업의 “계획” 을 로컬이 아니라 Anthropic 의 클라우드에서 작성합니다. 로컬 Claude Code 는 계획 요청을 전달한 즉시 제어권을 돌려받고, 사용자는 터미널에서 다른 작업을 계속하면서 웹 브라우저에서 작성된 계획을 검토하고 수정할 수 있습니다. 계획이 확정되면 두 가지 경로로 실행을 이어갈 수 있습니다. 클라우드 세션이 그대로 구현을 맡아 PR 을 생성하거나 (“Approve Claude's plan and start coding”), 계획만 로컬 터미널로 다시 끌어오는 teleport 모드 (“Approve plan and teleport back to terminal”) 입니다 (공식 문서).

2. 세 가지 호출 방법

공식 문서는 ultraplan 을 시작하는 세 가지 방법을 설명합니다.

  • 슬래시 명령: /ultraplan 뒤에 프롬프트를 붙여 실행합니다. 문서 인용: “run /ultraplanfollowed by your prompt” (공식 문서).
  • 키워드 감지: 일반 프롬프트 안에 “ultraplan” 이라는 단어를 포함하면 Claude Code 가 자동으로 ultraplan 경로를 제안합니다.
  • 로컬 plan mode 에서 업그레이드: 이미 로컬에서 plan mode 를 실행 중이면 그 세션에서 직접 ultraplan 으로 상승시킬 수 있습니다.

3. 요구 조건

요구 1

Claude Code v2.1.91 이상

공식 문서: “Ultraplan is in research preview and requires Claude Code v2.1.91 or later.” (공식 문서)

요구 2

Pro / Max / Team / Enterprise 플랜

공식 문서: “Ultraplan requires a Claude Code on the web account (Pro, Max, Team, or Enterprise)” (공식 문서). 사용자가 많이 퍼뜨린 “Pro/Max 만 지원” 은 공식 문서 기준 정확하지 않습니다 — Team · Enterprise 도 포함됩니다.

요구 3

GitHub 저장소 연결

공식 문서: “Ultraplan requires a Claude Code on the web account and a GitHub repository.” 프로젝트가 GitHub 과 동기화돼 있어야 클라우드 세션이 계획을 읽고 PR 을 생성할 수 있습니다.

제약

AWS Bedrock · GCP Vertex AI · Microsoft Foundry 에서는 작동하지 않음

공식 문서 인용: “Because it runs on Anthropic's cloud infrastructure, it is not available when using Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry.” 우회 연동 환경에서는 기존 로컬 plan mode 를 쓰셔야 합니다.

4. 실제 흐름 — 호출부터 PR 까지

공식 문서의 흐름을 요약하면 다음과 같습니다.

  1. 사용자가 로컬 Claude Code 에서 /ultraplan 명령으로 작업을 요청합니다.
  2. 로컬 CLI 는 클라우드 세션을 시작한 뒤 즉시 제어권을 반환합니다. 문서 인용: “Claude drafts the plan in the cloud while you keep working in your terminal.” CLI 는 3초 간격으로 상태를 폴링하면서 계획 진행 상황을 보여줍니다.
  3. 클라우드 세션이 계획 문서를 작성하는 동안 사용자는 브라우저에서 웹 UI 를 열 수 있습니다. 웹 UI 는 다음 세 가지 리뷰 기능을 제공합니다.
    • Inline comments: 계획의 특정 구간을 선택해서 수정 요청 댓글을 남깁니다. 인용: “highlight any passage and leave a comment for Claude to address.”
    • Emoji reactions: 긴 코멘트 없이 이모지 반응으로 승인·우려 신호를 전달합니다.
    • Outline sidebar: 긴 계획 문서의 섹션을 사이드바에서 빠르게 점프합니다.
  4. 사용자가 계획을 승인하면 두 가지 실행 경로 중 선택합니다.
    • Approve Claude's plan and start coding: 같은 클라우드 세션이 그대로 구현을 이어갑니다. 완료 시 웹에서 diff 를 검토하고 PR 을 생성합니다.
    • Approve plan and teleport back to terminal: 웹 세션은 아카이브되고, 계획이 로컬 터미널로 돌아옵니다. 이후 구현은 평소처럼 로컬 Claude Code 에서 진행합니다. CLI 는 “Ultraplan approved” 다이얼로그로 Implement here / Start new session / Cancel 세 옵션을 보여줍니다.

5. 언제 쓰면 가치가 있는가

공식 문서는 ultraplan 의 가치를 세 가지 표현으로 설명합니다.

  • Targeted feedback: 계획의 특정 섹션에 대해 구체적인 수정 요청을 주고받을 수 있어 대규모 작업의 초기 방향 잡기가 쉬워집니다.
  • Hands-off drafting: 계획이 원격에서 생성되므로 로컬 터미널이 다른 작업에 자유롭게 쓸 수 있습니다.
  • Flexible execution: 승인 후 클라우드에서 바로 PR 을 만들지, 로컬에서 구현할지 선택할 수 있습니다.

6. 내부 아키텍처에 대한 알림

사용자가 보고한 “3개 탐색 에이전트 + 1개 비평 에이전트 병렬 실행” 구성은 공식 Anthropic 출처에서 직접 확인되지 않습니다. Opus 4.6 의 “Agent Teams” 발표 (anthropic.com/news/claude-opus-4-6) 가 병렬 에이전트 조율 개념을 도입했고 ultraplan 이 그 위에서 동작할 가능성은 높지만, 정확한 에이전트 개수와 역할 구성은 현재 공식 문서에서 공개되지 않았습니다. 이 부분은 [출처 미확인 — 공식 문서 미명시, 커뮤니티 소스 분석만 존재] 로 표기합니다.

7. 운영 팁 — Front-load Context 가 가장 중요합니다

Ultraplan 의 클라우드 세션은 사용자의 로컬 환경을 완전히 처음 보는 상태에서 시작합니다. 로컬 CLAUDE.md, .claude/ 설정, 기존 파일 구조를 백지에서 탐색해야 하므로, 프롬프트를 짤 때 다음 세 가지를 앞쪽에 넣는 것이 결과 품질에 크게 영향을 줍니다.

  • 핵심 파일 경로: 작업의 시작점이 되는 파일들을 경로로 명시하면 클라우드 에이전트가 탐색 시간을 아낄 수 있습니다.
  • 현재 아키텍처의 한 줄 요약: 어느 프레임워크, 어느 빌드 시스템, 어느 배포 파이프라인인지 먼저 알려 주면 중간 판단이 빨라집니다.
  • 반드시 피해야 할 경로: 수정하면 안 되는 디렉터리, 손대면 안 되는 설정 파일, destructive 명령 금지 같은 제약을 앞에 둡니다.

이 원칙은 ultraplan 에만 해당하지 않고, 모든 클라우드 기반 AI 코딩 도구에 공통되는 권장입니다. 핵심은 “컨텍스트를 에이전트가 탐색하게 두지 말고, 처음부터 사용자가 던져라” 입니다.

8. 로컬 Plan mode 와의 차이

축로컬 Plan mode (기존)/ultraplan (클라우드 오프로드)
계획 실행 위치사용자 로컬 머신Anthropic 클라우드 인프라
터미널 점유점유 (사용자는 기다려야 함)즉시 반환 + 3초 폴링 상태
리뷰 UI터미널 텍스트브라우저 웹 UI (인라인 댓글, 이모지, 아웃라인)
실행 경로로컬 세션 계속클라우드 구현 + PR or Teleport
요구 조건Claude Code 설치만 있으면 됨v2.1.91+ · Pro/Max/Team/Enterprise · GitHub · Anthropic 클라우드
3rd-party 제공자Bedrock · Vertex AI · Foundry 지원모두 미지원

9. 같이 읽으면 좋은 페이지

Codex Best Practices

OpenAI Codex PM 이 제시한 운영 원칙. Planning 을 처음부터 구조화하는 관점은 ultraplan 과 맞닿아 있습니다.

핸드북 — 앞으로의 방향

클라우드 오프로드 planning 을 런타임 경쟁의 다음 단계로 정리한 섹션입니다.

Claude Code vs Codex 비교

Plan mode · 메모리 · 서브에이전트 차이를 한 장으로 정리한 페이지입니다.

10. Sources

← 참고자료 인덱스로 돌아가기