Claude Code의 CLAUDE.md와 Memory 시스템 활용기

들어가며

Claude Code를 쓰다 보면 매 세션마다 같은 규칙을 반복 설명하는 자신을 발견한다. "이 프로젝트는 Chakra UI 써야 해", "TanStack Query v5 문법으로 작성해줘", "이미지는 반드시 이 컴포넌트로 써야 해"...

이 반복을 없애주는 게 CLAUDE.md와 Memory 시스템이다.

CLAUDE.md란?

Claude Code가 세션 시작 시 자동으로 읽어들이는 설정 파일이다. 여기에 프로젝트 규칙, 코딩 컨벤션, 금지 패턴 등을 적어두면 매번 설명할 필요 없이 Claude가 알아서 지킨다.

로드 우선순위

CLAUDE.md는 여러 위치에 놓을 수 있고, 모두 자동 로드된다:

~/.claude/CLAUDE.md              ← 글로벌 (모든 프로젝트에 적용)
프로젝트루트/CLAUDE.md            ← 프로젝트 전체에 적용
프로젝트루트/apps/admin/CLAUDE.md ← 해당 디렉토리에서 작업 시에만 적용

세 파일이 모두 존재하면 전부 로드된다. 충돌 시 더 구체적인 경로의 규칙이 우선한다.

글로벌 vs 프로젝트: 어디에 뭘 넣을까?

핵심 원칙: 적용 범위에 맞는 위치에 놓는다.

처음에는 apps/admin/CLAUDE.md에 모든 규칙을 넣었는데, 같은 모노레포의 다른 앱(adv)도 동일한 스택을 쓴다는 걸 알고 프로젝트 루트로 올렸다. 이렇게 하면 한 벌의 규칙으로 모든 앱을 커버할 수 있다.

Memory 시스템이란?

CLAUDE.md가 "규칙서"라면, Memory는 세션 간 누적 학습 노트다.

~/.claude/projects/{프로젝트경로}/memory/
├── MEMORY.md              ← 매 세션 자동 로드 (인덱스 역할)
├── publishing-rules.md    ← 필요 시 참조
├── admin-components.md    ← 필요 시 참조
├── figma-token-mapping.md ← 필요 시 참조
└── figma-analysis-checklist.md ← 필요 시 참조

MEMORY.md의 역할: 라우터

MEMORY.md는 200줄 제한이 있다. 매 세션 자동 로드되므로 토큰을 소비하기 때문이다. 그래서 상세 내용은 별도 파일에 두고, MEMORY.md는 "이 작업을 할 땐 이 파일을 읽어라"라는 라우터 역할만 한다:

## 워크플로우별 참조 파일
 
| 작업 유형           | 읽어야 할 파일                          |
| ------------------- | --------------------------------------- |
| **Figma 퍼블리싱**  | `memory/publishing-rules.md`, `memory/admin-components.md` |
| **Figma 토큰 매핑** | `memory/publishing-rules.md`, `memory/figma-token-mapping.md` |
| **다이얼로그 구현** | `memory/admin-components.md` (Dialog 섹션) |

이렇게 하면 항상 로드되는 파일은 최소한으로 유지하면서, 상세 규칙은 필요할 때만 불러온다.

Memory에 뭘 저장할까?

저장 O:

• 여러 세션에서 반복 확인된 패턴과 컨벤션
• 프로젝트 구조, 주요 파일 경로
• 자주 쓰는 컴포넌트 사용법
• 디버깅 중 발견한 인사이트

저장 X:

• 현재 세션에서만 유효한 임시 정보
• 검증되지 않은 추측
• CLAUDE.md에 이미 있는 내용 (중복 금지)

Memory 저장 예시

작업 중 "셀렉터는 minWidth 대신 width로 지정해야 한다"는 규칙을 발견했다면:

## 셀렉터 / 검색바 스타일 규칙
- Select, MultiSelect: `minWidth` 대신 `width`로 고정 너비 지정
- SearchInput: placeholder가 2줄로 넘어가지 않도록 `width` 값 충분히 확보

이런 식으로 publishing-rules.md에 추가해두면, 다음 퍼블리싱 작업 때 Claude가 자동으로 참조한다.

CLAUDE.md vs Memory: 뭐가 다른가?

쉽게 말하면:

• CLAUDE.md = 팀 코딩 가이드라인
• Memory = 개인 업무 노트

실전 구성: 우리 프로젝트의 사례

전체 구조

~/.claude/CLAUDE.md (글로벌)
  → GATE 1~4 (작업 전 체크리스트)
  → 수동 우회 차단 목록
  → 완료 전 검증 절차
 
kodeflo-monorepo/CLAUDE.md (프로젝트)
  → Next.js 15, React 19, TanStack Query v5 문법 가이드
  → Chakra UI 퍼블리싱 규칙
  → 엣지케이스 검증 절차
 
memory/MEMORY.md (자동 로드)
  → 프로젝트 기본 정보
  → 워크플로우 라우터 테이블
 
memory/publishing-rules.md (필요 시 로드)
  → Figma 퍼블리싱 상세 규칙
  → 이미지 파이프라인
  → 테이블/셀렉터 패턴
 
memory/admin-components.md (필요 시 로드)
  → 공용 컴포넌트 사용법
  → Dialog, Table, Select 등

왜 이렇게 나눴는가

1. 글로벌 CLAUDE.md에는 "행동 원칙"만 — 어떤 프로젝트에서든 "Figma 스펙을 추측하지 마라", "완료 전 type-check 돌려라" 같은 규칙은 유효하다

2. 프로젝트 CLAUDE.md에는 "기술 규칙"만 — React 19 문법, Chakra UI 스킬 등은 이 프로젝트에서만 의미 있다

3. MEMORY.md는 가볍게, 상세는 별도 파일로 — 200줄 제한이 있으므로 인덱스만 두고, 실제 규칙은 별도 파일에 분리한다

팁과 주의사항

1. 토큰 효율을 생각하라

CLAUDE.md와 MEMORY.md는 매 세션 로드 = 매번 토큰 소비다. 불필요하게 길면 비용만 늘어난다.

// ❌ CLAUDE.md에 코드 예시를 20개씩 넣으면 토큰 낭비
// ✅ 핵심 패턴만 1-2개, 나머지는 memory 파일에

2. 중복을 피하라

CLAUDE.md에 "Chakra UI 전용"이라 적고, Memory에도 같은 내용을 적으면 토큰만 2배 소비된다. 각 파일의 역할을 명확히 구분하자.

3. Memory는 검증된 내용만

한 번 봤다고 바로 Memory에 적지 말자. 여러 세션에서 반복 확인된 패턴만 저장한다. 잘못된 Memory는 이후 세션에서 잘못된 판단을 유발한다.

4. 정기적으로 정리하라

프로젝트가 진화하면 규칙도 바뀐다. 오래된 Memory 내용이 현재 코드와 맞지 않으면 오히려 해가 된다. 가끔 "메모리 내용 확인해줘"라고 하면서 점검하자.

5. 사용자가 직접 요청할 수도 있다

"이거 기억해둬"라고 말하면 Claude가 Memory에 저장한다. "셀렉터는 width로 퍼블리싱해"처럼 작업 중 발견한 규칙을 바로 저장 요청할 수 있다.

마무리

CLAUDE.md와 Memory 시스템을 잘 구성하면:

• 반복 설명 제거: "이 프로젝트는 React 19야"를 매번 말할 필요 없다
• 실수 방지: 금지 패턴을 규칙으로 등록해두면 Claude가 알아서 피한다
• 지식 축적: 세션이 끝나도 발견한 패턴이 사라지지 않는다
• 토큰 절약: 필요한 정보만 필요할 때 로드한다

결국 핵심은 "항상 로드되는 건 작게, 상세한 건 필요할 때만" 이다. 이 원칙만 지키면 Claude Code와의 협업이 훨씬 매끄러워진다.