Plan mode in Claude Code: agree on the plan before the agent touches code

Lỗi phổ biến nhất khi dùng coding agent không phải code sai cú pháp, mà là làm đúng một việc không ai cần: agent hiểu sai yêu cầu, sửa 15 file theo hướng của nó, và bạn mất thời gian revert. Plan mode của Claude Code giải quyết đúng chỗ này: Claude được đọc code, chạy lệnh khám phá và viết kế hoạch, nhưng không được sửa mã nguồn cho đến khi bạn duyệt. Bài này tóm tắt cách dùng plan mode theo tài liệu chính thức và cách biến nó thành thói quen của cả team.

Plan mode nằm ở đâu trong các permission mode?

Deny rule trong settings luôn có hiệu lực ở mọi mode. Plan mode không thay thế deny rule; nó là lớp "suy nghĩ trước" chứ không phải lớp bảo mật.

Bật plan mode: 3 cách

1. Khi khởi động: claude --permission-mode plan.
2. Giữa phiên: nhấn Shift+Tab cho đến khi thanh trạng thái hiện ⏸ plan mode on. Nhấn tiếp để thoát mà không duyệt.
3. Cho một prompt: thêm /plan vào đầu prompt.

Muốn mặc định luôn vào plan mode cho một repo, đặt trong .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Với extension VS Code, tài liệu ghi rằng extension không đọc mode khởi động cấp dự án; dùng setting user "claudeCode.initialPermissionMode": "plan".

Luồng duyệt kế hoạch

Khi Claude viết xong plan, bạn có các lựa chọn:

• Yes, and use auto mode (hoặc auto-accept edits nếu auto không khả dụng): duyệt và để Claude làm liền một mạch.
• Yes, manually approve edits: duyệt hướng, nhưng vẫn xem từng thay đổi.
• No, keep planning: ở lại plan mode, nói rõ cần sửa gì trong plan.

Hai chi tiết hữu ích: nhấn Ctrl+G để mở plan trong text editor và sửa trực tiếp; plan được lưu trong ~/.claude/plans/ (đổi được bằng setting plansDirectory), nên có thể dán vào ticket hay PR làm tài liệu thiết kế.

Prompt để có một plan tốt

/plan Thêm rate limit cho API /login.
Yêu cầu:
- Tối đa 5 lần sai mật khẩu / 15 phút / IP + username
- Dùng Redis đang có, không thêm dependency mới
Plan cần nêu: file sẽ sửa, thiết kế key Redis, cách test,
rủi ro với user dùng chung IP (văn phòng, NAT).
Hỏi lại nếu có điểm chưa rõ thay vì tự giả định.

Plan tốt thường có: danh sách file sẽ đụng tới, thứ tự thực hiện, cách kiểm chứng (test nào, lệnh nào), và giả định đã đưa ra. Nếu plan thiếu phần kiểm chứng, đó là dấu hiệu nên "keep planning".

Khi nào nên dùng, khi nào không?

Rủi ro và lưu ý

• Plan đẹp không có nghĩa là code đúng: vẫn cần test và review sau khi thực thi.
• Context bị lấp đầy: giai đoạn khám phá đọc nhiều file. Có tuỳ chọn showClearContextOnPlanAccept để duyệt plan và xoá ngữ cảnh lập kế hoạch, giúp phần thực thi gọn hơn.
• Duyệt kèm auto mode: tiện nhưng bỏ qua bước xem từng edit. Với code nhạy cảm, chọn duyệt thủ công.

Áp dụng thế nào?

• Dev: Tập thói quen Shift+Tab vào plan mode cho mọi task trên 3 file. Đọc plan 2 phút rẻ hơn revert 30 phút.
• Tech Lead: Đặt defaultMode: "plan" cho repo quan trọng. Yêu cầu đính kèm plan (file trong ~/.claude/plans/) vào PR lớn để reviewer hiểu ý đồ.
• PM: Plan là bản mô tả kỹ thuật miễn phí: dùng nó để kiểm tra agent hiểu đúng acceptance criteria trước khi tốn thời gian code.