CLAUDE.md 파일로 AI에게 규칙 알려주기

Table of Contents

클로드 코드가 매번 “이 프로젝트가 어떤 프로젝트인가요?”라고 묻는다면?

클로드 코드를 쓰다 보면 답답한 순간이 생깁니다. 매번 새 대화를 시작할 때마다 “이 프로젝트는 React를 씁니다”, “들여쓰기는 2칸으로 해주세요”, “테스트 명령어는 npm test입니다”처럼 같은 말을 반복해야 하죠. 마치 새로 들어온 팀원에게 프로젝트 온보딩을 매일 반복하는 느낌이랄까요.

이 문제를 한 번에 해결해 주는 것이 바로 CLAUDE.md 파일입니다. 이 파일 하나를 제대로 만들어두면, 클로드 코드가 프로젝트를 열 때마다 자동으로 읽고 “아, 이런 프로젝트구나”를 스스로 파악합니다. 클로드 코드 설정의 핵심이자, 컨텍스트(context, AI가 대화에서 기억하는 맥락) 관리의 시작점입니다.

CLAUDE.md 파일이란 무엇인가요?

CLAUDE.md는 프로젝트 폴더 안에 만들어두는 마크다운(Markdown) 형식의 텍스트 파일입니다. 클로드 코드 세션이 시작될 때 이 파일의 내용이 자동으로 AI의 ‘시스템 지침’으로 로드(load, 불러오기)됩니다.

쉽게 말해, AI 팀원에게 미리 전달하는 프로젝트 온보딩 문서입니다.

“CLAUDE.md는 클로드 코드 프로젝트에 추가할 수 있는 가장 효과적인 도구입니다. 명확한 지침 20~30줄만 넣어도 클로드가 ‘대충 짐작’에서 ‘프로젝트를 완벽히 파악’하는 수준으로 달라집니다.” — builder.io 가이드

CLAUDE.md 파일은 어디에 만들어야 할까요?

클로드 코드는 여러 위치의 CLAUDE.md 파일을 계층적으로 읽습니다. 초보자라면 우선 프로젝트 루트(프로젝트 최상위 폴더) 에 하나만 만들면 충분합니다.

위치	경로 예시	적용 범위
프로젝트 루트	`내프로젝트/CLAUDE.md`	해당 프로젝트 전체, 팀 공유 가능
사용자 전용	`내프로젝트/.claude/CLAUDE.md`	본인 개인 설정만 (팀 공유 제외)
전역(글로벌)	`~/.claude/CLAUDE.md`	모든 프로젝트에 공통 적용
하위 폴더	`내프로젝트/src/CLAUDE.md`	해당 폴더 작업 시에만 적용

팀 프로젝트라면 프로젝트 루트의 CLAUDE.md를 Git(깃, 코드 버전 관리 도구)에 함께 올려 팀원 전체가 같은 규칙을 공유할 수 있습니다.

CLAUDE.md에 어떤 내용을 담아야 할까요?

아래 항목들을 필요에 맞게 골라 담으면 됩니다. 모두 넣을 필요는 없습니다.

프로젝트 개요: 이 프로젝트가 무엇을 하는 앱/사이트인지 한두 줄 설명
기술 스택: 사용하는 언어, 프레임워크(React, Django 등), 주요 라이브러리
폴더 구조: 주요 폴더의 역할 설명 (예: src/ = 소스 코드, tests/ = 테스트 파일)
자주 쓰는 명령어: 빌드, 실행, 테스트 명령어 (예: npm run dev, pytest)
코딩 컨벤션(convention, 규칙): 들여쓰기, 네이밍 규칙, 주석 스타일 등
하지 말아야 할 것: AI가 자주 실수하는 패턴, 피해야 할 방법론
배포(deploy) 관련 정보: 운영 환경, 주의 사항

💡 팁: CLAUDE.md는 너무 길면 오히려 독입니다. 200줄 이내로 간결하게 유지하는 것이 좋습니다. 파일 전체가 AI의 컨텍스트 창(context window, AI가 한 번에 읽을 수 있는 분량)을 차지하기 때문입니다.

실전 CLAUDE.md 예시: 이렇게 작성해보세요

아래는 간단한 웹 프로젝트를 위한 CLAUDE.md 예시입니다.

# 프로젝트 개요
온라인 독서 기록 앱. 사용자가 읽은 책을 기록하고 감상문을 저장하는 서비스.

## 기술 스택
- Frontend: React 18, TypeScript
- Backend: Node.js + Express
- DB: PostgreSQL

## 주요 명령어
- 개발 서버 실행: `npm run dev`
- 테스트 실행: `npm test`
- 빌드: `npm run build`

## 코딩 규칙
- 들여쓰기: 스페이스 2칸
- 컴포넌트는 함수형으로 작성 (클래스형 사용 금지)
- 변수명은 영어 카멜케이스(camelCase) 사용

## 금지 사항
- `any` 타입 사용 금지
- console.log는 커밋 전 반드시 제거

이렇게 작성하면 클로드 코드가 이 파일을 읽고, 매번 물어보지 않고도 프로젝트에 맞는 코드를 작성해 줍니다.

/init 명령어로 자동 생성하는 방법

CLAUDE.md를 처음부터 직접 쓰기 어렵다면, 클로드 코드 터미널에서 /init 명령어를 실행해보세요. 클로드 코드가 현재 프로젝트 폴더를 분석해서 CLAUDE.md 초안을 자동으로 만들어줍니다. 생성된 내용을 검토하고 불필요한 부분은 삭제하거나 내용을 보완하면 됩니다.

/init

자주 묻는 질문(FAQ)

Q. CLAUDE.md 파일이 없으면 클로드 코드가 제대로 작동하지 않나요?

A. 없어도 작동은 합니다. 하지만 CLAUDE.md가 없으면 클로드 코드는 대화할 때마다 프로젝트 맥락을 새로 파악해야 합니다. 특히 프로젝트가 클수록, 반복 작업이 많을수록 CLAUDE.md의 효과가 커집니다.

Q. 개인 설정과 팀 공유 설정을 분리할 수 있나요?

A. 가능합니다. 프로젝트 루트의 CLAUDE.md는 Git에 올려 팀 전체가 공유하고, .claude/CLAUDE.md는 .gitignore(깃이 무시할 파일 목록)에 추가해서 개인용 설정으로 따로 관리하면 됩니다.

Q. CLAUDE.md를 수정하면 바로 반영되나요?

A. 네. 다음 클로드 코드 세션을 시작하면 수정된 내용이 즉시 반영됩니다. 진행 중인 대화에서는 /clear 명령어로 컨텍스트를 초기화하거나 새 대화를 시작하면 됩니다.

한 줄 요약: CLAUDE.md는 클로드 코드에게 “이 프로젝트의 규칙”을 한 번에 알려주는 온보딩 문서로, 한 번만 잘 작성해두면 반복 설명 없이 일관된 AI 협업이 가능합니다.