포스트

[이제와서 시작하는 Claude AI 마스터하기 #9] CLAUDE.md로 메모리 관리하기

게시 업데이트
[이제와서 시작하는 Claude AI 마스터하기 #9] CLAUDE.md로 메모리 관리하기
[이제와서 시작하는 Claude AI 마스터하기 #9] CLAUDE.md로 메모리 관리하기
By YonYonWare
14 분읽는 시간
[이제와서 시작하는 Claude AI 마스터하기 #9] CLAUDE.md로 메모리 관리하기

Claude Code는 이제 자동으로 기억합니다! Auto Memory 기능으로 작업 중 중요한 내용을 스스로 기록하고, CLAUDE.md를 사용하면 프로젝트의 규칙, 컨벤션, 중요한 정보를 영구적으로 기억시킬 수 있어요. 마치 신입 개발자에게 팀의 규칙을 문서로 전달하는 것처럼요!

완독 시간: 20분 ⭐⭐⭐

🎯 이번에 배울 것

📚 사전 지식

📖 메모리 시스템 이해하기

왜 메모리가 필요한가?

Claude Code는 기본적으로 세션이 끝나면 대화 내용을 잊습니다. 하지만 두 가지 방법으로 기억을 유지할 수 있습니다:

방법 1: Auto Memory (자동)

1
2

Claude가 작업하면서 중요한 패턴, 선호도, 교훈을 자동으로 기록하고
다음 세션에서 자동으로 불러옵니다.

방법 2: CLAUDE.md (수동)

1

세션 1, 2, 3... 모두: "CLAUDE.md에 2-space라고 적혀있네, 그대로 할게!" 😊

Auto Memory: 자동 기억 시스템

Claude Code는 이제 작업 중 자동으로 메모리를 기록하고 참조합니다:

  • 작업하면서 발견한 프로젝트 패턴을 자동 기록
  • 실수와 교훈을 기록해서 같은 실수 반복 방지
  • 다음 세션에서 이전 학습 내용을 자동으로 활용

메모리 파일은 ~/.claude/projects/<project-path>/memory/ 디렉토리에 저장됩니다.

메모리의 종류

Claude Code는 4가지 레벨의 메모리를 지원합니다:

1
2
3
4
5
6
7
8
9
10
11

┌─────────────────────────────────────────────────────────────────┐
│                    메모리 계층 구조                              │
├─────────────────────────────────────────────────────────────────┤
│  🏢 Managed Policy    │ 조직 전체 규칙 (IT 관리자가 설정)         │
├───────────────────────┼─────────────────────────────────────────┤
│  📁 Project Memory    │ 팀 공유 규칙 (Git에 커밋)                │
├───────────────────────┼─────────────────────────────────────────┤
│  👤 User Memory       │ 개인 설정 (모든 프로젝트에 적용)          │
├───────────────────────┼─────────────────────────────────────────┤
│  🔒 Local Memory      │ 개인 + 프로젝트별 (Git에 안 올림)         │
└─────────────────────────────────────────────────────────────────┘

메모리 파일 위치

종류 위치 공유 범위
Managed Policy /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) 조직 전체
Project Memory ./CLAUDE.md 또는 ./.claude/CLAUDE.md 팀 (Git)
Project Rules ./.claude/rules/*.md 팀 (Git)
User Memory ~/.claude/CLAUDE.md 나만 (모든 프로젝트)
Local Memory ./CLAUDE.local.md 나만 (이 프로젝트)

💡 CLAUDE.local.md는 자동으로 .gitignore에 추가됩니다!

✍️ CLAUDE.md 작성법

기본 구조

CLAUDE.md는 마크다운 파일입니다. 자유롭게 작성하되, 명확하고 구체적으로!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Project Guidelines

## 아키텍처
- Layered Architecture 사용 (Controller → Service → Repository)
- 비즈니스 로직은 Service 레이어에만

## 코딩 스타일
- 2-space 들여쓰기
- 함수는 20줄 이하로
- `any` 타입 사용 금지

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

/init으로 자동 생성

처음 시작할 때 Claude가 도와줍니다:

1

/init

프로젝트를 분석하고 적절한 CLAUDE.md 초안을 만들어줍니다.

좋은 CLAUDE.md의 특징

좋은 예 ✅ 나쁜 예 ❌
“2-space 들여쓰기 사용” “코드 잘 포맷팅해”
“에러는 CustomError 클래스로 던져” “에러 처리 잘 해”
“테스트 명령: npm test” “테스트 돌려봐”

📂 메모리 계층 구조

우선순위

여러 CLAUDE.md가 있을 때 더 구체적인 것이 우선:

1
2
3
4
5

높음 ↑
  Managed Policy (조직 정책)
  Project Memory (프로젝트 규칙)
  User Memory (개인 설정)
낮음 ↓

상위 디렉토리 탐색

Claude Code는 현재 디렉토리부터 상위로 올라가며 CLAUDE.md를 찾습니다:

1
2
3
4
5

/project/
├── CLAUDE.md           ← 2순위
└── packages/
    └── frontend/
        └── CLAUDE.md   ← 1순위 (현재 위치)

/project/packages/frontend/에서 실행하면 두 파일 모두 적용됩니다!

하위 디렉토리 발견

특정 파일을 읽을 때, 그 파일 경로에 있는 CLAUDE.md도 로드됩니다:

1
2
3
4
5

/project/
├── CLAUDE.md
└── src/
    └── legacy/
        └── CLAUDE.md   ← src/legacy/ 파일 작업시 자동 로드

📑 .claude/rules/로 모듈화하기

CLAUDE.md가 너무 길어지면 규칙을 파일별로 분리할 수 있습니다.

디렉토리 구조

1
2
3
4
5
6
7
8

your-project/
├── .claude/
│   ├── CLAUDE.md           # 메인 설명
│   └── rules/
│       ├── code-style.md   # 코딩 스타일
│       ├── testing.md      # 테스트 규칙
│       ├── api-design.md   # API 설계 규칙
│       └── security.md     # 보안 규칙

조건부 규칙 (paths 필드)

특정 파일 패턴에만 적용되는 규칙을 만들 수 있습니다:

1
2
3
4
5
6
7
8
9
10

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

# API 개발 규칙

- 모든 엔드포인트에 입력 검증 필수
- 표준 에러 응답 포맷 사용
- OpenAPI 주석 포함

Glob 패턴 예시

패턴 의미
**/*.ts 모든 TypeScript 파일
src/**/* src 폴더 내 모든 파일
*.md 루트의 마크다운 파일만
src/**/*.{ts,tsx} src 내 ts/tsx 파일

서브디렉토리로 그룹화

1
2
3
4
5
6
7
8

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

모든 .md 파일이 재귀적으로 로드됩니다.

📥 파일 임포트 (@문법)

CLAUDE.md에서 다른 파일을 참조할 수 있습니다:

1
2
3
4
5

프로젝트 개요는 @README.md 참고
사용 가능한 npm 명령어는 @package.json 참고

# 추가 지침
- Git 워크플로우는 @docs/git-workflow.md 참고

지원 경로

  • 상대 경로: @./docs/guide.md
  • 절대 경로: @/path/to/file.md
  • 홈 디렉토리: @~/.claude/my-rules.md

주의사항

⚠️ 프로젝트에서 처음 외부 파일을 임포트하면 승인 대화상자가 표시됩니다. 어떤 파일이 어디서 임포트되는지 상세히 보여줍니다.

추가 디렉토리에서 CLAUDE.md 로드

--add-dir 플래그로 추가 디렉토리를 지정하면 그 디렉토리의 CLAUDE.md와 Skills도 자동 로드됩니다:

1

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

📋 실전 CLAUDE.md 템플릿

템플릿 1: 일반 웹 프로젝트

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

# Project: MyApp

## 기술 스택
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- ORM: Prisma

## 아키텍처
- `/src/components/` - React 컴포넌트
- `/src/services/` - 비즈니스 로직
- `/src/api/` - API 라우터
- `/prisma/` - DB 스키마

## 코딩 규칙
- 2-space 들여쓰기
- 세미콜론 필수
- 함수명: camelCase
- 컴포넌트명: PascalCase
- 상수: UPPER_SNAKE_CASE

## 자주 쓰는 명령어
- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 빌드: `npm run build`
- 린트: `npm run lint`
- DB 마이그레이션: `npx prisma migrate dev`

## 테스트
- 단위 테스트: Jest
- 테스트 파일: `*.test.ts` 또는 `*.spec.ts`
- 커버리지 80% 이상 유지

## Git 규칙
- 브랜치: `feature/기능명`, `fix/버그명`
- 커밋 메시지: Conventional Commits 사용

템플릿 2: Python 프로젝트

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# Project: DataPipeline

## 환경
- Python 3.11+
- 가상환경: poetry 사용
- 패키지 설치: `poetry install`

## 프로젝트 구조
- `/src/` - 메인 소스 코드
- `/tests/` - 테스트 코드
- `/notebooks/` - Jupyter 노트북
- `/data/` - 데이터 파일 (Git 제외)

## 코딩 스타일
- Black 포매터 사용 (line-length: 88)
- isort로 import 정렬
- Type hints 필수
- Docstring: Google 스타일

## 명령어
- 테스트: `poetry run pytest`
- 린트: `poetry run ruff check .`
- 포맷팅: `poetry run black .`
- 타입체크: `poetry run mypy src`

## 주의사항
- `.env` 파일은 절대 커밋하지 말 것
- 민감 정보는 환경변수로 관리

템플릿 3: 모노레포

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Monorepo: CompanyPlatform

## 구조
- `/packages/web/` - React 웹앱
- `/packages/mobile/` - React Native 앱
- `/packages/api/` - Node.js API 서버
- `/packages/shared/` - 공유 유틸리티

## 패키지 매니저
- pnpm workspace 사용
- 루트에서: `pnpm install`

## 각 패키지별 규칙
각 패키지의 CLAUDE.md 참고:
- @packages/web/CLAUDE.md
- @packages/api/CLAUDE.md

## 공통 규칙
- TypeScript strict mode
- ESLint + Prettier
- Husky pre-commit hooks

🔧 메모리 관리 명령어

/memory - 메모리 편집

1

/memory

시스템 에디터에서 메모리 파일을 직접 편집합니다.

/context - 현재 상태 확인

1

/context

현재 로드된 CLAUDE.md와 컨텍스트 사용량을 보여줍니다.

💡 베스트 프랙티스

1. 구체적으로 작성

1
2

❌ "코드 잘 써줘"
✅ "함수는 20줄 이하, 단일 책임 원칙 준수"

2. 자주 쓰는 명령어 명시

1
2
3
4

## Commands
- Test: `npm test`
- Build: `npm run build`
- Deploy: `./scripts/deploy.sh`

3. 금지사항 명확히

1
2
3
4

## 금지
- `any` 타입 사용 금지
- console.log 커밋 금지
- 직접 DOM 조작 금지 (React 사용)

4. 예외 상황도 기술

1
2
3

## 예외
- `/scripts/` 폴더는 린트 규칙 예외
- 레거시 코드(`/src/legacy/`)는 리팩토링 전까지 현상 유지

5. 정기적으로 업데이트

프로젝트가 발전하면 CLAUDE.md도 업데이트하세요!

📝 오늘 배운 것 정리

✅ Auto Memory = Claude가 자동으로 학습하고 기억하는 시스템

✅ CLAUDE.md = 수동으로 관리하는 영구 기억 장치

✅ 4가지 메모리 레벨: Managed → Project → User → Local

✅ 상위 디렉토리 탐색: 현재 위치부터 루트까지 CLAUDE.md 수집

✅ .claude/rules/: 규칙을 파일별로 모듈화

✅ 조건부 규칙: paths 필드로 특정 파일에만 적용

✅ @임포트: 다른 파일 내용 참조 가능

🔗 다음 편 미리보기

#05편: Skills - 나만의 슬래시 명령어 만들기

CLAUDE.md보다 더 강력한 확장 기능:

  • Skill이란 무엇인가?
  • SKILL.md 작성법
  • 인자 전달과 동적 컨텍스트
  • 실전 Skill 예제 (코드 리뷰어, PR 요약 등)

🔗 참고 자료

🚀 잘 정리된 CLAUDE.md는 생산성의 시작입니다!

AI, Claude
claude claude-code claude-md memory configuration project-settings tutorial
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.