Checkpointing — 세션 컨텍스트 지속성

세션 중 작업 기록을 저장하고 재사용 가능한 스킬 패턴을 찾는다.

모드

Mode 1: Session History(기본값)

CLI 상담 이력을 각 에이전트의 구성 파일에 추가한다.

┌─────────────────────────────────────────────────────────────┐
│  .claude/logs/cli-tools.jsonl                               │
│                      ↓                                      │
│  /checkpointing                                             │
│                      ↓                                      │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│  │  CLAUDE.md   │ │ AGENTS.md    │ │ GEMINI.md            │ │
│  │ ## Session   │ │ ## Session   │ │ ## Session           │ │
│  │ History      │ │ History      │ │ History              │ │
│  └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Mode 2: Full Checkpoint（--full）

전체 작업의 포괄적인 스냅 샷을 만든다.

┌─────────────────────────────────────────────────────────────┐
│  Data Sources:                                              │
│  ├─ git log (commits)                                       │
│  ├─ git diff (file changes)                                 │
│  └─ cli-tools.jsonl (Codex/Gemini logs)                     │
│                      ↓                                      │
│  /checkpointing --full                                      │
│                      ↓                                      │
│  .claude/checkpoints/2026-01-28-153000.md                   │
│  ├─ Summary (commits, files, consultations)                 │
│  ├─ Git History (commits list)                              │
│  ├─ File Changes (created, modified, deleted)               │
│  └─ CLI Consultations (Codex/Gemini)                        │
└─────────────────────────────────────────────────────────────┘

Mode 3: Skill Analysis（--full --analyze）

체크포인트에서 스킬화할 수 있는 패턴을 발견한다.

┌─────────────────────────────────────────────────────────────┐
│  /checkpointing --full --analyze                            │
│                      ↓                                      │
│  1. Full Checkpoint 생성                                   │
│  2. 분석용 프롬프트 생성                                    │
│     → .claude/checkpoints/YYYY-MM-DD-HHMMSS.analyze-prompt.md│
│                      ↓                                      │
│  3. 서브에이전트에서 AI 분석 수행                            │
│     → 작업 패턴 발견                                      │
│     → 스킬 후보 제안                                        │
│                      ↓                                      │
│  4. 새로운 스킬을 .claude/skills/에 추가                         │
└─────────────────────────────────────────────────────────────┘

발견할 패턴 예시:

• 테스트 → 구현 반복(TDD 워크플로우)
• 연구 → 설계 → 실장 흐름
• 특정 파일 세트의 동시 변경
• CLI 상담 → 코드 변경 순서

사용법

# Session History 모드(기본값)
/checkpointing

# Full Checkpoint 모드
/checkpointing --full

# Skill Analysis 모드(권장)
/checkpointing --full --analyze

# 기간 지정
/checkpointing --since "2026-01-26"
/checkpointing --full --analyze --since "2026-01-26"

Skill Analysis 실행 흐름

# Step 1: 체크포인트 + 분석 프롬프트 생성
python checkpoint.py --full --analyze

# Step 2: 서브에이전트에서 분석(Claude 자동 실행)
# → 분석 프롬프트 로드
# → 스킬 후보 제안
# → 사용자가 승인하면 스킬 생성

처리 내용

Session History 모드

1. .claude/logs/cli-tools.jsonl 구문 분석
2. Codex/Gemini에 상담 내용을 날짜별로 정리
3. 각 에이전트 구성 파일에 ## Session History 추가

Full Checkpoint 모드

1. Git 정보 수집

   • git log로 커밋 내역
   • git diff --name-status로 파일 변경
   • git diff --numstat로 행 수 변경

2. CLI 상담 로그 분석

   • Codex상담 내용 및 상태
   • Gemini조사 내용 및 상태

3. 체크포인트 파일 생성

   • .claude/checkpoints/YYYY-MM-DD-HHMMSS.md

Full Checkpoint 형식

# Checkpoint: 2026-01-28 15:30:00 UTC

## Summary
- **Commits**: 5
- **Files changed**: 12 (8 modified, 3 created, 1 deleted)
- **Codex consultations**: 3
- **Gemini researches**: 2

## Git History

### Commits
- `abc1234` Add checkpointing enhancement
- `def5678` Update documentation

### File Changes

**Created:**
- `new_feature.py` (+120)

**Modified:**
- `checkpoint.py` (+80, -20)
- `SKILL.md` (+45, -10)

**Deleted:**
- `old_script.py`

## CLI Tool Consultations

### Codex (3 consultations)
- ✓ 설계: 체크포인트 확장 아키텍처
- ✓ 디버깅: Git log parsing issue

### Gemini (2 researches)
- ✓ 조사: Git integration best practices

Session History 형식

## Session History

### 2026-01-26

**Codex상담:**
- ✓ 하위 에이전트 패턴으로 Codex / Gemini 호출 권장...

**Gemini조사:**
- ✓ MCP vs CLI 비교 조사...

실행 타이밍

타이밍	권장 모드
세션 종료 전	--full --analyze
중요한 설계 결정 후	--full
큰 기능 구현 완료 후	--full --analyze
장시간 작업 구분	--full
반복 패턴을 느꼈을 때	--full --analyze
일일 가벼운 기록	기본

주의사항

• 로그가 비어 있으면 아무 것도 추가되지 않는다.
• 기존 '## Session History'섹션은 덮어 쓴다.
• 로그 파일 자체는 변경되지 않는다 (읽기 전용)
• Full Checkpoint는 .claude/checkpoints/에 축적된다.
• Git 초기화되지 않은 프로젝트에서도 CLI 로그 부분이 작동한다. ---analyze 로 생성된 스킬 제안은 인간이 검토하고 나서 채용하는 것이다.
• 스킬 분석은 패턴을 고정하지 않고 AI가 자유롭게 발견하는 설계를 한다.