CLAUDE.md 템플릿 | Claude Code

1 CLAUDE.md가 뭔가요?

프로젝트 폴더에 넣어두면, Claude가 "이 프로젝트에선 이렇게 일해야 하는구나"를 자동으로 인식하는 규칙 파일입니다. 마치 새 팀원에게 건네는 업무 매뉴얼과 같습니다.

아래 템플릿에서 [대괄호] 안의 내용만 내 프로젝트에 맞게 바꾸면 됩니다. 또는 Claude에게 "CLAUDE.md 만들어줘"라고 요청해도 됩니다.

📁

어디에 파일을 만드나요? 내 프로젝트 폴더/CLAUDE.md 프로젝트 최상위 폴더(루트)에 CLAUDE.md라는 이름으로 파일을 만들면 Claude가 자동으로 읽습니다. 터미널에서 프로젝트 폴더에 들어간 뒤 claude를 실행하면 됩니다.

프로젝트용

이 프로젝트에만 적용

특정 프로젝트 폴더 안에 두는 규칙. 해당 프로젝트에서 Claude를 실행할 때만 읽힙니다.

프로젝트폴더/CLAUDE.md

글로벌 (전체 적용)

모든 프로젝트에 적용

"항상 한국어로 답해줘" 같은 나만의 기본 설정. 어느 프로젝트에서나 공통으로 적용됩니다.

~/.claude/CLAUDE.md

📊 CLAUDE.md가 있을 때 vs 없을 때

CLAUDE.md 없음

영어로 답변이 돌아옴
코드 수정 이유를 설명 안 해줌
중요한 파일을 실수로 건드림
매번 같은 규칙을 다시 말해야 함

CLAUDE.md 있음

항상 한국어로 답변
변경 사항마다 이유를 설명해줌
보호 파일은 자동으로 건드리지 않음
규칙을 기억하고 일관되게 작업

2 CLAUDE.md 템플릿

코드를 몰라도 바로 쓸 수 있는 간단 버전. [대괄호] 안만 바꾸세요

# 프로젝트: [프로젝트 이름]
# 예시: 팀 주간 보고서 자동화, 고객 데이터 정리 도구 등

## 이 프로젝트는
[한 줄 설명]
# 예시: 매주 월요일 팀 보고서를 자동으로 만들어주는 도구

## 답변 규칙
- 모든 답변과 주석은 한국어로 작성할 것
- 코드를 수정했다면 왜 바꿨는지 간단히 설명할 것
- 전문 용어를 사용할 경우 쉬운 말로 풀어서 함께 설명할 것
- 한 번에 하나씩만 변경하고, 변경 전 내용을 알려줄 것

## 절대 하지 마세요
- 파일 삭제 전 반드시 사용자 확인 받을 것
- .env 파일은 절대 수정하지 말 것
- [결제·개인정보 관련 코드는 수정 전 반드시 확인. 해당 없으면 삭제]
- 요청하지 않은 기능을 추가하지 말 것

## 자주 쓰는 명령어
- `[실행 명령어]` (예: npm start, python app.py)

## 주의사항
- [중요한 파일이나 폴더 이름 적기]
- [예: "data/ 폴더 안 파일은 수정하지 말 것"]

기술 스택과 개발 규칙까지 포함한 풀버전. 어떤 프로젝트에도 적용 가능

# Project: [프로젝트명]

## Overview
[프로젝트 한 줄 설명]

## Tech Stack
- Language: [언어]
- Framework: [프레임워크]
- Database: [DB]

## Project Structure
```
src/
├── components/   # UI 컴포넌트
├── pages/        # 페이지
├── utils/        # 유틸리티 함수
└── styles/       # 스타일
```

## Code Style Rules
- 커밋 메시지는 한글로 작성
- 모든 함수에 설명 주석 추가
- 테스트 코드 작성

## Do NOT
- 기존 테스트를 삭제하지 마세요
- 사용자 확인 없이 DB 구조를 수정하지 마세요
- .env 파일을 커밋하지 마세요
- 외부 라이브러리를 무단으로 추가하지 마세요

## Git Conventions
- 커밋: `feat: 기능 설명` / `fix: 버그 설명` / `refactor: 변경 설명`
- 브랜치: `feature/기능명`, `fix/버그명`
# ※ 커밋(commit) = 지금까지 바꾼 코드를 "이 시점의 버전"으로 저장하는 것

## Commands
- `[개발 서버 실행 명령어]` - 개발 서버 실행
- `[빌드 명령어]` - 빌드
- `[테스트 명령어]` - 테스트 실행
# ※ 예시: npm run dev, python manage.py runserver, go run main.go 등

## Important Notes
- [프로젝트별 주의사항을 여기에 작성]
- [예: "결제 관련 코드는 반드시 확인 후 수정"]

3 사용 팁 8가지

프로젝트 시작할 때 /init 먼저 실행. Claude가 프로젝트를 분석해 CLAUDE.md 초안을 자동으로 만들어줌
규칙은 구체적으로. "코드 정리해줘"보다 "함수마다 설명 주석 추가해줘"
자주 하는 실수 적어두기. Claude가 같은 실수 반복 안 함
명령어 정리해두기. Claude가 빌드/테스트 알아서 실행
CLAUDE.md는 500줄 이내로 유지. 너무 길면 핵심을 놓칠 수 있음
.claudeignore 파일로 Claude가 읽지 않을 파일/폴더 지정 가능
CLAUDE.md에서 파일 경로를 적으면 Claude가 자동으로 찾아봄 (예: docs/api-spec.md를 참고할 것)
[대괄호] 안의 내용은 본인 프로젝트에 맞게 바꿔 쓰세요

4 사용 방법 3단계

1 새 프로젝트: /init으로 자동 생성

프로젝트 폴더에서 Claude를 실행한 뒤 /init을 입력하면 Claude가 프로젝트 구조를 분석하고 CLAUDE.md 초안을 직접 만들어줍니다.

                        cd my-project
claude
> /init
                    

✓ /init 실행 결과

Claude가 폴더 구조, 파일 유형, 기존 설정을 읽고 "이 프로젝트에 맞는 CLAUDE.md를 작성했습니다"라고 응답합니다. 생성된 파일을 열어 내용을 확인하고 필요한 부분만 수정하면 됩니다.

2 기존 프로젝트: 템플릿 붙여넣기

이미 진행 중인 프로젝트라면 위 템플릿을 복사해 프로젝트 폴더에 CLAUDE.md 파일로 저장하세요.

                        # 프로젝트 폴더에서 파일 생성
touch CLAUDE.md
# 그 다음 위 템플릿을 붙여넣고 [대괄호] 내용을 수정
                    

3 Claude에게 규칙 추가 요청

작업 중 새로운 규칙이 필요하면 Claude에게 직접 요청하면 됩니다.

                        > CLAUDE.md에 다음 규칙 추가해줘:
> - 모든 API 응답에 타임스탬프 포함
                    

5 비개발자가 자주 넣는 규칙 TOP 5

1

한국어로 답변

모든 답변과 주석은 한국어로 작성할 것

2

코드 설명 의무화

코드 수정 시 왜 바꿨는지 간단한 주석 추가

3

확인 후 수정

데이터베이스 구조 변경 전 반드시 사용자 확인 받을 것

4

파일 보호

.env 파일은 절대 수정하지 말 것

5

스타일 유지

기존 코드 스타일과 동일한 패턴을 유지할 것