Claude Code — Anthropic이 만든 터미널(명령줄) 기반 AI 코딩 도우미 — 를 처음 쓰다 보면 이런 고민이 생깁니다. "매번 같은 설명을 반복하기 귀찮은데, Claude가 우리 팀 규칙을 자동으로 기억할 수는 없을까?" 그 해답이 바로 CLAUDE.md 파일입니다. 이 파일에 지침을 적어 두면 Claude Code가 새 대화를 시작할 때마다 자동으로 읽어 들입니다. 그런데 CLAUDE.md는 한 곳에만 둘 필요가 없습니다. 폴더마다 다른 범위의 규칙을 담아 두면, 팀 전체 규칙·프로젝트 규칙·나만의 습관을 각각 관리할 수 있습니다. 이 글에서는 파일을 어디에 두어야 하는지, 여러 위치의 파일이 동시에 있을 때 어느 순서로 읽히는지를 단계별로 설명합니다.
CLAUDE.md가 무엇인지 먼저 짚고 가겠습니다
CLAUDE.md — 확장자가 .md인 마크다운(Markdown) 형식의 텍스트 파일 — 는 Claude Code에게 전달하는 '신입 안내문'과 같습니다. 예를 들어 "이 프로젝트는 Python 3.11을 씁니다", "테스트는 반드시 pytest로 실행하세요"처럼 매번 말하기 번거로운 내용을 한 번 적어 두면, Claude Code가 새 대화를 시작할 때마다 자동으로 읽습니다. 별도 설정 없이 파일을 올바른 위치에 두는 것만으로 작동합니다.
중요한 점은, CLAUDE.md에 적힌 내용은 Claude가 '규칙으로 강제 실행'하는 것이 아니라 '맥락으로 참고'한다는 것입니다. 공식 문서에 따르면, 지시가 구체적이고 간결할수록 Claude가 더 일관되게 따릅니다. 반대로 너무 길거나 모호하면 효과가 떨어질 수 있으니 핵심만 적는 것이 좋습니다.
파일을 어디에 두느냐가 '범위'를 결정합니다
CLAUDE.md의 핵심 아이디어는 위치 = 범위입니다. 파일을 넓은 범위(조직 전체)부터 좁은 범위(특정 폴더)까지 계층적으로 나눠 둘 수 있습니다. Claude Code는 세션 시작 시 이 파일들을 넓은 범위부터 차례로 읽어 하나의 문맥으로 합칩니다.
1단계 — 조직 전체 규칙 (관리 정책 파일)
회사나 팀 전체에 강제하고 싶은 규칙 — 예: 보안 정책, 코딩 표준 — 은 시스템 수준 경로에 둡니다. IT 담당자나 DevOps(개발 운영) 팀이 관리하는 영역입니다. 공식 문서에 따르면 경로는 운영체제(OS — 컴퓨터 운영 체제)마다 다릅니다.
- macOS:
/Library/Application Support/ClaudeCode/CLAUDE.md - Linux 및 WSL (WSL — 윈도우에서 리눅스를 실행하는 환경):
/etc/claude-code/CLAUDE.md - Windows:
C:\Program Files\ClaudeCode\CLAUDE.md
이 파일은 모든 사용자의 모든 프로젝트에 적용됩니다. 개인이 직접 만질 일은 거의 없고, 조직 차원의 도구로 이해하면 됩니다.
2단계 — 내 모든 프로젝트에 적용되는 개인 규칙 (홈 디렉터리)
프로젝트와 무관하게 '나는 항상 이렇게 일한다'는 개인 습관을 적는 곳입니다. 예를 들어 "코드 설명은 한국어로 해줘", "커밋 메시지(Commit message — 저장 기록에 붙이는 설명)는 간결하게"처럼 개인 취향을 담습니다.
- 경로:
~/.claude/CLAUDE.md
여기서 ~는 '홈 디렉터리 — 내 계정의 기본 폴더'를 뜻하는 약칭입니다. macOS라면 /Users/내이름/.claude/, Linux라면 /home/내이름/.claude/에 해당합니다. 이 파일은 나만 영향을 받고, Git(깃 — 코드 변경 이력 관리 도구)에 올라가지 않으므로 팀원은 볼 수 없습니다.
3단계 — 프로젝트 전체 규칙 (프로젝트 루트)
팀이 함께 쓰는 규칙은 프로젝트 최상위 폴더(루트 — Root, 최상위 디렉터리)에 둡니다. 이 파일은 Git 저장소에 올려 팀원 전체가 공유합니다.
- 경로:
./CLAUDE.md또는./.claude/CLAUDE.md
예를 들어 "이 프로젝트는 Node.js 20을 사용합니다", "PR(Pull Request — 코드 병합 요청) 전에 반드시 lint를 실행하세요" 같은 내용이 여기에 어울립니다. 새 팀원이 합류했을 때 '이 프로젝트를 이해하는 데 필요한 모든 맥락'을 담는다고 생각하면 됩니다.
4단계 — 특정 폴더에만 적용되는 규칙 (서브디렉터리)
프로젝트 안에서도 폴더마다 규칙이 다를 수 있습니다. 예를 들어 src/ 폴더는 TypeScript(타입스크립트 — 자바스크립트에 타입을 추가한 언어)를 쓰고, scripts/ 폴더는 Python을 쓴다면 각 폴더 안에 CLAUDE.md를 따로 둘 수 있습니다.
- 예시 경로:
./src/CLAUDE.md,./tests/CLAUDE.md
공식 문서에 따르면 서브디렉터리(하위 폴더)의 CLAUDE.md는 Claude Code가 해당 폴더 안의 파일을 읽을 때 자동으로 로드(불러옴)됩니다. 즉, 처음부터 전부 읽히는 것이 아니라 '필요한 순간에 필요한 규칙만' 불러옵니다.
5단계 — 나만 쓰는 프로젝트 전용 메모 (CLAUDE.local.md)
팀과 공유하기 싫은 개인적인 메모 — 예: 로컬 테스트 서버 주소, 내가 자주 쓰는 테스트 데이터 — 는 CLAUDE.local.md에 담습니다.
- 경로:
./CLAUDE.local.md(프로젝트 루트)
⚠ 주의: 이 파일은 반드시 .gitignore(.gitignore — Git이 무시할 파일 목록)에 추가해야 합니다. 그렇지 않으면 팀원과 공유되어 의도치 않게 개인 정보가 노출될 수 있습니다. .gitignore 파일을 열어 아래 한 줄을 추가하세요.
CLAUDE.local.md여러 파일이 동시에 있을 때 어떤 순서로 읽히나요?
공식 문서에 따르면 Claude Code는 세션을 시작할 때 CLAUDE.md 파일들을 넓은 범위에서 좁은 범위 순서로 읽습니다. 즉, 조직 정책 → 개인 규칙 → 프로젝트 루트 → 로컬 메모 순서입니다. 작업 디렉터리(현재 열린 폴더)보다 상위 폴더에 있는 CLAUDE.md 파일들도 자동으로 전부 읽힙니다.
만약 조직 정책에서 "영어로 답변하라"고 했는데 개인 규칙에서 "한국어로 답변하라"고 했다면, 더 구체적인(나중에 읽힌) 지침이 우선됩니다. 충돌이 발생할 경우 Claude는 문맥상 더 구체적인 지시를 따르려 하지만, 완벽히 보장되는 것은 아닙니다. 따라서 규칙이 겹치지 않도록 각 파일의 역할을 명확히 나누는 것이 좋습니다.
실제로 어떻게 만들고 채우나요?
CLAUDE.md는 특별한 도구 없이 메모장이나 텍스트 편집기로 만들 수 있습니다. 확장자가 .md인 텍스트 파일이면 됩니다. 아래는 프로젝트 루트에 두는 CLAUDE.md의 간단한 예시입니다.
# 프로젝트 개요
- 언어: Python 3.11
- 패키지 관리: poetry
- 테스트 실행: pytest tests/
# 코딩 규칙
- 함수 이름은 snake_case(소문자와 밑줄)로 작성
- 모든 함수에 docstring(함수 설명 주석) 추가
# 자주 쓰는 명령어
- 서버 실행: python main.py --dev
- 린트 검사: ruff check .파일을 저장한 뒤 Claude Code를 새로 시작하면(또는 새 대화 세션을 열면) 자동으로 읽힙니다. 별도로 '불러오기' 버튼을 누를 필요는 없습니다.
.claude/rules/ 폴더로 규칙을 더 세밀하게 나누기
CLAUDE.md 하나가 너무 길어진다면, .claude/rules/ 폴더(디렉터리)를 활용해 규칙을 주제별 파일로 나눌 수 있습니다. 공식 문서에 따르면 이 구조를 쓰면 특정 파일 타입이나 경로에만 규칙을 적용하는 것도 가능합니다. 예를 들어 .claude/rules/testing.md에는 테스트 관련 규칙만, .claude/rules/api.md에는 API(API — 프로그램 간 통신 규약) 관련 규칙만 담을 수 있습니다. 이 기능은 프로젝트가 커질수록 유용합니다.
자주 막히는 지점과 해결 방법
- CLAUDE.md를 만들었는데 Claude가 따르지 않아요. 파일 위치가 정확한지 확인하세요. 특히 대소문자를 구분하는 Linux/macOS에서는
claude.md가 아니라 반드시CLAUDE.md로 저장해야 합니다. 또한 내용이 너무 길거나 모호하면 효과가 줄어듭니다. 공식 문서에 따르면 지시는 구체적이고 간결할수록 잘 지켜집니다. - 서브디렉터리 CLAUDE.md가 안 읽히는 것 같아요. 이 파일들은 세션 시작 시 바로 읽히지 않습니다. Claude Code가 해당 폴더의 파일을 실제로 다룰 때 읽힙니다. Claude에게 "src 폴더의 파일을 봐줘"라고 요청하면 그때 자동으로 불러옵니다.
- CLAUDE.local.md를 실수로 Git에 올렸어요. 즉시
.gitignore에 추가하고, Git에서 해당 파일을 추적 해제(git rm --cached CLAUDE.local.md)한 뒤 다시 커밋하세요. 민감한 정보가 포함되어 있다면 Git 이력에서도 제거해야 합니다. - Auto Memory(자동 메모리 — Claude가 스스로 기록한 학습 메모)가 뭔지 모르겠어요. Claude Code 내에서
/memory명령어를 입력하면 현재 저장된 자동 메모리를 확인하고 수정할 수 있습니다.
정리: 어떤 파일을 어디에 두어야 할까요?
처음 시작하는 분께는 이렇게 권합니다. 먼저 프로젝트 루트에 CLAUDE.md 하나를 만들어 팀 공통 규칙을 담으세요. 개인 습관은 ~/.claude/CLAUDE.md에, 공유하기 싫은 개인 메모는 CLAUDE.local.md에 넣고 .gitignore에 추가하세요. 프로젝트가 커지면 그때 서브디렉터리별 파일이나 .claude/rules/ 구조를 도입하면 됩니다. 한꺼번에 완벽하게 세팅하려 하기보다, Claude가 같은 실수를 두 번 하거나 매번 같은 설명을 반복해야 할 때마다 해당 내용을 파일에 추가하는 방식이 실용적입니다.