# 유튜브 3-Layer 요약 파이프라인 체크리스트

- 작성자: 아르고스 (QA/Tester)
- 작성일: 2026-03-03
- 프로젝트: InsuWiki - 유튜브 3-Layer 요약 파이프라인 확장
- 참조: RAG v2.1 스펙, crawlYoutubeChannels.ts, summary-pipeline.ts

---

## 개요

유튜브 콘텐츠에 약관 3-Layer 구조와 동일한 계층적 요약 파이프라인을 적용한다.

| 레벨 | 약관(기존) | 유튜브(신규) | 분량 |
|------|-----------|------------|------|
| Level 3 | 원문 청크 | 자막 원문 청크 | 원문 |
| Level 2 | 섹션 요약 | 영상 주제별 구조화 요약 | 300~500자 |
| Level 1 | 핵심 요약 | 채널/기간별 통합 인사이트 | 200~400자 |

**핵심 제약**: 유튜브는 4순위 참고자료 → 단독 인용 금지, 약관 상충 시 약관 우선

---

## Phase 0: 사전 준비 체크리스트

> 목표: 기존 시스템 현황 파악 및 신규 개발 범위 확정

### 기존 코드/스펙 확인

- [ ] 기존 RAG v2 스펙 (v2.1) 문서 확인 완료
- [ ] 현재 `youtube_knowledge` 컬렉션 데이터 구조 확인 (필드명, 타입, 샘플 문서)
- [ ] 현재 `insurance_chunks` (`sourceType: 'youtube'`) 데이터 존재 여부 및 구조 확인
- [ ] `insurance_summaries` 컬렉션 스키마 확인 (Level 1/2 저장 방식 참고)
- [ ] `summary_jobs` 컬렉션 스키마 확인 (작업 추적 방식 참고)
- [ ] `crawlYoutubeChannels.ts` 전체 코드 리뷰 완료
  - [ ] 자막 추출 로직 흐름 파악
  - [ ] 기존 6섹션 Gemini 요약 프롬프트 위치 확인
  - [ ] Drive 업로드 경로 확인 (`04_유튜브요약/{채널명}/{날짜}_{제목}.md`)
  - [ ] 약관 상충 감지 로직 위치 및 동작 방식 확인
  - [ ] 임베딩 저장 로직 확인
- [ ] `scripts/summary-pipeline.ts` 코드 리뷰 완료 (약관 파이프라인 참고)
- [ ] `scripts/prompts/summary-prompts.ts` 프롬프트 구조 이해 완료
  - [ ] Level 2 프롬프트 빌더 함수 시그니처 파악
  - [ ] Level 1 프롬프트 빌더 함수 시그니처 파악
  - [ ] 환각 방지 가드레일 표현 목록 확인

### API 할당량/비용 확인

- [ ] Gemini API 일일 무료 할당량 확인 (RPM, TPM, RPD)
- [ ] Gemini API 유료 사용 시 토큰당 비용 산정 (Level 2 × 영상 수, Level 1 × 채널 수)
- [ ] YouTube Data API v3 무료 할당량 확인 (일일 10,000 유닛 기준)
  - [ ] `videos.list` 요청당 유닛 소모량 확인
  - [ ] `captions.download` 요청당 유닛 소모량 확인
  - [ ] 현재 크롤링 빈도(6시간) 기준 일일 유닛 사용량 추정
- [ ] Firestore 읽기/쓰기 무료 한도 대비 예상 사용량 추정

---

## Phase 1: 설계 체크리스트

> 목표: 구현 전 모든 설계 결정 사항 문서화 및 팀 합의

### 데이터 구조 설계

- [ ] **Level 3 저장 구조 확정**: 기존 컬렉션 확장 vs 신규 컬렉션 생성
  - [ ] 옵션 A: `insurance_chunks`에 `sourceType: 'youtube'` 필드 추가 확장
  - [ ] 옵션 B: `youtube_chunks` 신규 컬렉션 생성
  - [ ] 결정 사항 및 근거 문서화
- [ ] **기존 6섹션 요약과의 관계 결정**: 유지 / 대체 / 병행
  - [ ] Level 2와 기존 6섹션 요약의 중복 여부 검토
  - [ ] 결정 시 `crawlYoutubeChannels.ts` 수정 범위 확정
- [ ] **Firestore 스키마 확정** (Level 3, Level 2, Level 1 각각)

  ```
  Level 3 (자막 청크) 예시:
  {
    videoId: string,
    channelId: string,
    chunkIndex: number,
    text: string,
    startTime: number,
    sourceType: 'youtube',
    createdAt: Timestamp
  }

  Level 2 (영상별 요약) 예시:
  {
    videoId: string,
    channelId: string,
    title: string,
    summaryText: string,        // 300~500자
    sections: string[],         // 주제별 구조
    conflictWarning: boolean,
    createdAt: Timestamp,
    level: 2
  }

  Level 1 (채널/기간별 통합) 예시:
  {
    channelId: string,
    period: string,             // 'YYYY-MM'
    insightText: string,        // 200~400자
    sourceVideoIds: string[],
    createdAt: Timestamp,
    level: 1
  }
  ```

- [ ] 스키마 확정 후 팀 검토 완료

### 프롬프트 설계

- [ ] **Level 2 프롬프트 초안 작성**
  - [ ] 입력: 자막 청크 배열 + 영상 제목 + 채널명
  - [ ] 출력: 주제별 구조화 요약 (300~500자)
  - [ ] 권위 계층 문구 포함: "본 내용은 참고용이며 정확한 내용은 약관을 확인하세요"
  - [ ] 환각 방지 가드레일 포함: 불확실 표현("아마도", "추정", "일반적으로") 금지 지시
  - [ ] 약관 상충 감지 시 경고 문구 삽입 지시 포함
- [ ] **Level 1 프롬프트 초안 작성**
  - [ ] 입력: 동일 채널 또는 동일 기간 Level 2 요약 배열
  - [ ] 출력: 채널/기간별 통합 인사이트 (200~400자)
  - [ ] 단독 인용 금지 문구 포함
  - [ ] 환각 방지 가드레일 동일 적용
- [ ] 프롬프트 초안 팀 검토 완료

### 파이프라인 흐름 설계

- [ ] **파이프라인 흐름도 확정** (문서 또는 다이어그램)

  ```
  크롤링(6시간 주기)
    └─ 자막 추출
         └─ Level 3 저장 (자막 청크)
              └─ Level 2 생성 (영상별 구조화 요약)
                   └─ Level 1 생성 (채널/기간별 통합 인사이트)
                        └─ Drive 업로드
                             └─ 임베딩 생성
                                  └─ 약관 상충 감지
                                       └─ youtube_knowledge 저장
  ```

- [ ] 각 단계 실패 시 재시도 정책 정의 (최대 재시도 횟수, 백오프 전략)
- [ ] 부분 실패 시 체크포인트 재개 방식 결정
- [ ] **권위 계층 준수 규칙 Level별 반영 확인**
  - [ ] Level 3: 원문 그대로 저장 (편집 없음)
  - [ ] Level 2: 약관 상충 감지 경고 문구 삽입 로직 포함
  - [ ] Level 1: 4순위 참고자료 명시, 단독 인용 금지 문구 포함
- [ ] `summary_jobs` 방식으로 작업 추적할지 여부 결정

---

## Phase 2: 구현 체크리스트

> 목표: 설계 문서 기반 실제 코드 구현, 의존 순서 준수

### Level 3: 자막 청킹 구현

- [ ] 자막 원문 청킹 함수 구현
  - [ ] 청크 단위 결정 (시간 기반 vs 문장 수 기반)
  - [ ] 최대 청크 크기 정의 (토큰 한도 고려)
  - [ ] 청크 간 오버랩 여부 결정
- [ ] Level 3 Firestore 저장 로직 구현
- [ ] 자막 없는 영상 처리 분기 구현 (영상 제목 + 설명 대체 경로)
- [ ] 자동 생성 자막(`asr`) 품질 플래그 저장 로직 구현

### Level 2: 영상별 구조화 요약 구현

> Level 3 구현 완료 후 시작

- [ ] **Level 2 프롬프트 모듈 구현**
  - [ ] 옵션 A: `summary-prompts.ts`에 `buildYoutubeLevel2Prompt()` 함수 추가
  - [ ] 옵션 B: `youtube-prompts.ts` 신규 파일 생성
  - [ ] 결정 사항 기반 구현, 함수 시그니처 확정
- [ ] Level 2 생성 로직 구현 (Gemini API 호출)
  - [ ] Gemini API 호출 시 temperature, maxOutputTokens 파라미터 최적화
  - [ ] 300~500자 범위 강제 재시도 로직 구현 (범위 벗어날 경우)
- [ ] Level 2 Firestore 저장 로직 구현
- [ ] 약관 상충 감지 결과 `conflictWarning` 필드 연동

### Level 1: 채널/기간별 통합 인사이트 구현

> Level 2 구현 완료 후 시작

- [ ] **Level 1 프롬프트 모듈 구현**
  - [ ] `buildYoutubeLevel1Prompt()` 함수 구현
  - [ ] 입력으로 받을 Level 2 요약 수 상한 정의 (컨텍스트 길이 제한 고려)
- [ ] Level 1 생성 로직 구현 (Gemini API 호출)
  - [ ] 200~400자 범위 강제 재시도 로직 구현
- [ ] Level 1 Firestore 저장 로직 구현
- [ ] Level 1 생성 트리거 결정 (영상 추가 시 즉시 vs 주기적 배치)

### CLI 및 파이프라인 통합

- [ ] **파이프라인 CLI 구현**
  - [ ] 옵션 A: `summary-pipeline.ts`에 `--source youtube` 플래그 확장
  - [ ] 옵션 B: `youtube-summary-pipeline.ts` 신규 CLI 작성
  - [ ] `--videoId`, `--channelId`, `--dry-run`, `--level` 옵션 지원
- [ ] **`crawlYoutubeChannels.ts` 통합**
  - [ ] 기존 파이프라인 하위 호환성 유지 확인
  - [ ] 3-Layer 단계(Level 3 저장 → Level 2 생성 → Level 1 생성) 순차 추가
  - [ ] 기존 6섹션 요약 단계와의 실행 순서 정의
  - [ ] 기존 `youtube_knowledge` 저장 경로 변경 없음 확인
- [ ] **환각 방지 가드레일 적용 확인**
  - [ ] 응답 후처리 단계에서 불확실 표현 패턴 감지 로직 구현
  - [ ] 감지 시 재생성 또는 경고 로그 정책 결정 및 구현
- [ ] **에러 처리 및 재시도 로직**
  - [ ] Gemini API 오류 (429 Rate Limit, 500 Server Error) 처리
  - [ ] YouTube Data API 할당량 초과 시 조기 종료 및 알림
  - [ ] Firestore 쓰기 실패 시 재시도 (지수 백오프)
  - [ ] 단계별 실패 시 `pipeline_logs`에 에러 기록
- [ ] Drive 업로드 경로 확인 (`04_유튜브요약/{채널명}/{날짜}_{제목}.md`)

---

## Phase 3: QA 체크리스트

> 목표: 기능 정확성, 품질 기준, 호환성 전체 검증

### 단위 테스트

- [ ] **Level 2 프롬프트 빌더 함수 테스트**
  - [ ] 정상 입력: 자막 청크 10개 + 제목 + 채널명 → 프롬프트 문자열 정상 생성
  - [ ] 엣지 케이스: 자막 청크 0개 (자막 없는 영상) → 예외 처리 또는 대체 프롬프트
  - [ ] 엣지 케이스: 자막 매우 짧은 경우 (30초 이하 영상)
  - [ ] 권위 계층 문구 포함 여부 assertion
  - [ ] 환각 방지 지시 문구 포함 여부 assertion
- [ ] **Level 1 프롬프트 빌더 함수 테스트**
  - [ ] 정상 입력: Level 2 요약 5개 → 프롬프트 문자열 정상 생성
  - [ ] 엣지 케이스: Level 2 요약 1개만 존재하는 경우
  - [ ] 엣지 케이스: Level 2 요약이 0개인 경우 → 예외 처리
  - [ ] 단독 인용 금지 문구 포함 여부 assertion
- [ ] 자막 청킹 함수 단위 테스트
  - [ ] 청크 수 정합성 확인
  - [ ] 청크 오버랩 정확성 확인

### 통합 테스트

- [ ] **단일 영상 전체 파이프라인 테스트** (보험명의정닥터 영상 1건 선정)
  - [ ] 자막 추출 → Level 3 저장 정상 확인
  - [ ] Level 3 → Level 2 생성 정상 확인
  - [ ] Level 2 → Level 1 생성 정상 확인
  - [ ] Drive 업로드 경로 정확성 확인
  - [ ] `pipeline_logs` 기록 정상 확인
- [ ] **ins-king 채널 영상 1건 동일 파이프라인 테스트**
- [ ] **자막 없는 영상 파이프라인 테스트** (제목+설명 대체 경로)
- [ ] **자동 생성 자막 영상 파이프라인 테스트** (`asr` 자막 플래그 정상 처리)

### 품질 검증

- [ ] **Level 2 요약 분량 기준 준수**
  - [ ] 테스트 영상 10건 대상 Level 2 요약 생성
  - [ ] 전체 300~500자 범위 내 확인 (위반 0건 목표)
  - [ ] 위반 발생 시 재시도 로직 동작 여부 확인
- [ ] **Level 1 요약 분량 기준 준수**
  - [ ] 테스트 채널 2개 Level 1 요약 생성
  - [ ] 전체 200~400자 범위 내 확인 (위반 0건 목표)
- [ ] **환각 표현 검증**
  - [ ] "아마도", "추정", "일반적으로", "~것 같습니다", "~로 보입니다" 패턴 검색
  - [ ] Level 2 전체 결과에서 0건 목표
  - [ ] Level 1 전체 결과에서 0건 목표
- [ ] **권위 준수 검증**
  - [ ] 약관 상충 감지된 영상: Level 2 요약 내 경고 문구 포함 확인
  - [ ] Level 1 요약 내 4순위 참고자료 명시 문구 포함 확인
  - [ ] Level 1 요약 내 단독 인용 금지 안내 문구 포함 확인

### 호환성 검증

- [ ] **기존 `youtube_knowledge` 데이터와의 호환성 확인**
  - [ ] 기존 문서 필드 손상 없음
  - [ ] 기존 임베딩 검색 정상 동작 확인
- [ ] **기존 `crawlYoutubeChannels.ts` 동작 하위 호환성 확인**
  - [ ] 3-Layer 코드 추가 전후 기존 기능 동일 동작 확인
  - [ ] 스케줄러 6시간 주기 변경 없음 확인
- [ ] **`insurance_chunks` sourceType 기반 검색 정상 동작 확인**

### 비용 및 성능 검증

- [ ] Firestore 읽기/쓰기 건수 모니터링 (1일 기준 추정 vs 실측)
- [ ] Gemini API 토큰 사용량 모니터링 (Level 2 + Level 1 합산)
- [ ] YouTube Data API 유닛 소모량 확인 (일일 10,000 유닛 한도 내)
- [ ] 전체 파이프라인 실행 시간 측정 (6시간 주기 내 완료 가능한지 확인)

---

## Phase 4: 배포 체크리스트

> 목표: 운영 환경 배포 및 초기 안정화

### 배포 전 준비

- [ ] **secrets 배열 확인**
  - [ ] `GEMINI_API_KEY` Cloud Functions secrets 등록 확인
  - [ ] `YOUTUBE_API_KEY` Cloud Functions secrets 등록 확인
  - [ ] `GOOGLE_DRIVE_CREDENTIALS` 또는 관련 인증 정보 등록 확인
- [ ] **Drive 폴더 구조 확인**
  - [ ] `04_유튜브요약/` 루트 폴더 존재 확인
  - [ ] `04_유튜브요약/보험명의정닥터/` 폴더 존재 또는 자동 생성 로직 확인
  - [ ] `04_유튜브요약/ins-king/` 폴더 존재 또는 자동 생성 로직 확인
- [ ] Firestore 인덱스 생성 완료 (Level 2, Level 1 컬렉션 쿼리용)
- [ ] `pipeline_logs` 컬렉션 쓰기 권한 확인

### 배포

- [ ] **Firebase Cloud Functions 배포** (`asia-northeast3` 리전)
  - [ ] 기존 함수 덮어쓰기 여부 확인 (신규 함수 vs 기존 함수 수정)
  - [ ] 배포 후 함수 목록 확인 (`firebase functions:list`)
- [ ] **스케줄러 설정 확인**
  - [ ] 기존 6시간 주기 크롤링 스케줄과 충돌 없음 확인
  - [ ] Level 1 생성 별도 스케줄 필요 시 cron 표현식 확인
- [ ] 배포 후 Cloud Functions 로그 초기 오류 없음 확인

### 배포 후 검증

- [ ] `pipeline_logs` 정상 기록 확인 (배포 후 첫 실행 기준)
- [ ] Drive 파일 생성 확인 (배포 후 첫 크롤링 결과)
- [ ] Firestore Level 2, Level 1 문서 생성 확인
- [ ] **에러 알림 설정 확인**
  - [ ] Cloud Functions 오류 발생 시 알림 채널 확인 (Slack, Email 등)
  - [ ] 파이프라인 실패율 임계치 알림 설정

### 롤백 절차

- [ ] **롤백 절차 문서화 완료**
  - [ ] 이전 Cloud Functions 버전 롤백 명령어 문서화
  - [ ] Firestore 신규 컬렉션 삭제 절차 문서화
  - [ ] `crawlYoutubeChannels.ts` 이전 버전 복구 절차 문서화
  - [ ] 롤백 후 기존 6시간 주기 크롤링 정상 동작 검증 절차 문서화
- [ ] 롤백 트리거 기준 정의 (파이프라인 실패율 > X%, API 오류율 > Y% 등)

---

## Phase 5: 운영 체크리스트

> 목표: 배포 이후 지속적인 품질 및 비용 관리

### 일상 모니터링

- [ ] **일일 파이프라인 실행 로그 모니터링**
  - [ ] `pipeline_logs` 컬렉션에서 전일 실행 성공/실패 건수 확인
  - [ ] 실패 건 원인 분류 (API 오류, 자막 없음, 할당량 초과 등)
- [ ] **API 할당량 모니터링**
  - [ ] Gemini API 일일 사용량 대시보드 확인
  - [ ] YouTube Data API 일일 유닛 소모량 확인

### 품질 관리

- [ ] **요약 품질 주기적 샘플링 검토** (주 1회 권장)
  - [ ] Level 2 요약 5건 무작위 샘플링 → 분량, 환각, 권위 준수 확인
  - [ ] Level 1 요약 2건 무작위 샘플링 → 분량, 환각, 권위 준수 확인
  - [ ] 품질 저하 감지 시 프롬프트 재검토 및 수정
- [ ] **약관 상충 감지 결과 주기적 검토** (월 1회)
  - [ ] 상충 감지율 이상 변동 여부 확인
  - [ ] 새로운 상충 패턴 발견 시 프롬프트 또는 상충 로직 업데이트

### 운영 절차 문서화

- [ ] **신규 채널 추가 절차 문서화**
  - [ ] `crawlYoutubeChannels.ts` 채널 목록 추가 방법
  - [ ] Drive 폴더 사전 생성 절차
  - [ ] 신규 채널 첫 실행 시 Level 1 생성 트리거 방법
- [ ] **요약 재생성 절차 문서화**
  - [ ] 특정 영상 Level 2 재생성 CLI 명령어 (`--videoId` 옵션)
  - [ ] 특정 채널 Level 1 재생성 CLI 명령어 (`--channelId` 옵션)
  - [ ] 재생성 시 기존 Firestore 문서 덮어쓰기 여부 정책
- [ ] **Gemini API 비용 모니터링 절차 문서화**
  - [ ] GCP Console 비용 대시보드 접근 경로
  - [ ] 월별 예산 알림 설정 방법

---

## 크리티컬 패스 (반드시 순서 준수)

```
Phase 0 전체 완료
  └─ Phase 1 전체 완료 (설계 합의)
       └─ Level 3 구현 완료
            └─ Level 2 구현 완료
                 └─ Level 1 구현 완료
                      └─ CLI/통합 구현 완료
                           └─ Phase 3 QA 전체 완료
                                └─ Phase 4 배포
```

**의존 관계 주의사항**

1. Level 3 저장 구조 확정 전에 Level 2, Level 1 구현 착수 금지
2. Level 2 프롬프트 팀 검토 완료 전에 Level 2 생성 로직 구현 착수 금지
3. 단위 테스트 통과 전에 통합 테스트 착수 금지
4. QA 전체 완료 전에 배포 착수 금지

---

## 위험 감지 체크리스트

> 아래 조건 감지 시 즉시 파이프라인 일시 중단 또는 담당자 알림

### 자막/데이터 품질

- [ ] **자막 추출 실패율 > 10%** → 파이프라인 일시 중단, 원인 분석 후 재개
  - 측정 방법: `pipeline_logs`에서 자막 추출 실패 건수 / 전체 크롤링 건수
- [ ] **자동 생성 자막 비율 > 50%** → 자막 품질 경고, Level 2 신뢰도 플래그 설정
- [ ] **Level 2 요약 분량 기준 미달 > 20%** → 프롬프트 즉시 재검토
  - 측정 방법: 300자 미만 또는 500자 초과 Level 2 요약 수 / 전체 Level 2 수
- [ ] **Level 1 요약 분량 기준 미달 > 20%** → 프롬프트 즉시 재검토
- [ ] **환각 표현 감지 건수 > 0** → 가드레일 로직 점검 및 해당 요약 재생성

### 약관 상충 감지

- [ ] **약관 상충 감지율 급감 (전주 대비 50% 이하)** → 상충 로직 오동작 의심, 점검
- [ ] **약관 상충 감지율 급증 (전주 대비 200% 이상)** → 새 상충 패턴 분석, 의도적 변화인지 확인

### API 할당량

- [ ] **YouTube Data API 일일 유닛 80% 도달** → 조기 경고, 비필수 요청 지연 처리
- [ ] **Gemini API RPM(분당 요청 수) 80% 도달** → 요청 간 딜레이 추가
- [ ] **Gemini API 월별 비용 예산 80% 도달** → 생성 빈도 조정 검토

### 시스템 안정성

- [ ] **전체 파이프라인 실행 시간 > 5시간** (6시간 주기 내 여유 1시간 미만) → 병렬화 또는 배치 분할 검토
- [ ] **Firestore 쓰기 오류율 > 1%** → Firestore 상태 점검
- [ ] **Cloud Functions 콜드 스타트 타임아웃 반복** → 메모리/타임아웃 설정 재검토

---

*이 체크리스트는 구현 진행에 따라 지속 업데이트합니다.*
*마지막 업데이트: 2026-03-03*