[공식문서읽기] Claude Code 메모리 완벽 가이드: 세션 간 설정과 선호도 관리하기

Claude Code를 사용하다 보면 매번 같은 설정을 반복해서 알려줘야 하는 번거로움을 느낀 적이 있으신가요? "들여쓰기는 2칸으로", "테스트는 pytest로", "커밋 메시지는 한글로" 같은 지침을 매 세션마다 입력하는 것은 비효율적입니다. Claude Code의 메모리 시스템을 활용하면 이런 선호도를 영구적으로 저장하고 자동으로 적용할 수 있습니다.

메모리란 무엇인가?

Claude Code의 메모리는 CLAUDE.md 파일을 통해 세션 간 지속되는 지침과 선호도를 저장하는 시스템입니다. 코드 스타일 가이드라인, 자주 사용하는 명령어, 프로젝트 아키텍처 정보 등을 저장해두면 매 세션마다 Claude가 이를 자동으로 참조합니다.

4가지 메모리 유형 이해하기

Claude Code는 계층 구조로 구성된 4가지 메모리 위치를 제공합니다. 각각 다른 범위와 목적을 가지고 있어 상황에 맞게 활용할 수 있습니다.

1. 엔터프라이즈 정책 (조직 전체)

IT/DevOps 팀에서 관리하는 조직 전체 지침입니다. 회사의 코딩 표준, 보안 정책, 규정 준수 요구사항 등을 정의합니다.

파일 위치:

• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
• Linux: /etc/claude-code/CLAUDE.md
• Windows: C:\Program Files\ClaudeCode\CLAUDE.md

2. 프로젝트 메모리 (팀 공유)

프로젝트 루트에 위치하며 팀 전체가 공유하는 지침입니다. Git을 통해 버전 관리되므로 팀원 모두가 동일한 컨텍스트를 공유할 수 있습니다.

파일 위치:

• ./CLAUDE.md 또는
• ./.claude/CLAUDE.md

활용 예시:

• 프로젝트 아키텍처 설명
• 코딩 컨벤션
• 빌드 및 테스트 명령어
• 일반적인 워크플로우

3. 프로젝트 규칙 (모듈식 관리)

대규모 프로젝트에서 지침을 주제별로 분리하여 관리할 수 있습니다.

파일 위치: ./.claude/rules/*.md

4. 사용자 메모리 (개인 선호도)

모든 프로젝트에 적용되는 개인 선호도입니다. 어떤 프로젝트에서 작업하든 일관된 경험을 제공합니다.

파일 위치: ~/.claude/CLAUDE.md

5. 로컬 프로젝트 메모리 (개인 + 프로젝트별)

특정 프로젝트에서만 사용하는 개인 설정입니다. 자동으로 .gitignore에 추가되어 버전 관리에 포함되지 않습니다.

파일 위치: ./CLAUDE.local.md

메모리 우선순위

메모리 파일들은 계층 구조에서 상위에 있는 파일이 먼저 로드됩니다. 즉, 엔터프라이즈 정책이 가장 먼저 적용되고, 그 위에 프로젝트 메모리, 사용자 메모리 순으로 쌓입니다. 더 구체적인 메모리가 일반적인 메모리 위에 구축되는 구조입니다.

빠른 시작: /init 명령어

프로젝트 메모리를 처음 설정할 때는 /init 명령어를 사용하면 편리합니다. 이 명령어는 코드베이스를 분석하여 기본적인 CLAUDE.md 파일을 자동 생성해줍니다.

> /init

파일 임포트 기능

CLAUDE.md 파일에서 @path/to/file 구문을 사용하면 다른 파일의 내용을 임포트할 수 있습니다. 이를 통해 메모리를 모듈화하고 재사용할 수 있습니다.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

주요 특징:

• 상대 경로와 절대 경로 모두 지원
• 최대 5단계 깊이까지 재귀적 임포트 가능
• 홈 디렉토리 참조 가능 (@~/.claude/my-instructions.md)
• 코드 블록 내 @ 기호는 임포트로 처리되지 않음

모듈식 규칙 관리: .claude/rules/

대규모 프로젝트에서는 하나의 큰 CLAUDE.md 파일 대신 주제별로 분리된 규칙 파일을 관리할 수 있습니다.

디렉토리 구조 예시

your-project/
├── .claude/
│   ├── CLAUDE.md           # 메인 프로젝트 지침
│   └── rules/
│       ├── code-style.md   # 코드 스타일 가이드
│       ├── testing.md      # 테스트 규칙
│       └── security.md     # 보안 요구사항

경로별 조건부 규칙

특정 파일 패턴에만 적용되는 규칙을 정의할 수 있습니다. YAML 프론트매터의 paths 필드를 사용합니다.

---
paths: src/api/**/*.ts
---

# API 개발 규칙

- 모든 API 엔드포인트에 입력 검증 포함
- 표준 에러 응답 형식 사용
- OpenAPI 문서 주석 포함

Glob 패턴 지원

패턴	설명
**/*.ts	모든 디렉토리의 TypeScript 파일
src/**/*	src 디렉토리 하위 모든 파일
*.md	루트의 마크다운 파일
src/**/*.{ts,tsx}	TypeScript와 TSX 파일 모두

서브디렉토리 구성

규칙 파일을 서브디렉토리로 구성하여 더 체계적으로 관리할 수 있습니다.

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

심볼릭 링크 활용

여러 프로젝트에서 공통 규칙을 공유하려면 심볼릭 링크를 활용할 수 있습니다.

# 공유 규칙 디렉토리 링크
ln -s ~/shared-claude-rules .claude/rules/shared

# 개별 규칙 파일 링크
ln -s ~/company-standards/security.md .claude/rules/security.md

메모리 편집: /memory 명령어

세션 중에 메모리를 직접 편집하려면 /memory 명령어를 사용합니다. 시스템 편집기에서 메모리 파일이 열리며, 수정 후 저장하면 즉시 반영됩니다.

> /memory

메모리 로드 확인하기

현재 로드된 메모리 파일을 확인하려면 /memory 명령어를 실행하면 됩니다. 어떤 파일들이 컨텍스트에 포함되어 있는지 확인할 수 있습니다.

메모리 작성 모범 사례

1. 구체적으로 작성하기

모호한 지침보다 구체적인 지침이 효과적입니다.

좋은 예: "들여쓰기는 2칸 스페이스 사용"
나쁜 예: "코드를 적절히 포맷합니다"

2. 구조화하여 정리하기

글머리 기호와 마크다운 제목을 활용하여 관련 메모리를 그룹화합니다.

# 코드 스타일
- 들여쓰기: 2칸 스페이스
- 따옴표: 작은따옴표 사용
- 세미콜론: 생략

# 테스트
- 프레임워크: Jest
- 커버리지 목표: 80% 이상

3. 자주 사용하는 명령어 포함하기

빌드, 테스트, 린트 명령어를 미리 정의해두면 반복적인 검색을 피할 수 있습니다.

# 명령어
- 빌드: `npm run build`
- 테스트: `npm test`
- 린트: `npm run lint`

4. 정기적으로 검토하고 업데이트하기

프로젝트가 진화함에 따라 메모리도 함께 업데이트해야 합니다. 오래된 정보는 오히려 혼란을 줄 수 있습니다.

5. 규칙 파일 집중화하기

.claude/rules/ 디렉토리를 사용할 때는 각 파일이 하나의 주제만 다루도록 합니다. 파일명은 내용을 명확히 나타내야 합니다.

실전 CLAUDE.md 예시

# 프로젝트 개요
React + TypeScript 기반 웹 애플리케이션

# 코드 스타일
- TypeScript strict 모드 사용
- 함수형 컴포넌트 선호
- CSS-in-JS (styled-components) 사용

# 명령어
- 개발 서버: `npm run dev`
- 빌드: `npm run build`
- 테스트: `npm test`
- 타입 체크: `npm run typecheck`

# 아키텍처
- components/: 재사용 가능한 UI 컴포넌트
- pages/: 라우트별 페이지 컴포넌트
- hooks/: 커스텀 훅
- utils/: 유틸리티 함수

# Git 컨벤션
- 커밋 메시지: 한글 작성
- 브랜치명: feature/기능명, fix/버그명

마무리

Claude Code의 메모리 시스템을 잘 활용하면 매 세션마다 동일한 지침을 반복할 필요 없이 일관된 개발 경험을 유지할 수 있습니다. 개인 선호도부터 팀 전체의 코딩 표준까지, 계층화된 메모리 구조를 통해 상황에 맞는 컨텍스트를 자동으로 제공받을 수 있습니다.

지금 바로 /init 명령어로 프로젝트 메모리를 설정해보세요!

---

참고 자료:

• Claude Code 공식 문서 - Memory