Claude Code를 쓸 때마다 같은 맥락을 반복 설명하고 계신가요?
메모리 기능을 한번만 설정해두면, 매 세션마다 프로젝트 배경을 자동으로 불러올 수 있습니다.
📌 3줄 요약
- LLM은 세션이 끝나면 대화 내용을 잊어버리므로, 매번 맥락을 반복 설명해야 하는 문제가 있습니다.
CLAUDE.md파일로 프로젝트 단위 맥락을, 자동 메모리로 개인 취향을 각각 저장할 수 있습니다.- 메모리가 작동하지 않을 때는 파일 위치·분량·충돌 여부를 순서대로 점검하면 대부분 해결됩니다.
🗂️ 목차
대화가 끝나면 다 잊어버리는 문제
Claude Code를 처음 쓰면 한 가지 불편함을 바로 느끼게 됩니다. "나는 Python보다 TypeScript를 선호해", "이 프로젝트는 ESLint 규칙이 엄격해" 같은 맥락을 매번 새 대화마다 반복 설명해야 한다는 점입니다.
이건 Claude Code만의 문제가 아니라, LLM(대규모 언어 모델)의 근본적인 한계 때문입니다. AI는 대화가 끝나면 해당 세션의 내용을 전부 잊어버립니다. 사람과 대화하는 것처럼 느껴지지만, 실제로는 매 세션이 완전히 독립적으로 동작하는 구조입니다. 이전 대화에서 아무리 자세히 설명했더라도, 새 세션에서는 그 정보가 전혀 남아 있지 않습니다.
🔍 왜 이런 일이 생길까?
LLM은 대화를 "기억"하는 것이 아니라, 매번 입력된 텍스트만 보고 응답을 생성합니다. 새 세션이 시작되면 이전 입력은 완전히 사라지기 때문에, 같은 맥락을 다시 알려줘야 합니다.
그래서 새 대화를 시작할 때마다 "나는 공대생이고, React 프로젝트를 하고 있고, 한국어로 답변해줘"라고 다시 입력하게 됩니다. 10번 대화하면 10번 같은 말을 반복하는 셈이구요. 프로젝트가 복잡해질수록 반복해야 하는 맥락도 점점 길어져서, 정작 코딩 요청 전에 설명하느라 시간을 낭비하게 됩니다. 특히 팀 프로젝트에서 코딩 컨벤션이나 폴더 구조까지 매번 알려줘야 하면, 생산성이 눈에 띄게 떨어집니다.
이 문제를 해결하기 위해 Claude Code에는 메모리(memory) 기능이 내장되어 있습니다. 메모리를 한번 설정해두면, 새 대화를 시작해도 이전에 알려준 정보를 자동으로 불러옵니다. 마치 동료 개발자가 프로젝트 배경을 이미 알고 있는 것처럼, 맥락을 다시 설명하지 않아도 바로 작업에 들어갈 수 있습니다.
💬 제가 직접 써보니, 메모리 설정 전후의 작업 효율 차이가 확연했습니다. 특히 여러 프로젝트를 오가며 작업할 때 효과가 큽니다. 프로젝트마다 기술 스택과 규칙이 다른데, 메모리가 이를 자동으로 구분해주니 전환 비용이 거의 사라집니다.
CLAUDE.md 파일로 프로젝트 맥락 저장하기
Claude Code의 메모리는 크게 두 가지 방식으로 작동합니다. 첫 번째는 CLAUDE.md 파일을 프로젝트 루트에 만들어두는 방식입니다.
CLAUDE.md는 Claude Code가 대화를 시작할 때 자동으로 읽어들이는 설정 파일입니다. 프로젝트의 기술 스택, 코딩 컨벤션, 주의사항 등을 적어두면 매번 설명할 필요가 없습니다. 일종의 프로젝트 설명서를 Claude Code 전용으로 작성해두는 것이라고 생각하면 이해하기 쉽습니다.
만드는 방법은 간단합니다. 프로젝트 폴더 최상위에 CLAUDE.md라는 이름으로 마크다운 파일을 하나 생성하면 됩니다. 터미널에서 touch CLAUDE.md를 실행하거나, VS Code에서 직접 파일을 만들어도 됩니다. 중요한 점은 파일 이름이 정확히 CLAUDE.md여야 한다는 것입니다. 대소문자도 구분하니 주의해주세요.
파일 안에는 이런 내용을 적을 수 있습니다. 기술 스택 정보, 코딩 스타일 규칙, 자주 쓰는 명령어, 프로젝트 구조 설명 등입니다.
예를 들어 # 코딩 규칙이라는 섹션 아래에 "함수명은 동사로 시작한다", "console.log 대신 logger를 사용한다" 같은 규칙을 나열합니다. 이렇게 하면 Claude Code가 코드를 작성할 때 이 규칙을 자동으로 따릅니다. 테스트 프레임워크 설정이나 빌드 명령어를 적어두면, Claude Code가 테스트를 실행하거나 빌드할 때 올바른 명령어를 사용합니다.
CLAUDE.md는 Git으로 버전 관리가 가능하다는 것이 큰 장점입니다. 팀 프로젝트라면 팀원 모두가 같은 맥락을 공유할 수 있구요. 새로운 팀원이 합류해도 CLAUDE.md만 있으면 Claude Code가 프로젝트 컨벤션을 즉시 이해합니다. 코드 리뷰에서 자주 지적되는 규칙을 추가해두면, Claude Code가 처음부터 해당 규칙을 반영한 코드를 작성해줍니다.
💬 제가 직접 써보니, CLAUDE.md에 "이 프로젝트는 한국어로 답변해줘"라고 한 줄만 적어둬도 매번 언어 설정을 반복하지 않아서 편했습니다.
💡 팁
너무 많은 내용을 넣으면 컨텍스트 윈도우(context window)를 불필요하게 소모하니, 핵심 정보만 간결하게 정리하는 것을 추천합니다.
자동 메모리로 개인 취향 기억시키기
두 번째 방식은 Claude Code의 자동 메모리 시스템입니다. 대화 중에 "이거 기억해줘"라고 말하면, Claude Code가 메모리 파일에 해당 정보를 저장합니다.
자동 메모리는 ~/.claude/ 폴더 하위에 프로젝트별로 관리됩니다. CLAUDE.md가 프로젝트 단위 설정이라면, 자동 메모리는 사용자 개인의 취향과 작업 패턴을 저장하는 공간입니다. 팀원마다 선호하는 코딩 스타일이나 답변 방식이 다를 수 있으니, 개인별 설정을 분리해서 관리하는 구조입니다.
사용 방법도 직관적입니다. 대화 중에 "앞으로 코드 설명할 때 항상 비유를 들어줘, 이거 기억해"라고 말하면 됩니다. 별도의 명령어나 설정 화면 없이, 자연어로 바로 저장할 수 있어서 진입 장벽이 매우 낮습니다. 코딩 작업을 하다가 떠오르는 규칙이나 선호도를 그때그때 저장하면 됩니다.
저장된 메모리는 다음 대화에서도 자동으로 불러와집니다. 별도 명령어 없이, 새 세션을 시작해도 이전에 기억시킨 취향이 반영됩니다.
메모리에 저장할 수 있는 정보 유형은 다양합니다. 코딩 스타일 선호도, 답변 톤 설정, 자주 작업하는 파일 경로, 팀 내 역할 등을 기억시킬 수 있습니다. 예를 들어 "에러 메시지는 항상 한국어로 작성해줘"라거나 "커밋 메시지는 영어 동사 원형으로 시작해줘" 같은 세부적인 선호도도 저장 가능합니다. 프로젝트별로 다른 메모리가 적용되기 때문에, A 프로젝트에서는 Python 스타일을, B 프로젝트에서는 TypeScript 스타일을 각각 기억시킬 수도 있습니다.
반대로 "이건 잊어줘"라고 말하면 해당 메모리를 삭제합니다. 불필요하거나 오래된 정보는 이렇게 정리할 수 있구요. 프로젝트 방향이 바뀌거나 기술 스택을 전환할 때, 기존 메모리를 삭제하고 새로운 맥락을 저장하면 깔끔하게 전환됩니다.
💬 제가 직접 써보니, 자동 메모리의 가장 큰 장점은 대화하다가 자연스럽게 저장할 수 있다는 점이었습니다. 단점은 메모리가 너무 많이 쌓이면 어떤 정보가 저장되어 있는지 파악하기 어려워진다는 것입니다. 주기적으로 저장된 메모리를 확인하고 정리하는 습관을 들이면 이 문제를 예방할 수 있습니다.
메모리가 제대로 작동하지 않을 때 점검법
메모리를 설정했는데도 Claude Code가 이전 맥락을 무시하는 경우가 있습니다. 이럴 때 확인해야 할 체크리스트를 정리했습니다. 아래 항목을 하나씩 점검하면 대부분의 문제를 해결할 수 있습니다.
CLAUDE.md 파일의 위치를 확인합니다
프로젝트 최상위 폴더(루트)에 있어야 Claude Code가 자동으로 인식합니다. 하위 폴더에 넣어두면 인식하지 못하는 경우가 많습니다. ls CLAUDE.md 명령으로 현재 작업 디렉토리에 파일이 있는지 확인해보세요. 만약 프로젝트 루트가 아닌 src/ 같은 하위 폴더에서 Claude Code를 실행했다면, 해당 위치에서는 CLAUDE.md를 찾지 못할 수 있습니다.
메모리 파일이 실제로 저장되었는지 확인합니다
~/.claude/ 경로 아래 프로젝트별 memory 폴더를 열어보면 저장된 메모리 파일 목록을 볼 수 있습니다. 파일이 비어 있거나 아예 생성되지 않았다면, "기억해줘"라고 말했을 때 저장이 제대로 되지 않은 것입니다. 이 경우 다시 한번 명확하게 기억시켜 달라고 요청하면 해결됩니다.
CLAUDE.md 내용이 너무 길지 않은지 점검합니다
권장 분량은 A4 1~2페이지 이내이며, 너무 긴 내용은 오히려 중요한 맥락이 묻힐 수 있습니다. 핵심 규칙만 간결한 리스트 형태로 정리하는 것이 가장 효과적입니다. 불필요한 설명은 과감하게 삭제하고, 키워드 중심으로 작성하면 Claude Code가 더 정확하게 맥락을 파악합니다.
메모리와 CLAUDE.md의 내용이 서로 충돌하지 않는지 확인합니다
예를 들어 메모리에는 "Python 선호"라고 저장되어 있는데 CLAUDE.md에는 "TypeScript만 사용"이라고 적혀 있으면 혼란이 생길 수 있습니다. 이런 충돌이 발생하면 Claude Code가 어느 쪽을 따를지 예측하기 어려워집니다. 두 설정을 주기적으로 비교해서 일관성을 유지하는 것이 중요합니다.
⚠️ 주의
메모리와 CLAUDE.md의 설정이 충돌하면, Claude Code가 어느 쪽을 따를지 예측하기 어렵습니다. 두 설정의 일관성을 반드시 유지하세요.
새 대화를 시작할 때 메모리 반영 여부를 살펴봅니다
정상적으로 로드되었다면, 첫 응답에서 기억한 맥락을 반영한 답변을 돌려줄 겁니다.
💬 제가 직접 써보니, 대부분의 문제는 CLAUDE.md 파일 위치가 잘못되었거나 내용이 과도하게 많은 경우였습니다. 간결하게 핵심만 정리하는 것이 메모리 기능을 안정적으로 활용하는 비결입니다.
💡 팁
처음에는 3~5줄 정도의 간단한 규칙부터 시작하고, 필요할 때마다 하나씩 추가하는 방식을 추천합니다.
✍️ 마치며
Claude Code의 메모리 기능은 CLAUDE.md로 프로젝트 맥락을, 자동 메모리로 개인 취향을 저장하는 구조입니다. 한번 설정해두면 매 세션마다 반복 설명할 필요 없이 바로 작업에 집중할 수 있습니다. 처음에는 간단한 규칙 몇 줄부터 시작하고, 작업하면서 필요한 맥락을 하나씩 추가해보세요. 반복 설명에 쓰던 시간이 사라지면, 그만큼 코딩에 더 집중할 수 있습니다.
'AI 툴 문제 해결' 카테고리의 다른 글
| Opus 4.8 전환 뒤 자주 발생하는 설정 오류 해결법 (0) | 2026.07.23 |
|---|---|
| Claude Code 모델 업데이트 후 코딩 결과가 달라졌을 때 확인법 (0) | 2026.07.23 |
| Opus 4.8 업데이트 후 체감되는 코딩 차이와 대응법 (0) | 2026.07.23 |
| Skill·Hook·MCP·서브에이전트 헷갈릴 때 선택 기준 (0) | 2026.07.23 |
| Claude Code 슬래시 커맨드 만들기 — 자주 쓰는 프롬프트 저장법 (0) | 2026.07.22 |
