Claude Code Ultraplan: Hướng Dẫn Từng Bước (2026)

Ultraplan trông rất hay trên giấy: Claude plan trên cloud, terminal vẫn tự do, bạn review qua browser với inline comments. Nhưng có một con số mình ước gì biết trước trước khi thử lần đầu: mỗi workflow Ultraplan với một lần revision tốn khoảng 33% session budget của Pro plan. Với giới hạn 5 giờ mỗi session, một task Ultraplan có thể ngốn gần 1.65 giờ quota chỉ để planning.

Mình dùng /ultraplan lần đầu cho task “migrate auth service từ sessions sang JWT”. Plan xong, revision một lần, approve execution. Nhìn lại /cost mới thấy mình vừa dùng một phần ba phần session cho ngày hôm đó chỉ để planning. Bài học đó thay đổi hoàn toàn cách mình nhìn claude code ultraplan: không phải tool dùng mọi lúc, mà tool dùng đúng chỗ.

Case study JWT migration này minh họa rõ nhất value của Ultraplan: thay vì nhảy vào code ngay, nó buộc bạn phải nghĩ qua toàn bộ impact trước.

Bài này sẽ hướng dẫn từng bước cách dùng Ultraplan, nhưng quan trọng hơn, nó sẽ cho bạn biết chính xác khi nào thì Ultraplan xứng đáng với chi phí đó và khi nào thì local plan mode vẫn tốt hơn.

Ultraplan Trong Claude Code Là Gì?

Ultraplan là tính năng cloud planning trong Claude Code CLI: khi bạn invoke /ultraplan, một session Claude Code on the web được mở trên server Anthropic, Claude dùng Opus 4.6 để đọc codebase từ GitHub và soạn thảo plan trong tối đa 30 phút, còn terminal của bạn vẫn tự do để tiếp tục làm việc khác. Khi plan xong, bạn mở link trên browser để review, comment inline, yêu cầu revision, rồi chọn execute cloud hoặc teleport plan về terminal.

Khác với local plan mode (Claude soạn plan ngay trong terminal, bạn đọc qua scrollback), Ultraplan cho bạn một review interface đầy đủ với 3 tính năng: inline comments (highlight đoạn nào cũng comment được), emoji reactions (approve hoặc flag từng section nhanh), và outline sidebar (nhảy giữa các phần của plan). Đây là điểm khác biệt lớn nhất về UX, không phải về chất lượng plan.

Điểm cần lưu ý ngay: Ultraplan yêu cầu cài đặt Claude Code phiên bản v2.1.92 trở lên, Pro hoặc Max subscription, và GitHub repository. Không có bất kỳ điều nào trong 3 điều trên thì Ultraplan không chạy được. Phần requirements chi tiết ở bước 1 của tutorial.

Tại Sao Không Nên Dùng Ultraplan Cho Mọi Task?

Câu trả lời ngắn: Ultraplan tốn session budget đáng kể và có overhead time nhất định. Hiểu rõ Ultraplan Cost Threshold giúp bạn tránh dùng tool này sai chỗ.

Trong thực tế, một workflow Ultraplan hoàn chỉnh có một lần revision tốn khoảng 33% session budget của tài khoản Pro (giới hạn 5 giờ). Số này bao gồm: provisioning cloud container, Claude clone repo và đọc codebase, soạn plan lần đầu, và một lần revision sau khi bạn comment. Tức là 3 workflows như vậy trong một ngày là hết session.

Thêm vào đó, overhead time không nhỏ: nhỏ nhất là 3-8 phút cho task trung bình, lên đến 10-15 phút cho task phức tạp. Nếu bạn dùng Ultraplan cho task mà local plan mode có thể xử lý trong 2 phút, bạn đang đánh đổi 15 phút + 33% budget để lấy một browser UI đẹp hơn.

Ultraplan Cost Threshold là framework đơn giản để quyết định: task có đủ phức tạp để xứng đáng với chi phí không?

• Vượt threshold (dùng Ultraplan): Task ảnh hưởng đến >50 files, migration/refactor lớn, quyết định kiến trúc có nhiều phương án, hoặc bạn ước tính local plan mode sẽ mất >10 phút để soạn một plan đủ tốt
• Dưới threshold (dùng local plan mode): Task rõ ràng dưới 30 files, approach đã biết trước, cần iteration nhanh, hoặc repo không trên GitHub

Một lý do nữa không ai nói đến: Ultraplan dùng Opus 4.6 cho cloud planning, còn local plan mode dùng model bạn đang chạy trong session (thường là Sonnet 4.6). Với task đơn giản, Sonnet plan đủ tốt và cost gần bằng 0 so với 33% session limit của Ultraplan. The model tier gap chỉ justify được với task thực sự phức tạp, multi-file, nơi Opus đọc codebase sâu hơn và đặt câu hỏi clarifying tốt hơn trước khi commit vào approach.

Làm Thế Nào Để Dùng Ultraplan Trong 4 Bước?

Quy trình cốt lõi: check requirements, invoke từ CLI, review trong browser, chọn execution path. Nhớ Ultraplan-Khi-Nào Rule: chỉ invoke khi task vượt Ultraplan Cost Threshold ở phần trên, tức là ảnh hưởng >50 files hoặc estimate local plan >10 phút.

Bước 1: Kiểm Tra Requirements

Trước khi invoke, confirm đủ 3 điều kiện:

1. Phiên bản: Claude Code v2.1.92 trở lên. Kiểm tra bằng claude --version. Nếu thấp hơn, chạy claude update. Từ v2.1.101 trở lên, Ultraplan tự tạo cloud environment lần đầu nếu chưa có, không cần setup tay.

2. Subscription: Pro hoặc Max (không phải Free hay API key-only). Nếu dùng API key mà không có Pro/Max account trên claude.ai, Ultraplan sẽ báo error và không launch. Đây là điểm nhiều người miss.

3. GitHub repository: Repo phải host trên GitHub, không phải GitLab hay Bitbucket. Ultraplan clone repo vào cloud container để đọc codebase, nên cần GitHub connection. Local-only repo hoặc private repo chưa push cũng không được.

Yêu cầu GitHub repository xuất phát từ cách Ultraplan cần truy cập vào code history và PR context để tạo kế hoạch chính xác.

Nếu thiếu bất kỳ điều kiện nào, Claude sẽ báo lỗi cụ thể trước khi launch confirmation dialog, không waste thời gian.

Bước 2: Khởi Chạy /ultraplan Từ CLI

Có 3 cách invoke Ultraplan từ terminal:

# Cách 1: Command trực tiếp
/ultraplan migrate the auth service from sessions to JWTs

# Cách 2: Keyword trong prompt thường
migrate the auth service from sessions to JWTs ultraplan

# Cách 3: Từ local plan mode đã có
# Claude soạn xong plan local, hiện approval dialog
# Chọn: "No, refine with Ultraplan on Claude Code on the web"

Sau khi invoke (cách 1 hoặc 2), Claude hiện confirmation dialog trước khi launch. Sau khi confirm, terminal hiện status indicator:

Trong khi terminal hiện status indicator, bạn hoàn toàn tự do làm việc khác: viết code, chạy tests, review PR. Đây là điểm khác biệt với local plan mode, vốn block terminal khi Claude đang plan.

Bước 3: Review Và Annotate Plan Trong Browser

Khi status chuyển thành ◆ ultraplan ready, chạy /tasks trong terminal để xem session link, hoặc Claude tự in link ra. Mở link trên browser để xem plan.

Plan hiện trong dedicated review view với 3 tính năng:

Inline comments: Highlight bất kỳ đoạn nào trong plan, để lại comment yêu cầu Claude address. Đây là cách hiệu quả nhất để chỉnh plan vì Claude nhận chính xác context của feedback thay vì phải đọc lại toàn bộ plan.

Emoji reactions: React emoji (approve, flag, reject) vào từng section để signal nhanh mà không cần viết comment đầy đủ. Dùng khi section looks good nhưng bạn muốn mark để review lại sau.

Outline sidebar: Jump giữa các section của plan mà không cần scroll. Hữu ích với plan dài 50+ steps.

Khi bạn để lại comments, Claude revision plan và hiện bản updated. Bạn có thể iterate nhiều lần trước khi approve. Lưu ý: mỗi lần revision cộng thêm vào session budget usage, nên target 1-2 lần revision tối đa.

Bước 4: Chọn Execute Cloud Hoặc Teleport Về Terminal

Khi plan đã ổn, bạn chọn 1 trong 2 execution path từ browser:

Execute trên cloud: Chọn “Approve Claude’s plan and start coding”. Claude implement plan trong cùng cloud session, terminal nhận confirmation và status indicator tắt. Khi implementation xong, bạn review diff trên web interface và tạo pull request từ đó. Kết hợp tốt với Monitor Tool nếu cần watch long-running build trong quá trình cloud execution.

Teleport về terminal: Chọn “Approve plan and teleport back to terminal”. Cloud session được archive, plan được gửi về terminal. Terminal hiện dialog với 3 options:

• Implement here: Inject plan vào conversation hiện tại và tiếp tục từ đó
• Start new session: Clear conversation hiện tại, bắt đầu fresh với chỉ plan làm context. Claude print claude --resume command để bạn quay lại session cũ sau nếu cần
• Cancel: Save plan vào file mà không execute, Claude print file path

Mình thường chọn “Teleport về terminal + Start new session” cho task migration lớn: context sạch, chỉ có plan làm foundation, không có noise từ conversation trước.

Platform Hỗ Trợ Ultraplan: GitHub, Bedrock Và Vertex AI

Ultraplan chỉ hoạt động trong Claude Code CLI với account claude.ai. Đây là giới hạn quan trọng cần biết trước khi setup workflow.

Bảng đầy đủ theo Anthropic Claude Code Documentation:

Nếu bạn đang dùng Claude Code qua Bedrock hoặc Vertex cho enterprise compliance requirements, Ultraplan không phải option. Trong trường hợp đó, local plan mode với Opus via API là cách gần nhất để đạt chất lượng plan tương đương, dù không có browser review UI.

Khi Nào Nên Dùng Ultraplan Và Khi Nào Dùng Local Plan Mode?

Ultraplan-Khi-Nào Rule là framework quyết định 3 chiều: Ultraplan, local plan mode, hoặc Superpowers skill. Mỗi tool có điểm mạnh riêng và không tool nào dominates hoàn toàn.

Ultraplan Cost Threshold là ranh giới: vượt qua nó thì Ultraplan worth it, dưới thì không.

Điểm phân biệt core của Ultraplan-Khi-Nào Rule: Ultraplan phù hợp khi “planning là phần khó nhất”, còn local plan mode phù hợp khi “execution là phần khó nhất”. Nếu bạn đã biết sẽ làm gì, chỉ cần Claude implement thôi, thì không cần Ultraplan.

Kết hợp với Claude Code Hooks sẽ giúp tự động trigger Ultraplan review cho một số loại task, ví dụ hook khi detect file count thay đổi lớn trong git diff.

Làm Thế Nào Để Xử Lý Lỗi Phổ Biến Với Ultraplan?

Lỗi “Stream idle timeout” (phổ biến nhất): Browser hiện “API Error: Stream idle timeout, partial response received” và nút approve không bao giờ xuất hiện. Đây là bug đã documented trong GitHub issue #47252. Workaround: retry một lần (stop ultraplan qua /tasks, invoke lại), reduce prompt complexity (chia task thành scope nhỏ hơn), và tránh invoke trong giờ cao điểm server load.

Lỗi “Approval UI missing”: Bạn mở session link nhưng không thấy review interface, chỉ thấy blank hoặc error. Nguyên nhân thường là session đã expired (mặc định timeout sau một thời gian không active) hoặc browser caching issue. Fix: clear browser cache, dùng incognito window, hoặc copy session link từ /tasks output thay vì dùng link cũ.

Lỗi “Plan mode violated”: Sau khi approve plan và teleport về terminal, Claude bắt đầu edit source files thay vì theo plan. Bug này được document trong GitHub issue #43576. Workaround tạm thời: dùng “Start new session” option thay vì “Implement here” khi teleport về terminal, context clean giúp Claude follow plan tốt hơn.

Ultraplan không launch (silent fail): Invoke /ultraplan nhưng không có gì xảy ra. Check: subscription type (Free plan không support), version Claude Code (claude --version phải từ v2.1.92+), và GitHub connection (claude auth status).

Hai lỗi “Stream idle timeout” và “Approval UI missing” thường xuất hiện cùng nhau khi session budget đã gần cạn – đây là dấu hiệu bạn nên bắt đầu session mới thay vì tiếp tục ép /ultraplan chạy.

Câu Hỏi Thường Gặp

Ultraplan Trong Claude Code Là Gì?

Ultraplan là tính năng cloud planning của Claude Code CLI: khi invoke /ultraplan, một session Claude Code on the web được mở trên server Anthropic, Claude Opus 4.6 đọc codebase từ GitHub và soạn implementation plan trong tối đa 30 phút, trong khi terminal của bạn vẫn tự do. Ra mắt trong Claude Code v2.1.92, Week 15 (April 2026). Không cần setup thêm từ v2.1.101 trở lên.

Ultraplan Khác Plan Mode Như Thế Nào?

Local plan mode chạy trong terminal, dùng model bạn đang session (thường Sonnet 4.6), plan hiện dưới dạng text thuần. Ultraplan chạy trong cloud, dùng Opus 4.6, plan hiện trong browser UI với inline comments và emoji reactions. Local plan mode gần như free về session budget. Ultraplan tốn ~33% session budget per workflow. Local plan mode nhanh hơn (2-3 phút). Ultraplan sâu hơn nhưng lâu hơn (3-15 phút).

Ultraplan Có Trên Bedrock Không?

Không. Ultraplan chỉ hoạt động trong Claude Code CLI với claude.ai Pro hoặc Max subscription và GitHub repo. Amazon Bedrock, Google Vertex AI, và Microsoft Azure Foundry đều không support. Nếu bạn cần cloud planning qua Bedrock, lựa chọn gần nhất là local plan mode với Opus 4.6 via API key, dù không có browser review UI.

Ultraplan Tốn Bao Nhiêu Token/Session Budget?

Khoảng 33% session budget của Pro plan (giới hạn 5 giờ) cho một workflow hoàn chỉnh với một lần revision. Tức là bạn có thể chạy khoảng 3 workflows Ultraplan mỗi ngày trước khi hit session limit. Con số này bao gồm: clone repo, đọc codebase, soạn plan, và revision. Task phức tạp hơn hoặc revision nhiều lần sẽ tốn hơn.

Làm Sao Fix Lỗi Stream Idle Timeout?

Đây là bug đã biết (GitHub issue #47252). Workaround: dừng ultraplan session qua /tasks chọn “Stop ultraplan”, invoke lại với prompt đơn giản hơn, tránh giờ cao điểm. Nếu lỗi lặp lại nhiều lần với cùng task, thử break task thành 2 Ultraplan sessions nhỏ hơn thay vì một session lớn.

Có Thể Dùng Ultraplan Với GitLab Không?

Không. Ultraplan chỉ support GitHub-hosted repositories. GitLab, Bitbucket, và local repositories (chưa push lên GitHub) không được support vì Ultraplan cần clone repo vào cloud container. Nếu bạn dùng GitLab, local plan mode là lựa chọn duy nhất hiện tại.

Kết Luận

Ultraplan giải quyết một vấn đề cụ thể: task quá phức tạp để plan tốt trong terminal, cần Opus 4.6 đọc sâu codebase, và cần review interface để catch misunderstood scope trước khi code một chữ. Ultraplan-Khi-Nào Rule đơn giản: task >50 files hoặc estimate local planning >10 phút thì dùng Ultraplan. Ngắn hơn thì local plan mode nhanh hơn và gần như free.

Hai điểm cần nhớ nhất: 33% session budget per workflow, tức là chỉ dùng cho task quan trọng nhất trong ngày. Và GitHub repository là bắt buộc, không có workaround.

Bước tiếp theo: sau khi có plan từ Ultraplan, kết hợp với lệnh /autofix-pr để Claude tự động watch CI và push fix khi execution xong. Hoặc xem thêm Claude Code Hooks để setup trigger tự động cho Ultraplan dựa trên git diff pattern. Xem tổng hợp tất cả tính năng tại roadmap đầy đủ Claude Code 2026.