공개 문서
content/courses/07-claude-md-setup.mdx
아래는 content/courses/07-claude-md-setup.mdx 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
---
title: "CLAUDE.md 설정"
slug: "07-claude-md-setup"
description: "프로젝트 맥락을 AI에게 전달하는 CLAUDE.md 작성법"
order: 7
date: "2026-03-10"
level: 1
draft: false
---
# 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 "현재 프로젝트 기술 스택이 뭐야?"`로 로드 확인 완료
> **다음 챕터 입력값:** 멀티파일 작업 시 적용할 규칙(우선순위, 검증 루프, 커밋 단위)
공개 문서 변환 코드 (HTML)
<hr>
<h2>title: "CLAUDE.md 설정"
slug: "07-claude-md-setup"
description: "프로젝트 맥락을 AI에게 전달하는 CLAUDE.md 작성법"
order: 7
date: "2026-03-10"
level: 1
draft: false</h2>
<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는 새 팀원에게 주는 온보딩 문서입니다.
"이 프로젝트는 이렇게 동작하고, 이 규칙을 따라야 해."</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 "이 Next.js 프로젝트를 분석해서 CLAUDE.md를 작성해줘"
</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 클래스만 사용 (인라인 스타일 금지)
- 서버 컴포넌트 기본, 클라이언트는 "use client" 명시
- 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
- 서버 컴포넌트 기본, 이벤트 핸들러 있을 때만 "use client"
- 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 "현재 프로젝트의 기술 스택이 뭐야?"
# → 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>예: "코드 잘 작성"</li>
<li>개선: "서버 컴포넌트 기본, 이벤트 핸들러 시에만 <code>use client</code>"</li>
</ul>
</li>
<li><p><strong>자주 바뀌는 임시 내용 과다</strong></p>
<ul>
<li>개선: 도메인 규칙/품질 기준 중심으로 유지</li>
</ul>
</li>
<li><p><strong>검증 단계 미기재</strong></p>
<ul>
<li>개선: "수정 후 <code>pnpm build</code> → <code>pnpm dev</code> 확인" 명시</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 "현재 프로젝트 기술 스택이 뭐야?"</code>로 로드 확인 완료</li>
</ul>
<blockquote>
<p><strong>다음 챕터 입력값:</strong> 멀티파일 작업 시 적용할 규칙(우선순위, 검증 루프, 커밋 단위)</p>
</blockquote>