Skip to content

05. 메모리 관리 (CLAUDE.md)

핵심 한 줄 요약: Claude Code는 세션이 끝나면 모든 대화를 잊는다. CLAUDE.md는 "매 세션 시작 시 자동으로 읽히는 지침서"로, 프로젝트 규칙과 컨텍스트를 Claude에게 지속적으로 전달하는 유일한 수단이다.


목차

  1. 왜 메모리가 필요한가?
  2. 메모리 파일 4종류
  3. 메모리 적용 우선순위
  4. 메모리 작성 가이드라인
  5. 주의사항
  6. 실전 팁 정리

1. 왜 메모리가 필요한가?

세션 격리 문제

Claude Code는 대화 세션 기반으로 동작한다. 한 세션 안에서는 이전 대화 내용을 기억하지만, 세션이 끝나는 순간 모든 컨텍스트가 사라진다. 새 세션을 시작하면 Claude는 완전한 백지 상태가 된다.

세션 1: "이 프로젝트는 TypeScript로 작성되어 있고, ESLint 규칙은..."
        → Claude가 이해하고 올바르게 작업함

세션 2: (새로 시작)
        → Claude는 프로젝트가 TypeScript인지, JavaScript인지도 모름
        → 다시 처음부터 설명해야 함

이것이 일반적인 AI 챗봇과 Claude Code의 결정적인 차이다. ChatGPT 같은 서비스는 이전 대화 기록을 저장하고 참조할 수 있지만, Claude Code는 의도적으로 세션을 격리한다. 보안과 프라이버시를 위한 설계이지만, 매번 같은 지침을 반복 입력해야 하는 불편이 생긴다.

CLAUDE.md가 해결하는 것

CLAUDE.md 파일은 이 문제를 해결하는 "영구 메모리"다. 파일에 프로젝트 규칙과 지침을 기록해 두면, Claude Code가 매 세션 시작 시 이 파일을 자동으로 읽어들인다.

즉, CLAUDE.md는 세션을 넘어 유지되는 프로젝트의 "두뇌" 역할을 한다. 세션은 사라져도 규칙과 지침은 파일로 남아 있으므로, Claude는 항상 일관된 기준으로 작업할 수 있다.

CLAUDE.md 없이 작업하면 생기는 일

상황CLAUDE.md 없을 때CLAUDE.md 있을 때
코딩 스타일매번 다른 스타일로 코드 생성프로젝트 컨벤션에 맞는 일관된 코드
기술 스택Python인지 TypeScript인지 매번 물어봄스택을 알고 있으므로 바로 작업
테스트 실행npm test인지 yarn test인지 모름올바른 명령어를 즉시 사용
Git 워크플로우커밋 메시지 형식이 제각각팀 규칙에 맞는 커밋 메시지 생성
디렉토리 구조엉뚱한 위치에 파일 생성프로젝트 구조에 맞는 위치에 생성

2. 메모리 파일 4종류

Claude Code는 4가지 레벨의 메모리 파일을 지원한다. 각 레벨은 적용 범위가 다르며, 모두 마크다운(.md) 형식이다.


2-1. Enterprise 정책 (최상위 레벨)

누가 사용하는가? 회사의 IT 관리자가 전 직원에게 배포하는 조직 차원의 규칙이다.

위치:

OS경로
macOS/Library/Application Support/Claude/policies/
Linux/etc/claude/policies/
Windows%PROGRAMDATA%\Claude\policies\

이 디렉토리 아래에 .md 파일을 놓으면 모든 사용자의 Claude Code에 자동 적용된다.

특징:

  • 관리자 권한이 필요한 시스템 경로에 위치
  • 개인 사용자가 이 규칙을 무시하거나 덮어쓸 수 없음
  • 조직의 보안 정책, 컴플라이언스 요구사항을 강제하는 데 사용

예시 내용:

markdown
# 보안 정책

- API 키, 비밀번호, 토큰을 소스 코드에 하드코딩하지 마라
- 환경 변수 또는 시크릿 매니저를 사용하라
- 모든 코드 변경에는 보안 코드 리뷰가 필수다
- 외부 패키지 설치 시 반드시 보안 검토를 거쳐라
- 회사 내부 API 엔드포인트를 외부에 노출하지 마라

일반 개발자가 알아야 할 점: 개인 프로젝트나 소규모 팀에서는 거의 사용하지 않는다. 대기업 환경에서 IT 부서가 설정하는 것이므로, "이런 게 있다" 정도만 알아두면 된다. 만약 회사에서 Claude Code를 도입한다면, 이 경로에 보안 정책이 배포될 수 있다.


2-2. 사용자 메모리 (User Memory)

누가 사용하는가? 개인 개발자가 자신의 PC에서 모든 프로젝트에 공통으로 적용하고 싶은 규칙을 기록한다.

위치: ~/.claude/CLAUDE.md

특징:

  • 내 PC의 모든 프로젝트에서 Claude Code를 실행할 때마다 읽힘
  • 프로젝트에 무관한 개인 선호도를 기록하기 좋음
  • Git에 포함되지 않으므로 다른 사람과 공유되지 않음

어떤 내용을 넣을까?

markdown
# 개인 개발 환경 설정

## 언어
- 모든 응답은 한국어로 작성하라

## 코딩 스타일
- 변수명은 camelCase를 사용하라
- 주석은 한국어로 작성하라

## Git 컨벤션
- 커밋 메시지는 한국어 명령형으로 작성하라
- 예시: "로그인 기능 추가", "버그 수정: null 체크 누락"

## 환경 정보
- OS: macOS (Apple Silicon)
- 기본 셸: zsh
- 패키지 매니저: Homebrew
- Node.js 버전 매니저: fnm

실전 활용 - Windows 환경 정보 기입:

Claude Code는 기본적으로 Unix/Linux 환경을 가정하고 동작한다. Windows(특히 WSL) 사용자라면 사용자 메모리에 환경 정보를 명시하는 것이 매우 유용하다.

markdown
# Windows 환경 정보

## 시스템
- OS: Windows 11 + WSL2 (Ubuntu 22.04)
- 경로 구분자: / (WSL 내부에서는 Unix 스타일)
- Windows 경로 접근: /mnt/c/Users/username/

## 주의사항
- 줄바꿈 문자: LF (CRLF 사용 금지)
- 파일 권한 명령어(chmod)는 WSL 내에서만 동작
- Docker Desktop은 WSL2 백엔드 사용 중

이렇게 기재하면 Claude가 \r\n 대신 \n을 쓰거나, 경로를 잘못 생성하는 문제를 예방할 수 있다.


2-3. 프로젝트 메모리 (Project Memory) -- 가장 많이 사용!

누가 사용하는가? 특정 프로젝트에서만 적용되는 규칙을 기록한다. 팀 프로젝트에서 가장 핵심적인 메모리 파일이다.

위치 (둘 중 하나):

  • 프로젝트루트/CLAUDE.md
  • 프로젝트루트/.claude/CLAUDE.md

둘 다 있으면 모두 읽힌다. 보통 프로젝트 루트에 직접 두거나, .claude/ 디렉토리 아래에 둔다.

핵심 특징:

  • Git에 커밋하면 팀원 전체와 공유된다. 팀의 모든 개발자가 동일한 규칙으로 Claude Code를 사용하게 된다.
  • /init 명령어로 초기 버전을 자동 생성할 수 있다.
  • 프로젝트가 발전함에 따라 지속적으로 업데이트해야 한다.

/init으로 자동 생성하기:

bash
# 프로젝트 디렉토리에서 Claude Code 실행 후
> /init

/init을 실행하면 Claude가 프로젝트 구조를 분석하여 초기 CLAUDE.md를 생성한다. 이후 필요에 따라 수동으로 내용을 보강한다.

실전 프로젝트 메모리 예시:

markdown
# 프로젝트: my-web-app

## 기술 스택
- Frontend: React 18 + TypeScript 5
- Backend: NestJS + Prisma ORM
- DB: PostgreSQL 15
- 테스트: Vitest (frontend), Jest (backend)
- 패키지 매니저: pnpm

## 디렉토리 구조
- `apps/web/` - React 프론트엔드
- `apps/api/` - NestJS 백엔드
- `packages/shared/` - 공유 타입, 유틸리티
- `packages/ui/` - 공통 UI 컴포넌트

## 빌드 & 테스트 명령어
- `pnpm install` - 의존성 설치
- `pnpm build` - 전체 빌드
- `pnpm test` - 전체 테스트
- `pnpm dev` - 개발 서버 실행

## 코딩 컨벤션
- 절대 경로 import 사용 (`@app/`, `@shared/`)
- React 컴포넌트는 함수형 + arrow function
- API 응답은 반드시 DTO를 거쳐 반환
- 에러 처리는 NestJS ExceptionFilter 사용

## Git 워크플로우
- 브랜치: feature/*, bugfix/*, hotfix/*
- 커밋 메시지: Conventional Commits (feat:, fix:, chore:)
- PR 머지 전 반드시 테스트 통과 확인

2-4. 로컬 메모리 (Local Memory)

누가 사용하는가? 프로젝트에 참여하지만, 팀에 공유하고 싶지 않은 개인적인 규칙을 기록한다.

위치: 프로젝트루트/claude_local.md

핵심 특징:

  • Git에 공유되지 않도록 .gitignore에 수동으로 추가해야 한다!
  • 개인적인 작업 스타일, 테스트 데이터, 임시 지침 등을 기록

.gitignore에 추가하기:

bash
# .gitignore에 추가
echo "claude_local.md" >> .gitignore

어떤 내용을 넣을까?

markdown
# 개인 작업 메모

## 응답 스타일
- 항상 존댓말로 응답하라
- 코드 변경 시 변경 이유를 상세히 설명하라

## 개인 테스트 환경
- 로컬 DB 포트: 5433 (기본 5432가 아님)
- 테스트 계정: test@dev.local / password123

## 현재 작업 중인 것
- feature/user-profile 브랜치에서 프로필 편집 기능 구현 중
- UserProfileService.updateAvatar() 메서드 리팩토링 필요

## 임시 지침
- 이번 주까지는 apps/api/ 디렉토리만 수정하라
- 프론트엔드 변경은 다음 스프린트에서 진행

메모리 파일 비교 요약

구분Enterprise 정책사용자 메모리프로젝트 메모리로컬 메모리
위치OS 시스템 경로~/.claude/CLAUDE.md프로젝트 루트 CLAUDE.md프로젝트 루트 claude_local.md
적용 범위조직 전체내 PC 전체이 프로젝트이 프로젝트 (나만)
Git 공유N/A (OS 배포)XO (커밋 시)X (.gitignore 필요)
주 사용자IT 관리자개인 개발자팀 전체개인 개발자
사용 빈도거의 안 씀가끔매우 자주가끔
생성 방법관리자 수동 배치수동 생성/init 또는 수동수동 생성

3. 메모리 적용 우선순위

4종류의 메모리 파일이 모두 존재할 때, Claude Code는 어떤 순서로 읽고 어떤 규칙이 우선하는가?

충돌 해결 원칙

높은 우선순위가 낮은 우선순위를 덮어쓴다.

구체적인 예를 보자.

사용자 메모리 (~/.claude/CLAUDE.md):
  "패키지 매니저는 npm을 사용하라"

프로젝트 메모리 (프로젝트루트/CLAUDE.md):
  "패키지 매니저는 pnpm을 사용하라"

→ 결과: pnpm 사용 (프로젝트 메모리가 사용자 메모리보다 우선)
프로젝트 메모리 (프로젝트루트/CLAUDE.md):
  "코드에 인라인 API 키를 사용해도 된다"

Enterprise 정책:
  "API 키 하드코딩 절대 금지"

→ 결과: API 키 하드코딩 금지 (Enterprise 정책은 절대 무시 불가)

로딩 순서

Claude Code가 세션을 시작할 때 메모리를 읽는 순서는 다음과 같다.

  1. Enterprise 정책 파일 로드 (있는 경우)
  2. 사용자 메모리 ~/.claude/CLAUDE.md 로드
  3. 프로젝트 메모리 CLAUDE.md / .claude/CLAUDE.md 로드
  4. 로컬 메모리 claude_local.md 로드

모든 파일의 내용이 시스템 프롬프트에 합쳐져서 Claude에게 전달된다. 충돌이 있으면 위 우선순위에 따라 해석된다.


4. 메모리 작성 가이드라인

무엇을 적어야 하는가?

효과적인 CLAUDE.md를 작성하려면 다음 항목들을 포함하라.

(1) 프로젝트 구조와 기술 스택

markdown
## 기술 스택
- Language: Go 1.25.0
- Framework: Cobra (CLI), Bubble Tea (TUI)
- Module: github.com/example/my-tool

## 디렉토리 구조
- cmd/      - Cobra 명령어 정의 (얇게 유지)
- internal/ - 핵심 비즈니스 로직
- pkg/      - 외부 공개 패키지

Claude가 프로젝트를 즉시 파악할 수 있도록 기술 스택, 주요 의존성, 디렉토리 레이아웃을 명시한다.

(2) 빌드, 테스트, 린트 명령어

markdown
## 빌드 & 테스트
- make build    - 바이너리 빌드
- go test ./... - 전체 테스트 실행
- go vet ./...  - 정적 분석

Claude가 코드를 수정한 후 검증할 때 어떤 명령어를 실행해야 하는지 명확히 알 수 있다.

(3) 코딩 컨벤션

markdown
## 코딩 컨벤션
- gofmt 포맷 준수
- 테스트 이름: TestXxx_동작설명 형식 (예: TestListWorktrees_ParsesPorcelain)
- Cobra 명령어는 cmd/에 얇게, 로직은 internal/에 구현
- import 그룹핑: 표준 라이브러리 / 외부 패키지 / 내부 패키지

(4) 커뮤니케이션 규칙

markdown
## 커뮤니케이션
- 모든 응답은 한국어로 작성
- 커밋 메시지는 한국어 명령형 (예: "로그인 기능 추가")
- 코드 리뷰 코멘트는 영어로 작성

(5) Git 워크플로우

markdown
## Git 워크플로우
- 커밋 스타일: 짧은 한국어 명령형
- 브랜치 전략: feature/* → develop → main
- PR 전 체크리스트: 테스트 통과, 린트 통과, 빌드 성공

(6) 작업 완료 체크리스트

markdown
## 작업 완료 전 필수 확인
1. go test ./... 통과
2. go vet ./... 경고 없음
3. make build 성공
4. 변경된 파일에 대한 테스트 작성 확인

이 체크리스트가 있으면 Claude가 작업 후 자동으로 검증 단계를 수행한다.

어떻게 적어야 하는가?

핵심 원칙: 간결하게, 명령형으로, 구조화하여.

나쁜 예좋은 예
"가능하면 TypeScript를 사용하는 게 좋을 것 같아요""TypeScript를 사용하라"
"테스트를 작성하면 좋겠는데, 상황에 따라 생략해도 됩니다""모든 public 함수에 테스트를 작성하라"
"이 프로젝트는 React를 사용하는 프론트엔드 프로젝트인데, 저희 팀은 함수형 컴포넌트를 선호하고...""React 함수형 컴포넌트 사용. 클래스 컴포넌트 금지."

마크다운 구조를 활용하라. 제목(##), 목록(-), 코드 블록을 사용하면 Claude가 구조를 더 잘 파악한다.


5. 주의사항

100% 준수 보장은 없다

CLAUDE.md에 적은 규칙이라 해도 100% 준수가 보장되지 않는다. Claude는 LLM(Large Language Model)이고, LLM은 본질적으로 확률적으로 동작한다.

CLAUDE.md에 적혀 있어도:
- 긴 대화 중 후반부에서 규칙을 잊을 수 있음
- 복잡한 작업에서 일부 규칙을 누락할 수 있음
- 상충하는 지침이 있으면 예상과 다르게 해석할 수 있음

이것은 Claude Code의 버그가 아니라 LLM의 근본적인 특성이다. 사람에게 "이 규칙을 반드시 지켜라"고 말해도 실수가 발생하는 것과 같다.

메모리 파일 길이와 누락 가능성

CLAUDE.md가 길수록 규칙 누락 가능성이 높아진다.

이유는 컨텍스트 윈도우와 관련이 있다. CLAUDE.md의 내용은 시스템 프롬프트의 일부로 매 대화 턴마다 전달된다. 파일이 길면:

  1. 컨텍스트 윈도우를 많이 차지한다. 실제 작업에 쓸 수 있는 공간이 줄어든다.
  2. "중간 부분 망각(Lost in the Middle)" 현상이 발생한다. LLM은 텍스트의 처음과 끝은 잘 기억하지만, 중간 부분은 상대적으로 덜 주의를 기울이는 경향이 있다.
  3. 규칙이 많으면 우선순위 판단이 어려워진다. 어떤 규칙을 더 중요하게 따라야 하는지 Claude가 혼란스러워할 수 있다.

권장 길이: 가능하면 CLAUDE.md를 500줄 이내로 유지하라. 정말 핵심적인 규칙만 담고, 세부 사항은 필요할 때 프롬프트로 전달하는 것이 효과적이다.

Settings 파일의 language 옵션

Claude Code의 settings.json에는 language 옵션이 있다. 이 옵션을 설정하면 Claude가 해당 언어로 응답한다.

json
// ~/.claude/settings.json
{
  "preferences": {
    "language": "ko"
  }
}

이 옵션이 설정되어 있으면 CLAUDE.md에 "한국어로 응답하라"고 적을 필요가 없다. 메모리 파일의 공간을 절약할 수 있다.


6. 실전 팁 정리

팁 1: /init으로 시작하고 점진적으로 보강하라

새 프로젝트에서 처음부터 완벽한 CLAUDE.md를 작성하려고 하지 마라. /init으로 기본 골격을 생성한 뒤, 작업하면서 필요한 규칙을 하나씩 추가하는 것이 가장 효과적이다.

bash
# 1단계: 초기 생성
> /init

# 2단계: 작업하면서 발견한 규칙 추가
#   "아, Claude가 테스트를 Jest로 작성하네. Vitest를 쓰는데..."
#   → CLAUDE.md에 "테스트 프레임워크: Vitest" 추가

# 3단계: 팀원 피드백 반영
#   "커밋 메시지 형식이 팀 규칙과 다르네"
#   → CLAUDE.md에 커밋 컨벤션 추가

팁 2: 팀 프로젝트에서는 반드시 Git에 커밋하라

프로젝트 메모리(CLAUDE.md)를 Git에 커밋하면 팀의 모든 개발자가 동일한 규칙으로 Claude Code를 사용하게 된다. 이것은 코드 품질의 일관성을 크게 높인다.

bash
git add CLAUDE.md
git commit -m "Claude Code 프로젝트 규칙 추가"

팁 3: 개인 설정과 프로젝트 설정을 분리하라

"한국어로 응답" 같은 개인 선호는 ~/.claude/CLAUDE.md(사용자 메모리)에, "pnpm 사용" 같은 프로젝트 규칙은 프로젝트 루트의 CLAUDE.md(프로젝트 메모리)에 넣어라. 개인 선호를 프로젝트 메모리에 넣으면 다른 팀원에게 불필요한 규칙이 강제된다.

팁 4: .gitignoreclaude_local.md 추가를 잊지 마라

로컬 메모리 파일(claude_local.md)은 자동으로 .gitignore에 추가되지 않는다. 반드시 수동으로 추가해야 한다. 그렇지 않으면 개인 테스트 데이터나 임시 지침이 실수로 커밋될 수 있다.

팁 5: 규칙의 "왜"를 함께 적으면 효과가 높아진다

단순히 "이렇게 하라"보다 "이런 이유로 이렇게 하라"고 적으면 Claude가 규칙의 의도를 이해하고 더 정확하게 따른다.

markdown
## 나쁜 예
- any 타입 사용 금지

## 좋은 예
- any 타입 사용 금지 (타입 안정성 저해, 런타임 오류 원인)

팁 6: CLAUDE.md도 코드처럼 리뷰하라

CLAUDE.md는 팀의 AI 워크플로우를 결정하는 중요한 파일이다. 코드 리뷰처럼 PR에서 변경 사항을 검토하고, 불필요하거나 상충하는 규칙이 없는지 확인하라.

팁 7: 하위 디렉토리에도 CLAUDE.md를 둘 수 있다

모노레포나 대형 프로젝트에서는 하위 디렉토리에 별도의 CLAUDE.md를 둘 수 있다. Claude가 해당 디렉토리의 파일을 작업할 때 그 CLAUDE.md도 함께 참조한다.

project-root/
  CLAUDE.md              ← 프로젝트 전체 규칙
  apps/
    web/
      CLAUDE.md          ← 프론트엔드 전용 규칙
    api/
      CLAUDE.md          ← 백엔드 전용 규칙
  packages/
    shared/
      CLAUDE.md          ← 공유 라이브러리 규칙

이 구조를 활용하면 루트 CLAUDE.md를 간결하게 유지하면서도, 각 모듈에 특화된 규칙을 제공할 수 있다.


핵심 요약 체크리스트

  • [ ] CLAUDE.md = 세션을 넘어 유지되는 프로젝트의 영구 메모리
  • [ ] 4종류: Enterprise 정책 > 사용자 메모리 > 프로젝트 메모리 > 로컬 메모리
  • [ ] 프로젝트 메모리를 가장 많이 사용한다 (Git 커밋으로 팀 공유)
  • [ ] 높은 우선순위가 낮은 우선순위를 덮어쓴다
  • [ ] 간결하게 유지 (500줄 이내 권장)
  • [ ] 100% 준수 보장 안 됨 (LLM의 확률적 특성)
  • [ ] /init으로 시작, 점진적으로 보강
  • [ ] claude_local.md.gitignore에 수동 추가 필수!
  • [ ] settings.jsonlanguage 옵션으로 응답 언어 설정 가능

이전: 04. 컨텍스트 윈도우 & 토큰 | 목차 | 다음: 06. 설정 파일