핵심 요약 (Summary)
CLAUDE.md는 Claude Code가 프로젝트에 진입할 때 가장 먼저 자동으로 읽는 마크다운 파일입니다. 프로젝트의 구조, 컨벤션, 주의사항, 작업 원칙을 이 파일에 담아두면 Claude는 매 대화마다 동일한 맥락을 가지고 작업을 시작합니다. 팀의 암묵적인 규칙을 문서화하는 수단이자, Claude에게 건네는 "이 프로젝트에서 일하는 방법"에 대한 가이드북입니다.
왜 필요한가요? (Why)
Claude Code는 대화 세션이 끝나면 이전 대화의 내용을 기억하지 못합니다. 어제 "우리 프로젝트는 함수형 컴포넌트만 써야 해", "이모지는 절대 쓰지 마"라고 말했더라도, 새 세션을 시작하면 Claude는 그 사실을 모릅니다.
매번 같은 설명을 반복하는 것은 비효율적이고, 설명을 빠뜨리면 Claude가 의도와 다른 방식으로 작업할 수 있습니다.
CLAUDE.md는 이 문제를 해결합니다. 한 번 잘 써두면 새 세션을 시작할 때마다 Claude가 파일을 읽고 프로젝트의 맥락을 자동으로 파악합니다. 설명을 반복하지 않아도 되고, 팀 전체가 동일한 기준으로 Claude를 활용할 수 있습니다.
어디에 두나요?
CLAUDE.md는 저장 위치에 따라 적용 범위가 달라집니다.
프로젝트 루트 (./CLAUDE.md)
가장 기본적인 위치입니다. 해당 프로젝트 안에서 Claude Code를 실행하면 자동으로 읽힙니다. 프로젝트 컨벤션, 폴더 구조, 주의사항 등을 담습니다. Git에 커밋해 팀 전체가 공유하는 것이 일반적입니다.
홈 디렉토리 (~/.claude/CLAUDE.md)
모든 프로젝트에 공통으로 적용되는 개인 설정을 담습니다. "항상 한국어로 대답해", "커밋 메시지는 이 형식을 따라" 같은 개인 작업 스타일을 여기에 넣습니다.
하위 디렉토리 (./src/CLAUDE.md 등)
특정 디렉토리 안에서만 적용될 규칙이 필요할 때 사용합니다. 예를 들어 백엔드와 프론트엔드가 같은 레포에 있을 때, 각 디렉토리에 별도의 CLAUDE.md를 두어 다른 규칙을 적용할 수 있습니다.
Claude는 현재 작업 위치에서 상위 디렉토리까지 CLAUDE.md를 순서대로 모두 읽어 합산합니다.
어떤 내용을 담으면 좋나요?
CLAUDE.md에 담을 내용은 프로젝트마다 다르지만, 효과적인 파일은 보통 다음 항목들을 포함합니다.
프로젝트 개요
한 줄로 이 프로젝트가 무엇인지 설명합니다. Claude가 작업의 목적과 맥락을 이해하는 출발점이 됩니다.
폴더 구조 설명
주요 디렉토리가 각각 무슨 역할을 하는지 설명합니다. Claude가 파일을 어디에 만들고 어디를 수정해야 하는지 판단하는 기준이 됩니다.
기술 스택과 버전
사용 중인 프레임워크, 라이브러리, 그리고 특이한 버전이 있다면 명시합니다. 특히 Claude의 학습 데이터와 다른 최신 버전이나 파격적인 변경이 있는 경우 반드시 적어야 합니다.
코딩 컨벤션
네이밍 규칙, 금지 패턴, 선호하는 코드 스타일을 명시합니다. "any 타입 사용 금지", "클래스 컴포넌트 대신 함수형 컴포넌트 사용" 같은 규칙이 여기에 들어갑니다.
절대 위반 금지 규칙
반드시 지켜야 하는 규칙을 별도로 강조합니다. 중요도가 높을수록 명확하게 표현하는 것이 좋습니다.
자주 참조하는 파일이나 문서
작업 전에 반드시 읽어야 할 파일, 디자인 가이드, API 명세 위치 등을 안내합니다.
잘 쓴 CLAUDE.md의 특징
구체적일수록 좋습니다
"좋은 코드를 써라"보다 "함수 하나는 하나의 역할만 한다, 중첩 삼항연산자는 쓰지 않는다"처럼 구체적인 규칙이 훨씬 효과적입니다. Claude는 모호한 지시보다 명확한 기준에 더 잘 반응합니다.
필요한 내용만 담습니다
CLAUDE.md가 너무 길면 중요한 내용이 묻힐 수 있습니다. 코드를 읽으면 자연스럽게 알 수 있는 내용보다는, 코드만 봐서는 알 수 없는 팀의 결정과 이유를 담는 것이 핵심입니다.
살아있는 문서로 관리합니다
프로젝트가 변화하면 CLAUDE.md도 함께 업데이트해야 합니다. 오래된 규칙이 남아있으면 Claude가 잘못된 기준을 따르게 됩니다. Git으로 관리하면 변경 이력을 추적할 수 있어 팀 내 합의 과정도 투명해집니다.
정리 (Conclusion)
CLAUDE.md는 Claude Code가 프로젝트를 이해하는 출발점입니다. 프로젝트 구조, 컨벤션, 절대 규칙을 담아두면 매 세션마다 같은 맥락에서 작업이 시작되고, 팀 전체가 동일한 기준으로 Claude를 활용할 수 있습니다. 한 번 잘 작성해두면 반복 설명 없이도 일관된 품질의 작업 결과를 얻을 수 있는, 비용 대비 효과가 가장 큰 Claude Code 설정입니다.