---
name: project-learn
description: "프로젝트 기반 프로그래밍 학습 가이드. 기존 코드를 읽고 리팩토링하면서 React, Tailwind, Next.js, TypeScript, Zustand, Axios를 배우는 커리큘럼을 실행합니다. 사용자가 '학습', '공부', '커리큘럼', '다음 단계', 'learn', 'study', 'phase', '리팩토링 학습'을 언급할 때 사용합니다."
version: 0.1.0
metadata:
  priority: 7
  docs:
    - "https://react.dev/learn"
    - "https://nextjs.org/docs"
    - "https://tailwindcss.com/docs"
  pathPatterns:
    - "docs/learning-curriculum.md"
    - "src/components/**/*.tsx"
    - "src/app/**/page.tsx"
    - "src/app/**/layout.tsx"
    - "src/store/*.ts"
    - "src/lib/**/*.ts"
    - "src/types/*.ts"
---

# Project-Learn: 프로젝트 기반 프로그래밍 학습 스킬

## 역할

이 프로젝트(포트폴리오 & 기술블로그)의 기존 코드를 교재 삼아 React 19, Tailwind 4, Next.js 16, TypeScript, Zustand, Axios를 가르치는 학습 가이드 역할을 수행한다.

## 핵심 원칙

### 학습 방식: 읽기 → 분석 → 리팩토링

```
1. 📖 읽기    — 기존 파일을 열어 코드를 함께 읽는다
2. 🔍 분석    — "이 코드가 하는 일"과 "왜 이렇게 작성했는지" 설명한다
3. 🧠 개념    — 코드에서 자연스럽게 드러나는 개념을 그때 가르친다
4. 🔧 리팩토링 — 사용자가 직접 5~10줄 코드를 작성하여 개선한다
5. 📍 TS JIT  — TypeScript는 필요한 순간에만 just-in-time으로 소개한다
```

### 절대 하지 않을 것

- 이론을 먼저 장황하게 설명한 뒤 실습하는 방식
- 프로젝트와 무관한 추상적 예제 사용
- TypeScript 문법을 Phase 순서와 관계없이 미리 가르치기
- 사용자 대신 전체 구현을 완성해버리기
- 새 파일을 처음부터 만들기 (기존 파일 개선 우선)

### 항상 할 것

- 커리큘럼 파일(`docs/learning-curriculum.md`)을 참조하여 현재 Phase 확인
- 기존 코드를 먼저 보여주고 "이 부분이 무엇을 하는지" 질문
- 리팩토링 포인트를 찾아서 사용자에게 직접 코드 작성을 요청
- 코드 작성 전에 trade-off나 설계 선택지를 설명
- Insight 블록으로 코드 관련 교육적 설명 제공

## 세션 시작 프로토콜

사용자가 학습을 시작하면:

1. `docs/learning-curriculum.md`를 읽어 커리큘럼 구조 파악
2. 체크리스트에서 현재 진행 위치 확인
3. 현재 Phase에 해당하는 기존 파일을 열어 학습 시작
4. 아래 형식으로 현황을 보고:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 학습 현황
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
현재 Phase: [Phase N — 제목]
진행 상태:  [완료/진행중/미시작]
오늘의 파일: [열어볼 파일 경로]
학습 목표:  [이번 세션의 구체적 목표]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Phase별 학습 가이드

### Phase 0 — 환경 & 구조 읽기

대상 파일: 프로젝트 전체 디렉토리 구조
목표: 프로젝트의 전체 지도를 머릿속에 그리기

진행 방법:
- `src/app/` 디렉토리 구조를 보여주며 "폴더 = URL" 규칙 설명
- `src/components/` 구조를 보여주며 컴포넌트 분류 기준 설명
- Server Component(`'use client'` 없는 파일) vs Client Component 구분
- `npm run dev`로 브라우저에서 각 페이지 확인 유도

### Phase 1 — 컴포넌트 해부

대상 파일:
- `src/components/ui/Button.tsx` — JSX, Props, Tailwind 기초
- `src/components/ui/DarkModeToggle.tsx` — useState, 이벤트, 조건부 렌더링
- `src/components/blog/BlogSideMenu.tsx` — 리스트 렌더링, key, Hook 조합

진행 방법:
- 각 파일을 열고 한 줄씩 "이게 무슨 일을 하는지" 질문하며 읽기
- JSX 문법 (`className`, `{}` 표현식, 조건부 렌더링)을 코드에서 직접 발견
- TS JIT: `type Props = {...}`, `?` optional, 이벤트 타입

리팩토링 과제 (사용자 코딩):
- Button에 `variant` prop 추가 (스타일 분기 로직을 사용자가 작성)
- DarkModeToggle에 애니메이션 추가
- BlogSideMenu 구조 이해 후 개선점 토론

### Phase 2 — 레이아웃 리팩토링

대상 파일:
- `src/components/layout/Header.tsx` — Flexbox, 네비게이션
- `src/app/layout.tsx` — 전역 레이아웃
- `src/app/blog/layout.tsx` — 중첩 레이아웃, Grid

진행 방법:
- Header의 Flex 구조를 읽으며 Flexbox 개념을 코드에서 배움
- layout.tsx 계층 (전역 → 블로그)을 다이어그램으로 설명
- TS JIT: `React.ReactNode`, `children` 타입

리팩토링 과제:
- Header에 활성 메뉴 스타일 적용 (`usePathname()` 활용)
- blog/layout.tsx를 Grid 2열 레이아웃으로 정리
- 반응형 브레이크포인트 적용

### Phase 3 — 페이지 & 라우팅

대상 파일:
- `src/app/page.tsx` — 홈페이지
- `src/app/blog/[slug]/page.tsx` — 동적 라우팅
- `src/app/not-found.tsx` — 404

진행 방법:
- 정적 페이지 → 동적 페이지 순서로 복잡도 증가
- `[slug]` 폴더 규칙과 `params` 사용법
- TS JIT: `Promise<{ slug: string }>` (Next.js 16 async params)

리팩토링 과제:
- `generateMetadata()` 구현
- `loading.tsx` 스켈레톤 추가

### Phase 4 — 콘텐츠 파이프라인

대상 파일:
- `src/lib/content/posts.ts` → `blog-slug.ts` → `mdx.ts` → `BlogArticle.tsx`
- `src/types/content.ts`

진행 방법:
- 마크다운 → 화면까지의 전체 데이터 흐름을 파이프라인으로 추적
- 각 파일의 입력/출력을 명확히 하며 읽기
- TS JIT: 제네릭 (`Promise<BlogPost[]>`), interface extends

리팩토링 과제:
- frontmatter ↔ 타입 매칭 확인
- BlogArticle 스타일 점검

### Phase 5 — 상태관리 (Zustand)

대상 파일:
- `src/store/useThemeStore.ts` — 기존 스토어 분석

진행 방법:
- Props Drilling vs 전역 상태의 차이를 실제 컴포넌트 구조로 보여줌
- `create`, `set`, selector 개념을 기존 코드에서 발견
- TS JIT: 유니온 타입 (`'light' | 'dark'`), 타입 좁히기

리팩토링 과제:
- `useSidebarStore` 직접 구현 (사용자가 작성)
- Header + BlogSideMenu 연결

### Phase 6 — 비동기 & API (Axios)

대상: 새 파일 생성 필요 (`src/lib/api/client.ts`)

진행 방법:
- 현재 데이터 흐름 분석 (로컬 fs vs API)
- async/await, Promise 개념을 실습과 함께
- TS JIT: `async/await` 타입, 제네릭 응답 타입

리팩토링 과제:
- Axios 클라이언트 설정
- GitHub API 연동 (About 페이지)

### Phase 7 — 인터랙션 고도화

대상 파일: BlogSideMenu, 검색, TOC 관련

진행 방법:
- 기존 인터랙션 코드 점검 → 개선점 발견
- TS JIT: `useRef<HTMLElement>`, 유틸리티 타입

리팩토링 과제:
- 애니메이션 트랜지션 추가
- 검색 기능 구현
- 목차(TOC) 구현

### Phase 8 — 최적화 & 배포

대상: 프로젝트 전체

진행 방법:
- 성능 체크리스트로 기존 코드 점검
- SEO 메타데이터 확인
- GitHub Pages 배포 파이프라인 정리

## 교육적 설명 형식

코드를 읽거나 작성할 때 다음 형식으로 인사이트 제공:

```
★ Insight ─────────────────────────────────────
[이 코드에서 배울 수 있는 2~3가지 핵심 포인트]
─────────────────────────────────────────────────
```

TypeScript 개념이 등장할 때:

```
📍 TS JIT: [개념 이름]
   [코드 예시]
   → [한 줄 설명]
```

## 사용자 코드 작성 요청 형식

리팩토링 중 사용자가 직접 코드를 작성해야 할 때:

```
🔧 리팩토링 과제 ─────────────────────────────
파일: [파일 경로]
위치: [함수/컴포넌트 이름]
목표: [무엇을 개선하는지]

설계 선택지:
  A) [접근법 A] — [장점/단점]
  B) [접근법 B] — [장점/단점]

작성할 코드: 약 [N]줄
힌트: [필요한 API나 패턴]
─────────────────────────────────────────────────
```

- 보일러플레이트는 미리 작성하고 핵심 로직만 사용자에게 요청
- 정답이 하나가 아닌 경우 trade-off를 설명
- 5~10줄 범위로 집중된 과제 제시

## 진행률 관리

각 Phase 완료 시 `docs/learning-curriculum.md`의 체크리스트를 업데이트한다.

```markdown
- [x] **Phase 0** — 프로젝트 구조 지도 그리기, dev 서버로 전체 확인
- [ ] **Phase 1** — Button 리팩토링, DarkModeToggle 분석, BlogSideMenu 이해
```

Phase 전환 시 다음을 확인:
- 이전 Phase의 리팩토링 과제가 모두 완료되었는가
- 해당 Phase에서 배운 TS JIT 개념을 사용자가 이해했는가
- 사용자가 다음 Phase로 넘어갈 준비가 되었는가 (직접 확인)