CLAUDE.md — 프로젝트 메모리 & 자동 메모리

두 가지 메모리 시스템

Claude Code에는 서로 보완하는 두 가지 메모리 시스템이 있습니다. 하나는 사람이 작성하고, 하나는 Claude가 스스로 작성합니다.

Two Memory Systems

Claude Code has two complementary memory systems. One is written by humans, and the other is written by Claude itself.

✍️

CLAUDE.md 파일File

사람이 작성합니다. 프로젝트 규칙, 기술 스택, 컨벤션 등 Claude에게 알려주고 싶은 모든 것을 담습니다.Written by humans. Contains everything you want Claude to know — project rules, tech stack, conventions, and more.

사람이 작성Human-written 영구 유지Persistent 팀 공유 가능Team-shareable

🤖

자동 메모리 (Auto-memory)Auto Memory

Claude가 스스로 작성합니다. 세션 중 배운 것, 선호도, 패턴 등을 자동으로 기억에 저장합니다.Written by Claude itself. Automatically saves things it learned during a session — preferences, patterns, and more.

Claude가 작성Claude-written 자동 저장Auto-saved 개인 전용Personal only

"새 팀원" 비유로 이해하기

새 팀원이 입사하면 가장 먼저 뭘 하나요? 프로젝트 위키를 읽습니다.

  📋 CLAUDE.md = 팀이 미리 써둔 프로젝트 온보딩 문서
      "React + TypeScript, npm run build로 빌드, camelCase 사용..."

  📓 자동 메모리 = 팀원이 일하면서 스스로 적는 개인 노트북
      "이 팀은 PR에 스크린샷을 넣길 좋아하는군. 다음부터 기억해야지."

둘을 함께 사용하면 Claude가 매 세션마다 처음부터 다시 배울 필요가 없습니다.

The "New Team Member" Analogy

What does a new team member do first? Read the project wiki.

  📋 CLAUDE.md = The team's pre-written project onboarding document
      "React + TypeScript, build with npm run build, use camelCase..."

  📓 Auto Memory = The team member's own personal notebook they fill in as they work
      "This team likes screenshots in PRs. I'll remember that next time."

Using both together means Claude doesn't need to relearn everything from scratch every session.

🔄

세션마다 자동 로드Auto-loaded Every Session

Claude Code를 실행할 때마다 CLAUDE.md를 자동으로 읽습니다. 매번 "우리 프로젝트는 이거야" 하고 설명할 필요가 없어요.CLAUDE.md is automatically read every time Claude Code starts. No need to explain "this is our project" every time.

🧠

프로젝트 컨텍스트 제공Provides Project Context

기술 스택, 폴더 구조, 빌드 명령어, 코딩 컨벤션 등 프로젝트의 핵심 정보를 Claude에게 전달합니다.Communicates key project information to Claude — tech stack, folder structure, build commands, and coding conventions.

🎯

일관된 코딩 스타일 유지Maintains Consistent Coding Style

네이밍 규칙, 에러 핸들링 패턴, 금지 사항 등을 명시해두면 Claude가 항상 같은 스타일로 코드를 작성합니다.Specify naming rules, error handling patterns, and prohibitions so Claude always writes code in the same style.

💡

빠른 시작: 프로젝트 루트에서 /init 명령을 실행하면 Claude가 프로젝트를 분석해서 CLAUDE.md를 자동 생성해줍니다. 거기서 시작해서 직접 다듬어 나가면 됩니다. /memory로 자동 메모리를 관리할 수 있습니다.

Quick start: Run /init in the project root and Claude will analyze your project and auto-generate a CLAUDE.md. Start from there and refine it yourself. Use /memory to manage auto memory.

CLAUDE.md 파일 위치 & 계층

CLAUDE.md는 4가지 범위에 배치할 수 있습니다. 범위가 넓은 것에서 좁은 것 순으로 모두 적용됩니다.

CLAUDE.md File Location & Hierarchy

CLAUDE.md can be placed at 4 different scopes. All of them are applied, from broadest to narrowest.

범위Scope	파일 위치File Location	용도Purpose
Managed Policy	/Library/Application Support/ ClaudeCode/CLAUDE.md (macOS)	IT 관리자가 조직 전체에 강제 적용하는 정책Policy enforced org-wide by IT administrators
User (전역Global)	~/.claude/CLAUDE.md	모든 프로젝트에 공통 적용되는 개인 설정Personal settings applied across all projects
Project (팀 공유Team-shared)	./CLAUDE.md 또는or ./.claude/CLAUDE.md	Git으로 팀 전체가 공유하는 프로젝트 규칙Project rules shared via Git with the whole team
Local (개인 로컬Personal Local)	./CLAUDE.local.md	개인 전용, git에 추적되지 않음 (.gitignore)Personal only, not tracked by git (.gitignore)

CLAUDE.md 전체 계층 구조

# ① Managed Policy (조직 IT 관리자용, macOS)
/Library/Application Support/ClaudeCode/CLAUDE.md

# ② User 전역 (개인, 모든 프로젝트 공통)
~/.claude/CLAUDE.md
                                   "항상 한국어로 응답해"
                                   "커밋 메시지는 영어로 써"

# ③ Project (팀 공유, Git 커밋)
~/my-project/
├── CLAUDE.md              ← 또는 .claude/CLAUDE.md
│                              "React 18 + TypeScript 사용"
│                              "빌드: npm run build"
├── CLAUDE.local.md        ← ④ Local (개인 전용, .gitignore)
│                              "내 로컬 DB 포트는 5433"
│
├── src/
│   ├── components/
│   │   └── CLAUDE.md      ← 서브디렉터리별 규칙
│   │                          "이 폴더는 UI 컴포넌트만"
│   └── api/
│       └── CLAUDE.md      ← 서브디렉터리별 규칙
│                              "API 호출은 react-query 사용"
└── ...
      

회사 규칙 비유로 이해하기

  🏛️ 그룹사 정책 (Managed Policy) — "모든 직원은 보안 규정 준수"
  🏢 본인 업무 스타일 (전역 User) — "나는 항상 한국어로 메모"
  🏬 부서 규칙 (Project) — "개발팀은 코드 리뷰 필수"
  🗊️ 내 개인 노트 (Local) — "이 프로젝트의 내 로컬 세팅"

범위가 겹치면 더 구체적인 규칙이 우선합니다.

The "Company Rules" Analogy

  🏛️ Corporate policy (Managed Policy) — "All employees must comply with security regulations"
  🏢 Your own work style (User Global) — "I always take notes in English"
  🏬 Department rules (Project) — "Dev team requires code reviews"
  🗊️ My personal notes (Local) — "My local settings for this project"

When scopes overlap, the more specific rule takes precedence.

⚠️

충돌 시 우선순위: Managed Policy > User 전역 > Project > Local 순서로 범위가 좁을수록 우선합니다. 하위(로컬) 파일이 상위(전역) 규칙을 덮어씁니다.

Priority on conflict: The order is Managed Policy > User Global > Project > Local — the narrower the scope, the higher the priority. Lower (local) files override higher (global) rules.

@ @import 문법으로 파일 가져오기Importing Files with @import Syntax

CLAUDE.md 안에서 다른 파일을 가져올 수 있습니다. 긴 문서를 분리하거나, README·패키지 정보를 바로 참조할 때 유용합니다. You can import other files inside CLAUDE.md. Useful for splitting long documents or referencing README and package info directly.

CLAUDE.md — @import 예시

# 프로젝트 개요
@README                          # README.md 전체 임포트
@package.json                    # 패키지 정보 임포트
@docs/git-instructions.md        # 특정 파일 임포트

# 코딩 컨벤션
변수/함수: camelCase, 컴포넌트: PascalCase
      

📂 .claude/rules/ 디렉터리로 규칙 분리Separating Rules with .claude/rules/ Directory

규칙이 많아지면 .claude/rules/ 디렉터리에 주제별로 분리할 수 있습니다. 특정 파일 패턴에만 적용되는 규칙도 설정 가능합니다. When rules grow large, you can split them by topic inside the .claude/rules/ directory. You can also configure rules that apply only to specific file patterns.

.claude/ 디렉터리 구조

.claude/
├── CLAUDE.md              # 공통 규칙
└── rules/
    ├── code-style.md     # 코딩 스타일 규칙
    ├── testing.md        # 테스트 작성 규칙
    └── security.md       # 보안 관련 규칙
      

.claude/rules/security.md — 경로 기반 규칙 (frontmatter)

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

# API 보안 규칙 (src/api/ 파일 작업 시에만 적용됨)
- 모든 입력 값은 zod로 검증
- SQL 쿼리 직접 작성 금지 (ORM 사용)
- 인증 토큰을 로그에 출력하지 말 것
      

💡

경로 기반 규칙: paths frontmatter를 사용하면, 해당 파일 패턴에 매칭되는 파일로 작업할 때만 그 규칙이 적용됩니다. 전체 CLAUDE.md를 짧게 유지하면서 세밀한 제어가 가능합니다.

Path-based rules: Using the paths frontmatter applies that rule only when working with files matching that pattern. This allows fine-grained control while keeping the main CLAUDE.md short.

🌍

전역 CLAUDE.mdGlobal CLAUDE.md

응답 언어, 커밋 메시지 스타일 등 모든 프로젝트에 공통으로 적용할 규칙을 작성합니다.Write rules that apply across all projects — response language, commit message style, etc.

📁

프로젝트 CLAUDE.mdProject CLAUDE.md

기술 스택, 빌드/테스트 명령어, 아키텍처 등 해당 프로젝트 고유의 정보를 작성합니다.Write information unique to this project — tech stack, build/test commands, architecture, etc.

📄

CLAUDE.local.md

개인 전용 설정으로 git에 추적되지 않습니다. 로컬 DB 포트, 개인 API 키 경로 등 팀과 공유하지 않을 내용을 넣습니다.Personal settings that are not tracked by git. Put anything you don't want to share with the team — local DB port, personal API key paths, etc.

자동 메모리 시스템

Claude가 스스로 작성하는 메모리입니다. 세션 중 배운 것을 자동으로 저장하고 다음 세션에서 활용합니다.

Auto Memory System

Memory that Claude writes itself. It automatically saves what it learned during a session and uses it in the next.

어떻게 작동하나요?

Claude Code가 작업하면서 중요한 것을 발견하면 스스로 메모합니다.

  📝 "이 팀은 ESLint auto-fix 후 반드시 수동 검토를 원하는군"
  📝 "이 프로젝트의 API 에러 패턴은 커스텀 AppError 클래스를 사용함"
  📝 "배포 전에 항상 npm run e2e를 실행해야 함"

다음 세션에서는 이 메모를 보고 처음부터 다시 설명하지 않아도 됩니다.

How does it work?

When Claude Code discovers something important while working, it takes its own notes.

  📝 "This team always wants manual review after ESLint auto-fix"
  📝 "This project's API error pattern uses a custom AppError class"
  📝 "Must always run npm run e2e before deploying"

In the next session, it reads these notes, so you don't have to explain it from scratch.

📂

저장 위치Storage Location

자동 메모리는 프로젝트별로 다음 위치에 저장됩니다:Auto memory is saved per project at the following location:

자동 메모리 경로Auto memory path

~/.claude/projects/
└── <project-name>/memory/
    ├── MEMORY.md       # 인덱스 (매 세션 앞 200줄 로드)
    ├── debugging.md    # 주제별 파일 (필요 시 로드)
    └── patterns.md     # 주제별 파일 (필요 시 로드)
          

⚙️

관리 방법How to Manage

/memory 명령으로 자동 메모리를 관리합니다:Use the /memory command to manage auto memory:

▸ 로드된 모든 CLAUDE.md 파일 확인View all loaded CLAUDE.md files
▸ 자동 메모리 켜기/끄기 토글Toggle auto memory on/off
▸ 메모리 폴더 직접 열어서 편집Open and edit the memory folder directly
▸ 잘못된 메모리 삭제 또는 수정Delete or correct inaccurate memories

핵심 동작 방식How It Works

세션 시작 시 MEMORY.md 로드MEMORY.md Loads at Session Start

매 세션마다 MEMORY.md의 앞 200줄이 자동으로 컨텍스트에 포함됩니다. 가장 자주 참조되는 핵심 정보가 여기에 담겨있습니다.The first 200 lines of MEMORY.md are automatically included in context every session. This contains the most frequently referenced key information.

필요 시 주제별 파일 동적 로드Topic-specific Files Loaded Dynamically When Needed

디버깅 작업을 하면 debugging.md가, 코드 패턴 관련 작업을 하면 patterns.md가 자동으로 로드됩니다. 불필요한 컨텍스트 낭비를 방지합니다.When doing debugging work, debugging.md auto-loads; for code pattern work, patterns.md loads. This prevents unnecessary context waste.

Claude가 기억할 가치 있는 것을 판단Claude Decides What Is Worth Remembering

모든 것을 다 저장하지 않습니다. Claude가 "다음 세션에도 알아야 할 중요한 정보"라고 판단한 것만 선별해서 메모리에 기록합니다.Not everything is saved. Only what Claude judges as "important information to know in the next session" is selectively recorded in memory.

언제든 비활성화 가능Can Be Disabled Anytime

/memory에서 토글하거나, settings에서 autoMemoryEnabled: false로 설정하면 자동 메모리가 비활성화됩니다.Toggle from /memory, or set autoMemoryEnabled: false in settings to disable auto memory.

✅

자동 메모리가 잘하는 것What Auto Memory Does Well

▸ 프로젝트별 특이한 패턴 기억Remembering project-specific patterns
▸ 반복해서 설명하지 않아도 되는 컨벤션Conventions you don't have to re-explain
▸ 이전 세션에서 발견한 버그 패턴Bug patterns discovered in previous sessions
▸ 팀의 선호도나 작업 스타일Team preferences and working style

⚠️

주의할 점Watch Out For

▸ 잘못된 정보가 기억될 수 있으므로 /memory로 주기적 확인Incorrect info may be stored — review periodically with /memory
▸ 개인 전용 (팀 공유 불가)Personal only (cannot be shared with team)
▸ CLAUDE.md와 중복되지 않게 관리Avoid duplicating content already in CLAUDE.md
▸ 민감한 정보가 저장되지 않았는지 확인Check that no sensitive information was stored

📋

CLAUDE.md vs 자동 메모리 역할 분리: CLAUDE.md는 팀 전체가 공유할 규칙과 프로젝트 구조를 담습니다. 자동 메모리는 작업하면서 Claude 스스로 발견한 개인적 학습을 담습니다. 둘을 중복 작성할 필요 없이, 각자의 역할에 집중하면 됩니다. CLAUDE.md vs Auto Memory — Clear Roles: CLAUDE.md holds rules and project structure that the whole team shares. Auto memory holds personal learning Claude discovers while working. No need to duplicate — each has its own role.

작성 템플릿 갤러리Template Gallery

프로젝트 유형별로 바로 복사해서 쓸 수 있는 CLAUDE.md 템플릿입니다. Ready-to-copy CLAUDE.md templates for each project type.

● 웹 프로젝트 (React / Next.js)Web Project (React / Next.js)

CLAUDE.md

# 프로젝트 개요
쇼핑몰 웹사이트 — Next.js 14 App Router 기반 이커머스 플랫폼

# 기술 스택
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS + shadcn/ui
- State: Zustand (글로벌), React Query (서버)
- DB: Prisma + PostgreSQL

# 빌드 & 테스트 명령어
- npm run dev       # 개발 서버 (포트 3000)
- npm run build     # 프로덕션 빌드
- npm run test      # Jest 단위 테스트
- npm run e2e       # Playwright E2E 테스트
- npm run lint      # ESLint + Prettier 검사

# 코딩 컨벤션
- 컴포넌트: PascalCase, 함수/변수: camelCase
- 서버 컴포넌트 기본, 'use client'는 최소한으로
- // 절대 하지 말 것: any 타입 사용 금지
- // 절대 하지 말 것: console.log 프로덕션 코드에 남기지 않기
      

● 모바일 앱 (SwiftUI / Flutter)Mobile App (SwiftUI / Flutter)

CLAUDE.md

# 프로젝트 개요
건강 관리 iOS 앱 — SwiftUI + MVVM 아키텍처

# 기술 스택
- UI: SwiftUI (iOS 17+)
- Architecture: MVVM + Coordinator 패턴
- Networking: URLSession + async/await
- Persistence: SwiftData
- DI: Swift Dependencies

# 빌드 & 테스트 명령어
- xcodebuild -scheme MyApp -sdk iphonesimulator build
- xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
- swiftlint          # 린트 검사

# 코딩 컨벤션
- View에 비즈니스 로직 넣지 말 것 → ViewModel로 분리
- @StateObject는 View가 소유할 때, @ObservedObject는 주입받을 때
- // 금지: force unwrap (!) 사용 금지
- // 금지: 거대한 View body → 반드시 subview로 분리
      

● API 서버 (Node.js / Python)API Server (Node.js / Python)

CLAUDE.md

# 프로젝트 개요
주문 관리 API 서버 — Express.js + TypeScript REST API

# 기술 스택
- Runtime: Node.js 20 LTS
- Framework: Express.js + TypeScript
- ORM: TypeORM + PostgreSQL
- Auth: JWT + Passport.js
- Docs: Swagger (OpenAPI 3.0)

# 빌드 & 테스트 명령어
- npm run dev         # nodemon 개발 서버 (포트 8080)
- npm run build       # tsc 빌드
- npm run test        # Vitest 단위 테스트
- npm run test:e2e    # Supertest 통합 테스트
- npm run migrate     # DB 마이그레이션 실행

# 코딩 컨벤션
- 모든 엔드포인트에 입력 유효성 검사 (zod 사용)
- 에러 핸들링: 커스텀 AppError 클래스 사용, try-catch 필수
- 환경변수는 .env가 아닌 config/ 폴더에서 관리
- // 금지: SQL raw query 직접 사용 금지 (ORM 사용)
      

● 데이터 분석 (Python / Jupyter)Data Analysis (Python / Jupyter)

CLAUDE.md

# 프로젝트 개요
고객 이탈 예측 모델 — Python 데이터 분석 & ML 파이프라인

# 기술 스택
- Language: Python 3.12
- Analysis: pandas, numpy, scipy
- Visualization: matplotlib, seaborn, plotly
- ML: scikit-learn, XGBoost
- Notebook: Jupyter Lab

# 실행 명령어
- pip install -r requirements.txt   # 의존성 설치
- jupyter lab                        # 노트북 실행
- python src/train.py                # 모델 학습
- pytest tests/                      # 테스트 실행

# 코딩 컨벤션
- 노트북 셀마다 마크다운 설명 필수
- 데이터 경로는 data/ 폴더 기준 상대경로
- 시각화에는 반드시 제목, 축 라벨, 범례 포함
- // 금지: 절대경로 하드코딩 금지
- // 금지: 전처리 없이 모델에 바로 데이터 넣지 않기
      

좋은 예 vs 나쁜 예Good vs Bad Examples

CLAUDE.md는 구체적일수록 효과적입니다. 실제 비교를 통해 차이를 느껴보세요. CLAUDE.md is more effective the more specific it is. See the difference through real comparisons.

프로젝트 설명Project Description

❌ 나쁜 예❌ Bad Example

코드 잘 짜줘. 웹 프로젝트야. React 써.

✅ 좋은 예✅ Good Example

# 프로젝트 개요 SaaS 대시보드 웹앱. Next.js 14 App Router + TypeScript. Tailwind CSS + shadcn/ui 사용. 서버 상태 관리: React Query v5. 인증: NextAuth.js (Google OAuth).

빌드 & 테스트 명령어Build & Test Commands

❌ 나쁜 예❌ Bad Example

빌드해서 테스트해줘. 한국어로 해줘.

✅ 좋은 예✅ Good Example

# 빌드 & 테스트 - npm run build # 프로덕션 빌드 - npm run test # Vitest 유닛 테스트 - npm run e2e # Playwright E2E - npm run lint # ESLint 검사 # 테스트 작성 규칙 - 새 기능에는 반드시 테스트 추가 - 테스트 파일은 __tests__ 폴더에 - describe/it 구조, 한국어 설명

코딩 컨벤션Coding Conventions

❌ 나쁜 예❌ Bad Example

깔끔하게 짜줘. 변수명 잘 지어줘.

✅ 좋은 예✅ Good Example

# 코딩 컨벤션 - 변수/함수: camelCase - 컴포넌트: PascalCase - 상수: UPPER_SNAKE_CASE - 인터페이스: I 접두사 없이 PascalCase # 절대 하지 말 것 - any 타입 사용 금지 - console.log 프로덕션 코드에 남기기 - 인라인 스타일 사용 (Tailwind 사용) - index.ts에서 직접 로직 구현

파일 길이File Length

❌ 너무 짧은 예❌ Too Short

React 프로젝트입니다. TypeScript 사용합니다. 잘 부탁합니다.

✅ 적절한 길이✅ Appropriate Length

# 프로젝트 개요 (구체적인 프로젝트 설명) # 기술 스택 (사용 기술 목록) # 빌드 & 테스트 (구체적인 명령어) # 코딩 컨벤션 (명확한 규칙 목록) # 절대 하지 말 것 (금지 사항 목록) # 폴더 구조 (주요 폴더 설명)

📏

핵심 원칙: CLAUDE.md는 "Claude에게 무엇을 해달라"가 아니라, "이 프로젝트는 이렇게 되어 있다"를 알려주는 문서입니다. 추상적인 요청 대신 구체적인 사실을 적어야 효과적입니다. Core Principle: CLAUDE.md is not "ask Claude to do something" — it's a document that says "this project is structured like this." Writing concrete facts instead of abstract requests makes it far more effective.

팀 공유 & Git 관리Team Sharing & Git Management

CLAUDE.md를 팀에서 공유하는 두 가지 전략과 셋업 가이드입니다. Two strategies for sharing CLAUDE.md as a team, plus a setup guide.

📤

Git에 커밋하기Commit to Git

CLAUDE.md를 저장소에 포함시킵니다.Include CLAUDE.md in the repository.

팀 전체 통일Team-wide consistency 버전 관리Version controlled 코드 리뷰 가능Reviewable via PR

팀 전체가 동일한 규칙을 사용해야 할 때 추천합니다. PR을 통해 규칙 변경 이력도 관리됩니다.Recommended when the whole team needs to use the same rules. Rule change history is also tracked through PRs.

🔒

.gitignore에 넣기Add to .gitignore

CLAUDE.md를 개인만 사용합니다.Keep CLAUDE.md for personal use only.

개인 설정 유지Personal settings 자유도 높음More flexibility 충돌 없음No conflicts

각자 선호하는 스타일이 다르거나, 개인적인 지시사항(예: 응답 언어)을 넣고 싶을 때 추천합니다.Recommended when team members have different style preferences or want to add personal instructions (e.g., response language).

.gitignore

# 개인 CLAUDE.md를 Git에서 제외하고 싶을 때
CLAUDE.md

# 또는 특정 폴더의 CLAUDE.md만 제외
src/**/CLAUDE.md

# 팀 공유용은 커밋하고, 개인용은 .local로 분리하는 전략도 가능
CLAUDE.local.md
      

팀 CLAUDE.md 셋업 가이드Team CLAUDE.md Setup Guide

팀 회의에서 규칙 합의Agree on Rules as a Team

코딩 컨벤션, 네이밍, 금지 사항 등을 팀원들과 함께 정합니다. 이미 있는 ESLint/Prettier 설정을 기반으로 하면 쉽습니다.Agree with teammates on coding conventions, naming rules, and prohibitions. Starting from existing ESLint/Prettier config makes this easy.

CLAUDE.md 초안 작성Write a Draft CLAUDE.md

한 명이 초안을 작성합니다. 위의 템플릿 갤러리에서 프로젝트에 맞는 것을 복사해서 시작하면 빠릅니다. /init으로 자동 생성 후 다듬어도 좋습니다.One person writes the draft. Copying from the template gallery above and customizing is the fastest approach. Auto-generating with /init then refining also works well.

PR로 리뷰 & 머지Review & Merge via PR

CLAUDE.md 변경도 코드 리뷰처럼 PR을 거칩니다. "왜 이 규칙을 추가했는지" 이유를 PR 본문에 적으면 나중에 돌아볼 때 좋습니다.Changes to CLAUDE.md go through a PR just like code reviews. Writing the reason "why this rule was added" in the PR description helps when looking back later.

정기적으로 업데이트Update Regularly

프로젝트가 진행되면서 기술 스택이 바뀌거나 새 규칙이 필요해집니다. 스프린트 회고 때 CLAUDE.md도 함께 리뷰하면 항상 최신 상태를 유지할 수 있습니다.As the project progresses, tech stacks change and new rules emerge. Reviewing CLAUDE.md during sprint retrospectives keeps it always up to date.

👥

하이브리드 전략: 팀 공통 CLAUDE.md는 Git에 커밋하고, 개인 설정(응답 언어, 선호 스타일 등)은 전역 CLAUDE.md(~/.claude/CLAUDE.md)에 넣으면 둘 다 적용됩니다. Hybrid Strategy: Commit the shared team CLAUDE.md to Git, and put personal settings (response language, preferred style, etc.) in the global CLAUDE.md (~/.claude/CLAUDE.md) — both will apply.

자주 묻는 질문Frequently Asked Questions

CLAUDE.md에 대해 가장 많이 궁금해하는 것들 The most common questions about CLAUDE.md

CLAUDE.md는 매 세션 시작 시 컨텍스트에 로드되므로, 너무 길면 컨텍스트 윈도우를 불필요하게 차지합니다. 공식 권장 사항은 200줄 이내입니다. 정보가 많다면 핵심 규칙만 프로젝트 루트 CLAUDE.md에 넣고, 세부 내용은 .claude/rules/ 디렉터리에 주제별로 분산시키거나, 하위 폴더별 CLAUDE.md로 나누세요. Claude는 해당 폴더에서 작업할 때만 하위 CLAUDE.md를 읽으므로 효율적입니다. 또한 @import 문법으로 외부 파일을 참조하는 것도 좋은 방법입니다. CLAUDE.md is loaded into context at the start of every session, so if it's too long it unnecessarily consumes your context window. The official recommendation is to keep it under 200 lines. If you have a lot of information, put only the core rules in the project root CLAUDE.md, and distribute the details across topic-specific files in the .claude/rules/ directory, or split them into per-subfolder CLAUDE.md files. Claude only reads subfolder CLAUDE.md files when working in that folder, so it's efficient. Using @import syntax to reference external files is also a good option.

물론입니다! /init은 프로젝트를 분석해서 초안을 만들어주는 것일 뿐입니다. 자동 생성된 내용이 정확하지 않을 수 있고, 프로젝트의 특수한 규칙이나 컨벤션은 사람이 직접 추가해야 합니다. 오히려 /init으로 시작하고 직접 다듬는 것이 가장 추천하는 방법입니다. Absolutely! /init simply analyzes your project and produces a draft. The auto-generated content may not be perfectly accurate, and project-specific rules or conventions need to be added by hand. In fact, starting with /init and then refining it manually is the recommended approach.

전역 CLAUDE.md(~/.claude/CLAUDE.md)는 각자의 컴퓨터에 있으므로 자유롭게 다르게 쓸 수 있습니다. 하지만 프로젝트 루트 CLAUDE.md는 Git으로 공유되기 때문에, 각자 다른 내용을 넣으면 머지 충돌이 발생합니다. 해결 방법은 두 가지입니다: (1) 팀 규칙을 합의해서 하나로 통일하거나, (2) 개인 설정은 전역 CLAUDE.md에 넣고 프로젝트 CLAUDE.md는 공통 규칙만 담는 하이브리드 전략을 사용하세요. The global CLAUDE.md (~/.claude/CLAUDE.md) lives on each person's machine, so everyone can freely use different content there. However, the project root CLAUDE.md is shared via Git — if different people put different content in it, merge conflicts will occur. There are two solutions: (1) agree on team rules and unify into one file, or (2) use the hybrid strategy where personal settings go in the global CLAUDE.md and the project CLAUDE.md contains only shared rules.

역할이 정반대입니다.

CLAUDE.md는 "이 정보를 반드시 알아둬"라고 알려주는 파일입니다. 프로젝트의 컨텍스트와 규칙을 제공합니다.

.claudeignore는 "이 파일/폴더는 보지 마"라고 숨기는 파일입니다. .gitignore와 같은 형식으로, Claude가 읽지 말아야 할 파일(예: 대용량 데이터, 빌드 결과물, 민감한 설정 파일)을 지정합니다.

둘을 함께 사용하면, Claude에게 필요한 정보만 효율적으로 전달할 수 있습니다. Their roles are the opposite of each other.

CLAUDE.md is a file that tells Claude "make sure you know this information." It provides the project's context and rules.

.claudeignore is a file that hides things, saying "don't look at these files/folders." Using the same format as .gitignore, it specifies files Claude should not read (e.g., large data files, build artifacts, sensitive config files).

Using both together lets you efficiently deliver only the information Claude needs.

작성 주체가 다릅니다.

CLAUDE.md는 사람이 작성합니다. 팀이 합의한 규칙, 기술 스택, 빌드 명령어 등 Claude에게 미리 알려주고 싶은 것을 담습니다. Git으로 팀 전체가 공유 가능합니다.

자동 메모리는 Claude가 스스로 작성합니다. 세션 중 학습한 것, 발견한 패턴, 팀의 선호도 등을 ~/.claude/projects/<project>/memory/에 자동 저장합니다. 개인 전용이라 팀과 공유되지 않습니다.

두 시스템은 서로 보완합니다. CLAUDE.md로 팀 규칙을 명시하고, 자동 메모리로 Claude가 작업하면서 발견한 것을 축적하면, 시간이 지날수록 Claude가 더 잘 협업할 수 있게 됩니다. /memory 명령으로 자동 메모리를 열람하거나 끌 수 있습니다. The author is different.

CLAUDE.md is written by a person. It contains things you want to tell Claude in advance — rules agreed upon by the team, tech stack, build commands, etc. It can be shared team-wide via Git.

Auto memory is written by Claude itself. Things learned during sessions, discovered patterns, and team preferences are automatically saved to ~/.claude/projects/<project>/memory/. It's personal and not shared with the team.

The two systems complement each other. By specifying team rules in CLAUDE.md and accumulating what Claude discovers while working in auto memory, Claude can collaborate more effectively over time. Use the /memory command to view or disable auto memory.

팀과 공유하고 싶지 않은 개인적인 프로젝트 설정이 있을 때 사용합니다.

예를 들어:
• 내 로컬 환경의 DB 포트가 팀과 다를 때
• 개인적으로 선호하는 디버깅 방식
• 로컬에서만 사용하는 환경변수 경로
• 팀 규칙과 충돌하지 않는 개인 편의 설정

CLAUDE.local.md는 자동으로 .gitignore에 추가하는 것이 좋습니다. 팀의 프로젝트 CLAUDE.md에는 영향을 주지 않고 개인 설정을 유지할 수 있습니다. Use it when you have personal project settings you don't want to share with the team.

For example:
• Your local DB port is different from the team's
• A debugging approach you personally prefer
• Environment variable paths used only locally
• Personal convenience settings that don't conflict with team rules

It's a good idea to automatically add CLAUDE.local.md to .gitignore. This lets you maintain personal settings without affecting the team's project CLAUDE.md.

CLAUDE.md& 자동 메모리& Auto Memory

두 가지 메모리 시스템

Two Memory Systems

CLAUDE.md 파일File

자동 메모리 (Auto-memory)Auto Memory

"새 팀원" 비유로 이해하기

The "New Team Member" Analogy

세션마다 자동 로드Auto-loaded Every Session

프로젝트 컨텍스트 제공Provides Project Context

일관된 코딩 스타일 유지Maintains Consistent Coding Style

CLAUDE.md 파일 위치 & 계층

CLAUDE.md File Location & Hierarchy

회사 규칙 비유로 이해하기

The "Company Rules" Analogy

@ @import 문법으로 파일 가져오기Importing Files with @import Syntax

📂 .claude/rules/ 디렉터리로 규칙 분리Separating Rules with .claude/rules/ Directory

전역 CLAUDE.mdGlobal CLAUDE.md

프로젝트 CLAUDE.mdProject CLAUDE.md

CLAUDE.local.md

자동 메모리 시스템

Auto Memory System

어떻게 작동하나요?

How does it work?

저장 위치Storage Location

관리 방법How to Manage

핵심 동작 방식How It Works

세션 시작 시 MEMORY.md 로드MEMORY.md Loads at Session Start

필요 시 주제별 파일 동적 로드Topic-specific Files Loaded Dynamically When Needed

Claude가 기억할 가치 있는 것을 판단Claude Decides What Is Worth Remembering

언제든 비활성화 가능Can Be Disabled Anytime

자동 메모리가 잘하는 것What Auto Memory Does Well

주의할 점Watch Out For

작성 템플릿 갤러리Template Gallery

● 웹 프로젝트 (React / Next.js)Web Project (React / Next.js)

● 모바일 앱 (SwiftUI / Flutter)Mobile App (SwiftUI / Flutter)

● API 서버 (Node.js / Python)API Server (Node.js / Python)

● 데이터 분석 (Python / Jupyter)Data Analysis (Python / Jupyter)

좋은 예 vs 나쁜 예Good vs Bad Examples

프로젝트 설명Project Description

빌드 & 테스트 명령어Build & Test Commands

코딩 컨벤션Coding Conventions

파일 길이File Length

팀 공유 & Git 관리Team Sharing & Git Management

Git에 커밋하기Commit to Git

.gitignore에 넣기Add to .gitignore

팀 CLAUDE.md 셋업 가이드Team CLAUDE.md Setup Guide

팀 회의에서 규칙 합의Agree on Rules as a Team

CLAUDE.md 초안 작성Write a Draft CLAUDE.md

PR로 리뷰 & 머지Review & Merge via PR

정기적으로 업데이트Update Regularly

자주 묻는 질문Frequently Asked Questions

요약하면 이겁니다Here's the Summary

CLAUDE.md
& 자동 메모리& Auto Memory