# CLAUDE.md

이 문서는 이 저장소에서 작업할 때 Claude Code (claude.ai/code)에게 제공되는 가이드입니다.

> **이 파일은 starter 키트의 골격입니다.** `<!-- TODO: ... -->` 마커 부분을 코스 고유 내용으로 갈아끼우세요. 구조와 원칙(이터레이션 / 4단계 / 데이터 흐름 3종 / 비유 사용 원칙) 은 그대로 유지하는 것을 강력히 권장합니다.

## 프로젝트 개요

<!-- TODO: 코스 한 줄 소개. 예) "Spring 기초 과정 웹사이트입니다." -->
**[코스 이름]** 사이트입니다. 콘텐츠 출처는 `자료/` 디렉토리(또는 강사 자체 자료)이며, 마무리 산출물은 <!-- TODO: 코스의 최종 산출물 (예: REST API + Ajax 게시판) --> 입니다.

> ⚠️ **표기 원칙**: 학습자가 보는 어떤 화면에도 「**비전공자**」라는 단어를 노출하지 않습니다. 이는 강사의 내부 포지셔닝일 뿐이며, 코스명·hero·헤더·footer·핸드아웃 표지·학습 목표·체크리스트 어디에도 등장하면 안 됩니다.

## 빌드 / 실행

빌드 시스템 없음. 정적 HTML + CDN. 로컬 미리보기:

```bash
python3 -m http.server 8000
```

## 핵심 교수법: 이터레이션(반복 개선) 패턴

이 과정의 모든 콘텐츠는 **하나의 프로젝트가 v0 → v∞ 로 진화하는 여정** 으로 짜입니다. 차시는 독립적인 토픽이 아니라 **"이번 시간 우리 프로젝트가 어디로 진화하는가"** 의 한 단계입니다.

### 버전 진화 지도

<!-- TODO: 여기에 코스의 v0~v∞ 마일스톤 표를 채우세요. 아래는 예시 한 줄. -->

| 버전 | 마일스톤 | 위치 |
|------|---------|------|
| v0   | 첫 화면 출력 | Part 1 |
| v1   | (예시) DB 첫 연동 | Part N |
| ...  | ...     | ...  |
| v∞   | 마무리 워크숍 | 마지막 Part |

## 모든 차시는 4단계 구조를 따른다 (필수)

차시 콘텐츠(slides, examples, labs)는 항상 다음 4단계 흐름으로 작성합니다:

1. **⚠️ 이전 버전의 불편** (`.pain-point`) — "어디가 아팠는가" 를 학생이 직접 체감
2. **🛠️ 새 도구 소개** (`.new-tool`) — 비유 + 어떤 점을 풀어주는가
3. **💻 코드 적용** — 같은 화면을 다시 만든다
4. **🔄 Before / After 비교** (`.before-after`) — "데이터 흐름이 어디가 달라졌나"

이전 버전이 없는 도입부 차시에는 ① 자리에 **"왜 이게 필요한가"** 를 둡니다.

## 데이터 흐름 컨벤션 3종 (필수)

학생이 디버깅 사고를 자연스럽게 익히도록 모든 차시 자료에 다음 3가지를 표준으로 박습니다.

### 1. 흐름도(Flow Diagram) 슬라이드 — 마지막 직전 위치

```
[브라우저] → [Controller] → [Service] → [Mapper] → [DB]
                                    ↑
                              이번 차시에서 새로 생긴 칸
```

- `.flow-diagram` 클래스 사용
- 차시가 누적될수록 흐름도가 길어지고, 새로 생긴 칸은 강조색으로 표시

### 2. 미니맵 — examples / labs 첫 페이지에 고정

- 전체 흐름도 중 이번 차시가 닿는 부분을 색으로 강조
- 코드를 만지기 전에 **"내가 지금 어디를 만지는가"** 를 먼저 인식

### 3. 확인 포인트(Checkpoint) — labs 의 모든 Step 마지막에 고정

- `.checkpoint` 클래스 사용
- 콘솔 / F12 / SQL 로그 / DB 등 어느 것을 볼지 매번 명시

## 차시 식별: 숫자 대신 기호 (절대 차시 번호 노출 금지)

| 기호 | 의미 |
|------|------|
| ◇ | 개념 차시 (concept) |
| ▣ | 실습 차시 (hands-on) |
| ◆ | 전환점 (새 도구 / 패러다임이 처음 등장) |
| ★ | 마일스톤 (프로젝트 새 버전 v_n_ 릴리스) |

UI 라벨 형식:
- 일반: `◇ 키워드 제목` / `▣ 화면 만들어보기`
- 마일스톤: `★ v3 — 키워드 제목`

**파일명** 은 의미 기반(Part 약어 + 키워드):
- `slides/<part약어>-<키워드>.html`

### Part 약어 표

<!-- TODO: 코스의 Part 6개를 채우세요. 아래는 빈 골격입니다. -->

| Part | 약어 | 색상 클래스 |
|------|------|-----------|
| [Part 1 이름] | `<!-- 약어 -->` | `.part-1` 파랑 |
| [Part 2 이름] | `<!-- 약어 -->` | `.part-2` 초록 |
| [Part 3 이름] | `<!-- 약어 -->` | `.part-3` 보라 |
| [Part 4 이름] | `<!-- 약어 -->` | `.part-4` 오렌지 |
| [Part 5 이름] | `<!-- 약어 -->` | `.part-5` 빨강 |
| [Part 6 이름] | `<!-- 약어 -->` | `.part-6` 틸 |

## 버전 뱃지 (시각 컨벤션)

마일스톤 차시(★)의 슬라이드/예제/실습/핸드아웃 헤더 우측 상단에 버전 뱃지:

```html
<div class="version-badge">v3</div>
```

`index.html` 카드에서도 마일스톤 카드는 버전 뱃지를 함께 노출합니다.

## 코스 식별: 시그니처 컬러 · 로고 · 공개 상태

세 가지가 코스 정체성을 만듭니다. 새 코스는 이 셋만 갈아끼우면 자기 색을 가집니다.

### ① 시그니처 컬러

`index.html` 의 `:root` 에 두 변수만 override:

```css
:root {
  --accent: #0074BD;       /* 1차 색 — 브랜드 메인 */
  --red:    #EA2D2E;       /* 2차 색 — 히어로 그라디언트 끝점, 마일스톤 뱃지 */
  --accent-light: #4DA3D6; /* (선택) --accent 의 밝은 변종 */
}
```

- 두 변수가 히어로 그라디언트·뱃지·하이라이트에 일제히 적용됩니다.
- 다크 베이스(`--bg`, `--surface`) 는 코스 간 일관성을 위해 그대로 두세요.
- 색은 가능하면 **로고에서 추출** (코스 로고와 사이트 톤이 같아짐).

### ② 코스 로고

`images/logo.svg` 자리에 SVG 로고 한 장. 외부 의존성 없는 인라인 가능 SVG 권장.

- 라이선스 안전: simple-icons (CC0) / Devicon (MIT) 등에서 받기. 공식 회사 로고는 트레이드마크 주의.
- 노출 위치: `index.html` 히어로 위쪽 (자동), 슬라이드 표지 (선택).
- 코스마다 SVG 의 `<title>` 을 코스명으로 갈아끼우세요.

### ③ 차시 단계별 공개 (admin/locked)

**왜**: 강의가 진행 중일 때 학생이 다음 차시 자료를 미리 보면 흐름이 깨집니다. 차시 끝날 때마다 강사가 그 카드만 "공개" 로 바꾸는 점진 공개 방식.

**작동**:

```html
<!-- 미공개 — 학생: 흐리게 + 🔒 + 클릭 비활성 -->
<div class="card" data-status="locked"> ... </div>

<!-- 공개 — 학생: 정상 노출 -->
<div class="card" data-status="released"> ... </div>
```

**공개 흐름** (강사):

1. 차시 끝남 → 학생이 그 자료 봐도 됨
2. `index.html` 의 해당 카드 `data-status="locked"` → `"released"` 로 변경
3. 저장 (정적 사이트면 즉시 반영, git repo 면 commit + push)
4. 학생은 새로고침하면 잠금 해제된 카드를 봄

**미리보기 (admin 모드)**: 강사가 잠긴 카드 포함 모두 보고 싶을 때 `?admin=smhrd` 를 URL 에 붙이면 비번 prompt → 인증 후 모든 카드 보임 (sessionStorage 저장, 탭 닫을 때까지 유지). 비번은 `index.html` 하단 `<script>` 의 `ADMIN_PW` 상수로 변경 가능.

**원칙**: 공개 여부는 **HTML 의 data 속성** 으로 박힌 정적 상태입니다. 학생 브라우저에서 자물쇠를 우회하는 게 어렵지는 않으나(F12 → 속성 변경), 의도가 "다음 차시는 아직 안 했어요" 라는 선언적 신호이므로 그 정도면 충분합니다. 강한 보호가 필요하면 서버 사이드로 분기.

## 아키텍처 개요 (자료 유형 4종)

| 디렉토리 | 용도 | 테마 | 프레임워크 |
|----------|------|------|-----------|
| `slides/` | 발표 (4단계 + 흐름도) | 다크 | reveal.js 5.1.0 (night) |
| `examples/` | 읽기 자료 (개념 + 미니맵 + 비유) | 다크 | 순수 HTML |
| `labs/` | 단계별 실습 (Step + Checkpoint) | 다크 | 순수 HTML |
| `handouts/` | 인쇄용 요약 (3~5쪽) | 라이트 | 순수 HTML (`@media print`) |

## 한국어 / 비유 컨벤션 (불변)

- **한국어 우선**: 모든 UI·설명·주석. 기술 용어는 `한국어 설명 (English Term)` 형식.

### 🚨 비유 사용 원칙 (가장 중요)

**비유는 본문 안에서 학생의 이해를 돕는 도구로만 사용**합니다. 다음에는 절대 등장하면 안 됩니다:

- ❌ 코스 이름 / 부제
- ❌ Part 라벨 / Part tagline
- ❌ 카드 제목
- ❌ 슬라이드 / 예제 / 실습 / 핸드아웃의 h1·h2·h3 섹션 제목
- ❌ 학습 목표 항목
- ❌ 체크리스트 항목
- ❌ 실습 Step 제목

**대신 비유는 다음 자리에서만**:

- ✅ 본문 단락 안의 보조 설명
- ✅ `.diagram` 안의 텍스트 다이어그램
- ✅ `.new-tool` / `.box` 안의 풀어쓰기
- ✅ 슬라이드의 강사 노트
- ✅ 핸드아웃의 「용어 ↔ 비유」 매핑 표

### 핵심 비유 사전 (본문에서 일관되게 사용)

<!-- TODO: 코스에서 쓰는 비유를 여기 채우세요. 같은 개념은 항상 같은 비유로. -->

| 개념 | 비유 |
|------|------|
| `<!-- 예: 서버 / 클라이언트 -->` | `<!-- 예: 카페의 바리스타 / 손님 -->` |
| `<!-- 새 행 추가 -->` | `<!-- ... -->` |

- **셸 코드 블록**: 학생 입력은 `$ ` 접두사, 출력은 접두사 없음.
- **하단 네비게이션 필수**: 모든 세션 페이지 하단에 `.nav` (이전 / 메인 / 다음).

## 학습 환경

<!-- TODO: 코스 도구 / 버전을 채우세요. -->

| 도구 | 버전·메모 |
|------|----------|
| IDE | <!-- 예: Eclipse / STS / IntelliJ --> |
| 빌드 | <!-- 예: Maven / Gradle --> |
| 실행 환경 | <!-- 예: Tomcat / 내장 컨테이너 --> |
| DB | <!-- 예: MySQL 8.x --> |
| 기타 | <!-- 매핑 / 뷰 / 암호화 등 --> |

## 새 차시를 만들 때

1. 해당 차시가 **어떤 버전 진화에 속하는지** 먼저 정한다 (v_n_ → v_(n+1)_)
2. **4 단계 구조** 로 본문을 짠다 (불편 → 도구 → 적용 → Before/After)
3. 슬라이드 마지막 직전에 **흐름도 슬라이드** 를 둔다 (이번에 새로 생긴 칸 강조)
4. examples / labs 첫 페이지에 **미니맵** 을 둔다
5. labs 의 모든 Step 마지막에 **Checkpoint** 를 둔다
6. 마일스톤 차시면 헤더에 **버전 뱃지** 를 단다
7. `index.html` 의 해당 Part 섹션에 **카드 한 장** 을 추가한다 (기호 + 키워드, 차시 번호 없음)

## 이 저장소에서 절대 하지 말 것

- ❌ 차시 번호를 학생에게 노출
- ❌ 학생 화면에 「**비전공자**」 노출
- ❌ 비유를 **제목·라벨·학습 목표·체크리스트** 로 사용
- ❌ 일상 비유 **없이** 새 개념 도입
- ❌ 흐름도 슬라이드 없이 차시 마무리
- ❌ "어렵게 → 쉽게" 의 Before/After 비교 없이 새 도구 소개
- ❌ 코스 범위 밖 주제 깊이 도입 (후속 과정으로 미루기)