CLAUDE.md 작성법 완벽 가이드 - 클로드 코드 프로젝트 설정 최적화

13 조회

CLAUDE.md란 무엇인가

CLAUDE.md는 클로드 코드(Claude Code)가 매 대화 시작 시 자동으로 읽는 특수 설정 파일입니다. 프로젝트의 기술 스택, 빌드 명령어, 코딩 컨벤션, 아키텍처 결정 사항을 기록해두면, 클로드 코드가 매번 동일한 맥락을 유지하며 작업할 수 있습니다.

일반적인 README.md가 사람을 위한 문서라면, CLAUDE.md는 AI를 위한 프로젝트 설명서입니다. 코드만으로는 추론하기 어려운 프로젝트 고유의 맥락을 AI에게 전달하는 역할을 합니다.

/init으로 시작하기

클로드 코드에서 /init 명령을 실행하면 프로젝트 구조를 자동으로 분석해 CLAUDE.md 초안을 생성합니다:

cd your-project
claude
# 클로드 코드 실행 후
/init

클로드 코드가 분석하는 항목:

  • package.json, requirements.txt 등 의존성 파일
  • 기존 문서(README.md, CONTRIBUTING.md)
  • 디렉토리 구조와 파일 패턴
  • 설정 파일(tsconfig.json, .eslintrc 등)

생성된 초안을 기반으로 점진적으로 개선해나가는 것이 권장됩니다.

필수 포함 항목

1. 프로젝트 개요

Project Overview

Next.js 16 기반 CMS 블로그. MariaDB + Prisma ORM 사용. 도메인: https://example.com


프로젝트의 목적과 핵심 기술 스택을 간결하게 기술합니다. 클로드 코드가 전체적인 맥락을 빠르게 파악할 수 있습니다.

### 2. 명령어 섹션

```markdown

Commands

npm run dev # 개발 서버 시작 npm run build # 프로덕션 빌드 npm run lint # ESLint 검사 npm run db:migrate # DB 마이그레이션


클로드 코드가 빌드, 테스트, 배포 시 어떤 명령어를 사용해야 하는지 명시합니다. 이것이 없으면 클로드 코드가 매번 package.json을 읽어 명령어를 추론해야 합니다.

### 3. 코딩 컨벤션

```markdown

Coding Conventions

  • 파일명: kebab-case (api-response.ts)
  • 컴포넌트: PascalCase (PostCard)
  • 함수/변수: camelCase (getPosts)
  • TypeScript strict 모드 필수
  • any 타입 사용 금지

팀의 코딩 스타일을 명시하면 클로드 코드가 일관된 코드를 생성합니다.

### 4. 아키텍처 결정

```markdown

Architecture

  • Server Components 기본, 'use client'는 인터랙션 필요 시만
  • API 응답은 { success, data } 또는 { success, error } 형식
  • 인증: JWT (HttpOnly cookie) + API Key

코드만으로는 파악하기 어려운 아키텍처 의사결정을 기록합니다. 이것이 CLAUDE.md의 가장 중요한 역할입니다.

### 5. 금지 사항

```markdown

Do NOT

  • marked 라이브러리 사용 (react-markdown 대신 사용)
  • any 타입 추가
  • .env 파일 커밋
  • 인라인 스타일 작성 (Tailwind 사용)

클로드 코드가 피해야 할 안티패턴을 명시하면 실수를 예방할 수 있습니다.

계층 구조 활용

CLAUDE.md는 계층적 구조를 지원합니다. 프로젝트 루트와 하위 디렉토리에 각각 CLAUDE.md를 배치할 수 있으며, 클로드 코드는 가장 구체적인(중첩된) 파일을 우선 참조합니다.

project/
├── CLAUDE.md              # 프로젝트 전체 설정
├── src/
│   ├── CLAUDE.md          # src 디렉토리 규칙
│   ├── components/
│   │   └── CLAUDE.md      # 컴포넌트 작성 규칙
│   └── api/
│       └── CLAUDE.md      # API 라우트 규칙

예를 들어 src/api/CLAUDE.md에는 API 라우트 전용 규칙(인증 체크, 응답 포맷, Zod 검증 등)을 기록하고, 루트 CLAUDE.md에는 프로젝트 전반 규칙을 유지하는 방식입니다.

팀 협업에서의 활용

버전 관리에 포함

CLAUDE.md를 Git에 커밋하면 팀 전체가 동일한 AI 컨텍스트를 공유할 수 있습니다. 새로운 팀원이 합류해도 클로드 코드를 실행하는 것만으로 프로젝트의 컨벤션과 아키텍처를 자동으로 파악할 수 있습니다.

살아있는 문서로 유지

CLAUDE.md는 한 번 작성하고 끝나는 문서가 아닙니다. 프로젝트가 발전하면서 지속적으로 업데이트해야 합니다:

  • 새로운 아키텍처 결정이 내려질 때
  • 코딩 컨벤션이 변경될 때
  • 새로운 의존성이 추가될 때
  • 반복적으로 같은 실수가 발생할 때

작성 시 주의사항

간결하게 유지

모든 정보를 CLAUDE.md에 넣으려는 유혹을 피하세요. 상세한 스펙은 별도 문서를 가리키는 방식이 효과적입니다:

상세 요구사항은 docs/PRD.md 참조
API 스펙은 docs/api-spec.md 참조

실제 워크플로우 반영

이론적인 모범 사례가 아닌, 팀이 실제로 사용하는 워크플로우를 기록하세요. 현실과 동떨어진 규칙은 오히려 클로드 코드의 판단을 방해합니다.

부정형보다 긍정형

"X하지 마라"보다 "Y를 사용하라"가 더 효과적입니다. 다만 치명적인 안티패턴은 Do NOT 섹션에 명시적으로 나열하는 것이 좋습니다.

마무리

잘 작성된 CLAUDE.md는 클로드 코드의 성능을 극적으로 향상시킵니다. 프로젝트의 암묵적 지식을 명시적으로 문서화함으로써, AI가 시니어 개발자처럼 프로젝트의 맥락을 이해하고 일관된 코드를 생성할 수 있게 됩니다.

/init으로 시작하고, 작업하면서 점진적으로 개선하는 것이 가장 실용적인 접근입니다.

이 포스트가 도움이 되셨다면, 클로드 코드 입문 가이드와 MCP 설정 가이드도 확인해보세요.

공유