Claude Code에서 CLAUDE.md와 메모리로 프로젝트 맥락 유지하기 - 매번 설명하지 않으려고 정리한 기록

Claude Code에서 CLAUDE.md와 메모리로 프로젝트 맥락 유지하기 - 매번 설명하지 않으려고 정리한 기록

개발 도구 사용기

공식 문서와 실제 사용 경험을 기준으로 정리했습니다.

새 세션을 열 때마다 "이 프로젝트는 들여쓰기 두 칸을 쓰고, 테스트는 이 명령으로 돌리고…" 같은 설명을 다시 적고 있다면, 그 반복을 한 번만 적어 두는 방법이 있습니다. Claude Code의 CLAUDE.md와 메모리(memory) 기능입니다. 이 글은 프로젝트 규칙과 자주 쓰는 정보를 어디에, 어떻게 적어 두면 매번 설명하지 않아도 되는지를 공식 문서를 기준으로 정리한 기록입니다. 명령과 동작은 버전에 따라 달라질 수 있으니 본문에 적은 공식 문서를 함께 확인하시길 권합니다.

매번 같은 설명을 반복하게 되는 이유

Claude Code는 각 세션을 빈 맥락에서 시작합니다. 그래서 지난 대화에서 알려 줬던 "우리 프로젝트의 규칙"이 다음 세션에는 남아 있지 않습니다. 빌드 명령, 코드 스타일, 디렉터리 구조, 자주 쓰는 워크플로 같은 정보를 매번 다시 설명하게 되는 것이 그 때문입니다.

이 반복을 줄이는 방법이 메모리 파일입니다. 한 번 적어 두면 세션이 시작될 때 그 내용이 맥락으로 함께 읽혀, 같은 설명을 되풀이하지 않아도 됩니다.

CLAUDE.md — 세션마다 자동으로 읽히는 프로젝트 메모

CLAUDE.md는 프로젝트에 두는 메모리 파일입니다. 공식 문서에 따르면 Claude Code는 세션을 시작할 때 현재 작업 디렉터리에서 상위로 올라가며 CLAUDE.md 파일들을 찾아 맥락에 함께 읽어들입니다. 즉 파일 하나에 프로젝트의 규칙을 적어 두면, 다음부터는 그 내용을 전제로 대화가 시작됩니다.

적는 형식은 평범한 마크다운입니다. 거창한 문법이 필요 없고, "무엇을 지켜야 하는지"를 사람이 읽듯 적으면 됩니다. 핵심은 "이 프로젝트에서 매번 설명하던 것"을 글로 옮겨 두는 것입니다.

어디에 두느냐 — 메모리의 계층

메모리 파일은 적용 범위에 따라 여러 위치에 둘 수 있습니다. 공식 문서 기준으로 정리하면 다음과 같습니다.

위치	적용 범위
엔터프라이즈 정책 (시스템 경로)	조직 전체에 공통 적용되는 규칙
사용자 전역 ~/.claude/CLAUDE.md	내 모든 프로젝트에 공통 적용
프로젝트 공유 ./CLAUDE.md	팀과 함께 쓰는 프로젝트 규칙(버전 관리에 포함)
로컬 개인용 ./CLAUDE.local.md	버전 관리에서 제외하는 나만의 설정

여러 위치의 파일이 함께 발견되면 모두 맥락에 더해지므로, "조직 → 나 → 팀 → 개인" 순으로 점점 구체적인 규칙을 얹어 가는 식으로 쓸 수 있습니다. 상위 디렉터리의 파일까지 올라가며 읽기 때문에, 모노레포처럼 폴더가 깊은 구조에서도 공통 규칙을 위쪽에 한 번만 둘 수 있습니다.

무엇을 적고, 어떻게 적나

공식 문서는 메모리에 적기 좋은 대상으로 코딩 규칙, 빌드·테스트 명령, 프로젝트 구조, 자주 쓰는 워크플로 같은 것을 듭니다. 적는 방법에는 몇 가지 권장 사항이 있습니다.

• 구체적으로 — "코드를 깔끔하게"보다 "들여쓰기는 공백 2칸"처럼 분명하게 적을수록 잘 지켜집니다.
• 구조를 잡아서 — 마크다운 헤더와 불릿으로 관련 규칙을 묶어 두면 읽기도 쉽고 적용도 정확합니다.
• 너무 길지 않게 — 문서는 파일 하나를 대략 200줄 이내로 권합니다. 길어질수록 맥락을 많이 차지하기 때문입니다.
• 주기적으로 정리 — 서로 충돌하거나 더는 맞지 않는 규칙은 지워 둡니다.

메모리는 "많이 적을수록 좋은" 파일이 아닙니다. 매번 설명하던 것 중 정말 반복되는 것만 골라 짧게 적어 두는 편이, 길게 적어 두고 맥락을 잡아먹는 것보다 나았습니다.

파일을 쪼개고 싶을 때 — @import

규칙이 늘어나 한 파일이 부담스러워지면, CLAUDE.md 안에서 @경로 구문으로 다른 파일을 끌어올 수 있습니다. 공식 문서에 따르면 import된 파일은 세션 시작 시 함께 펼쳐져 맥락에 들어갑니다.

# CLAUDE.md 안에서 다른 파일 불러오기
프로젝트 개요는 @README 를 참고
코딩 규칙은 @docs/coding-style.md 를 따른다
개인 설정은 @~/.claude/my-instructions.md

덕분에 "팀 공통 규칙"과 "개인 메모"를 파일로 나눠 두고 필요한 것만 끌어다 쓸 수 있습니다. 상대경로와 절대경로(~ 포함)를 모두 적을 수 있습니다.

처음 만들 때와 편집할 때 — /init, /memory

빈 프로젝트에서 무엇부터 적어야 할지 막막하다면 /init 명령이 시작점을 만들어 줍니다. 공식 문서에 따르면 Claude가 코드베이스를 살펴본 뒤, 발견한 빌드 명령·테스트 방법·프로젝트 관례를 담은 CLAUDE.md 초안을 생성합니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 제안만 합니다.

이미 만들어진 메모리를 보거나 고칠 때는 /memory 명령을 씁니다. 현재 세션에 읽힌 메모리 파일들의 목록을 보여 주고, 파일을 골라 편집기로 열 수 있습니다.

한 걸음 더 — 자동 메모리와 경로별 규칙

직접 적는 CLAUDE.md 외에, Claude가 대화 중 알게 된 내용을 스스로 저장해 두는 자동 메모리도 있습니다. 빌드 방법이나 디버깅 과정에서 얻은 정보 같은 것이 쌓이며, 기본적으로 켜져 있고 /memory에서 켜고 끌 수 있습니다. 매 세션 시작 시 전체가 아니라 앞부분 일부만 읽히는 것으로 문서는 설명합니다(세부 한도는 버전에 따라 달라질 수 있습니다).

또한 특정 폴더에만 적용되는 규칙이 필요하면 .claude/rules/ 아래에 파일을 두고 적용 경로를 지정할 수 있습니다. 모든 규칙을 한 파일에 몰지 않고, 해당 파일을 다룰 때만 관련 규칙이 읽히게 해 맥락을 아끼는 방식입니다.

써보며 걸렸던 점

• 너무 많이 적음 — 온갖 규칙을 다 넣었더니 정작 중요한 규칙이 묻혔습니다. 반복되는 핵심만 남기니 더 잘 지켜졌습니다.
• 두루뭉술하게 적음 — "보기 좋게"처럼 모호한 지시는 해석이 갈렸습니다. 수치와 예시로 적을수록 정확했습니다.
• 업데이트를 안 함 — 규칙이 바뀌었는데 파일을 안 고쳐 옛 규칙이 적용된 적이 있었습니다. 주기적으로 들여다보는 습관이 필요했습니다.
• 개인 설정을 공유 파일에 적음 — 나만의 설정은 버전 관리에서 제외되는 파일에 따로 두는 편이 팀에 혼선을 주지 않았습니다.

자주 묻는 질문

Q. CLAUDE.md는 직접 불러와야 하나요?

아닙니다. 공식 문서에 따르면 세션이 시작될 때 작업 디렉터리에서 상위로 올라가며 자동으로 찾아 맥락에 읽힙니다. 따로 열어 주지 않아도 됩니다.

Q. 팀 공용과 개인용을 나눌 수 있나요?

네. 팀과 공유할 규칙은 버전 관리에 포함되는 프로젝트 파일에, 나만의 설정은 버전 관리에서 제외되는 개인용 파일에 나눠 둘 수 있습니다.

Q. 처음 무엇을 적어야 할지 모르겠어요.

/init 명령으로 초안을 만들어 시작할 수 있습니다. Claude가 코드베이스를 살펴 빌드·테스트 명령과 관례를 담은 CLAUDE.md를 만들어 줍니다.

마무리

요령은 단순했습니다. "매번 설명하던 것"을 한 번 글로 옮겨 두는 것. CLAUDE.md에 프로젝트 규칙을 적어 두면 세션마다 자동으로 읽히고, 위치를 나눠 두면 조직·개인·팀·로컬 규칙을 겹쳐 쓸 수 있으며, 파일이 길어지면 @import로 쪼갤 수 있었습니다. 처음에는 /init으로 초안을 만든 뒤, 자주 반복하던 설명 한두 개만 짧게 적어 두는 것부터 시작하시길 권합니다. 그 작은 정리만으로도 다음 세션이 한결 매끄러워지는 걸 느낄 수 있습니다.

이 글의 기능 설명은 Claude Code 공식 문서를 기준으로 정리했습니다. 세부 구성과 명령은 버전에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.

• 메모리 문서: code.claude.com/docs/en/memory
• 대규모 코드베이스 가이드: code.claude.com/docs/en/large-codebases

※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. 도구의 기능·화면·명령은 버전에 따라 달라질 수 있으며, 특정 결과를 보장하지 않습니다.