Claude Code Worktree는 메모리를 공유하나요? 각 Worktree 세션이 로드하는 항목 (2026)

• 자동 메모리는 공유됩니다. 리포지토리의 모든 Worktree는 하나의 메모리 디렉터리를 사용합니다.
• CLAUDE.md는 Worktree 자체의 체크아웃에서 가져옵니다. 새 Worktree는 기본 브랜치에서 시작하므로, 해당 브랜치에 커밋된 버전을 갖게 됩니다.
• CLAUDE.local.md는 공유되지 않습니다. 이 파일은 생성된 해당 Worktree에만 존재합니다.
• Gitignored 파일은 존재하지 않습니다. .worktreeinclude에 나열하지 않는 한 포함되지 않습니다.
• 일부 설정은 메인 체크아웃과 공유됩니다: 플러그인, 권한 승인, 그리고 일부 경우 스킬, 에이전트, 명령어가 이에 해당합니다.

자동 메모리는 Claude가 스스로를 위해 작성하는 메모입니다. 사용자의 선호도, 수정 사항, 코드에서 도출할 수 없는 프로젝트 컨텍스트 등이 포함됩니다. Anthropic의 메모리 문서는 그 범위를 "리포지토리별로 지정되며, Worktree 간에 공유됨"으로 정의하고 있습니다.

저장소 섹션에서 그 이유를 설명합니다. "각 프로젝트는 ~/.claude/projects/<project>/memory/에 고유한 메모리 디렉터리를 갖습니다. <project> 경로는 Git 리포지토리에서 파생되므로, 동일한 리포지토리 내의 모든 Worktree와 하위 디렉터리는 하나의 자동 메모리 디렉터리를 공유합니다."

따라서 한 Worktree 세션에서 Claude에게 제공한 수정 사항은 동일한 리포지토리의 다른 Worktree에서 시작하는 다음 세션에 나타날 수 있습니다. 이는 아무런 설정 없이도 Worktree를 가로지르는 유일한 레이어입니다. 하지만 이는 로컬 장비로 제한됩니다. "자동 메모리는 로컬 장비에 한정됩니다. 동일한 Git 리포지토리 내의 모든 Worktree와 하위 디렉터리는 하나의 자동 메모리 디렉터리를 공유합니다. 파일은 장비 간 또는 클라우드 환경 간에 공유되지 않습니다." Claude Code가 장비 간에 망각하는 이유 가이드에서 이 경계를 다룹니다.

메모리 디렉터리는 ~/.claude/projects/ 아래에 존재하므로 Worktree 외부에 위치합니다. Worktree를 제거하면 Worktree의 디렉터리와 브랜치는 삭제되지만, 해당 메모리 폴더는 포함되지 않습니다.

CLAUDE.md는 리포지토리 내의 파일이므로, Worktree는 자체 복사본을 읽습니다. 어떤 복사본을 읽는지는 Worktree가 어디서 시작되었는지에 따라 다릅니다. Anthropic의 Worktree 페이지에 따르면 Claude Code는 "리포지토리의 기본 브랜치에서 브랜치를 생성하고, 추적된(tracked) 파일만 체크아웃합니다."

기본 베이스는 fresh이며, 이는 "원격의 리포지토리 기본 브랜치(보통 main)에서 브랜치를 생성하므로, Worktree가 원격과 일치하는 깨끗한 트리에서 시작함"을 의미합니다. 메인 체크아웃에서 CLAUDE.md를 편집하고 커밋 및 푸시하지 않았다면, 새 Worktree에는 해당 편집 사항이 반영되지 않습니다. 해당 Worktree의 CLAUDE.md는 원격 기본 브랜치에 있는 파일입니다.

대신 현재 작업에서 브랜치를 생성하려면 worktree.baseRef를 head로 설정하세요. 문서에 따르면 이 옵션은 "현재 로컬 HEAD에서 브랜치를 생성하므로, Worktree가 푸시되지 않은 커밋과 피처 브랜치 상태를 가져옵니다." 커밋되지 않은 변경 사항은 어떤 커밋에도 포함되지 않으므로 메인 체크아웃에 그대로 남습니다.

데스크톱 앱에서 시작된 Worktree 세션의 경우, 다른 프로젝트 설정은 메인 체크아웃의 루트에서 읽어오더라도 "CLAUDE.md 파일과 .claude/rules/는 여전히 Worktree에서 로드된다"고 문서에 명시되어 있습니다. 서로 다른 레이어가 충돌하기 시작하면, 충돌하는 CLAUDE.md 레이어 조정 가이드에서 이들이 어떻게 결합되는지 다룹니다.

CLAUDE.local.md는 커밋하지 않는 개인적인 선호 설정을 위한 것입니다. Git에서 무시(gitignored)되므로 새 Worktree에는 이 파일이 포함되지 않습니다. Anthropic은 이를 직접적으로 언급합니다. "동일한 리포지토리의 여러 Git Worktree에서 작업하는 경우, Git 무시된 CLAUDE.local.md는 생성한 해당 Worktree에만 존재합니다."

문서에서 제시하는 해결책은 콘텐츠를 홈 디렉터리로 이동하고 이를 임포트하는 것입니다. 개인 지침을 ~/.claude/my-project-instructions.md와 같은 파일에 넣은 다음, Anthropic의 예시처럼 @ 임포트로 참조하세요. 이렇게 하면 모든 Worktree가 홈 디렉터리의 동일한 파일을 읽게 됩니다.

추적되지 않는(untracked) 다른 파일에도 동일한 규칙이 적용됩니다. "Worktree는 새로 체크아웃된 상태이므로, 메인 리포지토리의 .env 또는 .env.local과 같이 추적되지 않는 파일은 존재하지 않습니다."

이 파일들을 복사해 넣으려면 프로젝트 루트에 .worktreeinclude 파일을 추가하세요. 이 파일은 ".gitignore 구문을 사용"하며, "패턴과 일치하고 Git 무시된 파일만 복사되므로 추적된 파일이 중복되는 일은 없습니다." 이는 서브에이전트 Worktree 및 데스크톱 앱의 병렬 세션을 포함하여 "Claude Code가 Git으로 생성하는 모든 Worktree"에 적용됩니다.

.worktreeinclude 패턴은 Worktree가 생성될 때 파일을 한 번 복사합니다. 복사된 CLAUDE.local.md 또는 .env는 각 Worktree에서 별개의 파일이 되며, 한 곳에서 편집해도 다른 곳에 업데이트되지 않습니다. 계속해서 변경되는 개인 지침의 경우, 홈 디렉터리 임포트 방식이 더 안정적인 옵션입니다.

Anthropic은 Worktree가 메인 체크아웃과 공유하는 항목을 다음과 같이 나열합니다:

• 리포지토리의 .git 디렉터리: Worktree에서 수행된 커밋이 동일한 리포지토리로 이동합니다.
• 플러그인: 메인 체크아웃에서 프로젝트 범위로 설치된 플러그인입니다.
• 권한 승인: Worktree에서 Bash 명령어를 항상 허용하도록 선택하면 "규칙이 메인 체크아웃의 .claude/settings.local.json에 저장"되므로 리포지토리의 모든 Worktree에 적용됩니다. Windows 및 일부 다른 경우에는 규칙이 해당 Worktree에만 유지됩니다.
• 추적되지 않는 스킬, 에이전트 및 명령어: Worktree 자체에 .claude/skills 디렉터리가 없는 경우에 해당합니다. "자체 .claude/skills 디렉터리가 있는 Worktree에서는 해당 복사본만 로드됩니다."

데스크톱 앱 Worktree 세션은 한 단계 더 나아갑니다. 여기에서 Claude Code는 "설정, 훅, 스킬, 에이전트, 명령어, .mcp.json 서버와 같은 프로젝트 구성을 메인 체크아웃의 루트에서 읽어옵니다."

서브에이전트는 요청에 따라 또는 커스텀 서브에이전트의 프런트매터(frontmatter)에 isolation: worktree를 설정하여 자체 Worktree에서 실행될 수 있습니다. 이들의 지침은 다른 곳에서 제공됩니다. "자체 Worktree에 있는 서브에이전트는 시작할 때 사용하는 지침 파일을 Worktree가 아닌 메인 대화에서 가져옵니다."

그리고 기본 위치에 있는 Worktree의 경우, "서브에이전트는 해당 Worktree의 브랜치에서 내용이 다르더라도, 파일을 읽을 때 Worktree 루트에 있는 CLAUDE.md 파일이나 .claude/rules/ 디렉터리를 로드하지 않습니다." 브랜치에서 CLAUDE.md를 변경하고 Worktree 서브에이전트가 이를 따르기를 기대한다면, 서브에이전트는 대신 메인 대화의 버전을 따르게 됩니다.

대화 자체는 실행된 Worktree에 그대로 유지됩니다. 세션 선택기(session picker)는 기본적으로 "현재 Worktree의 세션"을 표시하며, Ctrl+W를 누르면 리포지토리의 모든 Worktree로 범위를 넓힐 수 있습니다. 이름으로 재개하는 기능은 리포지토리의 모든 Worktree에서 작동합니다.

Claude가 Worktree에 진입하거나 나갈 때 "트랜스크립트가 따라가므로", --resume은 새 디렉터리에서 세션을 찾습니다. Worktree 내부에서 종료된 세션을 재개하면 해당 위치로 돌아갑니다. Worktree가 제거된 경우, Claude Code는 실행했던 디렉터리에서 재개하며 "세션의 Worktree 바인딩을 지웁니다." Claude Code 세션 기록 찾기 가이드에서 선택기에 대해 더 자세히 다룹니다.

메인 체크아웃에서 CLAUDE.md를 편집하고 Worktree 시작하기. 새 Worktree는 커밋되지 않은 편집본이 아니라 원격 기본 브랜치의 버전을 갖게 됩니다.

모든 Worktree에 CLAUDE.local.md가 있을 것이라 기대하기. 이 파일은 생성한 위치에만 존재합니다.

Worktree가 메모리를 격리할 것이라 가정하기. 자동 메모리는 리포지토리의 모든 Worktree에서 공유됩니다. 한 세션에서의 잘못된 수정 사항이 다른 세션으로 이어질 수 있습니다.

Worktree 서브에이전트를 위해 브랜치에서 CLAUDE.md 변경하기. 기본 위치의 Worktree에 있는 서브에이전트는 메인 대화의 지침 파일로 시작합니다.

Worktree에만 메모 보관하기. Worktree를 제거하면 해당 디렉터리, 브랜치 및 그 안의 작업 내용이 모두 삭제됩니다.

1단계: 공유 지침은 커밋하고, 개인 지침은 홈에서 임포트하기

모든 세션이 따라야 하는 내용은 커밋된 CLAUDE.md에 작성하고 기본 브랜치에 푸시하여 새 Worktree가 이를 가지고 시작하도록 하세요. 푸시되지 않은 지침 변경 사항을 Worktree가 가져와야 한다면, worktree.baseRef를 head로 설정하고 변경 사항을 먼저 커밋하세요.

CLAUDE.local.md에서 개인 메모를 홈 디렉터리의 파일로 이동하고 이를 임포트하세요. 하나의 파일을 모든 Worktree가 읽고, 한 곳에서 편집할 수 있습니다.

2단계: 각 Worktree에 필요한 Git 무시 파일 나열하기

프로젝트 루트에 .worktreeinclude 파일을 추가하고, .env 및 .env.local과 같이 세션 작동에 필수적인 Git 무시 파일을 나열하세요. 복사본은 시작점으로 취급하세요. 값이 변경되면 메인 체크아웃에서 업데이트하여 새 Worktree가 새 버전을 가져가도록 하세요.

자동 메모리도 수시로 확인하세요. 모든 Worktree가 이를 공유하므로, 한 세션의 잘못된 메모가 모든 세션에 영향을 미칩니다. 메모 파일은 ~/.claude/projects/<project>/memory/ 아래에 있는 일반 마크다운 파일이며, 직접 편집하거나 삭제할 수 있습니다.

3단계: 정리하기 전에 Worktree 세션이 파악한 내용 기록하기

Worktree 세션이 종료되면 그 결론은 트랜스크립트와 자동 메모리에 남을 수 있습니다. Worktree를 제거하기 전에 다른 세션에 필요한 결정 사항과 발견한 내용을 기록해 두세요. 영구적인 규칙은 CLAUDE.md에 작성합니다. 그 외의 모든 것은 개인 메모에 기록하세요.

세션이 실행되는 동안 발견한 내용을 서로 교환해야 하는 경우, Worktree 페이지에서 세션 간 메시징(cross-session messaging)을 참조하세요. 이를 통해 "Claude가 Worktree 세션 간에 발견한 내용을 전달"할 수 있습니다.

Worktree는 작업을 병렬 체크아웃으로 분할하며, 각 컨텍스트 레이어는 이 분할을 다르게 처리합니다. 자동 메모리는 Worktree를 가로지르지만 로컬 장비로 제한됩니다. CLAUDE.md는 브랜치를 따릅니다. 개인 메모는 작성한 위치에 그대로 유지됩니다.

MemoryLake는 이러한 작업 뒤에 숨겨진 결정 사항들을 사용자가 관리하는 하나의 목록으로 유지하고, Claude Code 및 연결된 다른 어시스턴트(예: Codex, ChatGPT)가 사용할 수 있도록 하는 메모리 레이어입니다.

사용자가 직접 자신의 언어로 항목을 작성합니다. 사용자의 Worktree, CLAUDE.md 또는 CLAUDE.local.md 파일, 자동 메모리 디렉터리, 세션 트랜스크립트 또는 기타 공급업체의 저장소에서 데이터를 읽거나, 쓰거나, 삭제하지 않습니다. 비밀 정보는 메모 항목이 아닌 환경 파일에 보관하세요.

1단계: API 키 생성하기

로그인한 후 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 워크스페이스에 속하며 Claude 계정과는 별개입니다.

2단계: 첫 번째 메모 업로드하기

해결책의 3단계에서 기록한 내용, 즉 곧 정리할 Worktree 세션의 결정 사항과 발견한 내용부터 시작하세요. 항목당 하나의 요점을 작성하고, 날짜를 기입하고, 리포지토리 및 브랜치 라벨을 지정합니다.

3단계: AI 및 에이전트 연결하기

Claude Code 및 사용하는 다른 어시스턴트를 연결하세요. 이 장비 또는 다른 장비의 모든 새 Worktree 세션이 동일한 결정 사항에서 시작할 수 있습니다.

첫 번째 차이점은 새 Worktree가 올바른 지침을 가지고 시작한다는 것입니다. 공유 규칙은 커밋되고, 개인 규칙은 홈에서 임포트되며, 세션에 필요한 파일이 복사됩니다.

두 번째는 병렬 세션이 일관되게 유지된다는 점입니다. 자동 메모리가 공유된다는 사실을 알고 있으므로 이를 확인하고, 각 Worktree와 서브에이전트가 어떤 CLAUDE.md를 읽는지 알 수 있습니다.

세 번째는 정리를 하더라도 컨텍스트를 잃지 않는다는 점입니다. Worktree가 제거되기 전에 해당 Worktree의 결론이 기록됩니다. 클라우드 세션도 실행하는 경우, Claude Code 클라우드 세션이 로컬 설정에서 가져오는 항목 가이드에서 이 경계를 넘나드는 항목을 다룹니다.

지침 변경 사항 커밋 및 푸시하기. 새 Worktree는 원격 기본 브랜치에서 시작합니다.

홈 디렉터리에서 개인 지침 임포트하기. CLAUDE.local.md는 하나의 Worktree에만 유지됩니다.

환경 파일에 .worktreeinclude 사용하기. 일치하는 Git 무시 파일만 복사됩니다.

자동 메모리가 공유된다는 점 기억하기. 세션 간 의견이 일치하지 않기 시작하면 검토하세요.

Worktree 서브에이전트가 메인 대화의 지침을 사용할 것이라 예상하기. 브랜치의 CLAUDE.md가 아닙니다.

.gitignore에 .claude/worktrees/ 추가하기. Anthropic은 Worktree 콘텐츠가 추적되지 않는 파일로 표시되지 않도록 이 설정을 권장합니다.

Worktree를 제거하기 전에 발견한 내용 기록하기. 제거 시 디렉터리와 브랜치가 삭제됩니다.

Claude Code Worktree는 컨텍스트가 아닌 파일 편집을 격리합니다. 자동 메모리는 동일한 장비에 있는 리포지토리의 모든 Worktree에서 공유됩니다. CLAUDE.md는 각 Worktree의 체크아웃(기본적으로 원격 기본 브랜치)에서 가져옵니다. CLAUDE.local.md 및 기타 Git 무시 파일은 .worktreeinclude가 복사하지 않는 한 생성한 위치에만 존재합니다. Worktree의 서브에이전트는 메인 대화에서 지침을 가져옵니다.

공유 지침은 커밋하고, 개인 지침은 홈에서 임포트하며, 각 Worktree에 필요한 파일을 나열하고, 정리하기 전에 세션이 파악한 내용을 기록해 두세요.