# CLAUDE.md 설정

> **이 챕터를 마치면** 프로젝트 루트에 CLAUDE.md를 만들고, AI가 맥락을 자동으로 읽게 할 수 있어요.

Claude Code는 프로젝트 루트의 `CLAUDE.md` 파일을 **매 세션마다 자동으로 읽어요.**
여기에 기술 스택, 코딩 규칙, 프로젝트 구조를 적어두면 매번 설명하지 않아도 돼요.

> **비유:** CLAUDE.md는 새 팀원에게 주는 온보딩 문서입니다.
> "이 프로젝트는 이렇게 동작하고, 이 규칙을 따라야 해."

---

## CLAUDE.md 만들기

프로젝트 루트에 파일을 생성합니다.

```bash
# 프로젝트 폴더에서
touch CLAUDE.md
```

또는 Claude Code로 바로 생성:

```bash
claude "이 Next.js 프로젝트를 분석해서 CLAUDE.md를 작성해줘"
```

---

## 효과적인 CLAUDE.md 구조

```markdown
# 프로젝트명

한 줄 설명: 이 프로젝트가 무엇인지

## 기술 스택

- Next.js 15 (App Router, TypeScript)
- Tailwind CSS v3
- Supabase (Auth, PostgreSQL, Storage)
- Vercel (배포)
- pnpm (패키지 매니저)

## 프로젝트 구조

app/           ← 페이지 및 API 라우트
components/    ← 재사용 UI 컴포넌트
lib/           ← 유틸리티, DB 클라이언트
content/       ← MDX 콘텐츠 파일
public/        ← 정적 파일

## 코딩 규칙

- 컴포넌트: PascalCase (예: CourseNav.tsx)
- 함수/변수: camelCase
- 스타일: Tailwind 클래스만 사용 (인라인 스타일 금지)
- 서버 컴포넌트 기본, 클라이언트는 "use client" 명시
- TypeScript strict 모드

## 중요 사항

- pnpm 사용 (npm, yarn 사용 금지)
- .env 파일은 절대 커밋하지 않음
- 컴포넌트 수정 시 반드시 기존 스타일 패턴 확인 후 작업
```

---

## 실제 예시: 이 튜터 사이트의 CLAUDE.md

```markdown
# Skoolchef Tutorial

AI 바이브코딩 커리큘럼 사이트.
Notion에서 추출한 MDX 콘텐츠를 Next.js 15로 렌더링합니다.

## 기술 스택

- Next.js 15 App Router + TypeScript
- Tailwind CSS v3 + @tailwindcss/typography
- next-mdx-remote (MDX 렌더링)
- gray-matter (프론트매터 파싱)
- Vercel (배포)
- pnpm

## 콘텐츠 구조

- MDX 파일: content/courses/{slug}.mdx
- 이미지: public/images/notion/
- 챕터 순서: frontmatter의 order 필드로 결정
- 모듈 구분: order 0=기초, 1-5=Cursor, 6-9=ClaudeCode, 10+=Gemini

## 규칙

- pnpm dev로 개발 서버
- 새 챕터 추가 시 content/courses/에 MDX 파일 생성
- 이미지는 public/images/에 저장
```

---

## 고급: @import로 파일 분리

CLAUDE.md가 길어지면 주제별로 분리할 수 있습니다.

```markdown
# My Project

@docs/architecture.md
@docs/api-conventions.md
@docs/deployment.md
```

Claude Code가 자동으로 해당 파일들도 읽습니다.

---

## CLAUDE.md 위치별 동작

| 위치 | 적용 범위 |
|------|-----------|
| `./CLAUDE.md` (프로젝트 루트) | 현재 프로젝트 |
| `~/.claude/CLAUDE.md` | 모든 프로젝트 (개인 설정) |
| `./subdir/CLAUDE.md` | 해당 하위 폴더 진입 시 추가 로드 |

---

## 작성 팁

**구체적으로 쓸수록 좋습니다.**

❌ 나쁜 예:
```
- React 사용
- 코드 잘 작성
```

✅ 좋은 예:
```
- React 19 + Next.js 15 App Router
- 서버 컴포넌트 기본, 이벤트 핸들러 있을 때만 "use client"
- Tailwind 클래스 정렬: layout → spacing → typography → color 순
- API 호출은 항상 lib/api/ 아래에 함수로 추상화
```

**자주 바뀌는 내용은 넣지 않습니다.** 버전 번호나 임시 설정보다는 변하지 않는 규칙 중심으로 작성합니다.

---

## 확인

CLAUDE.md 적용이 잘 되는지 확인하는 방법:

```bash
claude "현재 프로젝트의 기술 스택이 뭐야?"
# → CLAUDE.md에 적힌 내용을 정확히 답해야 함
```

잘 답하면 CLAUDE.md가 정상적으로 로드된 겁니다.

---

## 8장 보강 프로세스 적용: CLAUDE.md 최소 규격(실전)

유튜브 대본 분석 기준으로, 생산성이 높은 팀은 CLAUDE.md를 길게 쓰기보다 **반복 의사결정에 필요한 최소 규격**을 먼저 고정합니다.

### 최소 규격 6항목 (먼저 고정)

1. **프로젝트 목적 1~2문장**
2. **기술 스택(버전 포함)**
3. **폴더 구조와 책임**
4. **코딩 규칙(네이밍/스타일/컴포넌트 정책)**
5. **금지 규칙(예: `.env` 커밋 금지)**
6. **검증 루틴(빌드/린트/테스트 순서)**

### 자주 실패하는 CLAUDE.md 패턴

1. **너무 추상적인 문장**
   - 예: "코드 잘 작성"
   - 개선: "서버 컴포넌트 기본, 이벤트 핸들러 시에만 `use client`"

2. **자주 바뀌는 임시 내용 과다**
   - 개선: 도메인 규칙/품질 기준 중심으로 유지

3. **검증 단계 미기재**
   - 개선: "수정 후 `pnpm build` → `pnpm dev` 확인" 명시

4. **폴더 책임 불명확**
   - 개선: `app/`, `components/`, `lib/`, `content/` 책임을 한 줄씩 고정

### 07챕터 실행형 체크리스트 (DoD)

- [ ] 루트 `CLAUDE.md` 생성 완료
- [ ] 최소 규격 6항목 반영 완료
- [ ] 금지 규칙(`.env`, 시크릿) 명시 완료
- [ ] 검증 루틴 1개 이상 명시 완료
- [ ] `claude "현재 프로젝트 기술 스택이 뭐야?"`로 로드 확인 완료

> **다음 챕터 입력값:** 멀티파일 작업 시 적용할 규칙(우선순위, 검증 루프, 커밋 단위)

<h1>CLAUDE.md 설정</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> 프로젝트 루트에 CLAUDE.md를 만들고, AI가 맥락을 자동으로 읽게 할 수 있어요.</p>
</blockquote>
<p>Claude Code는 프로젝트 루트의 <code>CLAUDE.md</code> 파일을 <strong>매 세션마다 자동으로 읽어요.</strong>
여기에 기술 스택, 코딩 규칙, 프로젝트 구조를 적어두면 매번 설명하지 않아도 돼요.</p>
<blockquote>
<p><strong>비유:</strong> CLAUDE.md는 새 팀원에게 주는 온보딩 문서입니다.
&quot;이 프로젝트는 이렇게 동작하고, 이 규칙을 따라야 해.&quot;</p>
</blockquote>
<hr>
<h2>CLAUDE.md 만들기</h2>
<p>프로젝트 루트에 파일을 생성합니다.</p>
<pre><code class="language-bash"># 프로젝트 폴더에서
touch CLAUDE.md
</code></pre>
<p>또는 Claude Code로 바로 생성:</p>
<pre><code class="language-bash">claude &quot;이 Next.js 프로젝트를 분석해서 CLAUDE.md를 작성해줘&quot;
</code></pre>
<hr>
<h2>효과적인 CLAUDE.md 구조</h2>
<pre><code class="language-markdown"># 프로젝트명

한 줄 설명: 이 프로젝트가 무엇인지

## 기술 스택

- Next.js 15 (App Router, TypeScript)
- Tailwind CSS v3
- Supabase (Auth, PostgreSQL, Storage)
- Vercel (배포)
- pnpm (패키지 매니저)

## 프로젝트 구조

app/           ← 페이지 및 API 라우트
components/    ← 재사용 UI 컴포넌트
lib/           ← 유틸리티, DB 클라이언트
content/       ← MDX 콘텐츠 파일
public/        ← 정적 파일

## 코딩 규칙

- 컴포넌트: PascalCase (예: CourseNav.tsx)
- 함수/변수: camelCase
- 스타일: Tailwind 클래스만 사용 (인라인 스타일 금지)
- 서버 컴포넌트 기본, 클라이언트는 &quot;use client&quot; 명시
- TypeScript strict 모드

## 중요 사항

- pnpm 사용 (npm, yarn 사용 금지)
- .env 파일은 절대 커밋하지 않음
- 컴포넌트 수정 시 반드시 기존 스타일 패턴 확인 후 작업
</code></pre>
<hr>
<h2>실제 예시: 이 튜터 사이트의 CLAUDE.md</h2>
<pre><code class="language-markdown"># Skoolchef Tutorial

AI 바이브코딩 커리큘럼 사이트.
Notion에서 추출한 MDX 콘텐츠를 Next.js 15로 렌더링합니다.

## 기술 스택

- Next.js 15 App Router + TypeScript
- Tailwind CSS v3 + @tailwindcss/typography
- next-mdx-remote (MDX 렌더링)
- gray-matter (프론트매터 파싱)
- Vercel (배포)
- pnpm

## 콘텐츠 구조

- MDX 파일: content/courses/{slug}.mdx
- 이미지: public/images/notion/
- 챕터 순서: frontmatter의 order 필드로 결정
- 모듈 구분: order 0=기초, 1-5=Cursor, 6-9=ClaudeCode, 10+=Gemini

## 규칙

- pnpm dev로 개발 서버
- 새 챕터 추가 시 content/courses/에 MDX 파일 생성
- 이미지는 public/images/에 저장
</code></pre>
<hr>
<h2>고급: @import로 파일 분리</h2>
<p>CLAUDE.md가 길어지면 주제별로 분리할 수 있습니다.</p>
<pre><code class="language-markdown"># My Project

@docs/architecture.md
@docs/api-conventions.md
@docs/deployment.md
</code></pre>
<p>Claude Code가 자동으로 해당 파일들도 읽습니다.</p>
<hr>
<h2>CLAUDE.md 위치별 동작</h2>
<table>
<thead>
<tr>
<th>위치</th>
<th>적용 범위</th>
</tr>
</thead>
<tbody><tr>
<td><code>./CLAUDE.md</code> (프로젝트 루트)</td>
<td>현재 프로젝트</td>
</tr>
<tr>
<td><code>~/.claude/CLAUDE.md</code></td>
<td>모든 프로젝트 (개인 설정)</td>
</tr>
<tr>
<td><code>./subdir/CLAUDE.md</code></td>
<td>해당 하위 폴더 진입 시 추가 로드</td>
</tr>
</tbody></table>
<hr>
<h2>작성 팁</h2>
<p><strong>구체적으로 쓸수록 좋습니다.</strong></p>
<p>❌ 나쁜 예:</p>
<pre><code>- React 사용
- 코드 잘 작성
</code></pre>
<p>✅ 좋은 예:</p>
<pre><code>- React 19 + Next.js 15 App Router
- 서버 컴포넌트 기본, 이벤트 핸들러 있을 때만 &quot;use client&quot;
- Tailwind 클래스 정렬: layout → spacing → typography → color 순
- API 호출은 항상 lib/api/ 아래에 함수로 추상화
</code></pre>
<p><strong>자주 바뀌는 내용은 넣지 않습니다.</strong> 버전 번호나 임시 설정보다는 변하지 않는 규칙 중심으로 작성합니다.</p>
<hr>
<h2>확인</h2>
<p>CLAUDE.md 적용이 잘 되는지 확인하는 방법:</p>
<pre><code class="language-bash">claude &quot;현재 프로젝트의 기술 스택이 뭐야?&quot;
# → CLAUDE.md에 적힌 내용을 정확히 답해야 함
</code></pre>
<p>잘 답하면 CLAUDE.md가 정상적으로 로드된 겁니다.</p>
<hr>
<h2>8장 보강 프로세스 적용: CLAUDE.md 최소 규격(실전)</h2>
<p>유튜브 대본 분석 기준으로, 생산성이 높은 팀은 CLAUDE.md를 길게 쓰기보다 <strong>반복 의사결정에 필요한 최소 규격</strong>을 먼저 고정합니다.</p>
<h3>최소 규격 6항목 (먼저 고정)</h3>
<ol>
<li><strong>프로젝트 목적 1~2문장</strong></li>
<li><strong>기술 스택(버전 포함)</strong></li>
<li><strong>폴더 구조와 책임</strong></li>
<li><strong>코딩 규칙(네이밍/스타일/컴포넌트 정책)</strong></li>
<li><strong>금지 규칙(예: <code>.env</code> 커밋 금지)</strong></li>
<li><strong>검증 루틴(빌드/린트/테스트 순서)</strong></li>
</ol>
<h3>자주 실패하는 CLAUDE.md 패턴</h3>
<ol>
<li><p><strong>너무 추상적인 문장</strong></p>
<ul>
<li>예: &quot;코드 잘 작성&quot;</li>
<li>개선: &quot;서버 컴포넌트 기본, 이벤트 핸들러 시에만 <code>use client</code>&quot;</li>
</ul>
</li>
<li><p><strong>자주 바뀌는 임시 내용 과다</strong></p>
<ul>
<li>개선: 도메인 규칙/품질 기준 중심으로 유지</li>
</ul>
</li>
<li><p><strong>검증 단계 미기재</strong></p>
<ul>
<li>개선: &quot;수정 후 <code>pnpm build</code> → <code>pnpm dev</code> 확인&quot; 명시</li>
</ul>
</li>
<li><p><strong>폴더 책임 불명확</strong></p>
<ul>
<li>개선: <code>app/</code>, <code>components/</code>, <code>lib/</code>, <code>content/</code> 책임을 한 줄씩 고정</li>
</ul>
</li>
</ol>
<h3>07챕터 실행형 체크리스트 (DoD)</h3>
<ul>
<li><input disabled="" type="checkbox"> 루트 <code>CLAUDE.md</code> 생성 완료</li>
<li><input disabled="" type="checkbox"> 최소 규격 6항목 반영 완료</li>
<li><input disabled="" type="checkbox"> 금지 규칙(<code>.env</code>, 시크릿) 명시 완료</li>
<li><input disabled="" type="checkbox"> 검증 루틴 1개 이상 명시 완료</li>
<li><input disabled="" type="checkbox"> <code>claude &quot;현재 프로젝트 기술 스택이 뭐야?&quot;</code>로 로드 확인 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> 멀티파일 작업 시 적용할 규칙(우선순위, 검증 루프, 커밋 단위)</p>
</blockquote>