---
name: study-from-web
description: >
  웹 문서를 체계적으로 분석하고 단계별 학습을 돕는 스킬.
  URL에서 시작하여 재귀적으로 문서를 탐색하고, 기초-중급-고급 단계별 학습, 퀴즈, 진도 추적을 제공한다.
  트리거: 사용자가 URL을 제공하며 "공부", "학습", "배우고 싶어", "study", "learn" 등을 언급할 때.
  또는 이전 학습 세션을 이어서 하고 싶을 때 ("이어서", "계속", "resume", "continue").
---

# Study From Web

## 개요

웹 문서(공식 문서, 튜토리얼 등)를 체계적으로 탐색하여 **학습 로드맵**을 생성하고,
사용자가 기초부터 점진적으로 깊이 있는 이해를 할 수 있도록 돕는다.

**핵심 원칙:**
- 한 번에 하나의 섹션만 학습 (인지 과부하 방지)
- 기초 → 중급 → 고급 순서로 점진적 확장
- 매 섹션 완료 후 퀴즈로 이해도 확인
- 세션 저장/복원으로 끊김 없는 학습

## 워크플로우

```
[URL 입력] → Phase 1: 문서 탐색 → Phase 2: 학습 개요 생성
  → Phase 3: 단계별 학습 → Phase 4: 퀴즈 → Phase 5: 세션 저장
  → (반복: Phase 3~5)
```

---

## Phase 1: 문서 탐색

> 상세 전략: `references/exploration-strategy.md` 참조

### 1-1. 시작 URL 탐색

사용자가 제공한 URL을 WebFetch로 가져오고, 다음을 추출한다:

- **문서 제목과 설명**
- **네비게이션 구조** (사이드바, TOC 등)
- **학습 관련 링크** (Getting Started, Tutorial, Concepts, API Reference 등)

```
WebFetch 프롬프트 예시:
"이 페이지의 다음 정보를 JSON으로 추출해주세요:
1. 문서 제목과 주제 설명 (title, description)
2. 네비게이션/사이드바의 주요 링크 목록 (links: [{title, url, category}])
3. 카테고리는: getting-started, tutorial, concepts, api-reference, guide, example, other
4. 링크는 절대 URL로 변환"
```

### 1-2. 하위 문서 탐색

추출된 링크를 우선순위에 따라 탐색한다:

| 우선순위 | 카테고리 | 예시 |
|---------|---------|------|
| 1 | Getting Started | Quick Start, Installation |
| 2 | Tutorial | Step-by-step 가이드 |
| 3 | Concepts | 핵심 개념, Architecture |
| 4 | Guide | How-to, Best Practices |
| 5 | API Reference | API 문서 |
| 6 | Example | 코드 예시 |

**제한 사항:**
- 기본 탐색 깊이: 1 (시작 URL에서 직접 링크된 페이지)
- 최대 탐색 깊이: 2 (사용자 요청 시)
- 최대 페이지 수: 20
- 탐색 실패 시 해당 페이지 건너뛰기, 30% 이상 실패 시 사용자에게 알림

### 1-3. 문서 구조 분석

탐색된 문서들을 종합하여 다음을 파악한다:

- 전체 주제와 범위
- 선수 지식 관계 (A를 알아야 B를 이해)
- 난이도 추정 (URL 구조, 내용 복잡도 기반)
- 학습 최적 순서

---

## Phase 2: 학습 개요 생성

탐색 결과를 기반으로 **학습 로드맵**을 생성하여 사용자에게 제시한다.

### 로드맵 형식

```markdown
# 📚 [주제] 학습 로드맵

## 개요
[1~2문장으로 무엇을 배울 수 있는지 설명]

## 학습 구조

### 🟢 기초 (n개 섹션)
1. [섹션명] - [한 줄 설명]
2. [섹션명] - [한 줄 설명]
...

### 🟡 중급 (n개 섹션)
3. [섹션명] - [한 줄 설명]
4. [섹션명] - [한 줄 설명]
...

### 🔴 고급 (n개 섹션)
5. [섹션명] - [한 줄 설명]
6. [섹션명] - [한 줄 설명]
...

## 예상 소요
- 기초: ~n개 섹션
- 중급: ~n개 섹션
- 고급: ~n개 섹션

> 어디서부터 시작할까요? (기본: 기초 1번부터)
```

### 로드맵 원칙

- 기초/중급/고급 비율은 대략 3:4:3
- 각 섹션은 독립적으로 이해 가능하되, 순서대로 학습하면 최적
- 섹션명은 한국어로, 영문 기술 용어는 병기 (예: "상태 관리 (State Management)")

---

## Phase 3: 단계별 학습

> 상세 패턴: `references/learning-patterns.md` 참조

사용자가 학습할 섹션을 선택하면 (또는 순서대로 진행하면) 해당 섹션의 내용을 가르친다.

### 학습 콘텐츠 생성 규칙

1. **원문서 내용을 기반으로** 설명한다 (추측하지 않음)
2. **한국어로 작성**하되, 기술 용어는 원어 병기
3. **짧은 문장** 위주로 작성 (한 문장에 하나의 개념)
4. **비유와 예시** 를 적극 활용
5. **코드 예시**가 있으면 반드시 포함하고, 한국어 주석 추가

### 난이도별 구성

#### 🟢 기초 섹션
```
1. 정의 - 이것이 무엇인지 한 문장으로
2. 비유 - 일상적인 비유로 핵심 개념 설명
3. 핵심 용어 - 알아야 할 용어 정리 (표)
4. 기본 사용법 - 가장 간단한 예시 코드
5. 주의사항 - 초보자가 자주 하는 실수
```

#### 🟡 중급 섹션
```
1. 기초 복습 - 선수 지식 한 줄 요약
2. 심화 개념 - 더 깊은 동작 원리
3. 실용 패턴 - 실제 프로젝트에서 쓰는 패턴
4. 개념 비교 - 유사 개념과의 차이점 (표)
5. 실습 - 직접 해볼 수 있는 작은 과제
```

#### 🔴 고급 섹션
```
1. 배경 지식 - 이 개념이 왜 필요한지
2. 문제 정의 - 해결하려는 문제
3. 해결 방법 - 상세한 구현 방법
4. 성능 고려사항 - 성능에 미치는 영향
5. 안티패턴 - 피해야 할 패턴
6. 실전 사례 - 실제 프로젝트 적용 예시
```

### 섹션 완료 후

섹션 설명이 끝나면 다음 선택지를 제시한다:

```
---
✅ 섹션 [N] 완료!

다음 중 선택해주세요:
1. 📝 퀴즈 풀기 - 이해도 확인
2. ➡️ 다음 섹션으로 진행
3. 🔄 이 섹션 다시 설명
4. 📋 전체 진도 확인
5. 💾 세션 저장하고 나중에 계속
```

---

## Phase 4: 퀴즈

> 상세 패턴: `references/quiz-patterns.md` 참조

### 퀴즈 트리거

다음 키워드로 퀴즈를 요청할 수 있다:
- "퀴즈", "quiz", "문제", "테스트", "확인"
- 섹션 완료 후 자동 제안

### 퀴즈 구성

- 한 세트에 **3~5문제**
- 난이도 배분은 현재 학습 단계에 따라 조절:
  - 기초 학습 중: ⭐ 60%, ⭐⭐ 40%
  - 중급 학습 중: ⭐ 20%, ⭐⭐ 60%, ⭐⭐⭐ 20%
  - 고급 학습 중: ⭐⭐ 40%, ⭐⭐⭐ 60%

### 퀴즈 유형

| 유형 | 난이도 | 예시 |
|------|--------|------|
| 개념 확인 (정의 선택, T/F) | ⭐ | "다음 중 올바른 설명은?" |
| 코드 분석 (출력 예측) | ⭐⭐ | "이 코드의 출력은?" |
| 버그 찾기 | ⭐⭐ | "이 코드의 문제점은?" |
| 기능 구현 | ⭐⭐⭐ | "다음 기능을 구현하세요" |
| 최적화 | ⭐⭐⭐ | "이 코드를 개선하세요" |

### 피드백

- **정답**: ✅ 간단한 칭찬 + 왜 맞는지 한 줄 설명
- **오답**: ❌ 격려 + 올바른 답 + 왜 틀렸는지 설명
- **힌트 제공** ("힌트" 요청 시):
  - ⭐ 문제: 직접적 힌트
  - ⭐⭐ 문제: 방향성 제시
  - ⭐⭐⭐ 문제: 접근 구조만 알려줌

### 퀴즈 결과

```
📊 퀴즈 결과: 3/5 정답 (60%)

✅ 문제 1, 3, 4
❌ 문제 2 - [약한 부분 요약]
❌ 문제 5 - [약한 부분 요약]

💡 추천: 문제 2, 5와 관련된 내용을 복습하면 좋겠습니다.
```

---

## Phase 5: 세션 저장/복원

### 저장 위치

`~/.claude/study-sessions/` 디렉토리에 JSON 형식으로 저장한다.

- 파일명: `{topic-slug}_{sessionId}.json`
- 예시: `react-hooks_abc123.json`
- 디렉토리가 없으면 자동 생성

### 저장 형식

> 템플릿: `assets/session-template.json` 참조

### 저장 트리거

- 사용자가 "저장", "save" 요청 시
- 세션 종료 시 자동 저장 제안

### 복원 트리거

- 사용자가 "이어서", "계속", "resume" 요청 시
- `~/.claude/study-sessions/` 에서 세션 파일 목록을 보여주고 선택하게 한다

### 복원 시 동작

1. 세션 파일 로드
2. 진도 상태 표시
3. 마지막 학습 위치에서 이어서 진행
4. 이전 퀴즈 결과를 참고하여 약한 부분 우선 복습 제안

---

## 사용자 명령어

학습 중 다음 명령어를 사용할 수 있다:

| 명령어 | 설명 |
|--------|------|
| **개요** / overview | 전체 학습 로드맵 다시 보기 |
| **진도** / progress | 현재 진행 상황 확인 |
| **퀴즈** / quiz | 현재 섹션 퀴즈 풀기 |
| **복습** / review | 이전 섹션 다시 보기 |
| **저장** / save | 현재 세션 저장 |
| **다음** / next | 다음 섹션으로 진행 |
| **힌트** / hint | 퀴즈 힌트 요청 |
| **이어서** / resume | 저장된 세션 이어하기 |
| **건너뛰기** / skip | 현재 섹션 건너뛰기 |

---

## 품질 기준

### 한국어 작성 규칙

- **기술 용어 병기**: "상태 관리 (State Management)", "훅 (Hook)"
- **짧은 문장**: 한 문장에 하나의 개념만
- **비유 활용**: 추상적 개념은 일상 비유로 먼저 설명
- **존댓말 사용**: "~합니다", "~입니다" 체

### 콘텐츠 품질

- 원문서의 정보를 기반으로 설명 (환각 방지)
- 코드 예시에는 반드시 한국어 주석 포함
- 한 줄 최대 150자
- 트레일링 콤마 적용 (코드)

### 학습 경험

- 한 번에 너무 많은 정보를 주지 않음
- 매 섹션은 5~10분 분량으로 구성
- 이전 학습 내용과의 연결고리 제공
- 실패해도 좌절하지 않도록 격려하는 톤