Initial commit

2025-11-30 08:51:29 +08:00
commit 4f7c98dd9c
24 changed files with 5134 additions and 0 deletions
--- a/skills/checkpointing/SKILL.md
+++ b/skills/checkpointing/SKILL.md
@@ -0,0 +1,435 @@
+---
+name: checkpointing
+description: How checkpointing works for tracking file changes and rewinding to previous states. Use when user asks about checkpoints, rewinding, rollback, undo, or restoring previous states.
+---
+
+# Claude Code Checkpointing
+
+## Overview
+
+Claude Code includes an automatic checkpointing system that tracks file edits and allows users to recover from unwanted changes during development sessions.
+
+## How Checkpointing Works
+
+### Automatic Tracking
+
+The system captures code states before each modification.
+
+**Key features:**
+- Every user prompt creates a new checkpoint
+- Checkpoints persist across resumed conversations
+- Automatic cleanup occurs after 30 days (configurable)
+
+### What Gets Tracked
+
+**Tracked:**
+- Direct file edits via Edit tool
+- File creations via Write tool
+- File modifications by Claude
+
+**Not tracked:**
+- Files modified by bash commands (`rm`, `mv`, `cp`)
+- Manual file modifications outside Claude Code
+- Changes from concurrent sessions (unless they affect files the current session modified)
+
+## Rewinding Changes
+
+### Access Rewind Menu
+
+**Keyboard shortcut:**
+Press `Esc` twice (quickly)
+
+**Slash command:**
+```
+/rewind
+```
+
+### Restoration Options
+
+When you open the rewind menu, you have three options:
+
+#### 1. Conversation Only
+**Keeps:** All code changes
+**Reverts:** Conversation history to selected checkpoint
+
+**Use when:**
+- You want to start conversation over
+- Code changes are good
+- You want to try different approach in conversation
+
+#### 2. Code Only
+**Keeps:** Conversation history
+**Reverts:** Files to selected checkpoint
+
+**Use when:**
+- Recent changes broke something
+- Want to undo code changes
+- Conversation context is valuable
+
+#### 3. Both Code and Conversation
+**Reverts:** Everything to selected checkpoint (full rollback)
+
+**Use when:**
+- Complete do-over needed
+- Both code and conversation went wrong
+- Want to return to known good state
+
+### Selecting a Checkpoint
+
+Checkpoints are displayed with:
+- Timestamp
+- User prompt that created it
+- Files affected
+- Changes summary
+
+Navigate with arrow keys and select with Enter.
+
+## Use Cases
+
+### Testing Different Approaches
+
+**Scenario:** Try multiple implementation strategies without losing starting point.
+
+```
+# Approach 1
+"implement feature using strategy A"
+# Review, not ideal
+
+# Rewind
+Esc Esc → Select checkpoint → Code only
+
+# Approach 2
+"implement feature using strategy B"
+# Better!
+```
+
+### Quick Bug Recovery
+
+**Scenario:** Recent changes introduced a bug.
+
+```
+# Make changes
+"refactor the authentication module"
+# Oops, broke login
+
+# Rewind
+Esc Esc → Select checkpoint before refactor → Code only
+
+# Try again differently
+"refactor authentication but keep existing login flow"
+```
+
+### Iterative Development
+
+**Scenario:** Preserve working states while iterating.
+
+```
+# Working state 1
+"add basic user validation"
+# Works ✓
+
+# Iterate
+"add more complex validation rules"
+# Issues found
+
+# Return to working state
+Esc Esc → Code only
+
+# Try different iteration
+"add regex-based validation"
+```
+
+### Conversation Reset
+
+**Scenario:** Conversation got confused or went off track.
+
+```
+# Good code changes made
+"add user profile endpoint"
+"add user settings endpoint"
+
+# Conversation gets confusing
+# Want to restart conversation but keep code
+
+# Rewind conversation only
+Esc Esc → Conversation only → Select early checkpoint
+
+# Fresh conversation start with code intact
+```
+
+## Important Limitations
+
+### Bash Command Changes Not Tracked
+
+**Not captured:**
+```
+!rm file.txt
+!mv old.txt new.txt
+!cp source.txt dest.txt
+!git checkout -b new-branch
+```
+
+**Why:** Bash commands run outside Claude's file tracking system.
+
+**Workaround:**
+- Use Claude's Edit/Write tools instead when possible
+- Manually track bash file operations
+- Use git for version control of important changes
+
+### External Changes Not Tracked
+
+**Not captured:**
+- Manual edits in your text editor
+- IDE refactorings
+- File system operations outside Claude Code
+- Changes from other tools
+
+**Workaround:**
+- Use git to track all changes
+- Create manual checkpoints with git commits
+- Be aware of what Claude modified vs what you modified
+
+### Concurrent Session Caveats
+
+**Limited tracking:**
+If multiple Claude Code sessions modify the same files, only changes from the current session are tracked for checkpointing.
+
+**Best practice:**
+Use one Claude Code session at a time per project.
+
+## Not a Version Control Replacement
+
+### Checkpointing vs Git
+
+| Feature | Checkpointing | Git |
+|---------|--------------|-----|
+| **Scope** | Session-level | Repository-wide |
+| **Duration** | 30 days | Permanent |
+| **Granularity** | Per prompt | Per commit |
+| **Collaboration** | Single user | Team |
+| **Purpose** | Session recovery | Version control |
+| **Bash tracking** | No | Yes |
+
+### Use Both Together
+
+**Git for:**
+- Permanent history
+- Collaboration
+- Branch management
+- All file changes (including bash)
+- Release management
+
+**Checkpointing for:**
+- Quick session rollback
+- Trying different approaches
+- Recovering from mistakes
+- Conversation management
+- Rapid iteration
+
+**Recommended workflow:**
+```
+# Regular git commits for milestones
+git commit -m "Working authentication"
+
+# Use checkpointing for rapid iteration
+"try optimization A"
+Esc Esc → rewind if not good
+"try optimization B"
+Esc Esc → rewind if not good
+"try optimization C"
+# This one works!
+
+# Commit the winner
+git add .
+git commit -m "Optimized authentication"
+```
+
+## Configuration
+
+### Checkpoint Retention
+
+**Default:** 30 days
+
+**Configure retention:**
+Edit `.claude/settings.json`:
+```json
+{
+  "checkpointRetentionDays": 60
+}
+```
+
+### Disable Checkpointing
+
+**Not recommended**, but possible:
+```json
+{
+  "enableCheckpointing": false
+}
+```
+
+## Best Practices
+
+### 1. Review Before Rewinding
+
+**Look at:**
+- What checkpoint contains
+- What will be lost
+- What will be kept
+
+**Avoid:**
+- Blindly selecting checkpoints
+- Rewinding without understanding impact
+
+### 2. Use Descriptive Prompts
+
+**Good (easy to identify):**
+```
+"add email validation to user registration"
+"refactor database queries for performance"
+```
+
+**Bad (hard to identify):**
+```
+"make changes"
+"fix it"
+```
+
+Checkpoints show your prompts, so descriptive prompts make checkpoint selection easier.
+
+### 3. Combine with Git
+
+```
+# Checkpoint for rapid iteration
+Try approach → rewind → try approach → rewind
+
+# Git for confirmed changes
+git add .
+git commit -m "Final implementation"
+```
+
+### 4. Rewind Code, Not Conversation
+
+**Often better:**
+Rewind code only and keep conversation history.
+
+**Why:**
+- Maintains context
+- Claude learns from mistakes
+- Can explain what went wrong
+- Better for iterative improvement
+
+### 5. Regular Git Commits
+
+Don't rely solely on checkpoints:
+```
+# After significant progress
+git add .
+git commit -m "Checkpoint: working user authentication"
+
+# Continue with Claude Code
+# Checkpointing handles rapid iteration
+# Git handles permanent milestones
+```
+
+## Troubleshooting
+
+### Checkpoint Not Showing Expected State
+
+**Possible causes:**
+- Changes made via bash commands (not tracked)
+- External file modifications
+- Concurrent session changes
+- Checkpoint expired (>30 days)
+
+**Solution:**
+- Use git for those scenarios
+- Check git history: `git log`
+- Review git diff: `git diff`
+
+### Can't Find Recent Checkpoint
+
+**Check:**
+- Are you in the right directory?
+- Is this the same session?
+- Did checkpoint expire?
+
+**Solution:**
+- Use `/rewind` command instead of Esc Esc
+- Check session history
+- Verify working directory
+
+### Rewind Not Working
+
+**Check:**
+- Are files write-protected?
+- Do you have filesystem permissions?
+- Are files open in another program?
+
+**Solution:**
+- Close files in editors
+- Check file permissions
+- Ensure no file locks
+
+## Example Workflows
+
+### Refactoring Safely
+
+```
+# Current working state
+git commit -m "Pre-refactor checkpoint"
+
+# Try refactoring
+"refactor user controller for better error handling"
+
+# Test
+!npm test
+
+# If tests fail
+Esc Esc → Code only → Return to pre-refactor
+
+# Try different approach
+"refactor user controller with focus on backward compatibility"
+
+# If tests pass
+git commit -m "Refactored user controller"
+```
+
+### Feature Experimentation
+
+```
+# Baseline working
+git commit -m "Baseline"
+
+# Experiment 1
+"add feature using approach A"
+# Review, note pros/cons
+
+# Rewind
+Esc Esc → Code only
+
+# Experiment 2
+"add feature using approach B"
+# Compare, choose better
+
+# If experiment 2 is better
+git commit -m "Added feature using approach B"
+
+# If neither was good
+Esc Esc → Code only → Back to baseline
+```
+
+### Conversation Management
+
+```
+# Making good progress
+"implement auth"
+"add user roles"
+"add permissions"
+
+# Conversation gets complex/confused
+Esc Esc → Conversation only → Select first checkpoint
+
+# Start fresh conversation
+"explain the architecture we just built"
+# Code intact, conversation reset
+```