Plan Mode trong Claude Code — Lên kế hoạch trước khi code

Claude Code là CLI (Command Line Interface) chính thức của Anthropic, cho phép bạn làm việc với Claude trực tiếp trong terminal. Một trong những tính năng quan trọng nhất nhưng thường bị bỏ qua là Plan Mode — chế độ cho phép Claude phân tích codebase, lên kế hoạch chi tiết trước khi thực hiện bất kỳ thay đổi nào. Bài viết này hướng dẫn cách sử dụng Plan Mode hiệu quả để tăng chất lượng code và giảm thiểu lỗi.

Plan Mode là gì?

Trong Claude Code, có hai chế độ làm việc chính:

• Act Mode (mặc định): Claude đọc file, viết code, chạy lệnh, tạo file mới — thực hiện hành động trực tiếp trên codebase của bạn
• Plan Mode: Claude chỉ đọc và phân tích — không viết, không sửa, không chạy lệnh. Thay vào đó, Claude đưa ra kế hoạch chi tiết về những gì cần làm

Bạn chuyển đổi giữa hai chế độ bằng tổ hợp phím Shift+Tab. Khi ở Plan Mode, dòng input sẽ hiển thị chữ "plan" để bạn biết đang ở chế độ nào.

Ý tưởng cốt lõi: "Measure twice, cut once" — đo hai lần, cắt một lần. Với code, việc lên kế hoạch trước giúp bạn tránh phải refactor hoặc undo những thay đổi sai hướng.

Tại sao cần Plan Mode?

Khi bạn yêu cầu Claude Code làm một tác vụ ở Act Mode, nó sẽ ngay lập tức bắt đầu đọc file, phân tích, và viết code. Điều này hoạt động tốt cho các tác vụ đơn giản — sửa lỗi nhỏ, thêm một function, cập nhật config. Nhưng với tác vụ phức tạp, việc nhảy thẳng vào code có thể gây ra vấn đề:

• Thiếu cái nhìn tổng thể: Claude có thể sửa đúng file A nhưng không nhận ra rằng thay đổi đó ảnh hưởng đến file B và C
• Hướng tiếp cận sai: Có nhiều cách giải quyết một vấn đề. Không lên kế hoạch, Claude có thể chọn cách tiếp cận không tối ưu
• Bỏ sót trường hợp: Các edge case, error handling, và tương thích ngược thường bị bỏ qua khi không lên kế hoạch
• Khó kiểm soát: Khi Claude thực hiện nhiều thay đổi cùng lúc, việc review và rollback trở nên phức tạp

Khi nào nên dùng Plan Mode?

Không phải mọi tác vụ đều cần Plan Mode. Dưới đây là hướng dẫn khi nào nên và không nên dùng.

Nên dùng Plan Mode

• Tính năng mới phức tạp: Thêm authentication, payment integration, real-time notification — bất kỳ tính năng nào chạm đến nhiều file và nhiều layer
• Refactoring lớn: Tái cấu trúc thư mục, tách module, đổi design pattern, migration database schema
• Codebase lạ: Khi bạn mới tham gia dự án và chưa hiểu rõ kiến trúc, Plan Mode giúp Claude khám phá và tóm tắt codebase trước
• Bug phức tạp: Bug liên quan đến race condition, memory leak, hoặc logic phức tạp xuyên nhiều component
• Thay đổi có rủi ro cao: Sửa đổi authentication, payment, data migration — những thứ sai sẽ gây hậu quả lớn
• Khi bạn chưa chắc chắn về hướng đi: Plan Mode giúp bạn xem trước nhiều phương án trước khi cam kết

Không cần Plan Mode

• Sửa typo, cập nhật comment, đổi tên biến
• Thêm một function đơn giản, độc lập
• Cập nhật config, thêm dependency
• Tác vụ bạn đã rõ ràng 100% cần làm gì

Quy trình Plan -> Execute -> Verify

Quy trình hiệu quả nhất khi dùng Claude Code cho tác vụ phức tạp gồm 3 bước:

Bước 1: Plan — Lên kế hoạch

Bấm Shift+Tab để vào Plan Mode, sau đó mô tả tác vụ.

[Plan Mode] Tôi cần thêm tính năng đăng nhập bằng Google OAuth
vào ứng dụng Next.js hiện tại. Ứng dụng đang dùng NextAuth.js
nhưng chỉ có email/password. Hãy phân tích codebase và lên kế hoạch
chi tiết.

Claude sẽ:

1. Đọc cấu trúc dự án, file cấu hình (package.json, next.config.js)
2. Đọc file auth hiện tại (auth.ts, middleware.ts, các route liên quan)
3. Đọc database schema nếu có
4. Đưa ra kế hoạch chi tiết: file nào cần sửa, sửa gì, file nào cần tạo mới, thứ tự thực hiện

Kết quả Plan Mode thường có dạng:

## Kế hoạch: Thêm Google OAuth

### Phân tích hiện tại
- NextAuth.js v4.24 đã cấu hình với CredentialsProvider
- Database dùng Prisma với PostgreSQL
- User model có email, password, name
- Session strategy: JWT

### Thay đổi cần thực hiện
1. Cài đặt package: Không cần thêm vì NextAuth.js đã có GoogleProvider
2. File auth.ts:
   - Thêm GoogleProvider vào mảng providers
   - Cấu hình clientId, clientSecret từ env
   - Cập nhật callback để xử lý tài khoản liên kết
3. File .env.local:
   - Thêm GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
4. File prisma/schema.prisma:
   - Thêm model Account cho OAuth accounts
   - Cập nhật User model thêm trường accounts relation
5. File components/LoginForm.tsx:
   - Thêm nút "Đăng nhập bằng Google"
6. File app/api/auth/[...nextauth]/route.ts:
   - Cập nhật nếu cần

### Rủi ro và lưu ý
- User hiện tại đăng nhập bằng email cùng email Google sẽ cần
  logic liên kết tài khoản
- Cần tạo OAuth credentials trên Google Cloud Console
- Callback URL cần cấu hình đúng

Bước 2: Execute — Thực hiện

Sau khi review kế hoạch và đồng ý, bấm Shift+Tab để quay lại Act Mode, sau đó yêu cầu Claude thực hiện.

[Act Mode] Kế hoạch tốt. Hãy thực hiện theo đúng kế hoạch ở trên.
Bắt đầu từ bước 1.

Vì Claude đã có kế hoạch rõ ràng, quá trình thực hiện sẽ có hệ thống và ít sai sót hơn. Bạn cũng có thể yêu cầu Claude thực hiện từng bước một nếu muốn review kỹ hơn.

Bước 3: Verify — Kiểm tra

Sau khi Claude hoàn thành, chuyển lại Plan Mode để kiểm tra.

[Plan Mode] Review lại tất cả thay đổi vừa thực hiện cho Google OAuth.
Kiểm tra xem:
1. Có thiếu error handling nào không?
2. Có edge case nào chưa xử lý không?
3. Có vấn đề bảo mật tiềm ẩn nào không?
4. Code có tuân theo convention hiện tại của dự án không?

Ví dụ thực tế: Refactoring API layer

Một ví dụ phổ biến là refactoring API layer từ REST thuần sang pattern Repository + Service.

[Plan Mode] Dự án hiện tại có 15 file API route trong app/api/,
mỗi file trực tiếp query database bằng Prisma. Tôi muốn refactor
theo pattern Repository + Service:
- Repository layer: xử lý database queries
- Service layer: business logic
- API route: chỉ xử lý request/response

Hãy phân tích codebase và lên kế hoạch refactor chi tiết.
Ưu tiên: không break bất kỳ API endpoint nào đang hoạt động.

Claude sẽ phân tích toàn bộ 15 file API, xác định các pattern chung, và đưa ra kế hoạch refactor theo thứ tự an toàn — bắt đầu từ các endpoint đơn giản nhất, để khi gặp vấn đề, phạm vi ảnh hưởng nhỏ nhất.

Ví dụ thực tế: Debug production issue

Khi gặp bug phức tạp trên production, Plan Mode giúp bạn phân tích có hệ thống trước khi sửa.

[Plan Mode] Bug report: Một số user báo cáo rằng sau khi thanh toán
thành công trên payment gateway, đơn hàng vẫn hiển thị trạng thái
"chờ thanh toán". Bug xảy ra khoảng 5% đơn hàng, không reproduce
được một cách nhất quán.

Hãy phân tích:
1. Flow thanh toán hiện tại (từ checkout đến cập nhật trạng thái)
2. Các điểm có thể xảy ra failure
3. Giả thuyết nguyên nhân
4. Cách kiểm tra từng giả thuyết

Claude sẽ đọc toàn bộ flow thanh toán, từ frontend checkout page đến webhook handler, database update, và notification. Kế hoạch phân tích sẽ giúp bạn tiết kiệm thời gian debug đáng kể so với việc "thử và sai" ở Act Mode.

Tích hợp với CLAUDE.md

CLAUDE.md là file đặc biệt mà Claude Code tự động đọc khi bắt đầu. Nó chứa thông tin về dự án, coding convention, và hướng dẫn cho Claude. Kết hợp CLAUDE.md tốt với Plan Mode sẽ nâng cao chất lượng kế hoạch đáng kể.

Cấu trúc CLAUDE.md hiệu quả

# CLAUDE.md

## Về dự án
[Mô tả ngắn gọn mục đích và kiến trúc dự án]

## Tech stack
- Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
- Backend: Next.js API Routes, Prisma ORM
- Database: PostgreSQL (Supabase)
- Auth: NextAuth.js v4
- Deploy: Vercel

## Cấu trúc thư mục
- app/ — Next.js App Router pages và API routes
- components/ — React components chia theo feature
- lib/ — Shared utilities, database client, helpers
- prisma/ — Schema và migrations

## Convention
- Components dùng named export, không default export
- API response format: { success: boolean, data?: T, error?: string }
- File naming: kebab-case cho file, PascalCase cho components
- Commit message: conventional commits (feat:, fix:, refactor:)

## Lệnh thường dùng
- npm run dev — chạy development server
- npm run build — build production
- npx prisma db push — sync schema
- npm test — chạy test suite

## Lưu ý quan trọng
- Không sửa trực tiếp file trong node_modules hoặc .next
- Luôn chạy type check trước khi commit
- Database migration cần review manual trước khi chạy trên production

Khi Claude Code đọc CLAUDE.md này trước khi vào Plan Mode, kế hoạch sẽ tuân theo đúng tech stack, convention, và cấu trúc thư mục. Claude sẽ không đề xuất sử dụng thư viện hoặc pattern trái với quy ước dự án.

Mẹo sử dụng Plan Mode hiệu quả

1. Mô tả rõ ràng mục tiêu và ràng buộc

Thay vì "Thêm search", hãy nói:

[Plan Mode] Thêm tính năng full-text search cho bài viết blog.
Ràng buộc:
- Dùng PostgreSQL full-text search, không thêm service bên ngoài
  (không Elasticsearch, không Algolia)
- Search phải hỗ trợ tiếng Việt có dấu
- Kết quả trả về trong dưới 200ms cho 10,000 bài viết
- UI: ô search ở header, trang kết quả riêng với phân trang

2. Yêu cầu nhiều phương án

[Plan Mode] Tôi cần implement caching cho API. Hãy đưa ra 2-3 phương án
khác nhau, so sánh ưu nhược điểm, và recommend phương án tốt nhất
cho context dự án hiện tại.

3. Chia nhỏ tác vụ lớn

Với tác vụ rất lớn, dùng Plan Mode để chia thành các phase nhỏ hơn, sau đó thực hiện từng phase.

[Plan Mode] Tôi cần migrate từ Pages Router sang App Router.
Dự án có 25 pages và 40 API routes. Hãy chia thành các phase
có thể deploy độc lập, mỗi phase không quá 1 ngày làm việc.
Phase 1 nên là phase ít rủi ro nhất.

4. Kết hợp với git

Tạo branch mới trước khi thực hiện kế hoạch. Nếu kết quả không ưng, dễ dàng quay lại.

# Trước khi bắt đầu
git checkout -b feature/google-oauth

# Plan Mode -> review kế hoạch -> Act Mode -> thực hiện
# Sau khi xong
git diff  # Review tất cả thay đổi
git add -p  # Stage từng phần để review kỹ

5. Dùng Plan Mode để học codebase mới

[Plan Mode] Tôi mới tham gia dự án này. Hãy phân tích codebase và cho
tôi biết:
1. Kiến trúc tổng thể
2. Các module/component chính và mối quan hệ
3. Data flow từ frontend đến database
4. Các pattern và convention đang được sử dụng
5. Các phần code phức tạp nhất cần chú ý

Plan Mode trong CI/CD workflow

Plan Mode cũng hữu ích trong quy trình CI/CD. Bạn có thể dùng Claude Code ở Plan Mode để phân tích thay đổi trước khi merge.

[Plan Mode] Đây là diff của PR #142 (feature/user-notifications).
Hãy review và kiểm tra:
1. Có breaking changes nào không?
2. Error handling có đầy đủ không?
3. Có security issue tiềm ẩn nào không?
4. Performance: query N+1, memory leak, unnecessary re-renders?
5. Test coverage: có cần thêm test case nào không?

Sai lầm thường gặp

• Dùng Plan Mode cho mọi tác vụ: Tốn thời gian không cần thiết cho tác vụ đơn giản. "Sửa typo trong README" không cần kế hoạch.
• Không review kế hoạch: Plan Mode chỉ hiệu quả khi bạn thực sự đọc và đánh giá kế hoạch trước khi cho Claude thực hiện.
• Kế hoạch quá chi tiết: Kế hoạch nên ở mức đủ để đánh giá hướng đi, không cần liệt kê từng dòng code sẽ viết.
• Không cập nhật CLAUDE.md: Khi dự án thay đổi (thêm tech mới, đổi convention), cần cập nhật CLAUDE.md để kế hoạch tương lai vẫn chính xác.
• Bỏ qua bước Verify: Sau khi thực hiện kế hoạch, luôn quay lại Plan Mode để kiểm tra kết quả. Đây là bước nhiều người bỏ qua nhưng rất quan trọng.

So sánh có và không có Plan Mode

Dưới đây là so sánh kết quả điển hình giữa hai cách tiếp cận khi thêm tính năng phức tạp:

Bước tiếp theo

Plan Mode là một trong những tính năng giúp nâng cao hiệu quả làm việc với Claude Code đáng kể nhất. Bắt đầu bằng cách dùng Plan Mode cho tác vụ phức tạp tiếp theo của bạn — viết CLAUDE.md tốt, mô tả rõ ràng mục tiêu, review kế hoạch kỹ càng, và so sánh kết quả với cách làm cũ. Tìm hiểu thêm các hướng dẫn ứng dụng Claude Code tại Thư viện Ứng dụng Claude.