📋 CLAUDE.md 마스터 — 프로젝트 설명서 작성법

CLAUDE.md = AI에게 주는 업무 매뉴얼

팀에 새 동료가 합류하면 뭘 해주시나요? 아마 “우리 팀 업무 가이드” 같은 걸 건네줄 거예요. “보고서는 이 양식으로 써, 배포는 이 절차를 따라, 이 폴더에 손대지 마” — 이런 것들이요.

CLAUDE.md가 바로 그 역할이에요. Claude Code가 프로젝트에 “합류”할 때 가장 먼저 읽는 문서예요. 이 파일에 프로젝트 정보, 규칙, 주의사항을 적어두면 Claude Code가 자동으로 읽고 따라요.

왜 필요한가요?

“그냥 대화하면서 설명하면 안 돼요?” 라고 생각할 수 있어요. 물론 가능해요. 하지만 3가지 문제가 있거든요.

첫 CLAUDE.md 만들기

CLAUDE.md를 만드는 건 정말 간단해요. 프로젝트 루트 폴더에 CLAUDE.md라는 파일을 만들면 끝이에요. 이름이 꼭 CLAUDE.md여야 해요 — 대소문자도 정확히 맞춰야 해요.

방법 1: /init으로 자동 생성 (가장 쉬움)

Claude Code에서 /init 명령을 실행하면 프로젝트를 분석해서 CLAUDE.md를 자동 생성해줘요. 처음 시작할 때 가장 편한 방법이에요.

/init

이렇게 하면 Claude Code가 프로젝트의 파일 구조, package.json, 설정 파일 등을 분석해서 CLAUDE.md 초안을 만들어줘요. 여기서 필요한 부분만 수정하면 돼요.

방법 2: 말로 시켜서 생성

이 프로젝트를 분석해서 CLAUDE.md를 만들어줘.
빌드 방법, 파일 구조, 코딩 규칙을 포함해줘.

방법 3: 직접 작성

메모장이나 VS Code에서 직접 작성할 수도 있어요. 아래 기본 템플릿을 복사해서 시작하세요.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 [한 줄 설명]입니다.

## 기술 스택
- 프레임워크: Next.js 14
- 스타일: Tailwind CSS
- 언어: TypeScript (strict 모드)

## 명령어
```bash
npm run dev       # 개발 서버
npm run build     # 프로덕션 빌드
npm run lint      # 코드 검사
```

## 파일 구조
- src/app/        — 페이지
- src/components/ — 재사용 컴포넌트
- src/lib/        — 유틸리티 함수
- public/         — 정적 파일

## 코딩 규칙
- 컴포넌트: export default function (화살표 함수 X)
- 스타일: Tailwind 클래스만 사용
- 상태 관리: zustand
- import 순서: React > Next > 외부 라이브러리 > 내부 모듈

## 주의사항
- .env 파일을 커밋하지 마세요
- node_modules/ 수정 금지

CLAUDE.md 파일의 우선순위

CLAUDE.md는 한 곳에만 있는 게 아니에요. 여러 위치에 있을 수 있고, 각각 다른 범위에서 적용돼요. 마치 회사 규정 → 팀 규정 → 개인 설정 순서처럼, 범위가 넓은 것에서 좁은 것 순으로 합쳐져요.

대부분의 경우, 여러분이 신경 써야 할 건 2번(전역)과 3번(프로젝트 루트)뿐이에요. 나머지는 큰 프로젝트에서나 쓰는 거예요.

@import로 다른 파일 참조하기

CLAUDE.md가 점점 길어지면 읽기 어려워질 수 있어요. 이때 @import를 사용하면 내용을 여러 파일로 나눠서 관리할 수 있어요.

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 이커머스 플랫폼입니다.

@import docs/coding-rules.md
@import docs/api-guide.md
@import docs/deployment.md

이렇게 하면 Claude Code가 CLAUDE.md를 읽을 때,@import된 파일들도 함께 읽어요. 마치 하나의 큰 문서처럼 처리하는 거예요.

언제 @import를 쓰면 좋을까?

프로젝트/
├── CLAUDE.md                  # 메인 (개요 + @import 목록)
├── docs/
│   ├── coding-rules.md        # 코딩 규칙 상세
│   ├── api-guide.md           # API 연동 가이드
│   └── deployment.md          # 배포 절차
└── src/
    └── CLAUDE.md              # src 폴더 전용 규칙

.claude/rules/ — 조건부 규칙

“.ts 파일을 수정할 때만 이 규칙을 적용해줘” 같은 조건부 규칙을 만들 수 있어요. 프로젝트 루트에 .claude/rules/ 폴더를 만들고, 그 안에 규칙 파일을 넣으면 돼요.

폴더 구조

프로젝트/
├── .claude/
│   └── rules/
│       ├── typescript.md       # .ts 파일 작업 시 적용
│       ├── testing.md          # 테스트 파일 작업 시 적용
│       └── deployment.md       # 배포 관련 작업 시 적용
├── CLAUDE.md
└── src/

규칙 파일 예시

각 규칙 파일 상단에 --- 사이에 메타데이터를 넣어요.globs로 어떤 파일에 적용할지,description으로 간단한 설명을 적어요.

---
description: TypeScript 파일 작성 규칙
globs: "**/*.ts,**/*.tsx"
---

# TypeScript 규칙

- strict 모드: any 타입 사용 금지
- 인터페이스는 I 접두사 없이 작성 (UserProps O, IUserProps X)
- enum 대신 const object + as const 사용
- 함수 반환 타입 명시 필수

---
description: 테스트 파일 작성 규칙
globs: "**/*.test.ts,**/*.spec.ts"
---

# 테스트 규칙

- 테스트 프레임워크: Jest + React Testing Library
- describe > it 구조 사용
- 테스트 이름은 한국어로 작성
- mocking: jest.mock() 사용, 외부 라이브러리 mock 필수

이렇게 설정해두면, Claude Code가 .ts 파일을 수정할 때 자동으로 TypeScript 규칙을 참고하고,.test.ts 파일을 작성할 때 테스트 규칙을 참고해요. 매번 “strict 모드야, any 쓰지 마” 안 말해도 돼요.

프로젝트 유형별 CLAUDE.md 예시

어떤 프로젝트를 하느냐에 따라 CLAUDE.md 내용이 달라져요. 실제로 바로 쓸 수 있는 예시 3개를 준비했어요. 자기 프로젝트에 맞는 걸 복사해서 수정하세요.

# CLAUDE.md

## 프로젝트
회사 홈페이지. 5페이지 (홈, 소개, 서비스, 블로그, 문의).

## 기술 스택
- Next.js 14 (App Router)
- Tailwind CSS
- TypeScript

## 명령어
- 개발: npm run dev (포트 3000)
- 빌드: npm run build
- 배포: git push → Vercel 자동 배포

## 파일 구조
- app/           — 페이지 (App Router)
- components/ui/ — 재사용 UI 컴포넌트
- lib/           — 유틸 함수
- public/        — 이미지, 폰트

## 디자인 규칙
- 폰트: Pretendard
- 메인 색상: #171a20 (near-black)
- 강조 색상: #3e6ae1 (blue)
- 모서리: rounded-xl (카드), rounded-md (버튼)
- 여백: section 간 py-20

## 코딩 규칙
- 컴포넌트: export default function
- CSS: Tailwind만 (인라인 style 금지)
- 이미지: next/image 필수
- 한국어 콘텐츠

## 주의
- .env.local 커밋 금지
- public/에 10MB 이상 파일 올리지 마

# CLAUDE.md

## 프로젝트
업무 자동화 스크립트 모음. DART 공시 수집, 엑셀 처리, 메일 발송.

## 환경
- Python 3.12
- 가상환경: .venv (python -m venv .venv)
- 패키지: requirements.txt

## 실행
```bash
source .venv/bin/activate    # Mac/Linux
.venv\Scripts\activate      # Windows
pip install -r requirements.txt
python main.py
```

## 파일 구조
- scripts/     — 개별 자동화 스크립트
- data/        — 입력 데이터 (CSV, Excel)
- output/      — 실행 결과 (gitignore)
- utils/       — 공통 유틸 함수
- .env         — API 키 (gitignore)

## API 연동
- DART: https://opendart.fss.or.kr/guide/main.do
- Gemini: https://ai.google.dev/docs
- 모든 API 키는 .env에서 읽기

## 규칙
- 에러 처리: try/except 필수
- 로깅: print 대신 logging 모듈 사용
- 타입 힌트: 함수 시그니처에 필수
- 큰 파일(>10MB)은 output/에 저장

# CLAUDE.md

## 프로젝트
Claude Code 학습용 실험 프로젝트.
자유롭게 테스트하는 공간.

## 환경
- Node.js 22
- 별도 프레임워크 없음

## 규칙
- 자유롭게 실험 (깨져도 괜찮음)
- 결과물은 output/ 폴더에 저장
- 한국어로 주석 작성

## 메모
- 이 프로젝트에서 실험한 내용은 나중에 실전 프로젝트에 적용 예정

직접 해보기

지금 당장 CLAUDE.md를 만들어보세요. 5분이면 돼요.

cd 내-프로젝트-폴더
claude

/init

~/.claude/CLAUDE.md 파일을 만들어줘.
내용:
- 한국어로 답변해줘
- 커밋 메시지는 conventional commit 형식
- 코드 주석은 한국어로

# CLAUDE.md에 "컴포넌트는 화살표 함수로"라고 적어뒀다면:

버튼 컴포넌트 만들어줘.

# → Claude Code가 화살표 함수로 만들어야 해요.
# 안 그러면 CLAUDE.md를 제대로 읽지 못한 거예요.

확인 체크리스트

CLAUDE.md 작성 팁 + 출처

CLAUDE.md를 더 효과적으로 활용하기 위한 실전 팁들이에요.