Claude Code 공식문서 리뷰-Configuration[4] : Claude의 메모리 관리(Manage Claude's memory)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [설정] 섹션의 내용 중 [Claude Code 설정(Claude Code settings)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/memory

Manage Claude's memory - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

 

Claude Code 메모리 시스템

📅 원문 기준: 2025-12-23 | 🔗 공식 문서

이 문서에서 다루는 내용

• CLAUDE.md: Claude Code의 메모리 파일 개념
• 메모리 유형: 기업 정책, 프로젝트, 사용자, 로컬 메모리
• 모듈식 규칙: .claude/rules/ 디렉토리 활용
• 경로별 규칙: 특정 파일에만 적용되는 규칙 설정
• 조직 관리: 팀 전체에 일관된 규칙 배포

왜 메모리 시스템이 필요한가?

Claude Code를 실행할 때마다 "2칸 들여쓰기 써줘", "테스트는 pytest로 해줘", "커밋 메시지는 한글로 작성해줘"라고 반복하고 있지 않은가? CLAUDE.md에 한 번만 적어두면, Claude가 매번 자동으로 기억한다.

메모리 시스템을 쓰면

• 반복 설명 불필요 - 프로젝트 규칙을 매번 설명할 필요 없음
• 팀 일관성 - 팀원 모두가 같은 코딩 스타일로 작업
• 실수 방지 - "이 파일은 건드리지 마", "이 API는 deprecated야" 같은 주의사항 자동 적용
• 개인화 - 선호하는 응답 스타일, 언어, 도구 설정 저장

CLAUDE.md란?

Claude Code의 메모리 파일이다. 프로젝트 규칙, 코딩 스타일, 빌드 명령 등을 저장한다. Git의 .gitignore나 ESLint의 .eslintrc와 비슷한 역할이다.

 

메모리 유형 및 위치

Claude Code는 여러 수준의 메모리를 지원합니다. 각각 다른 범위와 용도를 가집니다:

유형	위치	용도	공유 범위
기업 정책	플랫폼별 시스템 경로	IT/DevOps 관리 조직 전체 지침	조직 전체
프로젝트 메모리	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 프로젝트 지침	팀원 공유 (Git)
프로젝트 규칙	./.claude/rules/*.md	주제별 모듈식 지침	팀원 공유 (Git)
사용자 메모리	~/.claude/CLAUDE.md	모든 프로젝트의 개인 선호도	본인만
로컬 프로젝트 메모리	./CLAUDE.local.md	개인 프로젝트별 선호도	본인만

기업 정책 파일 위치

플랫폼	경로
macOS	/Library/Application Support/ClaudeCode/CLAUDE.md
Linux	/etc/claude-code/CLAUDE.md
Windows	C:\Program Files\ClaudeCode\CLAUDE.md

초보자 팁

CLAUDE.local.md 파일은 자동으로 .gitignore에 추가되어 개인 설정을 저장하기에 적합합니다.

나에게 맞는 메모리 유형 선택하기

어떤 메모리를 써야 할까?

처음엔 헷갈릴 수 있다. 아래 상황별 가이드를 참고하자.

상황 1: "혼자 개발하는 사이드 프로젝트예요"

가장 간단하다. 프로젝트 루트에 CLAUDE.md 하나만 만들면 된다.

추천 설정

프로젝트/
└── CLAUDE.md        # 여기에 모든 규칙 작성

상황 2: "팀 프로젝트인데 내 설정도 따로 쓰고 싶어요"

팀 공통 규칙은 Git에 커밋하고, 개인 선호도는 CLAUDE.local.md에 저장하자.

추천 설정

프로젝트/
├── CLAUDE.md        # 팀 공통 규칙 (Git 커밋)
└── CLAUDE.local.md  # 내 개인 설정 (자동으로 .gitignore)

예: 팀은 영어 커밋 메시지를 쓰지만, 나는 한글 주석을 선호한다면 → CLAUDE.local.md에 작성

상황 3: "여러 프로젝트에서 같은 설정을 쓰고 싶어요"

모든 프로젝트에 적용할 개인 선호도는 홈 디렉토리의 사용자 메모리에 저장하자.

추천 설정

~/.claude/
└── CLAUDE.md    # 모든 프로젝트에 적용되는 내 선호도

예: "항상 한국어로 응답해줘", "커밋 메시지는 영어로 작성해줘" 같은 개인 선호도

상황 4: "대규모 프로젝트라 규칙이 너무 많아요"

.claude/rules/ 디렉토리로 규칙을 모듈화하자.

추천 설정

프로젝트/
└── .claude/
    ├── CLAUDE.md           # 핵심 규칙만
    └── rules/
        ├── frontend.md     # 프론트엔드 규칙
        ├── backend.md      # 백엔드 규칙
        └── testing.md      # 테스트 규칙

 

메모리 검색 방식

Claude Code는 메모리를 재귀적으로 검색합니다:

1. 현재 작업 디렉토리(cwd)에서 시작
2. 루트 디렉토리 / 직전까지 상위로 재귀
3. 발견된 모든 CLAUDE.md 또는 CLAUDE.local.md 파일 읽기
4. 현재 디렉토리 하위 트리의 CLAUDE.md도 발견

예시: foo/bar/에서 작업할 때 foo/CLAUDE.md와 foo/bar/CLAUDE.md 모두 로드됩니다.

실전 팁

/memory 명령으로 현재 로드된 모든 메모리 파일을 확인할 수 있습니다.

 

CLAUDE.md 임포트

CLAUDE.md 파일은 @path/to/import 구문으로 다른 파일을 임포트할 수 있습니다.

상대 경로 예시

프로젝트 개요는 @README, npm 명령은 @package.json 참조.

# 추가 지침
- Git 워크플로우 @docs/git-instructions.md

홈 디렉토리 예시

# 개인 선호도
- @~/.claude/my-project-instructions.md

임포트 규칙

규칙	설명
경로	상대 및 절대 경로 모두 허용
코드 블록	마크다운 코드 블록 내부는 평가하지 않음
재귀	최대 5단계까지 재귀 임포트 지원
확인	/memory 명령으로 로드된 파일 확인

 

프로젝트 메모리 설정

빠른 시작

프로젝트에 CLAUDE.md를 생성하려면:

/init

프로젝트 메모리는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 저장할 수 있습니다.

프로젝트 메모리에 포함할 내용

항목	예시
빌드/테스트/린트 명령	npm run build, pytest
코드 스타일 선호도	2칸 들여쓰기, 세미콜론 사용
네이밍 규칙	camelCase, PascalCase
아키텍처 패턴	MVC, 레이어드 아키텍처
프로젝트 규칙	PR 규칙, 코드 리뷰 가이드

예시 CLAUDE.md

# 프로젝트 규칙

## 빌드 명령
- 개발: `npm run dev`
- 빌드: `npm run build`
- 테스트: `npm run test`

## 코드 스타일
- TypeScript 사용
- 2칸 들여쓰기
- 세미콜론 필수
- import는 알파벳 순 정렬

## 컨벤션
- 컴포넌트: PascalCase
- 훅: useCamelCase
- 유틸: camelCase

실전 예제: 프론트엔드 프로젝트

React + TypeScript 프로젝트

Next.js, Vite 등 React 기반 프로젝트에 바로 적용할 수 있다.

# 프로젝트 개요
React + TypeScript + Tailwind CSS 기반 프론트엔드 프로젝트

## 명령어
- 개발 서버: `npm run dev`
- 빌드: `npm run build`
- 테스트: `npm run test`
- 린트: `npm run lint`

## 코드 스타일
- TypeScript strict 모드 사용
- 함수형 컴포넌트만 사용 (class 컴포넌트 금지)
- CSS는 Tailwind 유틸리티 클래스 사용
- 인라인 스타일 금지

## 컴포넌트 규칙
- 컴포넌트 파일명: PascalCase (예: UserProfile.tsx)
- 한 파일에 한 컴포넌트만
- Props 타입은 컴포넌트명 + Props (예: UserProfileProps)
- 기본 export 사용

## 상태 관리
- 전역 상태: Zustand 사용
- 서버 상태: TanStack Query 사용
- 로컬 상태: useState 또는 useReducer

## 폴더 구조
- components/: 재사용 컴포넌트
- pages/ 또는 app/: 라우트 컴포넌트
- hooks/: 커스텀 훅
- utils/: 유틸리티 함수
- types/: TypeScript 타입 정의

## 금지 사항
- any 타입 사용 금지
- console.log 커밋 금지
- 인라인 스타일 금지

실전 예제: 백엔드 프로젝트

Python FastAPI 프로젝트

FastAPI, Flask, Django 등 Python 백엔드 프로젝트에 적용할 수 있다.

# 프로젝트 개요
FastAPI + SQLAlchemy + PostgreSQL 기반 REST API 서버

## 명령어
- 개발 서버: `uvicorn app.main:app --reload`
- 테스트: `pytest`
- 린트: `ruff check .`
- 포맷: `ruff format .`
- 마이그레이션: `alembic upgrade head`

## 코드 스타일
- Python 3.11+ 문법 사용
- 타입 힌트 필수
- docstring은 Google 스타일
- 한 줄 최대 88자 (ruff 기본값)

## API 규칙
- RESTful 엔드포인트 설계
- 응답은 Pydantic 모델로 정의
- 에러는 HTTPException으로 처리
- 모든 엔드포인트에 OpenAPI 문서화

## 데이터베이스
- SQLAlchemy 2.0 스타일 사용
- 모델은 app/models/에 정의
- 마이그레이션은 Alembic 사용
- 쿼리는 Repository 패턴으로 분리

## 폴더 구조
- app/api/: 라우터 정의
- app/models/: SQLAlchemy 모델
- app/schemas/: Pydantic 스키마
- app/services/: 비즈니스 로직
- app/repositories/: 데이터 접근 계층

## 보안 규칙
- 환경 변수는 .env 파일에 저장 (.gitignore에 추가됨)
- 비밀번호는 bcrypt로 해싱
- JWT 토큰으로 인증
- SQL 인젝션 방지를 위해 ORM 사용

실전 예제: 사용자 메모리 (~/.claude/CLAUDE.md)

모든 프로젝트에 적용할 개인 선호도

홈 디렉토리의 ~/.claude/CLAUDE.md에 저장하면 모든 프로젝트에서 자동 적용된다.

# 개인 선호도

## 응답 스타일
- 한국어로 응답
- 설명은 간결하게
- 코드에는 주석 추가

## 커밋 메시지
- 영어로 작성
- Conventional Commits 형식 (feat:, fix:, docs: 등)
- 50자 이내로 제목 작성

## 코딩 습관
- 변경 전 기존 코드 먼저 분석
- 한 번에 하나의 변경만
- 변경 후 테스트 실행 확인

## 선호하는 도구
- 패키지 매니저: pnpm (Node.js), uv (Python)
- 포맷터: Prettier (JS/TS), Ruff (Python)
- 테스트: Vitest (JS/TS), pytest (Python)

 

모듈식 규칙: .claude/rules/

대규모 프로젝트는 .claude/rules/ 디렉토리로 지침을 여러 파일로 분리할 수 있습니다.

언제 모듈식 규칙을 써야 할까?

CLAUDE.md 하나로 충분한 경우가 많다. 다음 경우에만 .claude/rules/를 고려하자:

• CLAUDE.md가 100줄을 넘어 관리가 어려울 때
• 프론트엔드/백엔드 규칙이 완전히 다를 때
• 특정 파일 유형에만 적용할 규칙이 있을 때

규칙 파일 처음 작성하기

3단계로 시작하기

1단계: 디렉토리 생성

mkdir -p .claude/rules

2단계: 규칙 파일 생성

주제별로 파일을 나눈다. 파일명이 곧 규칙의 목적을 설명해야 한다.

# 예시: 테스트 규칙 파일
touch .claude/rules/testing.md

3단계: 규칙 내용 작성

마크다운으로 작성한다. 필요하면 YAML 프론트매터로 적용 범위를 지정한다.

---
paths: **/*.test.ts, **/*.spec.ts
---

# 테스트 작성 규칙

- Vitest 사용
- 테스트 파일은 소스 파일과 같은 디렉토리에
- describe/it 패턴 사용
- 각 테스트는 독립적으로 실행 가능해야 함

기본 구조

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

.claude/rules/ 내 모든 .md 파일은 .claude/CLAUDE.md와 동일한 우선순위로 자동 로드됩니다.

경로별 규칙 (Path-Specific Rules)

YAML 프론트매터의 paths 필드로 특정 파일에만 규칙을 적용할 수 있습니다:

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

# API 개발 규칙

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

paths 필드가 없는 규칙은 모든 파일에 무조건 적용됩니다.

Glob 패턴

패턴	매칭 대상
**/*.ts	모든 디렉토리의 TypeScript 파일
src/**/*	src/ 하위 모든 파일
*.md	프로젝트 루트의 마크다운 파일
src/components/*.tsx	특정 디렉토리의 React 컴포넌트

중괄호 확장

---
paths: src/**/*.{ts,tsx}
---

# TypeScript/React 규칙

다중 패턴

---
paths: {src,lib}/**/*.ts, tests/**/*.test.ts
---

하위 디렉토리 구성

규칙을 하위 디렉토리로 정리할 수 있습니다:

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

모든 .md 파일은 재귀적으로 검색됩니다.

심볼릭 링크

프로젝트 간 규칙 공유를 위해 심볼릭 링크를 지원합니다:

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

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

실전 팁

회사 공통 규칙을 별도 저장소에 관리하고 심볼릭 링크로 각 프로젝트에 연결하면 일관성을 유지할 수 있습니다.

 

사용자 레벨 규칙

~/.claude/rules/에 개인 규칙을 생성할 수 있습니다:

~/.claude/rules/
├── preferences.md    # 개인 코딩 선호도
└── workflows.md      # 선호하는 워크플로우

사용자 레벨 규칙은 프로젝트 규칙보다 먼저 로드되어, 프로젝트 규칙이 더 높은 우선순위를 갖습니다.

 

메모리 직접 편집

세션 중 /memory 슬래시 명령으로 시스템 편집기에서 메모리 파일을 열 수 있습니다:

/memory

대규모 추가나 정리 작업에 유용합니다.

 

조직 레벨 메모리 관리

기업은 중앙 관리형 CLAUDE.md 파일을 배포할 수 있습니다:

1. 기업 정책 위치에 메모리 파일 생성
2. 구성 관리 시스템(MDM, Group Policy, Ansible 등)으로 배포
3. 모든 개발자 머신에 일관된 지침 적용

 

모범 사례

메모리 내용

권장	비권장
"2칸 들여쓰기 사용"	"코드 올바르게 포맷"
마크다운 헤딩으로 구조화	긴 문단으로 작성
프로젝트 변화에 따라 정기 업데이트	오래된 지침 방치

.claude/rules/ 구성

권장	비권장
파일당 하나의 주제 (testing.md)	모든 규칙을 한 파일에
내용을 설명하는 파일명	모호한 이름 (rules1.md)
관련 규칙은 하위 디렉토리로 (frontend/)	평평한 구조
필요할 때만 paths 사용	모든 규칙에 paths 추가

 

자주 하는 실수 & 문제 해결

메모리가 적용되지 않는다면?

아래 체크리스트를 확인하자. 대부분 간단한 실수다.

문제 1: "CLAUDE.md를 만들었는데 적용이 안 돼요"

증상

CLAUDE.md를 작성했는데 Claude가 규칙을 무시하는 것 같다.

확인 사항

1. 파일명 확인 - 대소문자가 정확한가?
   ✅ CLAUDE.md (대문자)
   ❌ claude.md, Claude.md
2. 위치 확인 - 올바른 디렉토리에 있는가?
   /memory 명령으로 로드된 파일 목록 확인
3. 인코딩 확인 - UTF-8인가?
   특수문자가 깨지면 인코딩 문제일 수 있다

문제 2: "규칙이 너무 많아서 Claude가 혼란스러워해요"

증상

규칙을 많이 적었는데 Claude가 일부만 따르거나, 규칙끼리 충돌하는 것 같다.

해결 방법

• 핵심 규칙만 남기기 - 모든 것을 적을 필요 없다. 중요한 것만.
• 구체적으로 작성 - "좋은 코드 작성" → "2칸 들여쓰기, 세미콜론 필수"
• 상충하는 규칙 제거 - "간결하게" + "주석 많이" 같은 모순 피하기
• 우선순위 명시 - 중요한 규칙은 상단에, "필수", "권장" 구분

문제 3: "paths 패턴이 작동하지 않아요"

증상

YAML 프론트매터로 paths를 지정했는데 규칙이 적용되지 않는다.

확인 사항

올바른 예	paths: src/**/*.ts paths: **/*.test.ts
잘못된 예	paths: /src/*.ts (절대 경로) paths: src/ (파일 패턴 없음)

팁: paths 없이 시작하고, 필요할 때만 추가하는 것이 좋다.

문제 4: "팀원마다 다른 결과가 나와요"

증상

같은 프로젝트인데 팀원마다 Claude의 응답 스타일이 다르다.

원인 및 해결

• 개인 메모리 충돌 - 각자의 ~/.claude/CLAUDE.md가 다르다
  → 팀 규칙은 프로젝트 CLAUDE.md에만 작성
• CLAUDE.local.md 차이 - 개인 설정 파일이 다르다
  → 팀 필수 규칙은 CLAUDE.md에, 개인 선호는 CLAUDE.local.md에
• Git에 커밋 안 함 - CLAUDE.md가 커밋되지 않았다
  → git add CLAUDE.md 확인

디버깅 팁

/memory 명령으로 현재 로드된 모든 메모리 파일과 그 내용을 확인할 수 있다. 문제가 생기면 여기서 시작하자.

 

관련 문서

문서	언제 유용한가?
Settings 설정 파일 가이드	이럴 때 보자: - 메모리 외에 다른 설정도 커스터마이징하고 싶을 때 - 권한 설정, 자동 승인 등을 조정하고 싶을 때
슬래시 명령 /init, /memory 등	이럴 때 보자: - Claude Code에서 사용할 수 있는 모든 명령어를 알고 싶을 때 - /init으로 CLAUDE.md를 자동 생성하고 싶을 때