CLAUDE.md와 Skills로 Claude Code의 기억 리셋 문제를 해결하는 5분 셋업
요약
본 글은 Claude Code가 세션이 바뀔 때마다 기억을 리셋하는 문제를 해결하기 위한 실용적인 방법을 제시합니다. 이 문제로 인해 생산성이 저하되는 것을 막기 위해, 'CLAUDE.md', 'Skills', 그리고 'memory/' 디렉토리의 3가지 레이어를 활용하여 Claude Code에게 프로젝트에 대한 '영구 기억'을 심는 패턴을 소개합니다. 이 시스템은 CLAUDE.md로 상시 규칙과 기술 스택을 정의하고, Skills로 특정 워크플로우(예: PR 리뷰)를 분리하며, memory/ 디렉토리에 과거의 의사결정 및 배움을 축적하여 매 세션 시작 시 자동으로 참조되도록 합니다. 이 셋업을 통해 Claude Code는 단순한 도구를 넘어 프로젝트 전체를 이해하는 '영구적인 파트너'처럼 작동하게 됩니다.
핵심 포인트
- Claude Code는 기본적으로 세션마다 기억이 리셋되는 한계가 있다.
- 생산성 유지를 위해 CLAUDE.md (상시 규칙), Skills (특정 절차), memory/ (과거 결정)의 3가지 레이어를 구축해야 한다.
- CLAUDE.md에서 `@.claude/memory/`를 참조하여 과거의 지식(decisions, patterns 등)을 매 세션 시작 시 자동으로 로드할 수 있다.
- Skills는 PR 리뷰나 릴리스 절차처럼 반복되는 특정 워크플로우를 분리 정의하는 데 유용하다.
- 이 시스템은 일회성 스냅샷 기록보다는 지속적인 업데이트와 의사결정 이력(원칙)을 축적하는 것이 중요하다.
Qiita에서 "Claude Code는 세션을 넘어가면 기억이 리셋된다 — 5분 만에 영구 기억을 심는 방법"이 트렌드에 올랐습니다.
이는 Claude Code를 실무에서 사용하기 시작한 많은 엔지니어가 처음으로 맞닥뜨리는 문제입니다.
매일 Claude Code MAX로 실제 프로덕트를 구동하고 있는 입장에서, 이 문제를 CLAUDE.md / Skills / Hooks 3종 세트로 해결하는 실용적인 패턴을 공유합니다.
5분이면 셋업이 가능합니다.
Claude Code는 세션마다 기억이 리셋됩니다.
즉,
- 어제 "우리 프로젝트는 TypeScript로 작성한다"라고 알려주어도
- 오늘 새로운 세션을 열면 잊어버리고
- 매번 같은 설명을 반복해야 하는 상황이 발생합니다.
이것이 지속되면, 생산성이 체감상 30~50% 하락한다는 것이 현장의 실감입니다.
3가지 레이어로 "영구 기억"을 만듭니다:
Layer 1: CLAUDE.md → 프로젝트 전체의 상시 규칙 (매 세션 시작부터 적용)
Layer 2: Skills → 특정 절차·워크플로우 (트리거로 호출)
Layer 3: memory/ 디렉토리 → 과거의 결정·배움의 축적 (필요 시 참조)
각각의 역할과 작성법을 살펴보겠습니다.
프로젝트 루트에 CLAUDE.md를 만들고, 아래 내용을 넣습니다:
# 프로젝트 메모
## 기술 스택
- 프론트: Next.js 14 (App Router) + TypeScript + Tailwind
...
이것만으로도 매 세션 시작부터 Claude Code는 "당신의 프로젝트에 대한 상식"을 가진 상태로 기동합니다.
.claude/skills/ 하위에 특정 절차를 분리합니다.
예: pr-review/skill.md
# pr-review
PR 리뷰를 할 때의 절차:
1. PR의 개요를 요약한다
...
세션 중에 "PR 리뷰해줘"라고 말하는 것만으로 이 절차가 호출됩니다.
.claude/memory/를 만들어 과거의 결정이나 배움을 기록합니다:
.claude/memory/
├── decisions.md # 중요한 기술적 판단 이력
├── patterns.md # 반복적으로 나타나는 구현 패턴
...
CLAUDE.md에서 @.claude/memory/를 참조하게 하면 세션 시작 시 자동으로 읽어옵니다:
# CLAUDE.md
@.claude/memory/decisions.md
@.claude/memory/patterns.md
제 프로젝트에서 3가지를 갖춘 전후 비교:
| 지표 | 정비 전 | 정비 후 |
|---|---|---|
| 1세션의 평균 길이 | 짧음 (매번 처음부터 설명) | 길음 (깊은 토론이 가능) |
| ... |
"기억 리셋"이 해소되면, Claude Code는 영구적인 파트너가 됩니다.
-
너무 긴 CLAUDE.md는 역효과. 절차는 Skills로 분리할 것.
-
스냅샷처럼 "현재 상태"를 적으면 변화를 따라갈 수 없게 됨. 의사결정 이력과 원칙만 적을 것.
-
Skills나 memory는 지속적인 업데이트가 전제. 한 달에 한 번씩 검토하는 습관을 들일 것.
-
프로젝트 루트에 CLAUDE.md를 만든다 (철칙·스택·규약)
-
.claude/skills/에 PR 리뷰 / 릴리스 절차 등을 둔다 -
.claude/memory/에 과거의 결정·실패를 축적한다 -
CLAUDE.md에서
@.claude/memory/로 참조시킨다
이렇게 하면 Claude Code는 매 세션 "당신의 프로젝트를 완전히 이해한 파트너"로서 기동합니다.
세션 간의 기억 리셋으로 고민하고 계신 분들은 꼭 시도해 보세요.
관련: 교재로 직접 움직이며 배우기
- 우선 무료로 시도하고 싶은 분: 교재 체험판을 GitHub에서 배포 중 (
git clone)
してすぐ動かせます） → https://github.com/ayies128/next-ai-camp-trial - 全20セッション完全版＋メンタリング → https://menta.work/plan/20251?ref=qiita
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기