checkpoint

/checkpoint - 작업 상태 저장/복원 (v6)

---

0단계: 파라미터 파싱

서브커맨드	설명	필수 인자
save	현재 상태 저장	"이름"
restore	저장된 상태 복원	"이름"
list	저장된 체크포인트 목록	없음
diff	체크포인트 간 차이 비교	"이름"
delete	체크포인트 삭제	"이름"

옵션:

• --tag 태그: 체크포인트에 태그 부착 (예: --tag stable, --tag pre-refactor)

---

1단계: 저장소 경로

체크포인트 저장 위치:

.claude/checkpoints/
  {name}/
    metadata.json
    staged.patch      # staged 변경사항
    unstaged.patch    # unstaged 변경사항
    untracked/        # untracked 파일 복사본

저장소 디렉토리가 없으면 생성한다:

mkdir -p .claude/checkpoints

---

2단계: save 서브커맨드

2-1. 현재 상태 수집

# 현재 브랜치
git branch --show-current

# 현재 커밋
git rev-parse --short HEAD

# staged 변경사항
git diff --cached > .claude/checkpoints/{name}/staged.patch

# unstaged 변경사항
git diff > .claude/checkpoints/{name}/unstaged.patch

# 변경 통계
git diff --stat HEAD

# untracked 파일 목록
git ls-files --others --exclude-standard

2-2. untracked 파일 복사

untracked 파일이 있으면 복사본을 저장한다:

mkdir -p .claude/checkpoints/{name}/untracked
# 각 untracked 파일을 디렉토리 구조 유지하며 복사

2-3. 메타데이터 생성

{
  "name": "기능완료",
  "timestamp": "2026-02-07T15:30:00Z",
  "branch": "feature/auth",
  "commit": "abc1234",
  "files": [
    "src/auth/login.ts",
    "src/auth/register.ts"
  ],
  "stats": {
    "additions": 45,
    "deletions": 12,
    "files_changed": 3,
    "untracked_count": 1
  },
  "tags": ["stable"],
  "auto": false,
  "v6_metadata": {
    "security_status": "pass"
  }
}

v6_metadata 필드 설명:

• security_status: 마지막 보안 검사 결과 (pass/fail/unknown)

2-4. 자동 체크포인트

다음 상황에서 자동으로 체크포인트를 생성한다:

• /commit-push-pr 실행 전
• /handoff-verify 검증 3회 실패 시

자동 체크포인트의 auto 필드는 true로 설정한다. 이름 형식: auto-{YYYYMMDD-HHmmss}

---

3단계: restore 서브커맨드

3-1. 체크포인트 존재 확인

ls .claude/checkpoints/{name}/metadata.json

3-2. 현재 상태 백업

복원 전 현재 상태를 pre-restore-{timestamp} 이름으로 자동 저장한다.

3-3. 복원 실행

# staged 변경사항 복원
git apply .claude/checkpoints/{name}/staged.patch
git add -A

# unstaged 변경사항 복원
git apply .claude/checkpoints/{name}/unstaged.patch

# untracked 파일 복원
cp -r .claude/checkpoints/{name}/untracked/* ./ 2>/dev/null