Claude Code 메모리 기능, AI가 내 프로젝트를 기억하게 만드는 법

Claude Code 입문

어제 분명히 설명했던 내용을 오늘 새 대화에서는 전혀 기억하지 못하는 Claude Code, 답답하셨죠? 이번 글에서는 AI가 내 프로젝트를 계속 기억하게 만드는 메모리 기능을 처음부터 끝까지 정리합니다. CLAUDE.md 파일 만들기부터 # 단축키, 메모리 관리 요령까지 순서대로 따라가 보겠습니다.

📌 3줄 요약

1. AI는 대화가 끝나면 모든 내용을 잊어버리므로, CLAUDE.md 파일에 규칙을 적어두면 새 대화마다 자동으로 읽고 시작합니다.

2. 대화 중 문장 맨 앞에 # 기호만 붙이면 그 자리에서 바로 메모리에 저장할 수 있습니다.

3. /memory 명령어로 주기적으로 확인하고 낡은 정보를 지워야 메모리가 제 역할을 합니다.

목차

1. Claude Code 메모리 기능이 필요한 이유

2. CLAUDE.md 파일로 프로젝트 정보 기억시키기

3. # 단축키로 대화 중 기억 바로 저장하기

4. 저장된 메모리 확인하고 관리하는 방법

Claude Code 메모리 기능이 필요한 이유

Claude Code를 며칠 써보면 한 가지 불편한 점을 발견하게 됩니다. 어제 분명히 설명했던 내용을 오늘 새 대화에서는 전혀 기억하지 못하네요.

예를 들어 "우리 프로젝트는 파이썬 3.12를 쓴다"라고 알려줘도, 다음 날 새 세션을 열면 처음부터 다시 설명해야 합니다. AI는 기본적으로 대화가 끝나면 모든 내용을 잊어버리는 구조이기 때문입니다.

🔍 왜 AI는 기억하지 못할까?

이건 Claude Code만의 문제가 아니라 ChatGPT 같은 다른 AI 도구도 마찬가지입니다. 대화 하나하나가 독립된 세션이라서, 세션이 닫히는 순간 그 안의 맥락은 사라진다고 보시면 됩니다.

이 문제를 해결하는 것이 바로 메모리(memory) 기능입니다. 메모리는 쉽게 말해 AI에게 주는 포스트잇 메모장입니다.

사람도 인수인계 문서가 있으면 새 담당자가 바로 업무를 파악하듯이, AI에게도 그런 문서를 미리 만들어두는 개념이라고 이해하시면 편합니다.

중요한 정보를 파일로 적어두면, Claude Code가 새 대화를 시작할 때마다 그 파일을 자동으로 읽고 시작합니다. 매번 같은 설명을 반복할 필요가 없어지는 겁니다.

별도의 명령어를 입력하지 않아도 알아서 읽기 때문에, 한 번 설정해두면 그 뒤로는 신경 쓸 일이 거의 없습니다.

메모리에 저장하면 좋은 정보는 크게 세 가지입니다. 프로젝트의 기본 규칙, 자주 쓰는 명령어, 그리고 내 작업 취향입니다.

⚠️ 주의  반대로 지금 하고 있는 작업의 진행 상황처럼 금방 바뀌는 정보는 저장하지 않는 것이 좋습니다. 오늘은 맞는 말이지만 다음 주에는 틀린 말이 되어버리기 때문입니다.

💬 직접 써본 경험

제가 직접 써보니 메모리 설정 전과 후의 체감 차이가 상당히 컸습니다. 설정 전에는 세션마다 5분씩 배경 설명을 했는데, 지금은 바로 본론으로 들어갑니다.

다만 처음 한 번은 직접 정리하는 수고가 필요하다는 점은 미리 알아두시는 게 좋습니다.

CLAUDE.md 파일로 프로젝트 정보 기억시키기

메모리의 핵심은 CLAUDE.md라는 이름의 마크다운 파일입니다. 프로젝트 폴더 최상단에 이 파일을 만들어두면, Claude Code가 실행될 때 자동으로 읽습니다.

⚠️ 주의  파일 이름은 반드시 대문자로 CLAUDE.md라고 지어야 인식되니, 소문자로 쓰지 않도록 주의하시기 바랍니다.

만드는 방법은 두 가지가 있습니다. 첫 번째는 직접 파일을 만드는 방법이구요, 두 번째는 Claude Code에게 시키는 방법입니다.

1

가장 쉬운 방법은 터미널에서 Claude Code를 실행한 뒤 /init 명령어를 입력하는 것입니다. 그러면 Claude Code가 프로젝트 폴더를 스스로 분석해서 CLAUDE.md 초안을 만들어주네요.

2

폴더 구조, 사용 중인 프로그래밍 언어, 설치된 라이브러리 같은 정보를 알아서 읽고 정리해주기 때문에, 빈 파일 앞에서 뭘 써야 할지 고민할 필요가 없습니다.

 

생성된 파일은 메모장으로도 열어서 수정할 수 있습니다. 마크다운(markdown) 형식이지만 어렵게 생각할 필요 없이, 그냥 글머리 기호로 정리한 메모라고 보시면 됩니다.

샵 기호로 제목을 달고, 하이픈으로 목록을 만드는 정도만 알면 충분합니다.

내용은 짧고 구체적으로 쓰는 것이 좋습니다. 예를 들어 "이 프로젝트는 파이썬 3.12 사용", "테스트는 pytest로 실행", "주석은 한국어로 작성" 같은 식입니다.

한 줄에 규칙 하나씩, 누가 읽어도 해석이 갈리지 않는 문장이 가장 좋은 메모리입니다.

⚠️ 주의  반대로 길고 모호한 문장은 피해야 합니다. "코드를 깔끔하게 작성해줘" 같은 문장은 AI 입장에서 기준이 없어서 사실상 아무 효과가 없습니다.

파일이 너무 길어지면 매 대화마다 그만큼의 분량을 AI가 읽어야 해서, 오히려 응답 품질이 떨어질 수 있습니다.

💬 직접 써본 경험

제 경험상 CLAUDE.md는 처음부터 완벽하게 쓰려고 하면 오히려 시작을 못 합니다. 일단 규칙 서너 줄로 시작하고, 쓰면서 하나씩 추가하는 방식이 훨씬 부담이 적었습니다.

/init이 만들어준 초안도 절반은 제 상황에 맞게 고쳐야 했다는 점은 참고하시기 바랍니다.

# 단축키로 대화 중 기억 바로 저장하기

CLAUDE.md를 매번 직접 열어서 수정하는 건 번거롭습니다. 작업 흐름이 끊기기도 하구요.

그래서 Claude Code는 대화 중에 바로 기억을 추가하는 단축키를 제공합니다.

방법은 아주 간단합니다. 입력창에서 문장 맨 앞에 샵(#) 기호를 붙이고 기억시킬 내용을 적으면 됩니다.

일반 대화와 똑같이 입력하되, 맨 앞에 기호 하나만 추가하는 셈입니다.

예를 들어 # 커밋 메시지는 항상 한국어로 작성해줘라고 입력해보겠습니다. 그러면 Claude Code가 이 내용을 어느 메모리 파일에 저장할지 물어보네요.

저장이 끝나면 다음 대화부터 곧바로 적용되기 때문에, 방금 말한 규칙을 다시 설명할 필요가 없습니다.

 

저장 위치는 보통 두 가지 중에서 고르게 됩니다. 프로젝트 메모리는 지금 작업 중인 폴더에만 적용되구요, 사용자 메모리는 어떤 프로젝트를 열어도 항상 적용됩니다.

사용자 메모리는 내 컴퓨터의 홈 폴더 쪽에 저장되기 때문에 프로젝트를 옮겨 다녀도 계속 따라온다고 보시면 됩니다.

구분	프로젝트 메모리	사용자 메모리
적용 범위	지금 작업 중인 폴더에만 적용	어떤 프로젝트를 열어도 항상 적용
저장 위치	프로젝트 폴더	내 컴퓨터의 홈 폴더
어울리는 예시	"이 프로젝트는 테스트 코드 필수"	"설명은 짧게 해달라"

구분 기준은 간단합니다. "이 프로젝트에서만 필요한가, 아니면 내가 어디서든 원하는 취향인가"를 생각하면 됩니다.

헷갈리면 일단 프로젝트 메모리에 넣어두고, 다른 프로젝트에서도 같은 말을 반복하게 될 때 사용자 메모리로 옮기면 됩니다.

예를 들어 "설명은 짧게 해달라" 같은 개인 취향은 사용자 메모리에 저장하는 것이 맞습니다. 반면 "이 프로젝트는 테스트 코드 필수" 같은 규칙은 프로젝트 메모리가 어울립니다.

💬 직접 써본 경험

직접 써보니 이 # 단축키가 메모리 기능의 진짜 핵심이었습니다. 파일을 열어 편집하는 방식은 결국 귀찮아서 안 하게 되는데, 대화하다가 즉석에서 한 줄 추가하는 건 습관이 되더군요.

💡 팁  다만 아무거나 저장하다 보면 메모리가 금방 지저분해지니, 두 번 이상 반복해서 말하게 된 내용만 저장하는 기준을 추천합니다.

저장된 메모리 확인하고 관리하는 방법

메모리를 쌓기만 하면 끝이 아닙니다. 주기적으로 확인하고 정리해야 제 역할을 합니다.

냉장고에 넣어둔 음식도 가끔 정리해야 하듯이, 메모리도 방치하면 오래된 정보가 쌓여서 오히려 방해가 됩니다.

현재 어떤 메모리가 적용되고 있는지 보려면 /memory 명령어를 입력하면 됩니다. 지금 세션에 로드된 메모리 파일 목록이 한눈에 표시되고, 여기서 바로 편집할 파일을 선택할 수도 있습니다.

AI가 예상과 다르게 행동할 때 이 명령어로 확인해보면, 잊고 있던 옛날 규칙이 원인인 경우가 의외로 많습니다.

 

⚠️ 주의  관리에서 가장 중요한 것은 낡은 기억을 지우는 일입니다. 예를 들어 파이썬 버전을 올렸는데 메모리에는 옛날 버전이 적혀 있다면, AI는 계속 틀린 전제로 작업하게 되네요.

잘못된 메모리는 없는 것보다 나쁘다는 말이 괜히 있는 게 아닙니다.

💬 제 월간 점검 루틴

그래서 저는 한 달에 한 번 정도 CLAUDE.md를 열어서 세 가지를 점검합니다.

1

이미 바뀐 정보는 지우고,

2

중복된 내용은 합치고,

3

너무 길어진 항목은 줄입니다.

10분이면 끝나는 작업인데, 이걸 하고 나면 AI 응답의 정확도가 눈에 띄게 안정됩니다.

💡 팁  한 가지 활용 팁을 더 드리자면, CLAUDE.md를 팀원과 공유하는 방법도 있습니다. 이 파일을 프로젝트 저장소에 함께 올려두면, 팀원 모두의 Claude Code가 같은 규칙을 기억한 상태로 시작합니다.

새 팀원이 합류했을 때 따로 설명하지 않아도 AI가 팀 규칙대로 움직이니, 일종의 자동 인수인계 문서가 되는 셈입니다.

🔍 CLAUDE.local.md란?

혼자 쓰는 개인 취향 파일은 따로 분리할 수도 있습니다. CLAUDE.local.md라는 이름으로 만들면 저장소에 공유되지 않는 개인 메모리로 쓸 수 있으니, 상황에 맞게 나누면 됩니다.

팀 규칙은 CLAUDE.md에, 내 취향은 CLAUDE.local.md에 두는 식으로 역할을 나누면 깔끔합니다.

✍️ 마치며

메모리 기능을 두 달 넘게 쓰면서 느낀 점은, 이 기능이 Claude Code를 도구에서 동료로 바꿔준다는 것입니다. 처음에는 설정이 귀찮았지만, 지금은 새 프로젝트를 시작하면 CLAUDE.md부터 만드는 게 습관이 됐습니다.

다음 글에서는 이 메모리와 궁합이 좋은 커스텀 명령어 만들기를 다뤄볼 겁니다.