Claude가 프로젝트를 기억하는 방법

CLAUDE.md 파일로 Claude에게 지속적인 지시사항을 제공하고, 자동 메모리를 통해 Claude가 스스로 학습 내용을 축적하도록 하세요.

각 Claude Code 세션은 빈 컨텍스트 윈도우로 시작됩니다. 두 가지 메커니즘이 세션 간 지식을 전달합니다:

CLAUDE.md 파일: Claude에게 지속적인 컨텍스트를 제공하기 위해 사용자가 작성하는 지시사항
자동 메모리: 사용자의 수정 사항과 선호도를 기반으로 Claude가 스스로 작성하는 메모

이 페이지에서 다루는 내용:

CLAUDE.md 파일 작성 및 구성
.claude/rules/를 사용한 특정 파일 유형별 규칙 범위 지정
자동 메모리 설정으로 Claude가 자동으로 메모하도록 구성
지시사항이 잘 따라지지 않을 때의 문제 해결

CLAUDE.md vs 자동 메모리

Claude Code에는 두 가지 상호 보완적인 메모리 시스템이 있습니다. 둘 다 모든 대화 시작 시 로드됩니다. Claude는 이를 컨텍스트로 취급하며, 강제 설정으로 취급하지 않습니다. 지시사항이 구체적이고 간결할수록 Claude가 더 일관되게 따릅니다.

	CLAUDE.md 파일	자동 메모리
작성자	사용자	Claude
포함 내용	지시사항과 규칙	학습 내용과 패턴
범위	프로젝트, 사용자, 또는 조직	워킹 트리 단위
로드 대상	모든 세션	모든 세션 (처음 200줄)
용도	코딩 표준, 워크플로우, 프로젝트 아키텍처	빌드 명령어, 디버깅 인사이트, Claude가 발견한 선호도

Claude의 동작을 가이드하려면 CLAUDE.md 파일을 사용하세요. 자동 메모리는 수동 작업 없이 Claude가 사용자의 수정 사항으로부터 학습할 수 있게 해줍니다.

서브에이전트도 자체 자동 메모리를 유지할 수 있습니다. 자세한 내용은 서브에이전트 설정을 참고하세요.

CLAUDE.md 파일

CLAUDE.md 파일은 프로젝트, 개인 워크플로우, 또는 전체 조직에 대해 Claude에게 지속적인 지시사항을 제공하는 마크다운 파일입니다. 일반 텍스트로 작성하며, Claude는 매 세션 시작 시 이 파일을 읽습니다.

CLAUDE.md 파일을 배치할 위치 선택

CLAUDE.md 파일은 여러 위치에 둘 수 있으며, 각각 다른 범위를 가집니다. 더 구체적인 위치가 더 넓은 위치보다 우선합니다.

범위	위치	목적	사용 사례 예시	공유 대상
관리형 정책	• macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` • Linux 및 WSL: `/etc/claude-code/CLAUDE.md` • Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	IT/DevOps가 관리하는 조직 전체 지시사항	회사 코딩 표준, 보안 정책, 컴플라이언스 요구사항	조직 내 모든 사용자
프로젝트 지시사항	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	팀이 공유하는 프로젝트 지시사항	프로젝트 아키텍처, 코딩 표준, 공통 워크플로우	소스 컨트롤을 통한 팀 멤버
사용자 지시사항	`~/.claude/CLAUDE.md`	모든 프로젝트에 적용되는 개인 선호도	코드 스타일 선호도, 개인 도구 단축키	본인만 (모든 프로젝트)
로컬 지시사항	`./CLAUDE.local.md`	git에 체크인되지 않는 개인 프로젝트별 선호도	샌드박스 URL, 선호하는 테스트 데이터	본인만 (현재 프로젝트)

작업 디렉토리 상위의 디렉토리 계층에 있는 CLAUDE.md 파일은 실행 시 전체가 로드됩니다. 하위 디렉토리의 CLAUDE.md 파일은 Claude가 해당 디렉토리의 파일을 읽을 때 필요 시 로드됩니다. 전체 로드 순서는 CLAUDE.md 파일이 로드되는 방식을 참고하세요.

대규모 프로젝트의 경우, 프로젝트 규칙을 사용하여 지시사항을 주제별 파일로 분리할 수 있습니다. 규칙을 사용하면 특정 파일 유형이나 하위 디렉토리에 맞게 지시사항의 범위를 지정할 수 있습니다.

프로젝트 CLAUDE.md 설정

프로젝트 CLAUDE.md는 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 저장할 수 있습니다. 이 파일을 생성하고 프로젝트에서 작업하는 모든 사람에게 적용될 지시사항을 추가하세요: 빌드 및 테스트 명령어, 코딩 표준, 아키텍처 결정사항, 네이밍 컨벤션, 공통 워크플로우 등. 이 지시사항은 버전 관리를 통해 팀과 공유되므로, 개인 선호도보다는 프로젝트 수준의 표준에 집중하세요.

팁:

/init을 실행하면 자동으로 초기 CLAUDE.md가 생성됩니다. Claude가 코드베이스를 분석하여 빌드 명령어, 테스트 지시사항, 발견한 프로젝트 컨벤션이 포함된 파일을 만듭니다. CLAUDE.md가 이미 존재하면, /init은 덮어쓰지 않고 개선 사항을 제안합니다. 이후 Claude가 스스로 발견하지 못할 지시사항을 추가로 다듬으세요.

효과적인 지시사항 작성

CLAUDE.md 파일은 매 세션 시작 시 컨텍스트 윈도우에 로드되어 대화와 함께 토큰을 소비합니다. 강제 설정이 아닌 컨텍스트이므로, 지시사항 작성 방식이 Claude의 준수 정도에 영향을 미칩니다. 구체적이고, 간결하며, 잘 구조화된 지시사항이 가장 효과적입니다.

크기: CLAUDE.md 파일당 200줄 이하를 목표로 하세요. 긴 파일은 더 많은 컨텍스트를 소비하고 준수율을 낮춥니다. 지시사항이 길어지면 임포트나 .claude/rules/ 파일로 분리하세요.

구조: 마크다운 헤더와 불릿을 사용하여 관련 지시사항을 그룹화하세요. Claude는 읽는 사람과 같은 방식으로 구조를 스캔합니다: 정리된 섹션이 빽빽한 문단보다 따르기 쉽습니다.

구체성: 검증 가능할 정도로 구체적인 지시사항을 작성하세요. 예를 들어:

"코드를 제대로 포맷하라" 대신 "2칸 들여쓰기를 사용하라"
"변경사항을 테스트하라" 대신 "커밋 전에 npm test를 실행하라"
"파일을 정리해서 보관하라" 대신 "API 핸들러는 src/api/handlers/에 위치시켜라"

일관성: 두 규칙이 서로 모순되면 Claude가 임의로 하나를 선택할 수 있습니다. CLAUDE.md 파일, 하위 디렉토리의 중첩된 CLAUDE.md 파일, .claude/rules/를 주기적으로 검토하여 오래되었거나 충돌하는 지시사항을 제거하세요. 모노레포에서는 claudeMdExcludes를 사용하여 작업과 관련 없는 다른 팀의 CLAUDE.md 파일을 건너뛸 수 있습니다.

추가 파일 임포트

CLAUDE.md 파일은 @path/to/import 구문을 사용하여 추가 파일을 임포트할 수 있습니다. 임포트된 파일은 실행 시 해당 CLAUDE.md와 함께 확장되어 컨텍스트에 로드됩니다.

상대 경로와 절대 경로 모두 사용할 수 있습니다. 상대 경로는 작업 디렉토리가 아닌 임포트를 포함하는 파일을 기준으로 해석됩니다. 임포트된 파일은 최대 5단계까지 재귀적으로 다른 파일을 임포트할 수 있습니다.

README, package.json, 워크플로우 가이드를 가져오려면 CLAUDE.md 어디에서든 @ 구문으로 참조하세요:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

버전 관리에 체크인하지 않아야 하는 프로젝트별 개인 선호도는 CLAUDE.local.md를 사용하세요: 자동으로 로드되며 .gitignore에 추가됩니다.

여러 git 워크트리를 사용하는 경우, CLAUDE.local.md는 하나에만 존재합니다. 모든 워크트리가 동일한 개인 지시사항을 공유하도록 홈 디렉토리 임포트를 대신 사용하세요:

# Individual Preferences
- @~/.claude/my-project-instructions.md

주의:

Claude Code가 프로젝트에서 외부 임포트를 처음 발견하면, 파일 목록이 포함된 승인 대화 상자를 표시합니다. 거부하면 임포트가 비활성화되며 대화 상자가 다시 나타나지 않습니다.

지시사항을 더 체계적으로 구성하려면 .claude/rules/를 참고하세요.

CLAUDE.md 파일이 로드되는 방식

Claude Code는 현재 작업 디렉토리에서 디렉토리 트리를 상위로 탐색하면서 각 디렉토리의 CLAUDE.md와 CLAUDE.local.md 파일을 확인하여 CLAUDE.md 파일을 읽습니다. 즉, foo/bar/에서 Claude Code를 실행하면 foo/bar/CLAUDE.md와 foo/CLAUDE.md 양쪽의 지시사항이 모두 로드됩니다.

Claude는 현재 작업 디렉토리 아래의 하위 디렉토리에서도 CLAUDE.md 파일을 발견합니다. 실행 시 로드하는 대신, Claude가 해당 하위 디렉토리의 파일을 읽을 때 포함됩니다.

다른 팀의 CLAUDE.md 파일이 함께 로드되는 대규모 모노레포에서 작업하는 경우, claudeMdExcludes를 사용하여 건너뛸 수 있습니다.

추가 디렉토리에서 로드

--add-dir 플래그를 사용하면 주 작업 디렉토리 외부의 추가 디렉토리에 Claude가 접근할 수 있습니다. 기본적으로 이러한 디렉토리의 CLAUDE.md 파일은 로드되지 않습니다.

추가 디렉토리의 CLAUDE.md 파일(CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md 포함)도 로드하려면 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경 변수를 설정하세요:

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

`.claude/rules/`로 규칙 구성

대규모 프로젝트의 경우, .claude/rules/ 디렉토리를 사용하여 지시사항을 여러 파일로 구성할 수 있습니다. 이렇게 하면 지시사항이 모듈화되어 팀이 유지보수하기 쉬워집니다. 규칙은 특정 파일 경로에 범위를 지정할 수도 있어, Claude가 매칭되는 파일을 작업할 때만 컨텍스트에 로드되므로 노이즈를 줄이고 컨텍스트 공간을 절약합니다.

참고:

규칙은 매 세션마다 또는 매칭되는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지시사항은 스킬을 대신 사용하세요. 스킬은 사용자가 호출하거나 Claude가 프롬프트와 관련 있다고 판단할 때만 로드됩니다.

규칙 설정

프로젝트의 .claude/rules/ 디렉토리에 마크다운 파일을 배치하세요. 각 파일은 하나의 주제를 다루어야 하며, testing.md나 api-design.md와 같은 설명적인 파일명을 사용하세요. 모든 .md 파일은 재귀적으로 발견되므로, frontend/나 backend/와 같은 하위 디렉토리로 규칙을 구성할 수 있습니다:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

paths 프론트매터가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 실행 시 로드됩니다.

경로별 규칙

YAML 프론트매터의 paths 필드를 사용하여 규칙의 범위를 특정 파일로 지정할 수 있습니다. 이러한 조건부 규칙은 Claude가 지정된 패턴과 매칭되는 파일을 작업할 때만 적용됩니다.

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

paths 필드가 없는 규칙은 무조건적으로 로드되어 모든 파일에 적용됩니다. 경로 범위 규칙은 매 도구 사용 시가 아니라, Claude가 패턴과 매칭되는 파일을 읽을 때 트리거됩니다.

paths 필드에서 glob 패턴을 사용하여 확장자, 디렉토리, 또는 조합으로 파일을 매칭하세요:

패턴	매칭 대상
`*/.ts`	모든 디렉토리의 TypeScript 파일
`src/*/`	`src/` 디렉토리 아래의 모든 파일
`*.md`	프로젝트 루트의 마크다운 파일
`src/components/*.tsx`	특정 디렉토리의 React 컴포넌트

여러 패턴을 지정하고 중괄호 확장을 사용하여 하나의 패턴으로 여러 확장자를 매칭할 수 있습니다:

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

심링크로 프로젝트 간 규칙 공유

.claude/rules/ 디렉토리는 심링크를 지원하므로, 공유 규칙 세트를 유지하고 여러 프로젝트에 링크할 수 있습니다. 심링크는 정상적으로 해석되어 로드되며, 순환 심링크는 감지되어 적절히 처리됩니다.

이 예시는 공유 디렉토리와 개별 파일을 모두 링크합니다:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

사용자 수준 규칙

~/.claude/rules/에 있는 개인 규칙은 머신의 모든 프로젝트에 적용됩니다. 프로젝트에 특정되지 않는 선호도에 사용하세요:

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

사용자 수준 규칙은 프로젝트 규칙보다 먼저 로드되어, 프로젝트 규칙이 더 높은 우선순위를 가집니다.

대규모 팀을 위한 CLAUDE.md 관리

조직 전체에 Claude Code를 배포하는 경우, 지시사항을 중앙 집중화하고 어떤 CLAUDE.md 파일이 로드될지 제어할 수 있습니다.

조직 전체 CLAUDE.md 배포

조직은 머신의 모든 사용자에게 적용되는 중앙 관리 CLAUDE.md를 배포할 수 있습니다. 이 파일은 개별 설정으로 제외할 수 없습니다.

Step 1: 관리형 정책 위치에 파일 생성

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux 및 WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Step 2: 설정 관리 시스템으로 배포

MDM, 그룹 정책, Ansible 또는 유사한 도구를 사용하여 개발자 머신에 파일을 배포하세요. 다른 조직 전체 설정 옵션은 관리형 설정을 참고하세요.

특정 CLAUDE.md 파일 제외

대규모 모노레포에서는 상위 CLAUDE.md 파일에 작업과 관련 없는 지시사항이 포함될 수 있습니다. claudeMdExcludes 설정을 사용하면 경로나 glob 패턴으로 특정 파일을 건너뛸 수 있습니다.

이 예시는 최상위 CLAUDE.md와 상위 폴더의 규칙 디렉토리를 제외합니다. .claude/settings.local.json에 추가하면 제외 설정이 로컬에만 적용됩니다:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

패턴은 glob 구문을 사용하여 절대 파일 경로와 매칭됩니다. claudeMdExcludes는 모든 설정 레이어에서 구성할 수 있습니다: 사용자, 프로젝트, 로컬, 또는 관리형 정책. 배열은 레이어 간 병합됩니다.

관리형 정책 CLAUDE.md 파일은 제외할 수 없습니다. 이를 통해 개별 설정에 관계없이 조직 전체 지시사항이 항상 적용됩니다.

자동 메모리

자동 메모리를 사용하면 사용자가 아무것도 작성하지 않아도 Claude가 세션 간에 지식을 축적할 수 있습니다. Claude는 작업하면서 빌드 명령어, 디버깅 인사이트, 아키텍처 메모, 코드 스타일 선호도, 워크플로우 습관 등을 스스로 메모합니다. Claude는 매 세션마다 저장하지 않습니다. 향후 대화에서 유용할 정보인지에 따라 기억할 가치가 있는 것을 판단합니다.

자동 메모리 활성화 또는 비활성화

자동 메모리는 기본적으로 활성화되어 있습니다. 토글하려면 세션에서 /memory를 열어 자동 메모리 토글을 사용하거나, 프로젝트 설정에서 autoMemoryEnabled를 설정하세요:

{
  "autoMemoryEnabled": false
}

환경 변수를 통해 자동 메모리를 비활성화하려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하세요.

저장 위치

각 프로젝트는 ~/.claude/projects/<project>/memory/에 자체 메모리 디렉토리를 가집니다. <project> 경로는 git 저장소에서 파생되므로, 동일한 저장소 내의 모든 워크트리와 하위 디렉토리가 하나의 자동 메모리 디렉토리를 공유합니다. git 저장소 외부에서는 프로젝트 루트가 대신 사용됩니다.

디렉토리에는 MEMORY.md 엔트리포인트와 선택적 주제 파일이 포함됩니다:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

MEMORY.md는 메모리 디렉토리의 인덱스 역할을 합니다. Claude는 세션 중에 이 디렉토리의 파일을 읽고 쓰며, MEMORY.md를 사용하여 어디에 무엇이 저장되어 있는지 추적합니다.

자동 메모리는 머신 로컬입니다. 동일한 git 저장소 내의 모든 워크트리와 하위 디렉토리가 하나의 자동 메모리 디렉토리를 공유합니다. 파일은 머신이나 클라우드 환경 간에 공유되지 않습니다.

작동 방식

MEMORY.md의 처음 200줄이 모든 대화 시작 시 로드됩니다. 200줄을 초과하는 내용은 세션 시작 시 로드되지 않습니다. Claude는 상세한 메모를 별도의 주제 파일로 옮겨 MEMORY.md를 간결하게 유지합니다.

이 200줄 제한은 MEMORY.md에만 적용됩니다. CLAUDE.md 파일은 길이에 관계없이 전체가 로드되지만, 짧은 파일이 더 높은 준수율을 보입니다.

debugging.md나 patterns.md와 같은 주제 파일은 시작 시 로드되지 않습니다. Claude는 정보가 필요할 때 표준 파일 도구를 사용하여 필요 시 읽습니다.

Claude는 세션 중에 메모리 파일을 읽고 씁니다. Claude Code 인터페이스에서 "Writing memory" 또는 "Recalled memory"가 표시되면, Claude가 ~/.claude/projects/<project>/memory/에서 적극적으로 업데이트하거나 읽고 있는 것입니다.

메모리 감사 및 편집

자동 메모리 파일은 언제든지 편집하거나 삭제할 수 있는 일반 마크다운입니다. 세션 내에서 메모리 파일을 탐색하고 열려면 /memory를 실행하세요.

`/memory`로 확인 및 편집

/memory 명령어는 현재 세션에 로드된 모든 CLAUDE.md 및 규칙 파일을 나열하고, 자동 메모리를 켜거나 끌 수 있으며, 자동 메모리 폴더를 열 수 있는 링크를 제공합니다. 파일을 선택하면 편집기에서 열립니다.

Claude에게 무언가를 기억해달라고 요청하면(예: "항상 pnpm을 사용하고 npm은 쓰지 마" 또는 "API 테스트에 로컬 Redis 인스턴스가 필요하다는 것을 기억해"), Claude는 이를 자동 메모리에 저장합니다. 대신 CLAUDE.md에 지시사항을 추가하려면, "이것을 CLAUDE.md에 추가해"와 같이 Claude에게 직접 요청하거나, /memory를 통해 파일을 직접 편집하세요.

메모리 문제 해결

CLAUDE.md와 자동 메모리에 대한 가장 일반적인 문제와 디버그 방법입니다.

Claude가 CLAUDE.md를 따르지 않는 경우

CLAUDE.md는 컨텍스트이지 강제 사항이 아닙니다. Claude는 이를 읽고 따르려고 하지만, 특히 모호하거나 충돌하는 지시사항의 경우 엄격한 준수가 보장되지는 않습니다.

디버그 방법:

/memory를 실행하여 CLAUDE.md 파일이 로드되고 있는지 확인하세요. 파일이 목록에 없으면 Claude가 볼 수 없습니다.
해당 CLAUDE.md가 세션에 로드되는 위치에 있는지 확인하세요 (CLAUDE.md 파일을 배치할 위치 선택 참고).
지시사항을 더 구체적으로 만드세요. "코드를 깔끔하게 포맷하라"보다 "2칸 들여쓰기를 사용하라"가 더 효과적입니다.
CLAUDE.md 파일 간 충돌하는 지시사항이 있는지 확인하세요. 두 파일이 같은 동작에 대해 다른 가이드를 제공하면, Claude가 임의로 하나를 선택할 수 있습니다.

팁:

InstructionsLoaded 훅을 사용하면 어떤 지시사항 파일이 로드되었는지, 언제 로드되었는지, 왜 로드되었는지를 정확히 로그로 남길 수 있습니다. 경로별 규칙이나 하위 디렉토리에서 지연 로드되는 파일을 디버깅할 때 유용합니다.

자동 메모리가 무엇을 저장했는지 모르는 경우

/memory를 실행하고 자동 메모리 폴더를 선택하여 Claude가 저장한 내용을 탐색하세요. 모든 것은 읽고, 편집하고, 삭제할 수 있는 일반 마크다운입니다.

CLAUDE.md가 너무 큰 경우

200줄을 초과하는 파일은 더 많은 컨텍스트를 소비하고 준수율을 낮출 수 있습니다. 상세한 내용은 @path 임포트로 참조되는 별도 파일로 옮기거나 (추가 파일 임포트 참고), .claude/rules/ 파일로 지시사항을 분산하세요.

`/compact` 후 지시사항이 사라진 것처럼 보이는 경우

CLAUDE.md는 컴팩션 이후에도 완전히 유지됩니다. /compact 후 Claude는 디스크에서 CLAUDE.md를 다시 읽어 세션에 새로 주입합니다. 컴팩션 후 지시사항이 사라졌다면, CLAUDE.md에 작성된 것이 아니라 대화에서만 제공된 것입니다. 세션 간에 유지되도록 CLAUDE.md에 추가하세요.

크기, 구조, 구체성에 대한 가이드는 효과적인 지시사항 작성을 참고하세요.

Claude가 프로젝트를 기억하는 방법

CLAUDE.md 파일로 Claude에게 지속적인 지시사항을 제공하고, 자동 메모리를 통해 Claude가 스스로 학습 내용을 축적하도록 하세요.

각 Claude Code 세션은 빈 컨텍스트 윈도우로 시작됩니다. 두 가지 메커니즘이 세션 간 지식을 전달합니다:

CLAUDE.md 파일: Claude에게 지속적인 컨텍스트를 제공하기 위해 사용자가 작성하는 지시사항
자동 메모리: 사용자의 수정 사항과 선호도를 기반으로 Claude가 스스로 작성하는 메모

이 페이지에서 다루는 내용:

CLAUDE.md 파일 작성 및 구성
.claude/rules/를 사용한 특정 파일 유형별 규칙 범위 지정
자동 메모리 설정으로 Claude가 자동으로 메모하도록 구성
지시사항이 잘 따라지지 않을 때의 문제 해결

CLAUDE.md vs 자동 메모리

	CLAUDE.md 파일	자동 메모리
작성자	사용자	Claude
포함 내용	지시사항과 규칙	학습 내용과 패턴
범위	프로젝트, 사용자, 또는 조직	워킹 트리 단위
로드 대상	모든 세션	모든 세션 (처음 200줄)
용도	코딩 표준, 워크플로우, 프로젝트 아키텍처	빌드 명령어, 디버깅 인사이트, Claude가 발견한 선호도

서브에이전트도 자체 자동 메모리를 유지할 수 있습니다. 자세한 내용은 서브에이전트 설정을 참고하세요.

CLAUDE.md 파일

CLAUDE.md 파일을 배치할 위치 선택

CLAUDE.md 파일은 여러 위치에 둘 수 있으며, 각각 다른 범위를 가집니다. 더 구체적인 위치가 더 넓은 위치보다 우선합니다.

범위	위치	목적	사용 사례 예시	공유 대상
관리형 정책	• macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` • Linux 및 WSL: `/etc/claude-code/CLAUDE.md` • Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	IT/DevOps가 관리하는 조직 전체 지시사항	회사 코딩 표준, 보안 정책, 컴플라이언스 요구사항	조직 내 모든 사용자
프로젝트 지시사항	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	팀이 공유하는 프로젝트 지시사항	프로젝트 아키텍처, 코딩 표준, 공통 워크플로우	소스 컨트롤을 통한 팀 멤버
사용자 지시사항	`~/.claude/CLAUDE.md`	모든 프로젝트에 적용되는 개인 선호도	코드 스타일 선호도, 개인 도구 단축키	본인만 (모든 프로젝트)
로컬 지시사항	`./CLAUDE.local.md`	git에 체크인되지 않는 개인 프로젝트별 선호도	샌드박스 URL, 선호하는 테스트 데이터	본인만 (현재 프로젝트)

프로젝트 CLAUDE.md 설정

팁:

/init을 실행하면 자동으로 초기 CLAUDE.md가 생성됩니다. Claude가 코드베이스를 분석하여 빌드 명령어, 테스트 지시사항, 발견한 프로젝트 컨벤션이 포함된 파일을 만듭니다. CLAUDE.md가 이미 존재하면, /init은 덮어쓰지 않고 개선 사항을 제안합니다. 이후 Claude가 스스로 발견하지 못할 지시사항을 추가로 다듬으세요.

효과적인 지시사항 작성

구체성: 검증 가능할 정도로 구체적인 지시사항을 작성하세요. 예를 들어:

"코드를 제대로 포맷하라" 대신 "2칸 들여쓰기를 사용하라"
"변경사항을 테스트하라" 대신 "커밋 전에 npm test를 실행하라"
"파일을 정리해서 보관하라" 대신 "API 핸들러는 src/api/handlers/에 위치시켜라"

추가 파일 임포트

README, package.json, 워크플로우 가이드를 가져오려면 CLAUDE.md 어디에서든 @ 구문으로 참조하세요:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

버전 관리에 체크인하지 않아야 하는 프로젝트별 개인 선호도는 CLAUDE.local.md를 사용하세요: 자동으로 로드되며 .gitignore에 추가됩니다.

# Individual Preferences
- @~/.claude/my-project-instructions.md

주의:

Claude Code가 프로젝트에서 외부 임포트를 처음 발견하면, 파일 목록이 포함된 승인 대화 상자를 표시합니다. 거부하면 임포트가 비활성화되며 대화 상자가 다시 나타나지 않습니다.

지시사항을 더 체계적으로 구성하려면 .claude/rules/를 참고하세요.

CLAUDE.md 파일이 로드되는 방식

다른 팀의 CLAUDE.md 파일이 함께 로드되는 대규모 모노레포에서 작업하는 경우, claudeMdExcludes를 사용하여 건너뛸 수 있습니다.

추가 디렉토리에서 로드

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

`.claude/rules/`로 규칙 구성

참고:

규칙은 매 세션마다 또는 매칭되는 파일이 열릴 때 컨텍스트에 로드됩니다. 항상 컨텍스트에 있을 필요가 없는 작업별 지시사항은 스킬을 대신 사용하세요. 스킬은 사용자가 호출하거나 Claude가 프롬프트와 관련 있다고 판단할 때만 로드됩니다.

규칙 설정

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

paths 프론트매터가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 실행 시 로드됩니다.

경로별 규칙

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

paths 필드에서 glob 패턴을 사용하여 확장자, 디렉토리, 또는 조합으로 파일을 매칭하세요:

패턴	매칭 대상
`*/.ts`	모든 디렉토리의 TypeScript 파일
`src/*/`	`src/` 디렉토리 아래의 모든 파일
`*.md`	프로젝트 루트의 마크다운 파일
`src/components/*.tsx`	특정 디렉토리의 React 컴포넌트

여러 패턴을 지정하고 중괄호 확장을 사용하여 하나의 패턴으로 여러 확장자를 매칭할 수 있습니다:

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

심링크로 프로젝트 간 규칙 공유

이 예시는 공유 디렉토리와 개별 파일을 모두 링크합니다:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

사용자 수준 규칙

~/.claude/rules/에 있는 개인 규칙은 머신의 모든 프로젝트에 적용됩니다. 프로젝트에 특정되지 않는 선호도에 사용하세요:

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

사용자 수준 규칙은 프로젝트 규칙보다 먼저 로드되어, 프로젝트 규칙이 더 높은 우선순위를 가집니다.

대규모 팀을 위한 CLAUDE.md 관리

조직 전체에 Claude Code를 배포하는 경우, 지시사항을 중앙 집중화하고 어떤 CLAUDE.md 파일이 로드될지 제어할 수 있습니다.

조직 전체 CLAUDE.md 배포

조직은 머신의 모든 사용자에게 적용되는 중앙 관리 CLAUDE.md를 배포할 수 있습니다. 이 파일은 개별 설정으로 제외할 수 없습니다.

Step 1: 관리형 정책 위치에 파일 생성

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux 및 WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Step 2: 설정 관리 시스템으로 배포

MDM, 그룹 정책, Ansible 또는 유사한 도구를 사용하여 개발자 머신에 파일을 배포하세요. 다른 조직 전체 설정 옵션은 관리형 설정을 참고하세요.

특정 CLAUDE.md 파일 제외

이 예시는 최상위 CLAUDE.md와 상위 폴더의 규칙 디렉토리를 제외합니다. .claude/settings.local.json에 추가하면 제외 설정이 로컬에만 적용됩니다:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

관리형 정책 CLAUDE.md 파일은 제외할 수 없습니다. 이를 통해 개별 설정에 관계없이 조직 전체 지시사항이 항상 적용됩니다.

자동 메모리

자동 메모리 활성화 또는 비활성화

{
  "autoMemoryEnabled": false
}

환경 변수를 통해 자동 메모리를 비활성화하려면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하세요.

저장 위치

디렉토리에는 MEMORY.md 엔트리포인트와 선택적 주제 파일이 포함됩니다:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

작동 방식

이 200줄 제한은 MEMORY.md에만 적용됩니다. CLAUDE.md 파일은 길이에 관계없이 전체가 로드되지만, 짧은 파일이 더 높은 준수율을 보입니다.

debugging.md나 patterns.md와 같은 주제 파일은 시작 시 로드되지 않습니다. Claude는 정보가 필요할 때 표준 파일 도구를 사용하여 필요 시 읽습니다.

메모리 감사 및 편집

자동 메모리 파일은 언제든지 편집하거나 삭제할 수 있는 일반 마크다운입니다. 세션 내에서 메모리 파일을 탐색하고 열려면 /memory를 실행하세요.

`/memory`로 확인 및 편집

메모리 문제 해결

CLAUDE.md와 자동 메모리에 대한 가장 일반적인 문제와 디버그 방법입니다.

Claude가 CLAUDE.md를 따르지 않는 경우

디버그 방법:

/memory를 실행하여 CLAUDE.md 파일이 로드되고 있는지 확인하세요. 파일이 목록에 없으면 Claude가 볼 수 없습니다.
해당 CLAUDE.md가 세션에 로드되는 위치에 있는지 확인하세요 (CLAUDE.md 파일을 배치할 위치 선택 참고).
지시사항을 더 구체적으로 만드세요. "코드를 깔끔하게 포맷하라"보다 "2칸 들여쓰기를 사용하라"가 더 효과적입니다.
CLAUDE.md 파일 간 충돌하는 지시사항이 있는지 확인하세요. 두 파일이 같은 동작에 대해 다른 가이드를 제공하면, Claude가 임의로 하나를 선택할 수 있습니다.

팁:

InstructionsLoaded 훅을 사용하면 어떤 지시사항 파일이 로드되었는지, 언제 로드되었는지, 왜 로드되었는지를 정확히 로그로 남길 수 있습니다. 경로별 규칙이나 하위 디렉토리에서 지연 로드되는 파일을 디버깅할 때 유용합니다.

자동 메모리가 무엇을 저장했는지 모르는 경우

/memory를 실행하고 자동 메모리 폴더를 선택하여 Claude가 저장한 내용을 탐색하세요. 모든 것은 읽고, 편집하고, 삭제할 수 있는 일반 마크다운입니다.

CLAUDE.md가 너무 큰 경우

`/compact` 후 지시사항이 사라진 것처럼 보이는 경우

크기, 구조, 구체성에 대한 가이드는 효과적인 지시사항 작성을 참고하세요.

1. Claude가 프로젝트를 기억하는 방법

Claude가 프로젝트를 기억하는 방법

CLAUDE.md vs 자동 메모리

CLAUDE.md 파일

CLAUDE.md 파일을 배치할 위치 선택

프로젝트 CLAUDE.md 설정

효과적인 지시사항 작성

추가 파일 임포트

CLAUDE.md 파일이 로드되는 방식

추가 디렉토리에서 로드

.claude/rules/로 규칙 구성

규칙 설정

경로별 규칙

심링크로 프로젝트 간 규칙 공유

사용자 수준 규칙

대규모 팀을 위한 CLAUDE.md 관리

조직 전체 CLAUDE.md 배포

Step 1: 관리형 정책 위치에 파일 생성

Step 2: 설정 관리 시스템으로 배포

특정 CLAUDE.md 파일 제외

자동 메모리

자동 메모리 활성화 또는 비활성화

저장 위치

작동 방식

메모리 감사 및 편집

/memory로 확인 및 편집

메모리 문제 해결

Claude가 CLAUDE.md를 따르지 않는 경우

자동 메모리가 무엇을 저장했는지 모르는 경우

CLAUDE.md가 너무 큰 경우

/compact 후 지시사항이 사라진 것처럼 보이는 경우

관련 리소스

1. Claude가 프로젝트를 기억하는 방법

Claude가 프로젝트를 기억하는 방법

CLAUDE.md vs 자동 메모리

CLAUDE.md 파일

CLAUDE.md 파일을 배치할 위치 선택

프로젝트 CLAUDE.md 설정

효과적인 지시사항 작성

추가 파일 임포트

CLAUDE.md 파일이 로드되는 방식

추가 디렉토리에서 로드

.claude/rules/로 규칙 구성

규칙 설정

경로별 규칙

심링크로 프로젝트 간 규칙 공유

사용자 수준 규칙

대규모 팀을 위한 CLAUDE.md 관리

조직 전체 CLAUDE.md 배포

Step 1: 관리형 정책 위치에 파일 생성

Step 2: 설정 관리 시스템으로 배포

특정 CLAUDE.md 파일 제외

자동 메모리

자동 메모리 활성화 또는 비활성화

저장 위치

작동 방식

메모리 감사 및 편집

/memory로 확인 및 편집

메모리 문제 해결

Claude가 CLAUDE.md를 따르지 않는 경우

자동 메모리가 무엇을 저장했는지 모르는 경우

CLAUDE.md가 너무 큰 경우

/compact 후 지시사항이 사라진 것처럼 보이는 경우

관련 리소스

`.claude/rules/`로 규칙 구성

`/memory`로 확인 및 편집

`/compact` 후 지시사항이 사라진 것처럼 보이는 경우

`.claude/rules/`로 규칙 구성

`/memory`로 확인 및 편집

`/compact` 후 지시사항이 사라진 것처럼 보이는 경우