공개 문서
docs/structure-and-design-analysis.md
아래는 docs/structure-and-design-analysis.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Skoolchef Tutorial — 구조·설계 심화 분석 및 개선 제안
> 분석일: 2026-03-10
> 대상: `projects/skoolchef-tutorial` 전체
---
## 1. 현재 구조 요약
### 1.1 기술 스택
| 영역 | 기술 |
|------|------|
| 프레임워크 | Next.js 15 (App Router) |
| 스타일 | Tailwind CSS 3.4 + @tailwindcss/typography |
| 콘텐츠 | MDX (next-mdx-remote/rsc), gray-matter |
| 폰트 | Noto Sans KR (next/font) |
| 배포 | Vercel (가정, NEXT_PUBLIC_SITE_URL) |
### 1.2 디렉터리 구조
```
skoolchef-tutorial/
├── app/ # Next.js App Router
│ ├── layout.tsx # 루트 레이아웃, 메타, Navigation
│ ├── page.tsx # 홈 (히어로 + 도구 소개 + 커리큘럼)
│ ├── courses/
│ │ ├── page.tsx # 커리큘럼 목록
│ │ └── [slug]/page.tsx # 챕터 상세 (MDX 렌더)
│ └── globals.css
├── components/
│ ├── Navigation.tsx # 상단 고정 네비 (로고, 커리큘럼 링크, 모바일 메뉴)
│ └── CourseNav.tsx # 챕터 상세 좌측 사이드바
├── lib/
│ └── mdx.ts # 코스 메타·목록·모듈 그룹 (fs 동기 읽기)
├── content/
│ ├── curriculum-v2-plan.md # v2 기획안 (Module 0~4, 19챕터)
│ ├── image-mapping.json # Notion 이미지 → 로컬 매핑
│ └── courses/ # 17챕터 MDX (00-intro ~ 16-integrated-workflow)
├── public/images/notion/ # Notion 추출 이미지 01~13
├── scripts/
│ ├── extract-notion.mjs # Notion API → MDX 추출
│ ├── check-notion.mjs # Notion 연동 진단
│ ├── split-mdx.mjs # 단일 MDX → 챕터 분리 (라인 번호 기반)
│ └── download-images.mjs # Notion S3 이미지 → 로컬 + URL 교체
├── .env.example
├── package.json
├── next.config.ts
└── tailwind.config.ts
```
### 1.3 데이터 흐름
- **콘텐츠**: `content/courses/*.mdx` → `lib/mdx.ts`에서 frontmatter 파싱 및 목록 생성
- **모듈 구분**: `order` 숫자로 구간 매핑 (0=기초, 1–5=Cursor, 6–9=Claude Code, 10–12=Gemini, 13+=실전)
- **Notion 파이프라인**: `extract-notion` → (선택) `download-images` → (선택) `split-mdx`로 챕터 분리
---
## 2. 강점
- **명확한 앱 구조**: 홈 / 커리큘럼 목록 / 챕터 상세 3단계, 브레드크럼·이전·다음 네비 제공
- **보안·품질 의식**: `lib/mdx.ts`의 path traversal 방지, frontmatter 런타임 검증, 동적 클래스는 safelist로 보완
- **접근성·SEO**: `lang="ko"`, 메타·OG·viewport, aria 레이블
- **v2 기획 정리**: `curriculum-v2-plan.md`로 Module 0~4, 도구 비교표, Phase 1~4 우선순위 명시
- **Notion 연동**: 통합 추출·이미지 다운로드·매핑 JSON으로 편집–배포 분리 가능
---
## 3. 개선사항 및 추천 (우선순위별)
### 3.1 높음 — 구조·일관성
#### (1) 모듈 색상/테마 단일화
- **현상**: 모듈별 색이 `app/page.tsx`, `app/courses/page.tsx`, `components/CourseNav.tsx`에 각각 하드코딩되어 있고, **Module 2**가 홈/커리큘럼에서는 orange, CourseNav에서는 purple로 불일치
- **추천**: `lib/theme.ts` 또는 `constants/module-theme.ts`에 `moduleAccents` / `moduleColors`를 한 곳만 정의하고, 세 곳에서 import해 사용
- **효과**: 모듈 추가·색 변경 시 한 파일만 수정
#### (2) 콘텐츠 폴더 구조와 기획안 정렬
- **현상**: 기획안은 `module-1-cursor/`, `module-2-claude-code/` 등 **서브폴더** 구조를 제안하지만, 현재는 `content/courses/` 밑에 **플랫 파일**만 있음 (00-intro.mdx ~ 13-integrated-workflow.mdx)
- **추천**:
- **단기**: 현재처럼 플랫 유지해도 되며, `lib/mdx.ts`의 `getModuleInfo(order)`와 실제 챕터 수가 v2 기획(19챕터)과 다르다는 점만 문서화 → **적용 완료**: `lib/mdx.ts` 상단 주석 + `docs/content-structure.md`
- **중기**: v2 Phase 2 이후 챕터가 늘어나면 `content/courses/module-0/`, `module-1/` 등으로 이전하고, `getAllCourses()`에서 `fs.readdirSync` 재귀 또는 glob으로 수집하도록 변경
#### (3) `content/courses/index.mdx` 동기화
- **현상**: `index.mdx`는 “5단계 커리큘럼”, 01~05만 링크로 나열. 실제는 00~12 총 13챕터
- **추천**: 목차를 현재 챕터 목록과 맞추거나, `getAllCourses()` 결과로 index.mdx를 **생성**하는 스크립트를 두어 수동 편집 제거 → **적용 완료**: `scripts/generate-index-mdx.mjs` 추가, `pnpm generate-index-mdx`로 목차 자동 생성
---
### 3.2 높음 — 코드·성능
#### (4) MDX 이미지 컴포넌트
- **현상**: `<MDXRemote source={course.content} />`에 `components`를 넘기지 않아, MDX 내 ``이 일반 `<img>`로 렌더됨
- **추천**: `components={{ img: NextImageWrapper }}` 형태로 `next/image` 기반 컴포넌트 전달 (width/height 또는 fill + sizes). 로컬 `/images/notion/` 경로는 `sizes`로 반응형 지정
- **효과**: LCP 개선, 일관된 이미지 최적화 → **적용 완료**: `components/MdxImage.tsx` 추가, 챕터 페이지에서 `components={{ img: MdxImage }}` 전달
#### (5) `lib/mdx.ts` 읽기 방식
- **현상**: `getAllCourses()`가 매 요청마다 `fs.readdirSync` + `fs.readFileSync`로 모든 MDX를 읽음
- **추천**:
- 개발 시에는 현재처럼 유지해도 무방
- 필요 시 `getAllCourses()`/`getCoursesByModule()` 결과를 **캐시** (예: `unstable_cache` 또는 빌드 시 한 번만 읽어 JSON으로 저장 후 import)
#### (6) Tailwind content 경로에 content 포함
- **현상**: `tailwind.config.ts`의 `content`에 `./content/**/*.mdx`가 없음. MDX 안에서 사용하는 Tailwind 클래스는 JIT에 포함되지 않음
- **추천**: MDX 본문에서 Tailwind를 쓰지 않는다면 유지; 쓰면 `content: [ ..., "./content/**/*.mdx" ]` 추가 → **적용 완료**: `content` 배열에 `"./content/**/*.mdx"` 추가
---
### 3.3 중간 — 운영·문서
#### (7) 프로젝트 루트 `CLAUDE.md` 추가
- **현상**: 워크스페이스 규칙에서 “프로젝트별 CLAUDE.md”를 참조하도록 되어 있으나, skoolchef-tutorial 루트에는 없음
- **추천**: `projects/skoolchef-tutorial/CLAUDE.md`에 다음을 명시
- 목적(스쿨용 AI 바이브코딩 커리큘럼 사이트)
- 문서/콘텐츠 구조 (content/courses, curriculum-v2-plan, scripts)
- Notion → MDX 파이프라인 요약
- PDCA 폴더 사용 여부(사용 안 함 권장)
→ **적용 완료**: `projects/skoolchef-tutorial/CLAUDE.md` 생성
#### (8) 스크립트 입력 경로 통일
- **현상**: `download-images.mjs`는 `./content/courses/index.mdx`만 대상. 현재는 챕터가 개별 파일이라 index만 수정됨. `extract-notion`은 PAGE_ID 기준으로 여러 페이지 추출
- **추천**:
- 이미지 다운로드는 “전체 MDX 디렉터리 스캔”으로 확장하거나,
- “Notion 추출 후 한 번에 이미지 처리” 한 플로우를 README에 명시
→ **적용 완료**: `download-images.mjs`가 content/courses/ 전체 .mdx 스캔·교체, `README.md`에 파이프라인 명시
#### (9) `split-mdx.mjs` 유지보수성
- **현상**: 챕터 구간이 `startLine`/`endLine` 하드코딩. index.mdx 구조가 바뀌면 라인 번호가 어긋남
- **추천**:
- 가능하면 `## 제목` 기준으로 파싱해 구간 자동 분리하거나,
- 최소한 CHAPTERS를 JSON/별도 설정 파일로 빼고, “이 스크립트는 v1→챕터 분리용, v2는 Notion 추출 위주”라고 주석 명시
---
### 3.4 낮음 — UX·확장
#### (10) 모바일에서 챕터 네비
- **현상**: 챕터 상세에서 좌측 `CourseNav`가 `hidden lg:block`이라 모바일에서는 보이지 않음
- **추천**: 드로어/바텀 시트 또는 상단 드롭다운으로 “이번 모듈 목차” 열기
#### (11) 학습 진행 상태
- **현상**: 진행률·완료 체크 없음
- **추천**: 나중에 Skool/결제 연동 시 localStorage 또는 계정 기반으로 “완료” 표시 가능하도록 챕터 slug만 저장하는 구조를 고려
#### (12) 공통 UI 컴포넌트 규칙
- **현상**: `.cursor/rules/apple-theme-ui-components.mdc`는 `Button`, `Card`, `Typography` 등 공통 컴포넌트 사용을 권장하나, skoolchef-tutorial는 자체 Tailwind 마크업만 사용
- **추천**: 이 프로젝트가 apple-theme-ui를 사용하지 않는다면, 규칙의 glob에서 제외하거나, “랜딩/마케팅 페이지는 예외”로 문서화
---
## 4. 설계 일관성 정리
| 항목 | 현재 | 기획(v2) | 제안 |
|------|------|----------|------|
| 챕터 수 | 17 (00~16) | 19 → 22 | Phase에 따라 점진 확장, index.mdx와 기획안만 동기화 |
| 모듈 색상 | 3곳에 분산, Module 2 불일치 | — | 단일 theme/constants로 통일 |
| 콘텐츠 디렉터리 | 플랫 파일 | 서브폴더 제안 | 챕터 수 늘어나면 서브폴더 전환 검토 |
| Notion | PAGE_ID 1개 + 하위 페이지 | — | 유지. 이미지는 전체 MDX 스캔 옵션 추가 |
---
## 5. 바로 적용 가능한 체크리스트
- [x] `lib/theme.ts`(또는 `constants/module-theme.ts`) 생성 후 `moduleAccents`/`moduleColors` 통합, page/courses/CourseNav에서 import
- [x] `CourseNav`에서 Module 2 색상을 orange로 맞추기 (기존 violet → orange)
- [x] `content/courses/index.mdx` 목차를 00~12(현재 13챕터) 기준으로 수정하거나, `getAllCourses()` 기반 자동 생성 스크립트 추가
- [x] `app/courses/[slug]/page.tsx`에서 MDX `components`에 `img` 래퍼 전달 (next/image)
- [x] `projects/skoolchef-tutorial/CLAUDE.md` 작성 (목적, 구조, 파이프라인, PDCA 미사용)
- [ ] `scripts/README.md` 또는 메인 README에 Notion 추출 → 이미지 다운로드 → (선택) split 순서와 환경변수 정리
---
## 6. 요약
- **구조**: Next.js 15 + MDX 기반 커리큘럼 사이트로 목적에 잘 맞고, 보안·접근성 고려도 되어 있음.
- **개선 초점**: (1) 모듈 테마 단일화 및 Module 2 색상 일치, (2) index.mdx와 실제 챕터 목록 동기화, (3) MDX 이미지를 next/image로 처리, (4) 프로젝트 CLAUDE.md 및 스크립트 사용법 문서화.
- **기획과의 갭**: v2는 19챕터·서브폴더 구조를 제안하므로, Phase 2 이후 콘텐츠가 늘어날 때 폴더 구조와 `getAllCourses()` 수정을 함께 진행하는 것을 권장합니다.
공개 문서 변환 코드 (HTML)
<h1>Skoolchef Tutorial — 구조·설계 심화 분석 및 개선 제안</h1>
<blockquote>
<p>분석일: 2026-03-10<br>대상: <code>projects/skoolchef-tutorial</code> 전체</p>
</blockquote>
<hr>
<h2>1. 현재 구조 요약</h2>
<h3>1.1 기술 스택</h3>
<table>
<thead>
<tr>
<th>영역</th>
<th>기술</th>
</tr>
</thead>
<tbody><tr>
<td>프레임워크</td>
<td>Next.js 15 (App Router)</td>
</tr>
<tr>
<td>스타일</td>
<td>Tailwind CSS 3.4 + @tailwindcss/typography</td>
</tr>
<tr>
<td>콘텐츠</td>
<td>MDX (next-mdx-remote/rsc), gray-matter</td>
</tr>
<tr>
<td>폰트</td>
<td>Noto Sans KR (next/font)</td>
</tr>
<tr>
<td>배포</td>
<td>Vercel (가정, NEXT_PUBLIC_SITE_URL)</td>
</tr>
</tbody></table>
<h3>1.2 디렉터리 구조</h3>
<pre><code>skoolchef-tutorial/
├── app/ # Next.js App Router
│ ├── layout.tsx # 루트 레이아웃, 메타, Navigation
│ ├── page.tsx # 홈 (히어로 + 도구 소개 + 커리큘럼)
│ ├── courses/
│ │ ├── page.tsx # 커리큘럼 목록
│ │ └── [slug]/page.tsx # 챕터 상세 (MDX 렌더)
│ └── globals.css
├── components/
│ ├── Navigation.tsx # 상단 고정 네비 (로고, 커리큘럼 링크, 모바일 메뉴)
│ └── CourseNav.tsx # 챕터 상세 좌측 사이드바
├── lib/
│ └── mdx.ts # 코스 메타·목록·모듈 그룹 (fs 동기 읽기)
├── content/
│ ├── curriculum-v2-plan.md # v2 기획안 (Module 0~4, 19챕터)
│ ├── image-mapping.json # Notion 이미지 → 로컬 매핑
│ └── courses/ # 17챕터 MDX (00-intro ~ 16-integrated-workflow)
├── public/images/notion/ # Notion 추출 이미지 01~13
├── scripts/
│ ├── extract-notion.mjs # Notion API → MDX 추출
│ ├── check-notion.mjs # Notion 연동 진단
│ ├── split-mdx.mjs # 단일 MDX → 챕터 분리 (라인 번호 기반)
│ └── download-images.mjs # Notion S3 이미지 → 로컬 + URL 교체
├── .env.example
├── package.json
├── next.config.ts
└── tailwind.config.ts
</code></pre>
<h3>1.3 데이터 흐름</h3>
<ul>
<li><strong>콘텐츠</strong>: <code>content/courses/*.mdx</code> → <code>lib/mdx.ts</code>에서 frontmatter 파싱 및 목록 생성</li>
<li><strong>모듈 구분</strong>: <code>order</code> 숫자로 구간 매핑 (0=기초, 1–5=Cursor, 6–9=Claude Code, 10–12=Gemini, 13+=실전)</li>
<li><strong>Notion 파이프라인</strong>: <code>extract-notion</code> → (선택) <code>download-images</code> → (선택) <code>split-mdx</code>로 챕터 분리</li>
</ul>
<hr>
<h2>2. 강점</h2>
<ul>
<li><strong>명확한 앱 구조</strong>: 홈 / 커리큘럼 목록 / 챕터 상세 3단계, 브레드크럼·이전·다음 네비 제공</li>
<li><strong>보안·품질 의식</strong>: <code>lib/mdx.ts</code>의 path traversal 방지, frontmatter 런타임 검증, 동적 클래스는 safelist로 보완</li>
<li><strong>접근성·SEO</strong>: <code>lang="ko"</code>, 메타·OG·viewport, aria 레이블</li>
<li><strong>v2 기획 정리</strong>: <code>curriculum-v2-plan.md</code>로 Module 0<del>4, 도구 비교표, Phase 1</del>4 우선순위 명시</li>
<li><strong>Notion 연동</strong>: 통합 추출·이미지 다운로드·매핑 JSON으로 편집–배포 분리 가능</li>
</ul>
<hr>
<h2>3. 개선사항 및 추천 (우선순위별)</h2>
<h3>3.1 높음 — 구조·일관성</h3>
<h4>(1) 모듈 색상/테마 단일화</h4>
<ul>
<li><strong>현상</strong>: 모듈별 색이 <code>app/page.tsx</code>, <code>app/courses/page.tsx</code>, <code>components/CourseNav.tsx</code>에 각각 하드코딩되어 있고, <strong>Module 2</strong>가 홈/커리큘럼에서는 orange, CourseNav에서는 purple로 불일치</li>
<li><strong>추천</strong>: <code>lib/theme.ts</code> 또는 <code>constants/module-theme.ts</code>에 <code>moduleAccents</code> / <code>moduleColors</code>를 한 곳만 정의하고, 세 곳에서 import해 사용</li>
<li><strong>효과</strong>: 모듈 추가·색 변경 시 한 파일만 수정</li>
</ul>
<h4>(2) 콘텐츠 폴더 구조와 기획안 정렬</h4>
<ul>
<li><strong>현상</strong>: 기획안은 <code>module-1-cursor/</code>, <code>module-2-claude-code/</code> 등 <strong>서브폴더</strong> 구조를 제안하지만, 현재는 <code>content/courses/</code> 밑에 <strong>플랫 파일</strong>만 있음 (00-intro.mdx ~ 13-integrated-workflow.mdx)</li>
<li><strong>추천</strong>:<ul>
<li><strong>단기</strong>: 현재처럼 플랫 유지해도 되며, <code>lib/mdx.ts</code>의 <code>getModuleInfo(order)</code>와 실제 챕터 수가 v2 기획(19챕터)과 다르다는 점만 문서화 → <strong>적용 완료</strong>: <code>lib/mdx.ts</code> 상단 주석 + <code>docs/content-structure.md</code></li>
<li><strong>중기</strong>: v2 Phase 2 이후 챕터가 늘어나면 <code>content/courses/module-0/</code>, <code>module-1/</code> 등으로 이전하고, <code>getAllCourses()</code>에서 <code>fs.readdirSync</code> 재귀 또는 glob으로 수집하도록 변경</li>
</ul>
</li>
</ul>
<h4>(3) <code>content/courses/index.mdx</code> 동기화</h4>
<ul>
<li><strong>현상</strong>: <code>index.mdx</code>는 “5단계 커리큘럼”, 01<del>05만 링크로 나열. 실제는 00</del>12 총 13챕터</li>
<li><strong>추천</strong>: 목차를 현재 챕터 목록과 맞추거나, <code>getAllCourses()</code> 결과로 index.mdx를 <strong>생성</strong>하는 스크립트를 두어 수동 편집 제거 → <strong>적용 완료</strong>: <code>scripts/generate-index-mdx.mjs</code> 추가, <code>pnpm generate-index-mdx</code>로 목차 자동 생성</li>
</ul>
<hr>
<h3>3.2 높음 — 코드·성능</h3>
<h4>(4) MDX 이미지 컴포넌트</h4>
<ul>
<li><strong>현상</strong>: <code><MDXRemote source={course.content} /></code>에 <code>components</code>를 넘기지 않아, MDX 내 <code></code>이 일반 <code><img></code>로 렌더됨</li>
<li><strong>추천</strong>: <code>components={{ img: NextImageWrapper }}</code> 형태로 <code>next/image</code> 기반 컴포넌트 전달 (width/height 또는 fill + sizes). 로컬 <code>/images/notion/</code> 경로는 <code>sizes</code>로 반응형 지정</li>
<li><strong>효과</strong>: LCP 개선, 일관된 이미지 최적화 → <strong>적용 완료</strong>: <code>components/MdxImage.tsx</code> 추가, 챕터 페이지에서 <code>components={{ img: MdxImage }}</code> 전달</li>
</ul>
<h4>(5) <code>lib/mdx.ts</code> 읽기 방식</h4>
<ul>
<li><strong>현상</strong>: <code>getAllCourses()</code>가 매 요청마다 <code>fs.readdirSync</code> + <code>fs.readFileSync</code>로 모든 MDX를 읽음</li>
<li><strong>추천</strong>: <ul>
<li>개발 시에는 현재처럼 유지해도 무방 </li>
<li>필요 시 <code>getAllCourses()</code>/<code>getCoursesByModule()</code> 결과를 <strong>캐시</strong> (예: <code>unstable_cache</code> 또는 빌드 시 한 번만 읽어 JSON으로 저장 후 import)</li>
</ul>
</li>
</ul>
<h4>(6) Tailwind content 경로에 content 포함</h4>
<ul>
<li><strong>현상</strong>: <code>tailwind.config.ts</code>의 <code>content</code>에 <code>./content/**/*.mdx</code>가 없음. MDX 안에서 사용하는 Tailwind 클래스는 JIT에 포함되지 않음</li>
<li><strong>추천</strong>: MDX 본문에서 Tailwind를 쓰지 않는다면 유지; 쓰면 <code>content: [ ..., "./content/**/*.mdx" ]</code> 추가 → <strong>적용 완료</strong>: <code>content</code> 배열에 <code>"./content/**/*.mdx"</code> 추가</li>
</ul>
<hr>
<h3>3.3 중간 — 운영·문서</h3>
<h4>(7) 프로젝트 루트 <code>CLAUDE.md</code> 추가</h4>
<ul>
<li><strong>현상</strong>: 워크스페이스 규칙에서 “프로젝트별 CLAUDE.md”를 참조하도록 되어 있으나, skoolchef-tutorial 루트에는 없음</li>
<li><strong>추천</strong>: <code>projects/skoolchef-tutorial/CLAUDE.md</code>에 다음을 명시 <ul>
<li>목적(스쿨용 AI 바이브코딩 커리큘럼 사이트) </li>
<li>문서/콘텐츠 구조 (content/courses, curriculum-v2-plan, scripts) </li>
<li>Notion → MDX 파이프라인 요약 </li>
<li>PDCA 폴더 사용 여부(사용 안 함 권장)<br>→ <strong>적용 완료</strong>: <code>projects/skoolchef-tutorial/CLAUDE.md</code> 생성</li>
</ul>
</li>
</ul>
<h4>(8) 스크립트 입력 경로 통일</h4>
<ul>
<li><strong>현상</strong>: <code>download-images.mjs</code>는 <code>./content/courses/index.mdx</code>만 대상. 현재는 챕터가 개별 파일이라 index만 수정됨. <code>extract-notion</code>은 PAGE_ID 기준으로 여러 페이지 추출</li>
<li><strong>추천</strong>: <ul>
<li>이미지 다운로드는 “전체 MDX 디렉터리 스캔”으로 확장하거나, </li>
<li>“Notion 추출 후 한 번에 이미지 처리” 한 플로우를 README에 명시
→ <strong>적용 완료</strong>: <code>download-images.mjs</code>가 content/courses/ 전체 .mdx 스캔·교체, <code>README.md</code>에 파이프라인 명시</li>
</ul>
</li>
</ul>
<h4>(9) <code>split-mdx.mjs</code> 유지보수성</h4>
<ul>
<li><strong>현상</strong>: 챕터 구간이 <code>startLine</code>/<code>endLine</code> 하드코딩. index.mdx 구조가 바뀌면 라인 번호가 어긋남</li>
<li><strong>추천</strong>: <ul>
<li>가능하면 <code>## 제목</code> 기준으로 파싱해 구간 자동 분리하거나, </li>
<li>최소한 CHAPTERS를 JSON/별도 설정 파일로 빼고, “이 스크립트는 v1→챕터 분리용, v2는 Notion 추출 위주”라고 주석 명시</li>
</ul>
</li>
</ul>
<hr>
<h3>3.4 낮음 — UX·확장</h3>
<h4>(10) 모바일에서 챕터 네비</h4>
<ul>
<li><strong>현상</strong>: 챕터 상세에서 좌측 <code>CourseNav</code>가 <code>hidden lg:block</code>이라 모바일에서는 보이지 않음</li>
<li><strong>추천</strong>: 드로어/바텀 시트 또는 상단 드롭다운으로 “이번 모듈 목차” 열기</li>
</ul>
<h4>(11) 학습 진행 상태</h4>
<ul>
<li><strong>현상</strong>: 진행률·완료 체크 없음</li>
<li><strong>추천</strong>: 나중에 Skool/결제 연동 시 localStorage 또는 계정 기반으로 “완료” 표시 가능하도록 챕터 slug만 저장하는 구조를 고려</li>
</ul>
<h4>(12) 공통 UI 컴포넌트 규칙</h4>
<ul>
<li><strong>현상</strong>: <code>.cursor/rules/apple-theme-ui-components.mdc</code>는 <code>Button</code>, <code>Card</code>, <code>Typography</code> 등 공통 컴포넌트 사용을 권장하나, skoolchef-tutorial는 자체 Tailwind 마크업만 사용</li>
<li><strong>추천</strong>: 이 프로젝트가 apple-theme-ui를 사용하지 않는다면, 규칙의 glob에서 제외하거나, “랜딩/마케팅 페이지는 예외”로 문서화</li>
</ul>
<hr>
<h2>4. 설계 일관성 정리</h2>
<table>
<thead>
<tr>
<th>항목</th>
<th>현재</th>
<th>기획(v2)</th>
<th>제안</th>
</tr>
</thead>
<tbody><tr>
<td>챕터 수</td>
<td>17 (00~16)</td>
<td>19 → 22</td>
<td>Phase에 따라 점진 확장, index.mdx와 기획안만 동기화</td>
</tr>
<tr>
<td>모듈 색상</td>
<td>3곳에 분산, Module 2 불일치</td>
<td>—</td>
<td>단일 theme/constants로 통일</td>
</tr>
<tr>
<td>콘텐츠 디렉터리</td>
<td>플랫 파일</td>
<td>서브폴더 제안</td>
<td>챕터 수 늘어나면 서브폴더 전환 검토</td>
</tr>
<tr>
<td>Notion</td>
<td>PAGE_ID 1개 + 하위 페이지</td>
<td>—</td>
<td>유지. 이미지는 전체 MDX 스캔 옵션 추가</td>
</tr>
</tbody></table>
<hr>
<h2>5. 바로 적용 가능한 체크리스트</h2>
<ul>
<li><input checked="" disabled="" type="checkbox"> <code>lib/theme.ts</code>(또는 <code>constants/module-theme.ts</code>) 생성 후 <code>moduleAccents</code>/<code>moduleColors</code> 통합, page/courses/CourseNav에서 import</li>
<li><input checked="" disabled="" type="checkbox"> <code>CourseNav</code>에서 Module 2 색상을 orange로 맞추기 (기존 violet → orange)</li>
<li><input checked="" disabled="" type="checkbox"> <code>content/courses/index.mdx</code> 목차를 00~12(현재 13챕터) 기준으로 수정하거나, <code>getAllCourses()</code> 기반 자동 생성 스크립트 추가</li>
<li><input checked="" disabled="" type="checkbox"> <code>app/courses/[slug]/page.tsx</code>에서 MDX <code>components</code>에 <code>img</code> 래퍼 전달 (next/image)</li>
<li><input checked="" disabled="" type="checkbox"> <code>projects/skoolchef-tutorial/CLAUDE.md</code> 작성 (목적, 구조, 파이프라인, PDCA 미사용)</li>
<li><input disabled="" type="checkbox"> <code>scripts/README.md</code> 또는 메인 README에 Notion 추출 → 이미지 다운로드 → (선택) split 순서와 환경변수 정리</li>
</ul>
<hr>
<h2>6. 요약</h2>
<ul>
<li><strong>구조</strong>: Next.js 15 + MDX 기반 커리큘럼 사이트로 목적에 잘 맞고, 보안·접근성 고려도 되어 있음.</li>
<li><strong>개선 초점</strong>: (1) 모듈 테마 단일화 및 Module 2 색상 일치, (2) index.mdx와 실제 챕터 목록 동기화, (3) MDX 이미지를 next/image로 처리, (4) 프로젝트 CLAUDE.md 및 스크립트 사용법 문서화.</li>
<li><strong>기획과의 갭</strong>: v2는 19챕터·서브폴더 구조를 제안하므로, Phase 2 이후 콘텐츠가 늘어날 때 폴더 구조와 <code>getAllCourses()</code> 수정을 함께 진행하는 것을 권장합니다.</li>
</ul>