Chế độ Lập kế hoạch của Claude Code: Vòng lặp tái cấu trúc ưu tiên duyệt thiết kế

Nhiều lập trình viên bắt đầu dùng Claude Code theo cùng một cách: dán một tác vụ, để nó chạy, rồi xem phần diff. Cách đó hiệu quả với thay đổi nhỏ, nhưng hễ đụng tới nhiều tệp thì bắt đầu xuất hiện vấn đề. 

Mỗi quyết định không có định hướng mà Claude đưa ra có thể đúng phần lớn thời gian, nghe có vẻ ổn cho đến khi bạn nhân chồng chúng: ví dụ, nếu bạn giả định độ chính xác 80% cho mỗi quyết định, trên một tính năng có 20 điểm quyết định, 0.8^20 làm cơ hội của bạn tụt còn khoảng 1%.

Chế độ Lập kế hoạch thay đổi bài toán bằng cách thêm một pha chỉ đọc. Bạn buộc Claude đọc toàn bộ mã nguồn, nêu câu hỏi, và tạo một kế hoạch để bạn duyệt trước khi chạm vào bất kỳ tệp nào. 

Hướng dẫn này sẽ đi qua quy trình đó với ví dụ thực tế là một API blog FastAPI lộn xộn, bao quát vòng lặp Khám phá-Lập kế hoạch-Thực thi, chỉnh sửa kế hoạch bằng Ctrl+G, và mở rộng sang các lần tái cấu trúc lớn hơn với Agent Teams. 

Hướng dẫn thực hành tốt nhất cho Claude Code của chúng tôi trình bày sâu hơn về vấn đề lỗi cộng dồn, và hướng dẫn Claude Code 2.1 sẽ giúp bạn cài đặt và tìm hiểu tính năng nếu cần hỗ trợ thiết lập.

Để biết thêm về các mô hình đứng sau Claude Code, hãy xem các hướng dẫn về Claude Sonnet 4.6 và Opus 4.6, hoặc tham gia khóa học Giới thiệu về các Mô hình Claude.

Chế độ Lập kế hoạch của Claude Code là gì?

Chế độ Lập kế hoạch khóa Claude ở trạng thái chỉ đọc. Nó có thể đọc tệp, tìm kiếm trong mã nguồn, và hỏi bạn các câu làm rõ, nhưng mọi nỗ lực ghi tệp, chỉnh sửa mã, hoặc chạy lệnh shell sẽ bị từ chối. Hãy thử yêu cầu nó "chỉ sửa nhanh chỗ này thôi" khi đang ở Chế độ Lập kế hoạch, và nó sẽ không nhúc nhích.

Bạn có thể kích hoạt theo bốn cách:

• Nhấn Shift+Tab hai lần trong ô nhập để chuyển vòng qua Chế độ Thông thường, Tự động chấp nhận, và Lập kế hoạch

• Lệnh /plan đưa vào Chế độ Lập kế hoạch cho tới khi bạn đổi chế độ

• Cờ CLI --permission-mode plan khởi chạy phiên mới ở Chế độ Lập kế hoạch

• Mục settings.json dưới permissions.defaultMode đặt Chế độ Lập kế hoạch làm mặc định cố định

Khi Claude tạo xong một kế hoạch, nó lưu kết quả thành tệp markdown trong ~/.claude/plans/ với tên ngẫu nhiên (như dreamy-orbiting-quokka.md). 

Tệp này là một hợp đồng để duyệt lại: nó tồn tại qua nhiều phiên, sống sót cả khi /clear và khi nén ngữ cảnh, và sẽ không có gì được triển khai cho tới khi bạn phê duyệt. Lưu ý rằng dù tệp kế hoạch tồn tại, đôi khi Claude có thể mất dấu sau khi nén ngữ cảnh trừ khi bạn nhắc nó đọc lại kế hoạch.

Nếu bạn muốn lưu kế hoạch ngay trong dự án để quản lý phiên bản, hãy đặt plansDirectory trong settings.json thành một đường dẫn tương đối của dự án như ./plans.

Kế hoạch theo đường dẫn tương đối dự án mở ra các quy trình làm việc mà ~/.claude/plans/ không hỗ trợ:

• Duyệt diff của kế hoạch trong pull request trước khi bất kỳ ai bắt đầu viết mã
• Giữ chú thích qua nhiều phiên mà không phụ thuộc vào nén ngữ cảnh
• Coi tệp markdown như một bản đặc tả sống, nơi nhiều thành viên nhóm chỉnh sửa trực tiếp

Với các lần tái cấu trúc dài hạn hoặc công việc nhiều phiên, tệp kế hoạch được quản lý phiên bản cho bạn quyền kiểm soát nhiều hơn so với chỉ Ctrl+G.

Triển khai quy trình Khám phá-Lập kế hoạch-Thực thi với Claude Code

Để thấy ba pha phối hợp với nhau thế nào, chúng ta sẽ tái cấu trúc một kho fastapi-blog-api. Kho này không có bài kiểm thử và có ba tệp, mỗi tệp ôm đồm quá nhiều: 

• main.py: mọi route, kiểm tra xác thực inline, cấu hình hardcode, gửi email

• models.py: mô hình ORM, schema Pydantic, hàm truy vấn, dữ liệu seed

• utils.py: băm mật khẩu, token JWT, upload S3, render markdown, cache, giới hạn tần suất, xuất CSV

Pha 1: Thu thập ngữ cảnh trước tiên

Bắt đầu tác vụ trong Chế độ Lập kế hoạch (hãy clone repo GitHub về máy trước). Lời nhắc mở đầu nên nói cho Claude biết bạn muốn gì và chỉ dẫn nó đọc các tệp liên quan:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude giao việc khảo sát mã nguồn cho một subagent tích hợp bị giới hạn ở công cụ chỉ đọc. Nó đã đọc cả ba tệp, lần theo các import giữa chúng, và dùng AskUserQuestion để nêu ra các điểm chưa rõ. 

Các câu hỏi bao quát vài quyết định cấp cao:

• Độ sâu kiến trúc (router phẳng so với lớp service đầy đủ)
• Cách xử lý cấu hình hardcode
• Các hàm tiện ích không dùng nên xóa hay giữ
• Nên dùng khung kiểm thử nào

Những câu hỏi đó rất quan trọng. Riêng câu hỏi về kiến trúc đã là tung đồng xu nếu không có đầu vào của con người. Claude sẽ mặc định theo mẫu mà nó thường thấy trong dữ liệu huấn luyện, và với FastAPI, thường là cấu trúc router phẳng. Trả lời "dùng service layer" ở đây đã giúp tiết kiệm cả một vòng tái cấu trúc lại sau này.

Nếu bạn có một dự án tham chiếu khớp với kiến trúc mục tiêu, hãy đưa liên kết vào lời nhắc. Claude tạo kế hoạch tốt hơn khi có ví dụ hoạt động để tham chiếu thay vì mô tả trừu tượng.

Một điều cần kiểm tra trước khi chấp nhận bất kỳ kế hoạch nào: câu hỏi của Claude có tham chiếu đến các hàm cụ thể và chi tiết cấp dòng, hay chỉ tên tệp? Nếu nó hỏi về "hệ thống auth" nhưng không bao giờ nhắc đến verify_jwt_token hoặc chuỗi middleware trong main.py, tức là nó đã lướt qua thay vì đọc kỹ. Hãy yêu cầu nó đọc cẩn thận hơn trước khi chuyển sang Pha 2.

Pha 2: Tạo và chỉnh sửa kế hoạch

Sau khi bạn trả lời câu hỏi của Claude, nó sẽ tự động tạo kế hoạch. Không cần lời nhắc riêng. Kế hoạch được lưu vào ~/.claude/plans/ và bao gồm: 

• Tóm tắt ngữ cảnh
• Cấu trúc thư mục mục tiêu
• Thứ tự triển khai từng bước
• Mục xác minh với các lệnh để kiểm tra việc tái cấu trúc hoạt động

Trước khi chọn cách tiếp tục, nhấn Ctrl+G để mở kế hoạch trong trình soạn thảo mặc định của bạn (đặt bằng $EDITOR). Hoặc dùng /plan open để mở trực tiếp tệp kế hoạch đang hoạt động.

Chế độ Lập kế hoạch phát huy tác dụng ở bước này. Bạn có thể chú thích các bước bằng ghi chú inline, xóa các bước bạn không đồng ý, sắp xếp lại thao tác, rồi lưu. Khi quay lại terminal, Claude sẽ nắm bắt mọi chỉnh sửa.

Với kế hoạch cho API blog, chú thích có thể như sau:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

Với các kế hoạch phức tạp, một lượt Ctrl+G có thể chưa đủ. Hãy chú thích, quay lại, bảo Claude "xử lý mọi chú thích trong kế hoạch, chưa triển khai vội," xem lại phiên bản đã chỉnh, rồi Ctrl+G lần nữa. Mỗi vòng chú thích loại bỏ mơ hồ vốn sẽ trở thành quyết định triển khai sai.

Khi hợp đồng trông đã ổn, Claude đưa ra vài lựa chọn: 

1. Thực hiện theo kế hoạch và xóa ngữ cảnh (tốt khi phiên làm việc đã cũ), 
2. Thực hiện mà không xóa (để giữ lịch sử hội thoại), hoặc 
3. Tiếp tục trao đổi về kế hoạch. 

Chọn dựa trên mức ngữ cảnh bạn đã xây dựng. Nếu bạn đang ở giữa một phiên dài, xóa ngữ cảnh sẽ cho Claude một cửa sổ mới để thực thi.

Pha 3: Thực thi kế hoạch đã phê duyệt

Chọn một phương án làm việc, và Claude bắt đầu triển khai từng bước. Nó xử lý qua từng bước và dừng khi cần can thiệp thủ công (như xác thực tương tác trên terminal) hoặc khi toàn bộ kế hoạch hoàn tất.

Hãy để ý lệch hướng. Kế hoạch nói tách auth thành module riêng trước, nhưng Claude có thể bắt đầu kéo route và logic auth ra cùng lúc vì thấy đường tắt. Kiểu thao tác đó dễ dẫn tới một mã nguồn chuyển đổi dở dang, nơi vài import trỏ về vị trí cũ và số khác trỏ về vị trí mới. 

Các dấu hiệu lệch hướng khác: 

• Chỉnh sửa tệp không được nhắc tới trong bước hiện tại
• Âm thầm đưa ra quyết định kiến trúc mà kế hoạch còn để mở
• Kết hợp hai bước mà kế hoạch tách rời

Khi xảy ra lệch hướng, Shift+Tab quay lại Chế độ Lập kế hoạch. Claude đọc trạng thái tệp hiện tại, tạo kế hoạch sửa đổi cho các bước còn lại, và bạn duyệt lại trước khi tiếp tục. Đây không phải biện pháp khẩn cấp. Hầu hết tái cấu trúc nhiều tệp sẽ qua 2–3 vòng chỉnh kế hoạch trước khi xong.

Với các lần tái cấu trúc không gói gọn trong một phiên, hãy chia công việc thành các kế hoạch tuần tự thay vì một kế hoạch lớn. Hoàn tất tách auth theo kế hoạch riêng, rồi bắt đầu phiên mới và kế hoạch mới cho việc tách route. 

Dùng /rename để đặt tên cho mỗi phiên (ví dụ, "blog-api-auth-extraction") để bạn có thể tiếp tục dở dang bằng /resume. Kế hoạch nhỏ hơn giúp cửa sổ ngữ cảnh tập trung và tạo điểm dừng tự nhiên giữa các pha.

Chiến lược thực tiễn cho Chế độ Lập kế hoạch của Claude Code

Sau khi đã đi qua toàn bộ quy trình một lần, hãy xem một số thực hành tốt để đảm bảo bạn tận dụng tối đa Chế độ Lập kế hoạch.

Khi nào nên dùng Chế độ Lập kế hoạch (và khi nào nên bỏ qua)

Không phải tác vụ nào cũng cần kế hoạch. Sửa một dòng, sửa lỗi gõ, và cập nhật hàm cô lập sẽ nhanh hơn khi không phải gánh chi phí lập kế hoạch. Tương tự với thay đổi cơ học, như đổi tên biến trên một tệp.

Một quy tắc ước lượng hay: nếu thay đổi chạm tới ba tệp trở lên, hoặc bạn không thể mô tả đầy đủ thay đổi trong một câu, hãy lập kế hoạch trước. Ba tệp là ngưỡng nơi lỗi cộng dồn bắt đầu gây hại, vì mỗi tệp thêm một tập quyết định mà Claude phải xử lý đúng.

Các tác vụ luôn hưởng lợi từ Chế độ Lập kế hoạch:

• Tái cấu trúc di chuyển mã giữa các tệp hoặc đổi tên giao diện dùng chung
• Tính năng mới chạm vào module hiện có
• Nâng cấp phụ thuộc có thay đổi phá vỡ API
• Bất kỳ tác vụ nào bạn không chắc mã nguồn xử lý một trường hợp cụ thể ra sao
• Các buổi động não nơi bạn muốn lặp trên một cách tiếp cận với Claude mà không lo rủi ro chỉnh sửa sớm

Nhận diện kế hoạch yếu trước khi chúng làm bạn tốn kém

Một kế hoạch có vẻ có cấu trúc không phải lúc nào cũng tốt. Với các phiên bản Claude Code hiện tại, việc bịa tên tệp và các bước mơ hồ kiểu "cập nhật khi cần" là hiếm. Vấn đề bạn dễ gặp hơn là kế hoạch dồn toàn bộ bước triển khai lên trước và gắn thêm "viết kiểm thử" ở cuối.

Những kế hoạch cấu trúc như vậy cho ra kết quả tệ hơn bạn nghĩ. Không có kiểm thử trong lúc triển khai, Claude không có cách tự xác minh công việc của mình giữa phiên. Với việc tái cấu trúc API blog, một kế hoạch kiểu "Bước 1–6: tách mọi module, Bước 7: viết kiểm thử" đồng nghĩa sáu bước mã không có vòng phản hồi. 

Một kế hoạch mạnh hơn dùng phát triển hướng kiểm thử (TDD) và đan xen kiểm thử với triển khai: viết kiểm thử cho auth/ trước khi tách các hàm auth, xác nhận chúng chạy qua, rồi viết kiểm thử cho posts/ trước khi tách các route. Mỗi bài kiểm thử vượt qua sẽ cho Claude tín hiệu rõ ràng rằng tái cấu trúc đang đúng hướng. 

Thêm quy ước TDD vào CLAUDE.md của dự án sẽ khiến Claude mặc định đưa các bước kiểm thử vào kế hoạch. Claude Code Hooks có thể tự động hóa loại ràng buộc này bằng cách chạy script kiểm tra chất lượng kế hoạch trước khi phê duyệt triển khai.

Mở rộng các lần tái cấu trúc lớn với Agent Teams

Các kế hoạch đụng tới bảy tệp trở lên bắt đầu giảm chất lượng vì cửa sổ ngữ cảnh đầy lên trong lúc thực thi. Việc tái cấu trúc API blog chạm ngưỡng này khi bạn tính cả route, model, service, cấu hình, kiểm thử, và cấu trúc thư mục mới.

Agent Teams là tính năng thử nghiệm giúp phân chia loại công việc này cho nhiều phiên Claude Code. Một phiên đóng vai trò trưởng nhóm trong khi các đồng đội mỗi người có cửa sổ ngữ cảnh độc lập. 

Với API blog, bạn có thể chia làm ba đồng đội: một phụ trách tách route, một phụ trách lớp cơ sở dữ liệu và model, và một chịu trách nhiệm độ bao phủ kiểm thử. Trưởng nhóm giao việc, đồng đội nhận và hoàn thành, và các tác vụ bị chặn (như "cập nhật import" phụ thuộc vào "tách module") sẽ tự bỏ chặn khi phụ thuộc hoàn tất. 

Cách chia tương tự cũng hoạt động giữa các repository: nếu API của bạn phụ thuộc vào thư viện dùng chung, một đồng đội có thể tái cấu trúc thư viện trong khi người khác cập nhật cách API tiêu thụ nó.

Thiết lập tốt nhất cho Chế độ Lập kế hoạch là yêu cầu phê duyệt kế hoạch đối với các đồng đội. Hãy bảo trưởng nhóm: "Tạo ba đồng đội cho việc tái cấu trúc API blog. Yêu cầu phê duyệt kế hoạch trước khi họ thực hiện bất kỳ thay đổi nào." 

1. Mỗi đồng đội lập kế hoạch ở chế độ chỉ đọc
2. Trưởng nhóm xem xét và phê duyệt hoặc từ chối kèm phản hồi
3. Chỉ các kế hoạch đã được phê duyệt mới được thực thi

Bạn có thể định hình tiêu chí đánh giá của trưởng nhóm: "chỉ phê duyệt kế hoạch bao gồm độ bao phủ kiểm thử" hoặc "từ chối kế hoạch chỉnh sửa trực tiếp schema cơ sở dữ liệu." Kích hoạt Agent Teams bằng cách thêm "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" vào khối env trong settings.json.

Với cách song song hóa đơn giản hơn mà không cần cờ thử nghiệm, git worktree cho phép bạn chạy các phiên Chế độ Lập kế hoạch riêng trên các nhánh khác nhau, mỗi phiên tự xử lý kế hoạch của mình.

Nếu một phiên dài phải nén ngữ cảnh, hãy yêu cầu các đồng đội mở lại và đọc lại tệp kế hoạch của họ để tránh lệch hướng.

Bài hướng dẫn plugin Claude Code đề cập các mẫu bổ sung để quản lý công việc nhiều pha.

Kết luận

Giá trị của Chế độ Lập kế hoạch cô đọng ở một điểm: duyệt trước khi thực thi. Mỗi vòng chú thích bạn thêm, mỗi câu hỏi Claude hỏi thay vì đoán, đều loại bỏ một quyết định có thể sai.

Bắt đầu với thay đổi nhiều tệp tiếp theo của bạn, buộc Claude lập kế hoạch trước, và chỉnh kế hoạch đó bằng Ctrl+G trước khi cấp quyền ghi. Với cấu hình CLAUDE.md, quản lý ngữ cảnh, và hàng rào bảo vệ dựa trên hook, hướng dẫn thực hành tốt nhất sẽ tiếp nối từ đây. 

Để có cái nhìn rộng hơn về lập trình có hỗ trợ AI, tôi khuyên bạn xem lộ trình kỹ năng AI cho Kỹ thuật Phần mềm, nơi dạy các khái niệm nền tảng và cho bạn thực hành với các công cụ tương tự như GitHub Copilot, Windsurf, hoặc Replit.