---
task_id: task-1904
type: context
scope: task
created: 2026-04-16
updated: 2026-04-17
status: completed
---

# 맥락 노트: task-1904

**task**: task-1904

---

## 결정 근거

### 체크포인트 정리를 정제 완료 시점에 배치
- 정제 성공이 확인된 후에만 삭제해야 함. 실패 시엔 체크포인트를 보존하여 재시작이 가능해야 하므로.
- `extract_knowledge_v2()` return 직전이 가장 안전한 삭제 시점.

### 삭제 실패를 비차단(non-blocking)으로 처리
- 체크포인트 잔존은 치명적이지 않음 (다음 정제 시 덮어쓰기 가능).
- 삭제 실패 시 OSError를 잡아 경고 로그만 남기고 계속 진행.

### 기존 1~3번 구현 유지 (수정 불필요)
- 지시서 코드 예시(`model_dump()`)와 실제 코드(`_thread_to_dict()`)가 다름.
- 실제 코드가 올바름: ThreadV2는 dataclass이므로 Pydantic `model_dump()` 사용 불가.
- `_thread_to_dict()` + `_threads_from_dicts()`가 이미 정확하게 직렬화/역직렬화를 수행.

## 3 Step Why

### 1st Why: "왜 체크포인트 정리가 필요한가?"
- 정제 완료 후 체크포인트 파일이 남으면, 다음 정제 시 이전 데이터가 의도치 않게 복원되어 새 데이터 처리를 방해함.

### 2nd Why: "왜 정제 완료 시점에 정리하는 것이 최선인가?"
- 정제 성공이 확인된 후에만 삭제해야 하므로, `extract_knowledge_v2()` 결과가 정상 반환된 시점이 가장 안전함.
- 실패 시엔 체크포인트를 보존하여 재시작이 가능해야 함.

### 3rd Why: "왜 삭제가 보존보다 나은가?"
- 체크포인트 잔존은 다음 실행의 "이어서 정제" 로직을 오작동시킬 수 있음.
- 보존 옵션은 현재 불필요한 복잡도 (YAGNI). 필요 시 환경변수로 추가 가능하나 지금은 과설계.
- A-B-C 논리 일관: 방해 → 성공 후 안전 삭제 → 오작동 방지

## 참조 자료

- 대상 파일: `/home/jay/projects/insuwiki/scripts/kakao_knowledge/knowledge_extractor_v2.py`
- 테스트 파일: `/home/jay/projects/insuwiki/scripts/kakao_knowledge/tests/test_knowledge_extractor_v2.py`

## 주의사항

- ThreadV2는 dataclass, ChatMessage는 Pydantic — 직렬화 방식이 혼재
- output_dir이 None이면 체크포인트 미저장/미삭제 (기존 동작 유지)
- 디스크 공간 부족(123MB)으로 worktree 생성 불가 → main 브랜치에서 직접 작업