CLAUDE.md

# Skoolchef Tutorial — 프로젝트 가이드

> 스쿨용 AI 바이브코딩 커리큘럼 사이트. Cursor · Claude Code · Gemini CLI · Google Workspace CLI를 다루는 챕터형 학습 사이트.

### 워크스페이스 공통 규정 (루트 참조)

| 주제 | 규정 위치 |
|------|-----------|
| 목차·규격 인덱스 | 루트 **`docs/CLAUDE-workspace-standard.md`** |
| `.gitignore` | 루트 **`CLAUDE.md`** 「모노레포 `.gitignore` 규칙」, **`.cursor/rules/gitignore-monorepo-hierarchy.mdc`** |
| `git push` | 루트 **`CLAUDE.md`** 「Git 추적·원격 전략」「Git push 규칙」 |
| Vercel(OpenClaw `saas-engine`만) | **`.cursor/rules/vercel-deploy-openclaw.mdc`**, **`projects/openclaw/CLAUDE.md`** |
| 그 밖 배포·Vercel | **`docs/deployment.md`** 및 이 프로젝트 **`CLAUDE.md`** 우선 |

---

## 1. 목적

- **제품**: Skoolchef Tutorial — AI 코딩 도구 4종(Cursor, Claude Code, Gemini CLI, Google Workspace CLI) 커리큘럼
- **대상**: 스쿨 수강생
- **기술**: Next.js 15 (App Router), MDX, Tailwind CSS, Vercel 배포

---

## 2. 문서·콘텐츠 구조

| 경로 | 용도 |
|------|------|
| `content/courses/` | 챕터 MDX (00~16, index.mdx). 목차는 `pnpm generate-index-mdx`로 자동 생성 |
| `content/curriculum-v2-plan.md` | v2 기획안 (Module 0~5, 22챕터 제안) |
| `content/image-mapping.json` | Notion 이미지 → 로컬 경로 매핑 |
| `docs/` | 구조·배포·가이드. **진입점**: [docs/00-structure-and-design.md](docs/00-structure-and-design.md) |
| `docs/reference/` | Notion 원본 레퍼런스 (추출일 기준 스냅샷) |
| `scripts/` | Notion 추출·이미지·목차·강의안 export 스크립트 |

**PDCA 폴더**: 사용하지 않음. 계획/설계/보고는 `docs/` 또는 `content/curriculum-v2-plan.md`에 둠.

**전체 디렉터리 구조**: [docs/00-structure-and-design.md](docs/00-structure-and-design.md) §2 참고.

---

## 3. Notion → MDX 파이프라인

1. **추출**: `pnpm extract-notion` — Notion API로 페이지·하위 페이지를 MDX로 저장 (`.env`: `NOTION_TOKEN`, `NOTION_PAGE_ID`)
5. **레퍼런스**: `pnpm extract-notion-reference` — 지정 Notion 페이지를 `docs/reference/`에 마크다운으로 저장 (원본 스냅샷 용도)
2. **이미지**: `pnpm download-images` — **content/courses/ 전체 MDX**를 스캔해 Notion S3 URL을 다운로드 후 로컬 경로로 교체
3. **분리**(선택): `pnpm split-mdx` — 단일 MDX를 챕터별 파일로 분리 (라인 번호 기반, v1→챕터 분리용)
4. **목차**: `pnpm generate-index-mdx` — `getAllCourses()` 규칙으로 챕터 목록을 읽어 `content/courses/index.mdx` 생성

진단: `node scripts/check-notion.mjs` — Notion 연동·접근 가능 페이지 확인.

---

## 5. 문서 인덱스 (docs/)

| 문서 | 용도 |
|------|------|
| [00-structure-and-design.md](docs/00-structure-and-design.md) | **구조·설계 진입점** — 디렉터리·설계 원칙·문서 목록 |
| [00-structure-and-learning-plan.md](docs/00-structure-and-learning-plan.md) | 구조 **점검**(문서·실제 정합) + 학습 사이트 기획 **요약** |
| [structure-and-design-analysis.md](docs/structure-and-design-analysis.md) | 심화 분석·개선 제안·체크리스트 |
| [deployment.md](docs/deployment.md) | Vercel 배포 절차 |
| [gws-auth-and-verified-usage.md](docs/gws-auth-and-verified-usage.md) | Google Workspace CLI 인증·검증된 명령 |
| [content-structure.md](docs/content-structure.md) | 콘텐츠 폴더·v2 기획 관계 |
| [curriculum-levels.md](docs/curriculum-levels.md) | L1/L2 난이도 |

---

## 6. 작업 시 참고

- 챕터 추가·수정 후 목차 갱신: `pnpm generate-index-mdx`
- 모듈별 색·테마: `lib/theme.ts` 단일 소스
- 챕터 수집·모듈 구간: `lib/mdx.ts` (주석에 현재 vs v2 정리)
- 상세 분석·체크리스트: [docs/structure-and-design-analysis.md](docs/structure-and-design-analysis.md)

---

## 7. 최근 허브 업데이트 반영 (다음 작업 전 확인)

`projects/openclaw/saas-engine`의 스쿨셰프 허브가 아래 기준으로 개편되었으니, 커리큘럼/도구 문서 작업 시 동일 기준을 유지한다.

### 반영된 주요 변경

- `hub/curriculum/m1~m4`가 도구별 서브페이지로 재구성됨
  - 공통 구성: **설치**, **최근 업데이트 내역**, **핵심 기능 5가지**
  - 공통 템플릿: `projects/openclaw/saas-engine/components/skoolchef-hub/skoolchef-tool-page.tsx`
- 도구별 데이터 소스 분리
  - 메타/기능: `projects/openclaw/saas-engine/lib/skoolchef-tool-pages.ts`
  - 업데이트 목록/검증일: `projects/openclaw/saas-engine/lib/data/tool-updates.ts`
- 업데이트 섹션은 공식 소스 기준 최신 항목(3개) + `검증일(lastVerifiedAt)`을 표시함

### 유지보수 규칙

- 업데이트 항목 변경 시 `tool-updates.ts`만 수정하고, 페이지 컴포넌트 구조는 유지
- 검증일 갱신/링크 점검은 saas-engine에서 실행:
  - `pnpm update:tool-updates`
  - `pnpm update:tool-updates -- --dry-run`
  - `pnpm update:tool-updates -- --tool cursor`
- 링크 점검이 네트워크 환경에서 불안정하면 날짜 갱신만 먼저 수행:
  - `pnpm update:tool-updates -- --no-links`

---

## ⚠️ 미완료 작업 — 반드시 처리 필요

### 샘플 이미지 교체 (필수)

`public/images/notion/` 폴더의 이미지(01~13.png 등)는 **Notion에서 임시 추출한 샘플 이미지**다.
실제 서비스 배포 전 **실제 사이트 페이지 스크린샷 또는 제작 이미지로 전량 교체**해야 한다.

| 항목 | 내용 |
|------|------|
| **위치** | `public/images/notion/01-image.png` ~ `13-image.png` (총 13개) |
| **현재 상태** | Notion S3에서 다운로드한 임시 샘플 이미지 |
| **필요 조치** | 실제 서비스/강의 화면 캡처 이미지로 1:1 교체 |
| **매핑 파일** | `content/image-mapping.json` — 어떤 MDX의 어느 위치에 쓰이는지 확인 가능 |
| **교체 완료 시** | 이 섹션과 §7 전체를 삭제할 것 |

<h1>Skoolchef Tutorial — 프로젝트 가이드</h1>
<blockquote>
<p>스쿨용 AI 바이브코딩 커리큘럼 사이트. Cursor · Claude Code · Gemini CLI · Google Workspace CLI를 다루는 챕터형 학습 사이트.</p>
</blockquote>
<h3>워크스페이스 공통 규정 (루트 참조)</h3>
<table>
<thead>
<tr>
<th>주제</th>
<th>규정 위치</th>
</tr>
</thead>
<tbody><tr>
<td>목차·규격 인덱스</td>
<td>루트 <strong><code>docs/CLAUDE-workspace-standard.md</code></strong></td>
</tr>
<tr>
<td><code>.gitignore</code></td>
<td>루트 <strong><code>CLAUDE.md</code></strong> 「모노레포 <code>.gitignore</code> 규칙」, <strong><code>.cursor/rules/gitignore-monorepo-hierarchy.mdc</code></strong></td>
</tr>
<tr>
<td><code>git push</code></td>
<td>루트 <strong><code>CLAUDE.md</code></strong> 「Git 추적·원격 전략」「Git push 규칙」</td>
</tr>
<tr>
<td>Vercel(OpenClaw <code>saas-engine</code>만)</td>
<td><strong><code>.cursor/rules/vercel-deploy-openclaw.mdc</code></strong>, <strong><code>projects/openclaw/CLAUDE.md</code></strong></td>
</tr>
<tr>
<td>그 밖 배포·Vercel</td>
<td><strong><code>docs/deployment.md</code></strong> 및 이 프로젝트 <strong><code>CLAUDE.md</code></strong> 우선</td>
</tr>
</tbody></table>
<hr>
<h2>1. 목적</h2>
<ul>
<li><strong>제품</strong>: Skoolchef Tutorial — AI 코딩 도구 4종(Cursor, Claude Code, Gemini CLI, Google Workspace CLI) 커리큘럼</li>
<li><strong>대상</strong>: 스쿨 수강생</li>
<li><strong>기술</strong>: Next.js 15 (App Router), MDX, Tailwind CSS, Vercel 배포</li>
</ul>
<hr>
<h2>2. 문서·콘텐츠 구조</h2>
<table>
<thead>
<tr>
<th>경로</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td><code>content/courses/</code></td>
<td>챕터 MDX (00~16, index.mdx). 목차는 <code>pnpm generate-index-mdx</code>로 자동 생성</td>
</tr>
<tr>
<td><code>content/curriculum-v2-plan.md</code></td>
<td>v2 기획안 (Module 0~5, 22챕터 제안)</td>
</tr>
<tr>
<td><code>content/image-mapping.json</code></td>
<td>Notion 이미지 → 로컬 경로 매핑</td>
</tr>
<tr>
<td><code>docs/</code></td>
<td>구조·배포·가이드. <strong>진입점</strong>: <a href="docs/00-structure-and-design.md">docs/00-structure-and-design.md</a></td>
</tr>
<tr>
<td><code>docs/reference/</code></td>
<td>Notion 원본 레퍼런스 (추출일 기준 스냅샷)</td>
</tr>
<tr>
<td><code>scripts/</code></td>
<td>Notion 추출·이미지·목차·강의안 export 스크립트</td>
</tr>
</tbody></table>
<p><strong>PDCA 폴더</strong>: 사용하지 않음. 계획/설계/보고는 <code>docs/</code> 또는 <code>content/curriculum-v2-plan.md</code>에 둠.</p>
<p><strong>전체 디렉터리 구조</strong>: <a href="docs/00-structure-and-design.md">docs/00-structure-and-design.md</a> §2 참고.</p>
<hr>
<h2>3. Notion → MDX 파이프라인</h2>
<ol>
<li><strong>추출</strong>: <code>pnpm extract-notion</code> — Notion API로 페이지·하위 페이지를 MDX로 저장 (<code>.env</code>: <code>NOTION_TOKEN</code>, <code>NOTION_PAGE_ID</code>)</li>
<li><strong>레퍼런스</strong>: <code>pnpm extract-notion-reference</code> — 지정 Notion 페이지를 <code>docs/reference/</code>에 마크다운으로 저장 (원본 스냅샷 용도)</li>
<li><strong>이미지</strong>: <code>pnpm download-images</code> — <strong>content/courses/ 전체 MDX</strong>를 스캔해 Notion S3 URL을 다운로드 후 로컬 경로로 교체</li>
<li><strong>분리</strong>(선택): <code>pnpm split-mdx</code> — 단일 MDX를 챕터별 파일로 분리 (라인 번호 기반, v1→챕터 분리용)</li>
<li><strong>목차</strong>: <code>pnpm generate-index-mdx</code> — <code>getAllCourses()</code> 규칙으로 챕터 목록을 읽어 <code>content/courses/index.mdx</code> 생성</li>
</ol>
<p>진단: <code>node scripts/check-notion.mjs</code> — Notion 연동·접근 가능 페이지 확인.</p>
<hr>
<h2>5. 문서 인덱스 (docs/)</h2>
<table>
<thead>
<tr>
<th>문서</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td><a href="docs/00-structure-and-design.md">00-structure-and-design.md</a></td>
<td><strong>구조·설계 진입점</strong> — 디렉터리·설계 원칙·문서 목록</td>
</tr>
<tr>
<td><a href="docs/00-structure-and-learning-plan.md">00-structure-and-learning-plan.md</a></td>
<td>구조 <strong>점검</strong>(문서·실제 정합) + 학습 사이트 기획 <strong>요약</strong></td>
</tr>
<tr>
<td><a href="docs/structure-and-design-analysis.md">structure-and-design-analysis.md</a></td>
<td>심화 분석·개선 제안·체크리스트</td>
</tr>
<tr>
<td><a href="docs/deployment.md">deployment.md</a></td>
<td>Vercel 배포 절차</td>
</tr>
<tr>
<td><a href="docs/gws-auth-and-verified-usage.md">gws-auth-and-verified-usage.md</a></td>
<td>Google Workspace CLI 인증·검증된 명령</td>
</tr>
<tr>
<td><a href="docs/content-structure.md">content-structure.md</a></td>
<td>콘텐츠 폴더·v2 기획 관계</td>
</tr>
<tr>
<td><a href="docs/curriculum-levels.md">curriculum-levels.md</a></td>
<td>L1/L2 난이도</td>
</tr>
</tbody></table>
<hr>
<h2>6. 작업 시 참고</h2>
<ul>
<li>챕터 추가·수정 후 목차 갱신: <code>pnpm generate-index-mdx</code></li>
<li>모듈별 색·테마: <code>lib/theme.ts</code> 단일 소스</li>
<li>챕터 수집·모듈 구간: <code>lib/mdx.ts</code> (주석에 현재 vs v2 정리)</li>
<li>상세 분석·체크리스트: <a href="docs/structure-and-design-analysis.md">docs/structure-and-design-analysis.md</a></li>
</ul>
<hr>
<h2>7. 최근 허브 업데이트 반영 (다음 작업 전 확인)</h2>
<p><code>projects/openclaw/saas-engine</code>의 스쿨셰프 허브가 아래 기준으로 개편되었으니, 커리큘럼/도구 문서 작업 시 동일 기준을 유지한다.</p>
<h3>반영된 주요 변경</h3>
<ul>
<li><code>hub/curriculum/m1~m4</code>가 도구별 서브페이지로 재구성됨<ul>
<li>공통 구성: <strong>설치</strong>, <strong>최근 업데이트 내역</strong>, <strong>핵심 기능 5가지</strong></li>
<li>공통 템플릿: <code>projects/openclaw/saas-engine/components/skoolchef-hub/skoolchef-tool-page.tsx</code></li>
</ul>
</li>
<li>도구별 데이터 소스 분리<ul>
<li>메타/기능: <code>projects/openclaw/saas-engine/lib/skoolchef-tool-pages.ts</code></li>
<li>업데이트 목록/검증일: <code>projects/openclaw/saas-engine/lib/data/tool-updates.ts</code></li>
</ul>
</li>
<li>업데이트 섹션은 공식 소스 기준 최신 항목(3개) + <code>검증일(lastVerifiedAt)</code>을 표시함</li>
</ul>
<h3>유지보수 규칙</h3>
<ul>
<li>업데이트 항목 변경 시 <code>tool-updates.ts</code>만 수정하고, 페이지 컴포넌트 구조는 유지</li>
<li>검증일 갱신/링크 점검은 saas-engine에서 실행:<ul>
<li><code>pnpm update:tool-updates</code></li>
<li><code>pnpm update:tool-updates -- --dry-run</code></li>
<li><code>pnpm update:tool-updates -- --tool cursor</code></li>
</ul>
</li>
<li>링크 점검이 네트워크 환경에서 불안정하면 날짜 갱신만 먼저 수행:<ul>
<li><code>pnpm update:tool-updates -- --no-links</code></li>
</ul>
</li>
</ul>
<hr>
<h2>⚠️ 미완료 작업 — 반드시 처리 필요</h2>
<h3>샘플 이미지 교체 (필수)</h3>
<p><code>public/images/notion/</code> 폴더의 이미지(01~13.png 등)는 <strong>Notion에서 임시 추출한 샘플 이미지</strong>다.
실제 서비스 배포 전 <strong>실제 사이트 페이지 스크린샷 또는 제작 이미지로 전량 교체</strong>해야 한다.</p>
<table>
<thead>
<tr>
<th>항목</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><strong>위치</strong></td>
<td><code>public/images/notion/01-image.png</code> ~ <code>13-image.png</code> (총 13개)</td>
</tr>
<tr>
<td><strong>현재 상태</strong></td>
<td>Notion S3에서 다운로드한 임시 샘플 이미지</td>
</tr>
<tr>
<td><strong>필요 조치</strong></td>
<td>실제 서비스/강의 화면 캡처 이미지로 1:1 교체</td>
</tr>
<tr>
<td><strong>매핑 파일</strong></td>
<td><code>content/image-mapping.json</code> — 어떤 MDX의 어느 위치에 쓰이는지 확인 가능</td>
</tr>
<tr>
<td><strong>교체 완료 시</strong></td>
<td>이 섹션과 §7 전체를 삭제할 것</td>
</tr>
</tbody></table>