[Claude Code] 클로드 코드 CLAUDE.md 메모리 파일 사용법 총정리

클로드 코드는 대화가 끝나면 이전 세션의 내용을 기억하지 못합니다. 세션을 종료하고 새로운 세션을 시작할 때마다 완전히 백지 상태가 되는 것입니다. 이렇게 되면 공통의 규칙같은것이 있다면 매 세션마다 동일하게 입력을 시켜줘야 하죠. 이 과정을 효율화 하기 위해 별도의 지침을 기억하는 메모리 파일이 있습니다. 이것이 바로 CLAUDE.md 파일입니다.  메모리 파일(CLAUDE.md)에 "이 프로젝트에서는 이렇게 해줘"라는 지침을 별도의 파일로 기록해두면 매번 반복해서 설명하지 않아도 됩니다. 

 

클로드 코드 메모리 파일(CLAUDE.md)이란?

쉽게 말해 CLAUDE.md는 해당 프로젝트에서 매번 지켜야 할 규칙을 적어놓은 파일입니다. 이 프로젝트는 어떤 구조로 되어 있고 어떤 규칙을 따라야 하는지를 기재해두면, 클로드 코드는 세션을 시작할 때마다 이 내용을 자동으로 읽어들입니다.

 

이러한 메모리 파일은 /init 명령어를 통해 클로드 코드가 프로젝트 구조를 파악한 뒤 CLAUDE.md 파일을 자동으로 생성하도록 할 수도 있습니다. 한 번 파일을 생성한 이후에는 지속적으로 지켜야 할 규칙을 계속 업데이트해나가는 방식으로 사용하면 됩니다.

 

 메모리 파일의 세 가지 종류 

 

메모리 파일은 어디에 위치시키느냐에 따라 역할이 달라집니다. 공식 문서에는 여러 유형이 소개되어 있지만, 실제로 자주 사용하는 것은 몇 가지 되지 않으므로 각 유형의 역할만 대략 파악해두면 좋을것 같습니다.

 

1. 프로젝트 메모리 (CLAUDE.md)

가장 많이 사용하는 메모리 파일로, 프로젝트 폴더 안에 CLAUDE.md 파일로 저장합니다. 이 프로젝트에서만 적용되는 규칙을 적는 용도로 사용합니다. 예를 들어 "이 프로젝트는 리액트를 사용하고 디자인은 깔끔하면서 미니멀한 스타일로 통일한다"와 같은 내용을 적어두면, 해당 프로젝트에서 클로드 코드를 실행할 때마다 이 파일을 읽어들입니다.

 

저장 위치는 프로젝트 최상위 디렉터리 또는 .claude 디렉터리 바로 하위 중 한 곳을 선택하면 됩니다. 이 파일은 깃으로 커밋하면 팀원들과 함께 공유해서 사용할 수 있으므로, 팀 전체가 동일한 규칙으로 프로젝트를 관리하고자 할 때 활용하면 좋습니다.

 

2. 로컬 메모리 (CLAUDE.local.md)

마찬가지로 프로젝트 메모리 파일이지만, 깃으로 관리되지 않고 개인적인 규칙만 관리하는 파일입니다. 자주 사용되는 파일은 아니며, 대부분의 경우 프로젝트 메모리 파일(CLAUDE.md)만으로 충분합니다. 팀 단위로 개발하는 경우라면 CLAUDE.md에는 공유할 내용을, CLAUDE.local.md에는 선호하는 테스트 데이터나 개인적인 규칙을 적어두면 됩니다.

 

공식 문서에 따르면 CLAUDE.local.md 파일은 자동으로 .gitignore에 추가되어야 한다고 안내되어 있지만, 실제로는 자동으로 추가되지 않는 경우가 있으니 확인을 꼭 하시는것이 좋습니다. 따라서 이 파일을 사용할 계획이라면 .gitignore 파일에 CLAUDE.local.md를 직접 추가해서 깃 추적 대상에서 제외해야 팀원들과의 세팅이 꼬이지 않겠죠?

 

3. 사용자 메모리

자주 사용되지는 않지만 알아두면 유용한 메모리 파일입니다. 모든 프로젝트에 대한 개인 선호도를 반영한 규칙을 담는 용도로 사용합니다. 예를 들어 한 사용자가 블로그 프로젝트, 강의 사이트, 데이터 수집 사이트, 업무 자동화 사이트 등 여러 프로젝트를 운영하면서 각 프로젝트마다 CLAUDE.md 파일을 따로 두고 있다고 해도, "모든 프로젝트에 공통으로 적용해야 할 규칙"이 있을 수 있습니다. 이런 규칙을 담는 파일이 사용자 메모리 파일입니다.

 

저장 위치는 사용자 홈 디렉터리의 .claude 디렉터리 하위에 있는 CLAUDE.md 파일입니다. 여기에는 모든 프로젝트에서 공통적으로 지켜야 할 스타일 가이드라인, 깃 관리 방식, 클로드 코드의 작업 방식, 사용 중인 PC 환경 정보 등을 기재하면 좋습니다. 다만 최근 스펙 업데이트로 설정 파일에서 언어 옵션을 한국어로 지정하면 별도로 "한국어로 응답해줘"라고 기재하지 않아도 한국어로 응답을 받을 수 있다는 점도 참고하시면 좋을것 같습니다.

 

---

 

다른 파일 불러오기: import 문법

CLAUDE.md 파일에 기재한다고 해서 클로드 코드가 100% 이를 준수하는 것은 아닌데요. LLM이 이 정보를 읽고 작업하는 방식이기 때문에, 메모리 파일이 길어지면 내용을 누락하는 상황이 생길 수 있습니다. 실제로 공식 문서에서도 CLAUDE.md 파일을 500줄 이하로 유지할 것을 권장하고 있습니다.

 

그래서 CLAUDE.md 파일 안에서 중복을 최소화하면서 프로젝트 메모리를 효율적으로 관리하는 방법이 필요한데, 이때 사용하는 것이 다른 파일을 읽어오는 import 문법입니다. CLAUDE.md 파일에 @ 기호 뒤에 특정 파일의 경로를 적으면 해당 파일을 메모리로 읽어옵니다. 예를 들면 다음과 같이 작성할 수 있습니다.

프로젝트 개요는 @README.md 파일을 참고하세요.
이 프로젝트의 npm 명령어는 @package.json 파일을 참고하세요.
깃 관련 지침은 @docs/git-instructions.md 파일을 참고하세요.

이 import 문법을 가장 잘 활용하는 방법은 이미 프로젝트 안에 존재하는 파일을 가져오는 것입니다. 예를 들어 프로젝트가 어떤 프로젝트인지 소개하는 내용은 일반적으로 README.md 파일에 이미 작성되어 있으므로, 이 내용을 CLAUDE.md 파일에 복사해서 붙여넣는 대신 import 문법으로 편하게 연결해서 사용하면 됩니다.

 

---

 

 CLAUDE.md 직접 만들어보기 

Step 1. /init으로 자동 생성

프로젝트 폴더에서 클로드 코드를 실행하고 /init을 입력합니다.

/init

클로드가 프로젝트의 파일 구조, package.json, README 등을 분석하여 CLAUDE.md 초안을 생성합니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안합니다.

 

Step 2. 직접 작성하기

자동 생성 대신 직접 내용을 지정하면 더 정확한 지침을 줄 수 있습니다. 클로드에게 아래 예시를 참고하여 본인의 업무에 맞는 CLAUDE.md를 만들어달라고 요청해도 좋습니다.

 

비즈니스 업무용 예시 (마케팅팀, 기획팀 등)

# 마케팅팀 업무 자동화

## 작업 규칙
- 응답은 한국어로 작성
- 보고서는 격식체(합니다/습니다) 사용
- 금액 표기: 원화 기호 없이 숫자만, 천 단위 쉼표 포함 (예: 1,200,000)
- 날짜 형식: YYYY-MM-DD (예: 2024-03-15)

## 자주 쓰는 작업
- 주간 보고서: 성과 요약 + 다음 주 계획 + 이슈 사항
- 이메일 분류: 긴급도(높음/중간/낮음) + 주제별 분류
- 경쟁사 분석: 제품, 가격, 강점/약점 비교표

## 참고 정보
- 팀장: 박팀장 (보고 대상)
- 주간 회의: 매주 월요일 오전 10시
- 보고서 마감: 매주 금요일 오후 5시

 

 

개발 프로젝트용 예시

# 프로젝트 개요
할일 관리 REST API - 사용자별 할일 CRUD 및 카테고리 분류

## 기술 스택
- Node.js 20 + Express
- PostgreSQL + Prisma
- Jest + Supertest (테스트)

## 빌드/테스트 명령어
- 개발 서버: npm run dev
- 테스트 전체: npm test
- 단일 테스트: npm test -- --testPathPattern=파일명
- 린트: npm run lint

## 코드 규칙
- require 대신 import/export 사용 (ES Modules)
- 에러 핸들링은 express-async-errors 미들웨어 사용
- 환경변수는 dotenv로 관리, .env 파일은 커밋하지 않음

 

메모리 파일 작성 모범사례

메모리 파일을 작성할 때 참고하면 좋은 세 가지 모범사례는 다음과 같습니다.

• 구체적으로 작성합니다. "코드를 적절히 포맷합니다"라는 모호한 지침보다는 "2칸 들여쓰기를 사용합니다"처럼 구체적으로 작성해야 합니다. 모호하게 작성하면 클로드가 상황에 따라 다르게 판단하게 됩니다.

예를 들면 다음과 같이 작성할 수 있습니다.

[X] 나쁜 예
코드를 적절히 포맷합니다.

[O] 좋은 예
- 들여쓰기는 2칸 스페이스를 사용합니다.
- 문자열은 큰따옴표 대신 작은따옴표를 사용합니다.
- 세미콜론은 항상 붙입니다.

• 구조를 사용하여 작성합니다. 한 문장으로 길게 쓰기보다는 리스트 형식으로 항목을 그룹핑해서 작성하면 클로드가 내용을 더 잘 이해하고 지침을 준수할 확률이 올라갑니다.

 

예를 들면 다음과 같이 작성할 수 있습니다.

[X] 나쁜 예
이 프로젝트는 리액트로 만들어져 있고 상태 관리는 줄스탄드를 쓰고 API 호출은 액시오스를 사용하며 스타일링은 테일윈드로 합니다.

[O] 좋은 예
## 기술 스택
- 프레임워크: React
- 상태 관리: Zustand
- API 호출: Axios
- 스타일링: Tailwind CSS

• 정기적으로 업데이트합니다. 처음부터 완벽하게 작성하려고 무리할 필요는 없습니다. 프로젝트가 진화함에 따라 메모리 파일도 함께 업데이트해나가는 것이 중요합니다.

 

예를 들어 처음에는 다음과 같이 간단하게 시작했다가,

## 코드 스타일
- 2칸 들여쓰기를 사용합니다.

 

클로드에게 같은 내용을 반복해서 알려주는 상황이 생길 때마다 아래처럼 규칙을 하나씩 추가해나가면 됩니다.

## 코드 스타일
- 2칸 들여쓰기를 사용합니다.
- 함수명은 camelCase로 작성합니다.
- 컴포넌트 파일명은 PascalCase로 작성합니다.

 

또한 클로드가 지침을 기재했음에도 잘 따르지 않는 경우에는 IMPORTANT나 MUST와 같은 강조 문구를 추가해서 준수도를 높일 수 있습니다.

IMPORTANT: 커밋 메시지는 반드시 한국어로 작성해야 합니다.
데이터베이스 마이그레이션 파일은 절대(MUST NOT) 직접 수정하지 않습니다.

참고로 문장이 너무 길거나 규칙이 모호하면 지침을 따르지 않을 수 있으므로, 간결하게 작성하는 것이 매우 중요합니다.

 

마무리

이번 글에서는 클로드 코드의 메모리 파일인 CLAUDE.md의 기본 개념과 네 가지 종류(엔터프라이즈 정책, 프로젝트 메모리, 프로젝트 로컬 메모리, 사용자 메모리), 그리고 import 문법과 작성 모범사례를 정리해보았습니다. 대부분의 프로젝트에서는CLAUDE.md 파일 하나만으로도 충분하며, 규칙이 많지 않다면 이 정도만 잘 활용해도 클로드 코드를 효율적으로 사용할 수 있습니다. 다음 글에서는 프로젝트가 커지면서 규칙이 많아졌을 때 사용할 수 있는 모듈형 메모리 관리 방법을 다뤄보겠습니다.