Claude Code checkpointing for QA is valuable only when you know what the rewind button actually protects. Anthropic documents automatic checkpoints before user prompts and a /rewind menu that can restore code, conversation, or both. That sounds like a safety net, but it has clear boundaries: shell-command changes, external edits, and some subagent edits may not be restored.

This tutorial turns those boundaries into a repeatable QA recovery drill. You will use a disposable Git branch, introduce a controlled bad test edit, rewind it, compare the result with an untracked shell-created marker, and capture evidence. The goal is not to prove Claude can never make a damaging change. The goal is to know which recovery layer works for which failure.

What Anthropic officially documents

The current Claude Code checkpointing documentation says each user prompt creates a checkpoint and Claude Code snapshots changes made through its file-editing tools. Checkpoints are saved with the conversation, so /rewind remains available after resuming a session. Anthropic currently documents file snapshots for the 100 most recent checkpoints in a session and cleanup with the session retention policy.

The rewind menu can restore code and conversation together, restore only the conversation, restore only code, or summarize part of the conversation. The official commands reference lists /rewind, with /checkpoint and /undo as aliases.

The limitations matter more than the happy path. Checkpointing tracks direct changes made through Claude’s file-editing tools. It does not generally track files changed by shell commands or external processes. Anthropic also says subagent edits are not always captured, symlinked and hard-linked paths have restoration limits, and checkpoints are not a replacement for version control.

Define the QA recovery contract

Write the expected result before touching a file:

After a controlled bad AI edit, rewind must restore the tracked test file to its baseline. A separate file created outside Claude’s direct editing tools must remain, proving that checkpoint coverage is narrower than the working tree. Git status and a focused test command must independently confirm the final state.

Use synthetic data only. Do not run the drill in production, on a release branch, or in a workspace with uncommitted work you care about. Never assume the rewind menu will recover a secret, generated artifact, database change, remote API call, pushed commit, or deployment.

Step 1: create a disposable baseline

Create a short-lived branch or throwaway repository containing one tiny deterministic test. For example, use a pure function that calculates a discount and a test that expects 90 from an input of 100 with a 10 percent discount. Run the test once and save the passing output.

Record the repository path, branch, commit hash, test command, result, and timestamp. Confirm git status --short is empty. This is your known-good baseline and makes the recovery result observable rather than a matter of visual judgment.

Step 2: ask for one bounded bad edit

Start Claude Code in the disposable project and give it a controlled instruction:

For this recovery drill only, edit the discount assertion from 90 to 91.
Change only the test file. Do not run shell commands, commit, push, or edit configuration.
After the edit, stop and list the changed file.

Inspect the diff yourself. The only difference should be the seeded incorrect assertion. Run the focused test outside the agent flow and capture the expected failure. If any other file changes, stop the drill and use Git to restore the disposable branch before investigating why the scope expanded.

Step 3: add an out-of-scope marker safely

Now create a harmless marker through your terminal, not through Claude’s direct file editor. For example, create checkpoint-shell-marker.txt containing a random drill ID. Do not delete, rename, or overwrite a real file for this test.

This marker represents the documented gap for shell-command and external-process changes. Capture git status --short showing both the modified test and the new marker. Your expected rewind result is intentionally asymmetric: the test edit should disappear, while the marker should remain.

Step 4: open the rewind menu

Run /rewind, or press Escape twice while the prompt input is empty. Select the checkpoint immediately before the bad-edit prompt and choose Restore code. Keeping the conversation allows you to compare the transcript with the filesystem after recovery.

Do not choose by vague timestamps alone. Match the exact prompt text and confirm the menu shows tracked file changes. If code-restore choices are missing, Anthropic says that checkpoint has no captured file edits to revert. Record that as evidence instead of selecting a different point until something looks successful.

Step 5: verify state outside Claude

After rewind, inspect the test diff and run git status --short from your own terminal. The bad assertion should be back to 90, but the shell marker should still exist. Run the focused test again and save the passing output.

Evidence Expected after rewind Why it matters
Tracked test diff No seeded assertion change Proves direct edit recovery
Shell-created marker Still present Proves the documented coverage gap
Focused test Passes Checks behavior, not only text
Git status Only the marker remains Independent working-tree evidence
Claude transcript Original edit prompt remains Preserves audit context when restoring code only

If the test passes but the diff is not clean, recovery is incomplete. If the diff is clean but the test fails, the baseline or test environment changed. Treat both as investigation results, not as permission to merge.

Step 6: test all three restore choices

Repeat the drill in fresh disposable sessions for the other options. Restore conversation should rewind the dialogue while keeping current code. Restore code and conversation should return both to the selected point. Never reuse the same working tree without resetting it to the recorded baseline first, or evidence from one trial will contaminate the next.

For each trial, use a unique drill ID and capture the selected checkpoint, action, files before and after, test result, and Git status. This creates a compact matrix that another QA engineer can reproduce.

Step 7: exercise the limits deliberately

  • Shell change: confirm the harmless marker survives rewind.
  • External edit: modify a second synthetic file from another editor and confirm it is not assumed recoverable.
  • Concurrent session: change a different synthetic file in another Claude session and inspect which session owns the checkpoint.
  • Subagent edit: run only in a throwaway branch and verify rather than assume whether the parent session restores it.
  • Resume: close and resume the session, then confirm the checkpoint is listed before testing recovery.
  • Older checkpoints: do not rely on indefinite retention; record the documented snapshot and cleanup boundaries.
  • Symlink: use only a disposable target and verify both link and resolved file state.

Do not convert this into a destructive demo. A safe drill can prove the same control boundaries using synthetic files and reversible test failures.

Step 8: keep Git as the durable control

Checkpointing is session-level undo. Git provides durable history, reviewable diffs, branches, commits, and team collaboration. Before asking an agent to make a broad test-framework change, create a clean branch, record the baseline commit, and keep commits small enough to review.

Use checkpoint rewind for fast local recovery during exploration. Use Git when the change spans sessions, includes shell tooling, involves multiple actors, must be reviewed, or could affect CI and releases. Neither layer recovers external state such as test data written to a service, a message sent to a shared channel, or a deployment already triggered.

Evidence checklist for QA teams

  • Disposable repository or branch identified
  • Clean baseline commit and passing test captured
  • One bounded bad edit and expected failure recorded
  • Checkpoint prompt and restore option captured
  • Before-and-after diff saved
  • Shell or external marker behavior verified
  • Focused test rerun after recovery
  • Git status independently checked
  • Uncovered side effects documented
  • Human reviewer signs off before merge or release

Common mistakes

Do not treat a successful menu action as proof that every side effect was reversed. Do not run the first drill in a dirty workspace. Do not use checkpointing instead of Git. Do not assume a passing test proves the original state returned when fixtures, generated files, environment variables, or external services may have changed. Finally, do not hide the limitation test: the surviving marker is useful evidence that the team understands the boundary.

Official sources

Claude Code checkpointing can shorten recovery from a bad AI edit, but the safe QA pattern is layered: bounded experiments, checkpoints for direct edits, Git for durable history, deterministic tests for behavior, explicit checks for untracked side effects, and human control over merge and release decisions.