5-2. CLAUDE.md가 뭔지 — 프로젝트의 규칙 파일
Claude Code는 세션이 새로 시작될 때마다 아무것도 기억하지 못합니다. 그래서 매번 같은 지시를 반복하게 되죠. CLAUDE.md는 그 반복을 끝내는 프로젝트 설정 파일입니다.
1. 매 세션 반복하는 지시들
분석 작업을 며칠 해보면 이런 말을 계속 하고 있는 자신을 발견합니다:
- "답변이랑 차트 라벨은 한국어로 해줘"
- "CSV는 utf-8-sig로 읽어야 안 깨져"
- "원본 데이터는 건드리지 말고 가공본은 따로 저장해"
- "변화율 말할 때 기준 연도 꼭 적어줘"
어제 분명히 말했는데 오늘 새 세션에서는 처음부터 다시. 이 지시들을 파일로 적어두면 Claude Code가 매 세션 시작할 때 자동으로 읽습니다. 그게 CLAUDE.md예요.
2. 어떻게 동작하나
프로젝트 폴더 맨 위에 CLAUDE.md라는 마크다운 파일을 만들어 두면 끝입니다. 등록도 실행도 필요 없어요.
작성 — 프로젝트 폴더에 CLAUDE.md 파일을 만들고 규칙을 적는다
자동 로드 — 모든 세션 시작 시 Claude Code가 이 파일을 먼저 읽는다
항상 적용 — 별도 지시 없이 첫 응답부터 규칙대로 동작한다
3. 스킬과 뭐가 다른가
모듈 2에서 배운 스킬과 헷갈리기 쉬운데, 역할이 다릅니다.
| 스킬 (SKILL.md) | CLAUDE.md | |
|---|---|---|
| 성격 | 특정 작업의 매뉴얼 | 프로젝트 전체의 규칙 |
| 로드 시점 | 그 작업이 필요할 때만 | 모든 세션 시작 시 항상 |
| 적는 내용 | 전처리 절차, 리포트 양식 같은 다단계 작업 | 출력 언어, 폴더 구조, 항상 지킬 규칙 |
| 예시 | "CSV 전처리는 이 순서로" | "이 프로젝트는 항상 한국어로" |
회사에 비유하면 스킬은 업무별 매뉴얼이고, CLAUDE.md는 근무 수칙입니다. 공식 문서의 기준도 같아요 — 모든 세션에서 지켜야 할 사실과 규칙은 CLAUDE.md에, 특정 작업의 다단계 절차는 스킬로.
4. 어디에 두느냐 = 적용 범위
스킬과 마찬가지로, 저장 위치가 적용 범위를 결정합니다.
| 위치 | 경로 | 적용 범위 |
|---|---|---|
| 프로젝트 | ./CLAUDE.md | 이 프로젝트만 — git으로 공유하면 팀 전체 |
| 개인 전역 | ~/.claude/CLAUDE.md | 내 모든 프로젝트 |
| 개인·이 프로젝트만 | ./CLAUDE.local.md | 나만, 이 프로젝트에서만 (git 제외) |
5. 잘 쓰는 요령 — 구체적으로, 짧게
CLAUDE.md는 명령이 아니라 Claude가 읽는 컨텍스트라서, 구체적일수록 잘 지켜집니다.
막연한 지시 ✕
"차트를 보기 좋게 만들어" — 기준이 없어 매번 다르게 동작
검증 가능한 지시 ◯
"차트 제목·축 라벨은 한국어, 출처를 하단에 표기" — 지켰는지 확인 가능
분량은 200줄 이하가 권장입니다. 길어질수록 규칙이 덜 지켜져요. 같은 실수를 두 번째 고쳐주고 있다면 — 그게 CLAUDE.md에 한 줄 추가할 때입니다.
"CLAUDE.md 파일은 프로젝트, 개인 워크플로우 또는 전체 조직에 대해 Claude에 지속적인 지침을 제공하는 마크다운 파일입니다. 일반 텍스트로 작성하면 Claude가 모든 세션의 시작 시 읽습니다."
— Claude Code 공식 문서 · Claude가 프로젝트를 기억하는 방법
★ 핵심. CLAUDE.md는 매 세션 반복하던 지시를 파일 하나로 끝내는 프로젝트 규칙입니다. 스킬이 작업 매뉴얼이라면, CLAUDE.md는 근무 수칙 — 다음 클립에서 직접 만듭니다.