Blog NotebookLM -- 문서 기반 출처 확보 연구
Claude Code에서 Google NotebookLM 노트북을 직접 쿼리하여 업로드된 문서로부터 인용 기반 답변을 얻을 수 있습니다. 각 질문은 헤드리스 브라우저 세션을 열고, 사용자가 업로드한 문서에서만 답변을 검색한 후 종료됩니다. 응답은 Tier 1 품질(사용자 자신의 1차 출처)로, 환각(hallucination) 위험이 전혀 없습니다.
빠른 참조
| 명령어 | 설명 |
|---|---|
/blog notebooklm ask <질문> | 노트북에 출처 기반 답변 질의 |
/blog notebooklm discover <url> | 노트북 콘텐츠를 스마트하게 발견하여 목록화 |
/blog notebooklm library list | 라이브러리의 모든 노트북 나열 |
/blog notebooklm library add <url> | 라이브러리에 노트북 추가 |
/blog notebooklm library search <질의> | 키워드로 노트북 검색 |
/blog notebooklm library remove <id> | 라이브러리에서 노트북 제거 |
/blog notebooklm setup | 일회성 Google 인증 (브라우저 표시) |
/blog notebooklm status | 인증 상태 확인 |
/blog notebooklm cleanup | 브라우저 상태 정리 (라이브러리 유지) |
사전 요구 사항
- NotebookLM 액세스 권한이 있는 Google 계정
- Python 3.11+ (
run.py가 자동으로 venv 관리) - Google Chrome (최초 실행 시 Patchright를 통해 자동 설치)
- 일회성 인증 설정 (표시되는 브라우저에서 대화형 Google 로그인)
항상 run.py 래퍼 사용
절대 스크립트를 직접 호출하지 마세요. 항상 python3 scripts/run.py [스크립트]를 사용하세요:
# 올바른 예:
python3 scripts/run.py auth_manager.py status
python3 scripts/run.py ask_question.py --question "..."
# 잘못된 예 -- venv 없이 실패:
python3 scripts/auth_manager.py status
run.py 래퍼는 자동으로 .venv를 생성하고, 종속성을 설치하며, Chrome을 설정한 후 대상 스크립트를 실행합니다.
인증 확인 (게이트 패턴)
쿼리 작업 전에 인증 상태를 확인하세요:
python3 scripts/run.py auth_manager.py status
- 인증됨: 쿼리 진행
- 인증되지 않음: 사용자에게 알리고 설정으로 안내:
"NotebookLM은 Google 로그인이 필요합니다.
/blog notebooklm setup을 실행하여 인증하세요." - 내부에서 호출될 때 (blog-write 또는 blog-researcher에서): 인증되지 않은 경우 오류 없이 조용히 반환합니다. 절대 글쓰기 워크플로를 차단하지 마세요.
설정 워크플로
/blog notebooklm setup의 경우:
# 수동 Google 로그인을 위한 브라우저 창 열기 (일회성)
python3 scripts/run.py auth_manager.py setup
사용자에게 알림: "브라우저 창이 열립니다. Google 계정으로 로그인해 주세요." 인증은 브라우저 프로필 + 쿠키 주입(하이브리드 방식)을 통해 유지됩니다.
기타 인증 명령어:
python3 scripts/run.py auth_manager.py status # 인증 확인
python3 scripts/run.py auth_manager.py reauth # 재인증
python3 scripts/run.py auth_manager.py clear # 모든 인증 데이터 삭제
쿼리 워크플로
/blog notebooklm ask <질문>의 경우:
1단계: 인증 확인
인증 확인 실행 (위 게이트 패턴 참조). 인증되지 않은 경우 설정으로 안내합니다.
2단계: 노트북 확인
쿼리할 노트북 결정:
--notebook-url제공됨: 직접 사용--notebook-id제공됨: 라이브러리에서 조회- 둘 다 없음: 라이브러리의 활성 노트북 사용
- 활성 노트북 없음: 라이브러리 표시 및 사용자 선택 요청
3단계: 질문하기
# 기본 쿼리 (활성 노트북 사용)
python3 scripts/run.py ask_question.py --question "여기에 질문을 입력하세요"
# 특정 노트북 ID로 쿼리
python3 scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
# URL로 직접 쿼리
python3 scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
# JSON 출력 (내부/프로그래밍용)
python3 scripts/run.py ask_question.py --question "..." --json
# 디버깅을 위해 브라우저 표시
python3 scripts/run.py ask_question.py --question "..." --show-browser
4단계: 분석 및 후속 질문
모든 응답은 후속 질문으로 끝납니다. 필수 동작:
- 멈춤 -- 사용자에게 즉시 응답하지 마세요
- 분석 -- 답변을 사용자의 원래 요청과 비교하세요
- 갭 식별 -- 추가 정보가 필요한지 확인하세요
- 후속 질문 -- 갭이 있으면 즉시 후속 질문을 하세요
- 반복 -- 정보가 완전해질 때까지 계속하세요
- 종합 -- 사용자에게 응답하기 전에 모든 답변을 결합하세요
스마트 발견 워크플로
/blog notebooklm discover <url>의 경우:
내용을 모르는 노트북을 추가할 때 먼저 쿼리하세요:
# 1단계: 콘텐츠 발견
python3 scripts/run.py ask_question.py \
--question "이 노트북의 내용은 무엇인가요? 어떤 주제가 다루어지나요? 간결하게 전체 개요를 제공해 주세요." \
--notebook-url "<URL>"
# 2단계: 발견된 메타데이터로 추가
python3 scripts/run.py notebook_manager.py add \
--url "<URL>" \
--name "<콘텐츠 기반 이름>" \
--description "<콘텐츠 기반 설명>" \
--topics "<추출된 주제>"
절대 추측하거나 일반적인 설명을 사용하지 마세요. 항상 발견하거나 사용자에게 물어보세요.
라이브러리 관리
# 모든 노트북 나열
python3 scripts/run.py notebook_manager.py list
# 노트북 추가 (모든 매개변수 필수 -- 발견하거나 사용자에게 물어보세요!)
python3 scripts/run.py notebook_manager.py add \
--url "https://notebooklm.google.com/notebook/..." \
--name "설명적 이름" \
--description "이 노트북이 포함하는 내용" \
--topics "주제1,주제2,주제3"
# 키워드로 검색
python3 scripts/run.py notebook_manager.py search --query "키워드"
# 활성 노트북 설정
python3 scripts/run.py notebook_manager.py activate --id notebook-id
# 노트북 제거
python3 scripts/run.py notebook_manager.py remove --id notebook-id
# 라이브러리 통계
python3 scripts/run.py notebook_manager.py stats
내부 API (blog-write / blog-researcher용)
blog-write 또는 blog-researcher에서 태스크 서브에이전트로 호출될 경우:
입력 (호출 스킬에서 제공):
question: 블로그 주제와 관련된 연구 질문notebook_id또는notebook_url: 쿼리할 노트북context: "internal" (정상적인 폴백 모드 신호)
프로세스:
- 인증 상태 확인 -- 인증되지 않으면 조용히 빈 결과 반환
- 연구 질문으로 노트북 쿼리
- 구조화된 응답 파싱 및 반환
출력 (호출 스킬로 반환):
### NotebookLM 연구
- **출처:** [노트북 이름]
- **질문:** [무엇을 질문했는지]
- **답변:** [사용자 문서에서 출처 기반 응답]
- **출처 품질:** Tier 1 (사용자 업로드 1차 문서)
정상적인 폴백: 인증이 없거나 쿼리가 실패하면 오류 없이 즉시 반환합니다. 호출 워크플로는 WebSearch 기반 연구로 계속 진행됩니다. NotebookLM을 사용할 수 없어도 blog-write 또는 blog-rewrite를 차단하지 마세요.
데이터 저장
모든 데이터는 스킬 디렉토리 내에 저장됩니다:
scripts/data/library.json-- 노트북 메타데이터 및 라이브러리scripts/data/auth_info.json-- 인증 상태scripts/data/browser_state/-- 쿠키가 포함된 Chrome 프로필
보안: 모든 데이터 디렉토리는 gitignore 처리됩니다. 인증 또는 브라우저 상태를 절대 커밋하지 마세요.
오류 처리
| 오류 | 해결 방법 |
|---|---|
| 인증되지 않음 | /blog notebooklm setup 실행 |
| ModuleNotFoundError | 항상 run.py 래퍼 사용 |
| 브라우저 충돌 | cleanup_manager.py --confirm --preserve-library 실행 후 재인증 |
| 속도 제한 (일 50회) | 자정(PST)까지 대기 또는 Google 계정 전환 |
| 노트북을 찾을 수 없음 | notebook_manager.py list로 확인 |
| 쿼리 시간 초과 (120초) | 더 간단한 질문으로 재시도하거나 --show-browser로 디버깅 |
| MCP 사용 불가 (내부) | 조용히 반환 -- 글쓰기 워크플로가 WebSearch 사용 |
제한 사항
- 세션 지속성 없음 (각 질문 = 새 브라우저 세션)
- 무료 Google 계정 속도 제한 (일 50회 쿼리)
- 수동 업로드 필요 (사용자가 NotebookLM 웹 UI에 문서를 추가해야 함)
- 브라우저 오버헤드 (질문당 실행 및 종료에 몇 초 소요)
- 로컬 Claude Code에서만 사용 가능 (웹 UI에서는 사용 불가)
참조 문서
필요 시 로드 -- 시작 시 모두 로드하지 마세요:
references/commands.md-- 전체 CLI 명령어, 매개변수 및 워크플로 패턴references/troubleshooting.md-- 오류 해결, 복구 절차, 디버깅