Checkpoint trong Claude Code: quay lại khi AI sửa hỏng code

Bạn vừa để Claude Code refactor một module lớn. Nó chạy mượt mười phút, sửa cả chục file — rồi test fail loạn xạ. Giờ muốn quay lại trạng thái trước đó thì làm sao, khi bạn quên commit?

Đây chính là lý do Anthropic thêm checkpoint vào Claude Code từ bản 2.0: tool tự chụp trạng thái code trước mỗi prompt, và bạn quay lại chỉ bằng một lệnh /rewind hoặc hai lần nhấn Esc. [1][2]

Đây là bài thứ sáu trong series Claude Code. Nếu bạn chưa cài tool, đọc Claude Code là gì? Hướng dẫn cài đặt trước. Còn bài này sẽ chỉ cho bạn checkpoint Claude Code hoạt động ra sao, restore nào nên chọn, và — quan trọng không kém — những thứ checkpoint không cứu được.

Checkpoint Claude Code là gì?

Checkpoint là cơ chế tự động lưu trạng thái code của bạn trước mỗi prompt bắt đầu một turn, để bạn có thể quay lại bất kỳ điểm nào trong session. Nó ra mắt cùng Claude Code 2.0 — và theo Anthropic, đây là tính năng được yêu cầu nhiều nhất. [2]

Checkpoint

Bản snapshot trạng thái file được chụp trước khi Claude bắt đầu xử lý một prompt, gắn với prompt đó trong hội thoại.

Rewind

Hành động quay lại một checkpoint — có thể khôi phục code, hội thoại, hoặc cả hai.

Turn

Một lượt làm việc hoàn chỉnh của Claude, bắt đầu từ prompt bạn gửi cho đến khi nó dừng lại.

Cần nói rõ ngay một điểm hay bị hiểu sai: đơn vị undo là prompt, không phải từng file hay từng tool call. Nếu Claude sửa 6 file trong một turn, rewind về prompt mở turn đó sẽ hoàn tác cả 6 — bạn không thể chỉ giữ lại 2 file. [3]

Đây là điều bạn nên biết: checkpoint không phải thứ bạn phải “bật lên”. Nó chạy ngầm ngay khi bạn dùng Claude Code. Công việc của bạn chỉ là biết cách gọi nó ra khi cần — phần tiếp theo sẽ chỉ rõ.

Checkpoint Claude Code hoạt động như thế nào?

Mỗi prompt bạn gửi để bắt đầu một turn sẽ tạo một checkpoint mới, và Claude Code giữ file snapshot cho 100 checkpoint gần nhất trong session. Checkpoint được lưu cùng hội thoại, nên bạn vẫn rewind được sau khi /resume session cũ. [1]

Về vòng đời của snapshot, có 3 con số đáng nhớ:

• 100 checkpoint — session chỉ giữ file snapshot cho 100 checkpoint gần nhất. Bỏ checkpoint cũ sẽ xóa các snapshot không còn được tham chiếu, trừ snapshot đầu tiên của mỗi file — thứ VS Code extension dùng làm baseline cho session diff. [1]
• Khoảng 30 ngày — snapshot của một session bị dọn trong đợt retention sweep, mặc định khoảng 30 ngày sau lần session lưu snapshot cuối. Rewind vào checkpoint đã mất snapshot sẽ báo lỗi No files were restored. [1]
• cleanupPeriodDays — nếu muốn giữ snapshot lâu hơn, đặt setting này trong file cấu hình. [1]

Một chi tiết khá tinh tế: khi file Claude từng sửa bị lệnh bash đổi sau đó, rewind vẫn hoàn tác được thay đổi đó — vì file đã nằm trong diện theo dõi. Nhưng file chỉ bị bash thay đổi mà Claude chưa từng edit thì nằm ngoài tầm tay của checkpoint. Chi tiết này quan trọng, mình sẽ mở rộng ở phần giới hạn bên dưới. [1]

Cách mở menu rewind: /rewind và Esc Esc

Có hai cách mở menu rewind: gõ /rewind, hoặc nhấn Esc hai lần khi ô nhập prompt đang trống. Hai alias /checkpoint và /undo mở cùng một menu. [1][3]

Chú ý cái bẫy nhỏ này — nhiều người vấp ngay lần đầu: nếu ô nhập đang có chữ, nhấn Esc hai lần sẽ xóa bản nháp thay vì mở menu. Đừng hoảng, chữ không mất — nó được lưu vào input history, nhấn phím mũi tên Up là lấy lại được. [1]

/rewind       # mở menu rewind
/checkpoint   # alias của /rewind
/undo         # alias thứ hai

Menu hiện danh sách các prompt bạn đã gửi trong session, kèm số file đã thay đổi dưới mỗi prompt. Nếu bạn từng chạy /clear trong cùng process, đỉnh danh sách sẽ có thêm mục /resume (previous session) để quay lại hội thoại trước khi clear — mục này tồn tại cho tới khi bạn thoát Claude Code hoặc resume session khác. [4]

Bạn đang đọc bài thuộc chuyên mục Lập trình của VietnamTutor — nơi mình viết về workflow AI coding thực chiến. Nếu mới làm quen các lệnh cơ bản, ghé qua bài 7 lệnh Claude Code cần biết để nắm nhanh /clear, /compact và các phím tắt hay dùng.

Restore code, conversation hay cả hai: chọn cái nào?

Sau khi chọn prompt muốn quay lại, menu cho bạn 6 hành động — nhưng hai tùy chọn restore code chỉ xuất hiện khi checkpoint đó có file thay đổi được theo dõi. [1]

Ba lựa chọn đáng cân nhắc nhất:

• Restore code là con đường khôn ngoan khi Claude sửa hỏng nhưng bạn muốn nó rút kinh nghiệm. Code quay về sạch, còn hội thoại giữ lại toàn bộ “dấu vết” thất bại — Claude biết hướng nào không nên đi nữa. [5]
• Restore code and conversation là nút “làm lại từ đầu” — dùng khi cả hướng tiếp cận lẫn kết quả đều sai.
• Summarize không động vào file nào trên đĩa; nó giống một /compact có mục tiêu. Bạn thậm chí có thể gõ hướng dẫn cho phần tóm tắt ở dòng add context (optional) trước khi nhấn Enter. [1]

Sau khi chọn Restore conversation hoặc Summarize from here, prompt gốc của điểm đó được đưa lại vào ô nhập — bạn sửa rồi gửi lại, tiện cho việc “diễn đạt khác đi” thay vì viết lại từ đầu. [4]

Một lưu ý quan trọng: tin nhắn đã rewind có thể “hồi sinh” nếu bạn thoát session trước khi gửi prompt mới. Cách xử lý: mở /rewind, chọn lại đúng prompt đó, Restore conversation — và nhớ gửi một prompt trước khi thoát, vì Claude Code lưu hội thoại đã rewind cùng prompt kế tiếp. [1]

Checkpoint Claude Code không cứu được những gì?

Checkpoint Claude Code chỉ theo dõi những file Claude đã sửa bằng file editing tools trong session hiện tại — mọi thay đổi khác đều nằm ngoài tầm phục hồi. Đây là phần nhiều người đọc lướt rồi trả giá. [1]

Năm giới hạn của checkpoint Claude Code cần thuộc lòng:

• Thay đổi từ lệnh bash. File chỉ bị bash chỉnh sửa (ví dụ script sed, mv hàng loạt) mà Claude chưa từng edit bằng tool thì không được theo dõi — rewind không đụng tới. Ngược lại, file Claude đã edit rồi bị bash đổi tiếp vẫn được hoàn tác. [1]
• Edit từ subagent. Subagent chạy nền (gồm cả forked skill ở background — chế độ mặc định, hay /code-review --fix chạy nền) sửa file nào thì file đó không được restore; chỉ file Claude chính đã edit mới quay lại được. Ngoại lệ duy nhất: forked skill chạy foreground (background: false) thì edit của nó được tính như edit của bạn. [1]
• Thay đổi ngoài session. Bạn tự sửa file trong editor, hoặc một session Claude Code khác chạy song song đổi file — checkpoint không thấy, trừ khi trùng đúng file session này đã theo dõi. [1]
• Tin nhắn gửi giữa turn. Message bạn gõ khi Claude đang chạy bị đánh dấu No code restore — nó không có checkpoint riêng. Muốn undo edit của turn đó, chọn prompt mở turn và Restore code. [1]
• Symlink và hard link. Restore sẽ bỏ qua các đường dẫn symlink/hard link kèm cảnh báo Restored the code, but skipped N files — config do dotfile manager link vào hay file pnpm hard-link đều rơi vào nhóm này. Bật /debug trước khi restore để xem log từng đường dẫn bị skip tại ~/.claude/debug/<session-id>.txt. [1]

Và một giới hạn “mềm” nữa, không nằm trong docs nhưng rất đời thực: mọi thứ đã gây tác động ra bên ngoài — commit đã push, bản build đã deploy, email đã gửi — thì rewind không kéo lại được. Checkpoint Claude Code chỉ quay file và hội thoại trong session. [5]

Checkpoint Claude Code hay Git: dùng thế nào cho đúng?

Checkpoint Claude Code là công cụ undo cấp session — nhanh, tự động, nhưng ngắn hạn; Git là lịch sử vĩnh viễn của dự án. Anthropic khuyên dùng checkpoint kết hợp với version control, không thay thế nó. [1][2]

Cách chia việc thực tế mình hay áp dụng:

• Checkpoint Claude Code lo phần “trong lúc làm”: thử hai hướng implement, hoàn tác một refactor hỏng, giải phóng context giữa session — những pha quay lui không đáng tạo commit.
• Git lo phần “chốt mốc”: trước khi giao cho Claude một task lớn, hãy git commit hoặc ít nhất git stash để có mốc cứng. Checkpoint Claude Code mất sau ~30 ngày và theo session; commit thì ở lại mãi và đi cùng repo khi làm việc nhóm.

Một quy trình an toàn cho task rủi ro: commit working tree sạch → giao task cho Claude → để checkpoint Claude Code làm lớp undo tức thì trong session → nếu mọi thứ ổn, commit tiếp; nếu hỏng, /rewind trước, git reset là phương án cuối. Kết hợp này cho bạn hai lớp phòng thủ thay vì một. Nếu muốn an toàn hơn nữa khi để agent chạy tự do, tham khảo thêm cách dựng Docker sandbox cho AI coding agent.

Và nhớ rằng checkpoint Claude Code chỉ là một mảnh của quy trình sửa code bằng AI. Quy trình đầy đủ — từ cách viết yêu cầu, review diff, tới khi nào nên dừng tool — mình đã viết ở bài Sửa code bằng Claude Code: quy trình an toàn cho người mới bắt đầu.

Nguồn tham khảo

1. Claude Code Docs — Checkpointing
2. Anthropic — Enabling Claude Code to work more autonomously
3. Omniscio — Claude Code rewind: checkpoints, undo and what it misses
4. Aftergradient — Claude Code checkpointing and rewind explained
5. Carlos Lastres — Claude Code Checkpoints and /rewind: Undo Changes Safely

Checkpoint Claude Code là một trong những tính năng “nhỏ mà có võ” nhất của bản 2.0: không cần cấu hình, nhưng biết dùng đúng lúc sẽ cứu bạn cả buổi chiều. Chỉ cần nhớ hai việc — commit bằng Git trước task lớn, và đừng kỳ vọng checkpoint cứu được những thay đổi ngoài session.

Bạn đã dùng /rewind cứu được một lần “hỏng việc” nào chưa? Chia sẻ tình huống của bạn ở comment nhé — mình rất tò mò! Và nếu thấy bài hữu ích, đừng quên đọc tiếp các bài khác trong series Claude Code trên VietnamTutor.