AI Agent로 Obsidian 연동 학습 정리 도구를 만들다 (진행 보고)

# [PRD] LinkNote 2.0: Obsidian 연동형 로컬 지식 자산 변환기 (Slid 경쟁 제품 확장판)

## 0. 제품 철학 (Vision)

> "우리는 단순한 노트 앱이 아니다. **영상·강의 속 지식을 사용자의 로컬 지식 그래프(Obsidian)로, 가장 빠르고 가장 안전하게 운반하는 '지식 수송선'이다.**"

핵심 원칙:
- **Ownership:** 모든 원본 데이터(캡처, 전사, 메타데이터)는 사용자의 로컬 드라이브 및 개인 클라우드에 귀속된다.
- **Seamless:** 영상 시청 → 캡처 → 필기 → 구조화 → 재학습까지 최소 인터랙션, 최대 자동화.
- **Integrative:** 생성된 노트는 즉시 Obsidian 지식 그래프 및 사용자의 기존 PKM 워크플로우와 통합된다.
- **AI-Augmented, not AI-Locked:** AI는 보조 수단이며, 핵심 가치는 구조화된 로컬 데이터에 있다. (Slid처럼 SaaS 락인 최소화)

---

## 1. 문제 정의 및 목표

### 1.1 사용자 문제 (Pain Points)

- **분절된 워크플로우:** 영상 시청, 스크린샷, 파일 저장, 링크 삽입, 노트 정리까지 여러 툴과 단계를 오가며 몰입이 깨진다.[file:12]
- **클라우드 락인:** Slid 등 SaaS는 강력하지만, 데이터가 클라우드에만 쌓여 장기적인 소유감과 이식성이 떨어진다.[web:2][web:3][web:8]
- **재학습 비용:** 노트에서 다시 영상 특정 시점으로 돌아가기 번거롭고, ‘전사/요약’과 실제 영상 간 맥락이 쉽게 끊긴다.[file:12][web:3][web:9]
- **PKM 통합 난이도:** Obsidian/Logseq 등 로컬 지식베이스를 쓰는 유저 입장에선, 영상 노트와 기존 노트의 그래프 통합이 어렵다.[file:12]

### 1.2 제품 목표

- 단 한 번의 키 입력/클릭으로 영상 프레임·텍스트·메타데이터를 Obsidian Vault에 즉시 반영.
- 영상 ↔ 노트 간 양방향 타임스탬프 링크를 기본값으로 제공.
- Slid 수준(또는 그 이상)의 AI 요약/QA/퀴즈 생성 기능을 지원하되, BYOK로 로컬 중심 워크플로우 유지.[web:2][web:3][web:6][web:9][file:12]
- Obsidian 사용자 기준, **수동 캡처/복붙 대비 정리 시간 70% 이상 단축** 및 **재학습 진입 시간(영상 특정 시점 복귀) 80% 이상 단축**.[file:12]

---

## 2. 타겟 사용자

- 🎯 **Primary**
  - Obsidian/Logseq 등 로컬 PKM 도구를 메인으로 사용하는 개발자, 연구자, 대학생, 지식 노동자.[file:12]
  - 유튜브/온라인 강의/사내 교육 영상으로 학습하는 1인 학습자.
- 🎯 **Secondary**
  - Slid, Readwise Reader 등 SaaS를 쓰고 있으나 “로컬 백업”과 “Obsidian 통합”을 강하게 원하는 파워 유저.[web:2][web:3][web:8]
- 🚫 **Non-Target**
  - 팀 위주의 실시간 협업 노트, 엔터프라이즈 문서 승인 워크플로우.
  - 순수 모바일 캐주얼 학습자(단, 나중에 “뷰어/소비 전용” 앱은 확장 여지).

---

## 3. 핵심 기능 요구사항 (Functional)

### F1. 브라우저 확장 프로그램 UI

- HTML5 플레이어(YouTube, Udemy 등) 우측 또는 화면 상단에 오버레이 패널 제공.[file:12][web:2][web:3][web:7][web:9]
- 키보드 중심 인터랙션:
  - 글로벌 단축키 예시:
    - `Alt+Shift+C`: 현재 프레임 캡처 + 타임스탬프 삽입.
    - `Alt+Shift+N`: 현재 타임스탬프 섹션 시작(헤더 생성).
    - `Alt+Shift+V`: 현재 구간 전사 요청.
- 플랫폼: Chrome/Edge(Chromium), 향후 Firefox는 비차선.

### F2. 무중단 스마트 캡처 (Smart Capture)

- 영상 정지 없이 현재 프레임을 이미지로 캡처하고, 지정 Vault의 `/assets` 폴더에 저장 후 MD 본문에 링크 삽입.[file:12]
- 사양:
  - 원본 해상도(또는 사용자 설정 비율) 유지.
  - 파일명 규칙 커스터마이즈: `{{videoTitle}}_{{timestamp}}.png` 등.[file:12]
- 에셋 관리:
  - 강의별 폴더 자동 생성: `/00_Inbox/LinkNote/[강의_제목]/assets/…`.[file:12]

### F3. 양방향 타임스탬프 (Interactive Timestamps)

- MD 본문 구조:
  - `### ⏱ 12:34` (섹션 헤더) + `[12:34](https://youtu.be/ID&t=754)` 형태 링크 자동 삽입.[file:12]
- 기능:
  - 브라우저 측: 링크 클릭 시 해당 영상 탭이 열리고, 지정 타임스탬프로 점프.
  - Obsidian 측: 플러그인 또는 OS 프로토콜(`linknote://...`)을 통해 역으로 브라우저를 제어하는 확장 가능성은 v2 이후.

### F4. Obsidian 로컬 저장소 직접 연동 (Core)

- 저장 방식:
  - `File System Access API`로 사용자가 선택한 Vault 루트 및 특정 하위 폴더에 쓰기 권한 획득.[file:12]
- 폴더/파일 구조:
  - `/00_Inbox/LinkNote/[강의_제목]/index.md`
  - `/00_Inbox/LinkNote/[강의_제목]/assets/*.png`.[file:12]
- 실시간성:
  - 별도 “Export” 없이 필기/캡처가 발생하는 즉시 Vault 파일에 쓰기, Obsidian 실시간 렌더링 기준 0.5~1초 이내 반영.[file:12]

### F5. AI 학습 어시스턴트 (BYOK, Opt-in)

- BYOK:
  - OpenAI/Anthropic API Key 사용, 키는 로컬에 암호화 저장, 서버에 업로드 금지.[file:12]
- 기능:
  - 캡처 이미지 OCR + 코드 블록 인식 후, 사용자가 선택 시 본문에 삽입.[file:12]
  - 전사 텍스트 기반 핵심 요약(길이 옵션: 3줄/문단/시험 대비).[web:3][web:6][web:9][file:12]
  - FAQ/퀴즈 생성(MCQ/단답/서술형 선택).
  - YAML Frontmatter 자동 채우기:
    - `source, author, created, tags, status, difficulty, duration 등`.[file:12]

### F6. Slid 대비 확장 기능 (차별 포인트)

- **로컬 우선·SaaS 백업 옵션:**
  - 기본은 로컬 Vault, 선택적으로 WebDAV/Dropbox/OneDrive에 백업.
- **멀티 소스 지원:**
  - 브라우저 영상 + 로컬 동영상 파일(파일 선택 시 플레이어 내장)까지 단일 UX로 처리.[web:2][web:3][web:5][web:11]
- **Replay-first UX:**
  - 나중에 복습할 때 “노트 → 관련 캡처 → 관련 영상 구간” 순으로 3단 점프가 되도록, 각 섹션에 관련 캡처/클립을 자동 정렬.

---

## 4. 데이터 구조 및 템플릿

### 4.1 폴더 계층 예시

```text
[Obsidian_Vault]/
└── 00_Inbox/
    └── LinkNote/
        └── [강의_제목]/
            ├── index.md            <-- 메인 필기 노트
            └── assets/             <-- 캡처 이미지 보관소
                └── {{videoTitle}}_{{timestamp}}.png

***
source: {{video_url}}
author: {{channel_name}}
created: {{date}}
duration: {{video_duration}}
tags: [video-note, {{subject}}]
status: in-progress
difficulty: {{difficulty}}
platform: {{platform}} # youtube, udemy, internal, ...
***

# 📺 {{video_title}}

> [!abstract] AI Summary
> {{summary_content}}

## ✍️ 학습 기록

### ⏱ {{timestamp}}
- 필기 내용...


***
## 🧠 Generated Quiz (optional)
- Q1: ...
- A1: ...

5. 비기능 요구사항 (Non-Functional)
성능

캡처 입력 → Obsidian 파일 반영까지 500ms 이내(로컬 SSD 기준, 최초 권한 획득 제외).[file:12]

단일 강의 노트 용량 50MB까지 성능 저하 없이 편집 가능.

신뢰성

브라우저 재시작 시 폴더 권한 재요청 UX 최소화, 허용되지 않은 경우에도 데이터 손실 없이 대기열 처리.[file:12]

보안/프라이버시

영상 URL/메타데이터/전사 텍스트는 로컬 저장이 기본, 서버로 전송 X.

AI 호출 시에도 식별 가능 개인정보는 마스킹 옵션 제공.[file:12]

호환성

Obsidian Desktop 1.5+ 지원, 모바일 앱은 “보기 전용” 시나리오에서만 고려(추가 설치 없이 읽기 가능해야 함).

6. 성공 지표 (KPI)
Setup Completion: 최초 설치 후 Obsidian Vault 연동 완료율 80% 이상.[file:12]

Learning Efficiency: 사용자가 자기 보고 설문에서 “영상 노트 정리 시간 70% 이상 단축” 응답 60% 이상.[file:12]

Retention: 첫 연동 성공 유저 중 7일 이내 재사용 비율 40% 이상, 30일 재사용 비율 25% 이상.[file:12]

Stability: 파일 저장·이미지 링크 깨짐 발생률 0.1% 미만.[file:12]

7. 의도적 제외 (Non-Goals)
팀 공유/실시간 협업(동시 편집).

자체 마크다운 뷰어, 자체 지식 그래프 UI (Obsidian에 위임).[file:12]

순수 클라우드-only 워크스페이스 (로컬 없는 계정 기반 서비

***

## TDD.md

```markdown
# [TDD] LinkNote 2.0: 테스트 계획서

## 1. 테스트 범위

- 브라우저 확장 기능 (캡처, 타임스탬프, 단축키).
- 로컬 파일 쓰기 및 Obsidian 연동.
- AI 어시스턴트 기능(BYOK).
- 오류/예외 상황(권한 거부, 오프라인 등).

---

## 2. 테스트 환경

- OS: Windows 11, macOS 최신 2버전.
- 브라우저: Chrome Stable, Edge Stable.
- Obsidian Desktop: 1.5+ (기본 플러그인 세트 기준).
- 네트워크: 정상(>50Mbps), 느린 네트워크(3~5Mbps), 오프라인 모드.

---

## 3. 기능별 테스트 케이스

### 3.1 브라우저 확장 UI & 단축키

**TC-01: 확장 사이드바 로드**
- Given: YouTube 영상 페이지 로드.
- When: 확장 아이콘 클릭.
- Then:
  - 영상 우측/상단에 패널이 나타난다.
  - 현재 영상 제목, 채널명, 재생 시간 정보가 패널 헤더에 노출된다.[web:2][web:3][web:9]

**TC-02: 글로벌 단축키 캡처(Alt+Shift+C)**
- Given: 영상이 재생 중이고 Vault 경로가 설정되어 있음.
- When: `Alt+Shift+C` 입력.
- Then:
  - 영상 재생은 멈추지 않는다.
  - 현재 프레임 이미지가 지정 `assets` 폴더에 저장된다.
  - `index.md`에 해당 이미지 링크 + 타임스탬프 섹션이 추가된다.[file:12]

**TC-03: 단축키 충돌 시 대체 키 안내**
- Given: OS 또는 다른 앱이 동일 단축키를 사용 중.
- When: 단축키 등록 실패.
- Then:
  - “단축키 충돌 감지” 안내와 함께 대체 키 설정 UI 표시.

---

### 3.2 무중단 스마트 캡처

**TC-04: 연속 캡처 시 파일명/타임스탬프**
- Given: 동일 영상에서 3회 연속 캡처.
- When: 각 시점에서 캡처 실행.
- Then:
  - `{{videoTitle}}_{{timestamp}}.png` 패턴으로 서로 다른 파일명 생성.
  - 각 캡처의 타임스탬프가 MD 내에서 올바른 값으로 기록.[file:12]

**TC-05: 고해상도 영상 캡처 성능**
- Given: 4K YouTube 영상.
- When: 캡처 10회 연속 수행.
- Then:
  - 캡처마다 UI 응답 지연이 500ms를 넘지 않는다(측정 로그 확인).[file:12]

---

### 3.3 양방향 타임스탬프

**TC-06: 타임스탬프 링크 생성**
- Given: 10:24 지점에서 노트 섹션 생성.
- When: 캡처 또는 “섹션 시작” 버튼 클릭.
- Then:
  - `### ⏱ 10:24` 헤더와 `[10:24](URL&t=624)` 링크가 MD에 삽입된다.[file:12]

**TC-07: 링크 클릭 시 영상 점프**
- Given: Obsidian에서 `index.md` 열려 있음.
- When: `[10:24](https://youtu.be/...)` 링크 클릭.
- Then:
  - 브라우저에서 해당 영상 탭이 열리고 10:24 지점으로 재생 위치가 이동한다.

---

### 3.4 Obsidian 로컬 저장소 연동

**TC-08: 최초 권한 획득**
- Given: Vault 경로가 아직 설정되지 않음.
- When: 첫 캡처 또는 첫 필기 저장 시도.
- Then:
  - `File System Access API` 폴더 선택 다이얼로그 표시.
  - 사용자가 Vault 루트를 선택하면, 이후 동일 경로에 파일이 생성된다.[file:12]

**TC-09: Vault 선택 취소 시 동작**
- Given: 권한 요청 다이얼로그에서 취소 선택.
- When: 다시 캡처 시도.
- Then:
  - “Vault 경로가 설정되지 않았습니다” 경고와 함께 다시 설정 유도.
  - 기존 데이터 손실 없이 UI만 대기 상태 유지.

**TC-10: Obsidian 렌더링 실시간성**
- Given: Obsidian에서 `index.md` 파일 열려 있음.
- When: 브라우저에서 캡처 수행.
- Then:
  - 1초 이내 Obsidian 화면에서 새 이미지 링크가 표시된다(수동 새로고침 없이 가능하면 베스트).[file:12]

---

### 3.5 AI 학습 어시스턴트 (BYOK)

**TC-11: API Key 등록 & 검증**
- Given: 설정 화면에서 OpenAI Key 입력.
- When: “테스트 호출” 실행.
- Then:
  - 유효 키인 경우 “연결 성공” 메시지.
  - 무효 키인 경우 적절한 오류 메시지(429/401 등 분기별 표시).[file:12]

**TC-12: 캡처 OCR 추출**
- Given: 텍스트/코드가 포함된 캡처 이미지 존재.
- When: 해당 캡처 옆 “텍스트 추출” 버튼 클릭.
- Then:
  - 추출된 텍스트가 미리보기로 표시되고, “노트에 삽입” 선택 시 MD 본문에 코드 블록/텍스트 블록으로 삽입된다.[file:12]

**TC-13: 강의 요약 생성**
- Given: 20분 분량 전사 텍스트가 노트에 존재.
- When: “3줄 요약 생성” 실행.
- Then:
  - 상단 Summary 블록에 3줄 이내 요약이 생성된다.
  - Free 모드/월간 사용량 제한이 있는 경우, 제한 초과 시 적절한 안내 후 호출 차단.[web:3][web:4][web:6][web:9]

**TC-14: 개인정보 마스킹 옵션**
- Given: 전사 내 이메일/전화번호 등 패턴 존재.
- When: “AI 호출 전 개인정보 마스킹” 옵션 ON 상태에서 요약 요청.
- Then:
  - 외부 API로 전송된 텍스트에서는 해당 패턴이 마스킹된 상태(`***@***` 등)로 전송된다.[file:12]

---

### 3.6 데이터 구조 및 템플릿

**TC-15: 폴더 구조 자동 생성**
- Given: `[강의_제목]` 노트가 아직 없음.
- When: 첫 캡처 수행.
- Then:
  - `/00_Inbox/LinkNote/[강의_제목]/index.md` 파일과 `assets/` 폴더가 자동 생성된다.[file:12]

**TC-16: 템플릿 필드 채우기**
- Given: 영상 메타데이터/전사/요약이 존재.
- When: 노트가 처음 생성될 때.
- Then:
  - Frontmatter에 `source, author, created, duration, platform, tags` 필드가 올바르게 채워진다.[file:12]

---

## 4. 비기능 테스트

### 4.1 성능

**TC-NF-01: 대용량 노트 성능**
- Given: `index.md` 크기 5MB, 이미지 200장 이상 포함.
- When: 페이지 로딩 및 추가 캡처 수행.
- Then:
  - 캡처 후 파일 쓰기까지 800ms 이내.
  - UI 프리즈/스크롤 렉 현상 없는 수준 유지.[file:12]

### 4.2 안정성

**TC-NF-02: 네트워크 오프라인 상태**
- Given: 인터넷 연결 끊김.
- When: 캡처 및 로컬 저장, AI 요약 시도.
- Then:
  - 캡처/로컬 저장은 정상 동작.
  - AI 호출은 실패하고 “오프라인 상태” 안내 표시, 재시도 버튼 제공.

### 4.3 보안

**TC-NF-03: 외부 전송 데이터 검증**
- Given: 디버그 모드에서 AI 호출 Payload 로깅.
- When: 요약/QA 기능 사용.
- Then:
  - 사용자의 로컬 경로, Vault 이름 등 민감 데이터가 Payload에 포함되지 않는다.[file:12]

---

## 5. 회귀 테스트 시나리오

- Obsidian 버전 업그레이드 후:
  - Vault 구조 변경 없이 정상 연결되는지.
  - 플러그인 충돌(예: 다른 파일 워처 플러그인) 발생 여부.
- 브라우저/OS 업데이트 후:
  - File System Access API 권한 정책 변경 시 흐름 점검.
  - 단축키 권한 관련 경고/제한 사항 발생 여부.

---

## 6. 향후 확장 고려 (Out of Scope for v1, 참고용)

- Obsidian 플러그인 형태로 일부 기능 이동(예: Obsidian에서 영상 열기/타임스탬프 점프).
- Logseq/Heptabase 연동용 Export 포맷 추가.
- “학습 세션 타임라인 뷰” (영상/노트/퀴즈를 시간축 기반으로 시각화).