완벽한 CLAUDE.md 파일을 작성하는 방법 (2026)

2026년 완벽한 CLAUDE.md 파일을 작성하는 방법

CLAUDE.md 파일은 Claude Code를 사용하는 프로젝트에 추가할 수 있는 가장 영향력 있는 요소입니다. 이는 Claude가 해당 저장소에서 세션을 시작할 때마다 읽는 지속적인 시스템 프롬프트 역할을 합니다. 잘 작성된 CLAUDE.md는 실수를 획기적으로 줄이고, 코딩 표준을 강제하며, 매번 설명할 필요 없이 Claude가 프로젝트의 아키텍처를 이해하도록 돕습니다.

이 가이드는 템플릿과 실제 사례를 통해 효과적인 CLAUDE.md 파일을 작성하는 데 필요한 모든 내용을 다룹니다.

CLAUDE.md란 무엇인가요?

CLAUDE.md는 프로젝트 루트(또는 전역 설정을 위한 ~/.claude/CLAUDE.md)에 위치하는 마크다운 파일입니다. Claude Code가 디렉토리에서 실행되면 자동으로 이 파일을 읽고 모든 상호작용의 컨텍스트로 사용합니다.

이 파일의 역할은 다음과 같습니다:

• 인간 개발자가 아닌 AI 어시스턴트를 위한 README
• 세션이 바뀌어도 유지되는 지속적인 시스템 프롬프트
• Claude가 실제로 준수하는 코딩 표준 문서

CLAUDE.md 배치 위치

Claude Code는 다음 순서대로 CLAUDE.md 파일을 검색합니다:

위치	범위	사용 사례
~/.claude/CLAUDE.md	Global (모든 프로젝트)	개인 선호도, 기본 컨벤션
./CLAUDE.md	프로젝트 루트	프로젝트 전용 컨텍스트 및 규칙
./src/CLAUDE.md	하위 디렉토리	모듈별 지침

검색된 모든 파일은 병합되며, 더 구체적인 위치의 파일이 우선권을 갖습니다.

필수 섹션

좋은 CLAUDE.md 파일에는 다음 섹션들이 포함되어야 합니다:

1. Project Overview (프로젝트 개요)

Claude가 추측하지 않도록 프로젝트가 무엇인지 2~3문장 내외로 알려주세요.

# Project Overview
이 프로젝트는 Next.js 14 (App Router), TypeScript, Tailwind CSS로 구축된 
AI 미디어 생성용 SaaS 플랫폼입니다. 백엔드는 인증 및 데이터베이스를 위해 
Supabase를 사용하고, 결제는 Stripe를 사용하며, AI 모델 추론을 위한 
커스텀 API 레이어를 갖추고 있습니다.

2. Tech Stack (기술 스택)

주요 기술, 프레임워크, 라이브러리를 모두 나열하세요. 버전을 명시하는 것이 좋습니다.

# Tech Stack
- Framework: Next.js 14.2 (App Router, NOT Pages Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS 3.4 + shadcn/ui components
- Database: PostgreSQL via Supabase
- ORM: Prisma 5.x
- Auth: NextAuth.js v5 (Auth.js)
- Payments: Stripe (subscriptions + one-time)
- State: Zustand for client state
- Forms: React Hook Form + Zod validation
- Testing: Vitest + React Testing Library
- Package manager: pnpm (NOT npm or yarn)

3. Project Structure (프로젝트 구조)

Claude가 파일을 찾고 생성할 위치를 알 수 있도록 주요 디렉토리를 나타내세요.

# Project Structure
- src/app/ - Next.js App Router 페이지 및 레이아웃
- src/app/api/ - API 라우트 핸들러
- src/app/[locale]/ - 다국어 지원 라우트
- src/components/ - 재사용 가능한 React 컴포넌트
- src/components/ui/ - shadcn/ui 기본 컴포넌트 (수정 금지)
- src/lib/ - 유틸리티 함수, API 클라이언트, 헬퍼
- src/hooks/ - 커스텀 React 훅
- src/types/ - TypeScript 타입 정의
- src/config/ - 앱 설정 파일
- prisma/ - 데이터베이스 스키마 및 마이그레이션
- content/ - MDX 블로그 아티클
- messages/ - i18n 번역 JSON 파일
- public/ - 정적 자산(assets)

4. Coding Conventions (코딩 컨벤션)

가장 중요한 섹션입니다. 코딩 표준을 명시적으로 작성하세요.

# Coding Conventions

## General
- Hook을 사용하는 함수형 컴포넌트 사용 (클래스 컴포넌트 제외)
- default export보다 named export 선호
- @/ 접두사를 사용한 절대 경로 임포트 (예: @/components/Button)
- 모든 파일은 TypeScript(.ts/.tsx) 사용, 순수 JavaScript 금지

## Naming
- Components: PascalCase (예: UserProfile.tsx)
- Hooks: "use" 접두어가 붙은 camelCase (예: useAuth.ts)
- Utilities: camelCase (예: formatDate.ts)
- Types: 서술적인 이름의 PascalCase (예: UserProfile, ApiResponse)
- Constants: UPPER_SNAKE_CASE
- CSS classes: Tailwind 유틸리티 사용, 커스텀 CSS 지양

## Components
- 파일당 하나의 컴포넌트
- 컴포넌트 상단에 Props 인터페이스 정의
- React.FC 사용은 가급적 피하고 명시적인 반환 타입 선호
- 함수 시그니처에서 Props 구조 분해 할당
- 필요한 경우에만 "use client" 지시어 사용

## Error Handling
- API 라우트 및 서버 액션에서 try/catch 사용
- 구조화된 에러 응답 반환: { error: string, code: number }
- 클라이언트에 내부 에러 디테일을 노출하지 말 것
- console.error를 사용하여 서버 측 에러 로깅

## Imports Order
1. React/Next.js 임포트
2. 서드파티 라이브러리 임포트
3. 내부 임포트 (@/)
4. 타입 임포트
5. 상대 경로 임포트

5. Important Rules and Constraints (중요 규칙 및 제약 조건)

Claude가 절대 어겨서는 안 되는 엄격한 규칙을 배치하는 곳입니다.

# Important Rules
- src/components/ui/ 파일을 절대 수정하지 말 것 (shadcn/ui 생성 파일임)
- .env 파일을 커밋하거나 비밀값을 하드코딩하지 말 것
- 데이터 변경(mutations) 시 API 라우트가 아닌 Server Actions를 항상 사용할 것
- 훅이나 이벤트 핸들러를 사용할 때는 반드시 "use client"를 추가할 것
- 태스크를 완료하기 전에 항상 `pnpm lint`를 실행할 것
- 데이터베이스 마이그레이션은 반드시 `pnpm prisma migrate dev`로 생성할 것
- 기존 마이그레이션 파일을 삭제하거나 수정하지 말 것
- 모든 유저 노출 텍스트는 i18n 시스템(useTranslations)을 사용할 것
- `any` 타입을 절대 사용하지 말 것. 타입을 알 수 없는 경우 `unknown` 사용

6. Common Commands (일반 명령어)

Claude가 프로젝트를 빌드, 테스트, 린트하는 데 필요한 명령어를 나열하세요.

# Common Commands
- `pnpm dev` - 개발 서버 시작
- `pnpm build` - 프로덕션 빌드
- `pnpm lint` - ESLint 실행
- `pnpm typecheck` - TypeScript 타입 체크 실행
- `pnpm test` - 테스트 스위트 실행
- `pnpm test:watch` - 워치 모드로 테스트 실행
- `pnpm prisma generate` - Prisma 클라이언트 재생성
- `pnpm prisma migrate dev` - 마이그레이션 생성 및 실행
- `pnpm prisma studio` - 데이터베이스 브라우저 열기

7. API and Data Patterns (API 및 데이터 패턴)

애플리케이션에서 데이터가 흐르는 방식을 문서화하세요.

# Data Patterns

## API Routes
API 라우트는 src/app/api/에 위치합니다. Next.js Route Handler 형식을 사용합니다:
export async function POST(request: Request) { ... }

## Server Actions
데이터 변경 시 API 라우트보다 Server Actions를 선호합니다.
Server Actions는 src/lib/actions/에 위치하며 "use server" 지시어를 사용합니다.

## Database Queries
모든 DB 쿼리는 Prisma를 거칩니다. 클라이언트는 src/lib/db.ts에 있습니다.
컴포넌트에서 직접 데이터베이스를 쿼리하지 마세요.

## Authentication
src/lib/auth.ts의 auth() 헬퍼를 사용하여 현재 세션을 가져옵니다.
보호된 API 라우트는 핸들러 상단에서 인증을 확인해야 합니다.

전체 템플릿

적용 가능한 전체 CLAUDE.md 템플릿입니다:

# Project Overview
[프로젝트를 설명하는 2-3개 문장]

# Tech Stack
- Framework: [프레임워크 및 버전]
- Language: [언어 및 버전]
- Styling: [CSS 접근 방식]
- Database: [데이터베이스]
- Auth: [인증 솔루션]
- Testing: [테스트 프레임워크]
- Package manager: [pnpm/npm/yarn]

# Project Structure
- src/app/ - [설명]
- src/components/ - [설명]
- src/lib/ - [설명]
[필요에 따라 추가]

# Coding Conventions
[코딩 표준]

# Important Rules
- NEVER [중요 제약 사항]
- ALWAYS [필수 실천 사항]
[필요에 따라 추가]

# Common Commands
- `[명령어]` - [설명]
[필요에 따라 추가]

# Data Patterns
[앱의 데이터 흐름 방식]

# Known Issues
[Claude가 알아야 할 주의 사항]

고급 팁

하위 디렉토리에 CLAUDE.md 사용

모노레포나 복잡한 프로젝트의 경우, 하위 디렉토리에 CLAUDE.md 파일을 추가하세요:

project/
  CLAUDE.md           # 루트 레벨 프로젝트 컨텍스트
  packages/
    api/
      CLAUDE.md       # API 관련 컨벤션
    web/
      CLAUDE.md       # 프런트엔드 관련 컨벤션

좋은 패턴의 예시 포함

컨벤션을 설명만 하지 말고 직접 보여주세요:

# Example: Creating a New API Route

새로운 API 라우트의 패턴은 다음과 같습니다:

\`\`\`typescript
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  try {
    const data = await db.item.findMany({
      where: { userId: session.user.id },
    });
    return NextResponse.json(data);
  } catch (error) {
    console.error("Failed to fetch items:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}
\`\`\`

주요 파일 참조

Claude가 읽어야 할 중요한 파일들을 지정해 주세요:

# Key Files
- src/lib/auth.ts - 인증 설정 및 헬퍼
- src/lib/db.ts - 데이터베이스 클라이언트 및 연결
- src/types/index.ts - 공통 타입 정의
- .env.example - 필수 환경 변수

최신 상태 유지

CLAUDE.md를 살아있는 문서로 취급하세요. 컨벤션이 변경되면 파일을 업데이트하세요. Claude가 실수를 하면, 그것을 방지하기 위한 규칙을 추가하세요.

피해야 할 일반적인 실수

1. 너무 모호함: "좋은 코딩 관행을 사용하라"는 말은 Claude에게 아무것도 알려주지 않습니다. 구체적으로 작성하세요.
2. 너무 김: Claude에게는 컨텍스트 윈도우 한계가 있습니다. 500줄 이하로 유지하세요.
3. 일관성 없음: 한 곳에서는 "named export를 사용하라"고 하고 예제에서는 default export를 사용하지 마세요.
4. 부정적 규칙 누락: 무엇을 해야 하는지뿐만 아니라, 무엇을 하지 말아야 하는지도 알려주세요.
5. 기술 스택 생략: Claude가 잘못된 프레임워크 버전을 가정할 수 있습니다.

효과 측정

CLAUDE.md를 추가한 후, Claude가 다음과 같이 행동하는지 확인하세요:

• 매번 상기시키지 않아도 네이밍 컨벤션을 따르는가
• 파일을 올바른 디렉토리에 배치하는가
• 올바른 임포트와 패턴을 사용하는가
• "Important Rules"에 나열된 실수를 피하는가
• 올바른 빌드/린트 명령어를 실행하는가

Claude가 같은 실수를 반복한다면, CLAUDE.md에 더 명시적인 규칙을 추가하세요.

결론

잘 만든 CLAUDE.md 파일은 Claude Code를 평범한 AI 어시스턴트에서 프로젝트를 이해하는 컨텍스트 기반 팀원으로 바꿔놓습니다. 30분만 투자해 양질의 파일을 작성하면, 수 시간의 수정 작업과 반복적인 설명을 아낄 수 있습니다.

이미지, 비디오, 오디오 또는 말하는 아바타와 같은 AI 미디어 생성 기능이 필요한 애플리케이션을 구축하고 있다면, Hypereal AI는 단일 API를 통해 이 모든 것을 제공합니다. 사용한 만큼 지불하는 요금제, 빠른 생성 속도, 창의적인 작업에 대한 콘텐츠 제한이 없는 Hypereal AI는 귀하의 제품에 AI 미디어를 추가하는 가장 쉬운 방법입니다.