1. Claude Code는 왜 기억을 못 할까?

Claude Code를 쓰다 보면 이런 경험을 하게 됩니다.

"어제 분명히 pnpm 쓰라고 했는데 오늘 또 npm을 써버렸어..."
"커밋 전에 테스트 실행하라고 했잖아, 왜 또 빠뜨려..."
"매번 같은 설명을 반복해야 하다니..."

이유는 단순합니다. Claude Code의 각 세션(대화)은 완전히 독립적으로 시작되기 때문입니다. 어제 한 대화 내용은 오늘 새 세션에서 전혀 없는 것처럼 시작돼요.

마치 매일 아침 기억을 잃는 개발자 동료와 일하는 것처럼요.

이 문제를 해결하는 두 가지 메커니즘이 바로 CLAUDE.md와 자동 메모리입니다.

2. 두 가지 메모리 시스템 한눈에 보기

구분 CLAUDE.md 자동 메모리

누가 작성 개발자(나) Claude 스스로
담는 내용 프로젝트 규칙, 지침 작업하며 발견한 패턴과 노하우
범위 프로젝트 / 사용자 / 조직 작업 폴더(git 저장소) 단위
로드 시점 매 세션 시작 시 자동 로드 매 세션 시작 시 자동 로드 (200줄 제한)
비유 팀 공지판 Claude의 개인 메모장

두 시스템은 서로 보완 관계입니다. CLAUDE.md는 내가 규칙을 정해주고, 자동 메모리는 Claude가 스스로 유용한 정보를 축적합니다.

3. CLAUDE.md — 개발자가 작성하는 규칙 파일

CLAUDE.md란?

세션이 시작될 때 Claude가 자동으로 읽는 마크다운 파일입니다.

한 번 작성해 두면 매 대화에서 Claude가 이 파일을 먼저 읽고 규칙을 따릅니다.

# CLAUDE.md 예시

## 패키지 매니저
- npm 대신 반드시 pnpm을 사용하세요

## 커밋 규칙
- 커밋 전에 반드시 `pnpm test`를 실행하세요
- 커밋 메시지는 한국어로 작성합니다

## 코드 스타일
- 들여쓰기는 2칸(space)으로 통일합니다
- 함수형 컴포넌트만 사용합니다

## 프로젝트 구조
- API 핸들러는 src/api/handlers/ 폴더에 위치합니다
- 공통 유틸리티는 src/utils/ 폴더에 위치합니다

언제 CLAUDE.md에 추가해야 할까?

  • ✅ Claude가 같은 실수를 두 번 반복할 때
  • ✅ 지난 세션과 동일한 설명을 또 입력하게 될 때
  • ✅ 새 팀원이 합류해서 공통 규칙이 필요할 때
  • ✅ 코드 리뷰에서 발견한 팀 표준을 문서화하고 싶을 때

핵심 원칙: "매번 말해야 한다면 파일에 적어두자!"

/init으로 자동 생성하기

CLAUDE.md를 처음 만들 때 직접 쓰기 어렵다면 /init 명령을 써보세요.

/init

Claude가 프로젝트를 분석해서 빌드 명령, 테스트 방법, 발견한 규칙들을 자동으로 채워줍니다. 이미 CLAUDE.md가 있다면 덮어쓰지 않고 개선 사항만 제안합니다.

4. CLAUDE.md 파일 위치와 범위

CLAUDE.md는 여러 위치에 둘 수 있고, 위치에 따라 적용 범위가 달라집니다.

파일 위치 적용 범위 주요 용도 git 공유

./CLAUDE.md 현재 프로젝트 팀 공통 규칙 ✅ 올림
./.claude/CLAUDE.md 현재 프로젝트 팀 공통 규칙 ✅ 올림
~/.claude/CLAUDE.md 내 모든 프로젝트 개인 코딩 스타일 ❌ 로컬만
./CLAUDE.local.md 현재 프로젝트, 나만 개인 로컬 설정 ❌ .gitignore
/etc/claude-code/CLAUDE.md 회사 전체 컴퓨터 조직 정책 IT팀 관리

파일 로드 순서

프로젝트 실행 시
  ↓
상위 디렉토리부터 찾기 시작 (루트까지 올라가며)
  ↓
각 위치의 CLAUDE.md → CLAUDE.local.md 순서로 로드
  ↓
하위 디렉토리 파일은 해당 폴더 작업 시 추가 로드

💡 팁: CLAUDE.local.md는 반드시 .gitignore에 추가하세요. 팀과 공유하면 안 되는 개인 설정(로컬 DB 주소, 개인 API 키 등)을 여기에 보관하세요.

5. 효과적인 지침 작성법

CLAUDE.md 지침은 구체적일수록 잘 따릅니다. 모호한 표현은 Claude가 자의적으로 해석할 수 있어요.

구체적 vs 모호한 지침 비교

❌ 모호한 표현:
"코드를 제대로 포맷합니다"
"변경 사항을 테스트합니다"
"파일을 정리된 상태로 유지합니다"

✅ 구체적인 표현:
"들여쓰기는 2칸(space)으로 통일합니다"
"커밋하기 전에 pnpm test를 실행합니다"
"API 핸들러는 src/api/handlers/에 저장합니다"

좋은 CLAUDE.md 작성 팁

크기 관리: 파일당 200줄 이내를 목표로 하세요.

너무 길면 Claude가 중요한 규칙을 놓칠 수 있고, 컨텍스트 윈도우를 많이 소비해서 오히려 효율이 떨어집니다.

구조화: 마크다운 헤더와 목록을 활용해 섹션을 나눠주세요.

## 패키지 매니저
## 코드 스타일
## 테스트 규칙
## 폴더 구조

일관성: 서로 충돌하는 규칙이 없는지 주기적으로 검토하세요. 두 규칙이 충돌하면 Claude가 임의로 선택합니다.

HTML 주석 활용: 유지보수자를 위한 메모를 남기고 싶지만 Claude가 읽지 않아도 되는 내용은 HTML 주석으로 작성하세요. 컨텍스트 토큰을 소비하지 않습니다.

<!-- 이 규칙은 2025년 3월 팀 회의에서 결정됨 -->
- API 응답은 항상 JSON 형태로 반환합니다

6. 파일 가져오기(@import) 기능

CLAUDE.md에서 다른 파일을 불러올 수 있습니다.

# CLAUDE.md

프로젝트 개요는 @README를 참조하세요.
사용 가능한 명령어는 @package.json을 참조하세요.

# 추가 지침
- git 워크플로우: @docs/git-instructions.md
- 배포 절차: @docs/deploy-guide.md

@경로/파일명 형식으로 참조하면 해당 파일 내용이 세션 시작 시 함께 로드됩니다.

⚠️ 주의: 가져온 파일도 컨텍스트에 전부 로드되므로, 파일이 많을수록 컨텍스트를 더 소비합니다. 꼭 필요한 파일만 가져오세요.

다른 에이전트 도구의 AGENTS.md 활용

다른 AI 도구가 사용하는 AGENTS.md가 있다면, CLAUDE.md에서 가져와서 두 도구가 같은 규칙을 공유하게 할 수 있습니다.

# CLAUDE.md
@AGENTS.md

## Claude Code 전용 추가 설정
- src/billing/ 변경 시 반드시 계획 모드(Plan Mode) 사용

7. .claude/rules/로 규칙 주제별 분리하기

CLAUDE.md가 200줄을 넘어서기 시작하면 주제별로 파일을 분리할 때입니다.

my-project/
├── CLAUDE.md                  ← 핵심 규칙만 (200줄 이하)
└── .claude/
    └── rules/
        ├── code-style.md      ← 코딩 스타일 규칙
        ├── testing.md         ← 테스트 관련 규칙
        ├── security.md        ← 보안 요구사항
        └── api-design.md      ← API 설계 규칙

.claude/rules/ 안의 모든 .md 파일은 자동으로 인식됩니다. 하위 폴더로도 구성할 수 있어요.

.claude/rules/
├── frontend/
│   ├── react.md
│   └── css.md
└── backend/
    ├── spring.md
    └── database.md

팀 간 규칙 공유 (심볼릭 링크)

여러 프로젝트에서 공통 규칙을 쓰고 싶다면 심볼릭 링크를 활용하세요.

# 공유 규칙 폴더를 현재 프로젝트에 링크
ln -s ~/shared-claude-rules .claude/rules/shared

# 특정 파일만 링크
ln -s ~/company-standards/security.md .claude/rules/security.md

8. 경로별 규칙 — 특정 파일에만 적용하기

규칙에 paths 설정을 추가하면 해당 경로의 파일을 작업할 때만 로드됩니다. 컨텍스트를 절약하고 노이즈를 줄일 수 있습니다.

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

# API 개발 규칙
# (TypeScript API 파일 작업 시에만 자동 적용)

- 모든 API 엔드포인트는 입력 검증을 포함해야 합니다
- 표준 오류 응답 형식을 사용합니다: { success, data, message }
- OpenAPI 문서 주석을 포함합니다

여러 경로를 지정할 수도 있습니다.

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

자주 쓰는 경로 패턴

패턴 적용 대상

**/*.ts 모든 폴더의 TypeScript 파일
src/**/* src 폴더 아래 모든 파일
*.md 프로젝트 루트의 마크다운 파일
src/**/*.{ts,tsx} TypeScript, TSX 파일
tests/**/*.test.ts 테스트 파일만

💡 paths 설정이 없는 규칙은 항상 로드됩니다. 자주 쓰지 않는 규칙은 경로를 지정해서 필요할 때만 로드되게 하면 효율적입니다.

9. 자동 메모리 — Claude가 스스로 쓰는 메모장

자동 메모리란?

Claude가 작업하면서 유용하다고 판단한 정보를 스스로 파일에 저장하는 기능입니다.

개발자가 아무것도 안 해도 Claude가 알아서 기록합니다.

저장되는 내용 예시:

  • 이 프로젝트의 빌드 명령어
  • 디버깅 과정에서 발견한 노하우
  • 자주 사용하는 코드 패턴
  • 아키텍처 관련 발견

ℹ️ Claude Code v2.1.59 이상에서 사용 가능합니다. claude --version으로 확인하세요.

저장 위치

~/.claude/projects/<프로젝트명>/memory/
├── MEMORY.md          ← 핵심 인덱스 (매 세션 처음 200줄 자동 로드)
├── debugging.md       ← 디버깅 관련 상세 메모
├── api-conventions.md ← API 설계 발견 사항
└── ...                ← Claude가 필요에 따라 생성하는 주제 파일들

MEMORY.md는 인덱스 역할을 하며, 처음 200줄만 매 세션에 자동 로드됩니다. 상세 내용은 주제별 파일로 분리해서 필요할 때만 읽어요.

⚠️ 자동 메모리는 컴퓨터 로컬에만 저장됩니다. 팀원과 공유되지 않으며, 다른 기기에도 동기화되지 않습니다.

Claude에게 직접 기억 요청하기

자동 저장 외에 직접 요청도 가능합니다.

"항상 npm이 아닌 pnpm을 쓴다는 걸 기억해줘"
→ Claude가 MEMORY.md에 자동으로 저장

"이것을 CLAUDE.md에 추가해줘"
→ 팀과 공유되는 규칙 파일에 직접 추가

자동 메모리 켜기/끄기

기본적으로 켜져 있습니다. 끄고 싶다면:

# 세션 내에서 끄기
/memory  → 토글 사용

# 설정 파일로 끄기
# .claude/settings.json
{
  "autoMemoryEnabled": false
}

# 환경 변수로 끄기
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

10. /memory 명령으로 메모리 관리하기

/memory

이 명령 하나로 현재 메모리 상태를 모두 확인하고 관리할 수 있습니다.

기능 설명

로드된 파일 목록 확인 어떤 CLAUDE.md가 현재 세션에 로드됐는지 보기
자동 메모리 내용 확인 Claude가 저장한 메모 찾아보기
파일 직접 편집 에디터로 바로 열기
자동 메모리 토글 켜기/끄기

Claude가 메모리 파일을 읽거나 쓸 때 인터페이스에 "Writing memory" 또는 "Recalled memory" 메시지가 표시됩니다.

11. 자주 겪는 문제와 해결법

❓ "Claude가 CLAUDE.md 규칙을 자꾸 무시해요"

체크리스트:

# 1. /memory 실행해서 파일이 로드됐는지 확인
/memory
# 목록에 없으면 Claude가 못 보는 것

# 2. 지침을 더 구체적으로 수정
"코드를 정리합니다" → "2칸 space 들여쓰기 사용"

# 3. 서로 충돌하는 규칙 찾기
# 같은 동작에 다른 규칙이 있으면 Claude가 임의로 선택

💡 CLAUDE.md는 시스템 프롬프트가 아니라 사용자 메시지로 전달됩니다. 100% 강제 준수가 아닌 "강력한 권고" 수준입니다. 구체적일수록 잘 따릅니다.

❓ "CLAUDE.md가 너무 길어졌어요"

해결책 3가지:

1. 경로별 규칙 활용
   → paths 설정으로 필요할 때만 로드

2. .claude/rules/로 분리
   → 주제별 파일로 나누기

3. Skills로 이동
   → 항상 필요하지 않은 내용은 Skills에 저장
      (필요할 때만 로드됨)

❓ "/compact 후 규칙이 사라졌어요"

프로젝트 루트의 CLAUDE.md는 압축 후에도 살아남습니다. /compact 후에 Claude가 자동으로 다시 읽고 주입합니다.

사라진 경우는 두 가지 중 하나입니다:

  • 대화 중에만 말하고 파일에 저장하지 않은 경우
  • 하위 폴더의 중첩된 CLAUDE.md인 경우 (아직 재로드 안 됨)

해결: 중요한 규칙은 반드시 파일로 저장하세요.

❓ "자동 메모리가 뭘 저장했는지 모르겠어요"

/memory
→ 자동 메모리 폴더 선택
→ 저장된 파일 목록 확인
→ 원하는 파일 열어서 읽기/편집/삭제

모든 메모리 파일은 일반 마크다운이라 직접 편집하거나 삭제할 수 있습니다.

12. 마무리 — 어떻게 시작할까?

Claude Code 메모리 시스템을 한 줄로 요약하면:

"반복해서 말하게 되는 것은 파일에 적어두고, Claude가 발견하는 것은 Claude가 스스로 기록하게 하라"

핵심 정리

  • CLAUDE.md: 매 세션 자동 로드되는 팀 규칙 파일. 200줄 이내 유지
  • CLAUDE.local.md: 나만 쓰는 개인 로컬 설정. .gitignore에 추가
  • .claude/rules/: 주제별 규칙 분리. 경로 지정으로 필요 시만 로드
  • 자동 메모리: Claude가 스스로 쌓는 노하우. /memory로 확인
  • /init: CLAUDE.md 자동 생성 명령. 처음 시작할 때 유용

초보자 권장 시작 순서

1단계: /init 실행 → CLAUDE.md 자동 생성
         ↓
2단계: 반복되는 지시사항 → CLAUDE.md에 추가
         ↓
3단계: 파일 길어짐 → .claude/rules/로 분리
         ↓
4단계: /memory로 자동 메모리 확인 및 정리

처음에는 간단하게 /init으로 시작하고, 개발하면서 불편한 점이 생길 때마다 CLAUDE.md에 한 줄씩 추가해나가는 방식을 추천합니다. 🚀

📌 참고 문서: Claude Code 메모리 공식 한국어 문서

 

+ Recent posts

티스토리툴바