컨텍스트 손실 없이 Zed에서 Claude Code로 마이그레이션하는 방법 (2026)

디렉터리 이동을 통한 스킬(Skills) 이전. Zed 스킬은 "전역 사용을 위해 ~/.agents/skills/에 설치되거나, 프로젝트 로컬 사용을 위해 프로젝트의 .agents/skills/ 폴더에 설치"되며, 스킬은 "메타데이터와 지침이 포함된 SKILL.md 파일이 들어 있는 폴더"입니다. Claude Code의 레이아웃도 경로는 다르지만 동일한 개념입니다. 개인용은 ~/.claude/skills/<skill-name>/SKILL.md에, 프로젝트용은 .claude/skills/<skill-name>/SKILL.md에 위치합니다. 폴더를 복사하고 상위 디렉터리 이름을 바꾸면 끝납니다.

양쪽 모두 로드하는 방식도 동일합니다. Zed: "기본적으로 에이전트는 자율적으로 스킬을 선택합니다. 시스템 프롬프트에서 설치된 모든 스킬(이름 및 설명)의 카탈로그를 확인하고, 작업이 스킬 설명과 일치할 때 skill 도구를 호출합니다." Claude Code: "Claude는 관련이 있을 때 스킬을 사용하거나, /skill-name으로 직접 호출할 수 있습니다."

이름 변경을 통한 지침 내용 이전. Zed가 실제로 읽고 있던 파일의 내용이 무엇이든 CLAUDE.md가 됩니다. 해당 파일이 이미 CLAUDE.md였다면 작업은 끝난 것이며, 다음 섹션을 다시 한 번 확인해야 합니다. 왜냐하면 목록의 앞부분에 다른 파일이 존재하지 않았을 때만 Zed가 이를 읽었음을 의미하기 때문입니다.

개인 설정 레이어의 새 보금자리. Zed의 개인 지침은 ~/.config/zed/AGENTS.md 또는 Windows의 경우 %APPDATA%\Zed\AGENTS.md에 저장됩니다. Claude Code의 해당 파일은 모든 프로젝트에 대한 개인 기본 설정을 담는 ~/.claude/CLAUDE.md입니다.

그 외에는 깔끔하게 이전되는 것이 없으며, 두 가지 동작 방식이 다릅니다.

우선순위가 양방향으로 뒤바뀝니다. Zed는 "충돌 시 프로젝트 지침이 개인 AGENTS.md보다 우선합니다"라고 명확히 밝히고 있습니다. 반면 Claude Code는 덮어쓰지 않습니다. 파일 시스템 루트부터 아래로 정렬되어 "발견된 모든 파일이 서로를 덮어쓰는 대신 컨텍스트로 병합(concatenate)"되며, 두 파일이 충돌할 경우 "Claude가 임의로 하나를 선택할 수 있습니다."

스킬의 경우 반대로 뒤집힙니다. Claude Code의 규칙은 "모든 수준에서 엔터프라이즈가 개인보다 우선하고, 개인은 프로젝트보다 우선한다"입니다. 예를 들어 ~/.claude/skills/와 프로젝트의 .claude/skills/ 모두에 deploy 스킬이 있는 경우, /deploy는 개인 스킬을 실행합니다. Zed에서는 프로젝트 범위 파일이 충돌에서 승리했지만, Claude Code에서는 개인 스킬이 승리합니다. 귀하와 팀원이 동일한 이름의 스킬을 가지고 있다면, 동일한 리포지토리에서 서로 다른 동작을 겪게 됩니다.

Zed의 호환성 파일은 더 이상 읽히지 않습니다. .rules, .cursorrules, .windsurfrules, .github/copilot-instructions.md는 모두 Zed가 프로젝트 지침으로 기꺼이 로드하는 파일들입니다. Claude Code는 기본적으로 이 중 어느 것도 읽지 않습니다. .clinerules는 유일한 예외로, CLAUDE_CODE_NEW_INIT=1 환경 변수가 설정된 경우에만 /init이 이를 가져오고, 그렇지 않으면 자동으로 건너뜁니다. 지금까지 호환성 파일 이름으로 지침을 유지해 왔다면, 이제 그 지침들은 보이지 않게 될 것입니다.

Zed의 스킬 배포 메커니즘은 제공되지 않습니다. Zed는 "전체 SKILL.md 내용(base64url 인코딩)을 포함하여 수신자가 프로젝트나 레지스트리에 액세스할 필요가 없도록" 자체 포함된 zed://skill?data=… 링크로 팀원에게 스킬을 전달할 수 있습니다. 또한 "명시적으로 저장하기 전에는 디스크에 아무것도 기록되지 않으므로, 공유 링크가 다른 사람의 에이전트에 지침을 몰래 설치할 수 없다"는 장점이 있습니다. 또한 커뮤니티 레지스트리인 skills.sh에서도 설치할 수 있습니다. 이것들은 배포 경로일 뿐 스킬 자체가 아닙니다. 파일은 이전되지만 공유 워크플로우는 이전되지 않습니다.

스킬별 권한 동작이 다릅니다. Zed에서는 "에이전트가 사용자가 생성하거나 설치한 스킬을 호출할 때, Zed는 다른 도구와 동일한 권한 흐름을 사용하여 허용 또는 거부할지 묻는 메시지를 표시"하며, 스킬별 기본값을 설정할 수 있습니다. Claude Code는 자체 권한 모델을 가지고 있습니다. Zed 스킬에 설정했을 수 있는 disable-model-invocation 토글은 복사하는 파일에 직접 대응하는 설정이 없습니다.

1단계: Zed가 실제로 읽고 있던 파일 확인하기

이것이 핵심이며, 단 하나의 명령어로 확인할 수 있습니다.

리포지토리 루트에 있는 후보 파일들을 Zed의 우선순위 순서대로 나열하고, 가장 먼저 존재하는 파일을 확인합니다:

ls -1 .rules .cursorrules .windsurfrules .clinerules \
      .github/copilot-instructions.md AGENT.md AGENTS.md CLAUDE.md GEMINI.md 2>/dev/null

출력의 첫 번째 줄이 현재 활성화된 지침 파일입니다. 그 아래에 있는 모든 파일은 Zed에서 무용지물이었으며, 어쩌면 몇 달 동안 방치되어 우선순위가 높은 파일과 모순되는 내용을 담고 있었을 수도 있습니다.

대비해야 할 세 가지 결과가 있습니다. 우선순위가 높은 파일이 CLAUDE.md라면 할 일이 없습니다. 만약 AGENTS.md라면 Claude Code가 이를 읽지 않으므로, 이름을 바꾸거나 가져오기(다음 단계)를 해야 합니다. .cursorrules와 같은 호환성 파일이라면 해당 내용을 CLAUDE.md로 이동해야 합니다. 상대 도구에는 해당 파일 이름을 읽는 기능이 없기 때문입니다.

또한 ~/.config/zed/AGENTS.md에 있는 개인 파일도 확인하세요. Zed의 '개인보다 프로젝트 우선' 규칙 때문에 프로젝트 파일과 충돌했던 개인 설정들은 무시되어 왔지만, Claude Code에서는 이제 함께 병합되므로 덮어써졌다고 생각했던 설정이 다시 활성화될 수 있습니다.

2단계: 스킬 이동 후 지침 레이어 재구축하기

기계적인 작업이므로 스킬부터 먼저 처리합니다. ~/.agents/skills/*를 ~/.claude/skills/로 복사하고, 프로젝트의 .agents/skills/*를 .claude/skills/로 복사합니다. 디렉터리 이름이 입력하는 명령어가 되며, Claude Code는 프런트매터(frontmatter)의 description을 읽고 자동으로 로드할 시점을 결정하므로 동일한 설명이 계속 작동합니다.

스킬을 옮긴 후 알아야 할 두 가지가 있습니다. 첫째, Claude Code 측에서는 사용자 정의 명령어와 스킬이 이제 동일한 개념입니다: ".claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md 스킬은 모두 /deploy를 생성하며 동일하게 작동합니다." 둘째, 중첩된 스킬은 컨텍스트에 따라 로드됩니다: "스킬은 작업 디렉터리 하위의 중첩된 .claude/skills/ 디렉터리에서도 로드"되며, 이는 "Claude가 하위 디렉터리의 파일을 읽거나 편집할 때" 사용할 수 있게 됩니다. 이는 최상위 디렉터리가 시사하는 것보다 Zed의 프로젝트 범위 지정에 더 가깝습니다.

기본 제공 세트와의 이름 충돌에 주의하세요. 프로젝트 스킬은 내장 스킬을 대체할 수 있습니다: "프로젝트의 .claude/skills/에 있는 code-review 스킬은 내장된 /code-review를 대체합니다." 보통은 괜찮지만 가끔 놀라운 결과를 초래할 수 있습니다.

그 다음 지침 파일의 형태를 선택합니다. 두 가지 깔끔한 옵션이 있습니다.

해당 리포지토리에서 이제 Claude Code만 유일한 에이전트로 사용한다면 이름을 CLAUDE.md로 변경하세요. 또는 AGENTS.md를 단일 진실 공급원(source of truth)으로 유지하고 이를 가져오는 CLAUDE.md를 추가할 수도 있습니다. 문서화된 패턴은 맨 위에 한 줄로 @AGENTS.md를 추가하는 것이며, 이후 "Claude는 세션 시작 시 가져온 파일을 로드한 다음 나머지 내용을 추가"합니다. 팀원들이 여전히 Zed를 사용 중이거나 다른 에이전트가 AGENTS.md를 읽는 경우, 두 개의 복사본이 서로 달라지는 대신 하나의 파일에 권한을 유지할 수 있으므로 이 방법이 올바른 선택입니다.

하나의 파일이었던 내용을 범위 지정 규칙으로 분할합니다. Claude Code는 Zed에는 없는 컨테이너를 제공합니다. 바로 glob 패턴의 paths: 프런트매터 필드를 가진 .claude/rules/ 파일로, "Claude가 지정된 패턴과 일치하는 파일로 작업할 때만 적용"됩니다. paths 필드가 없는 규칙은 "시작 시 .claude/CLAUDE.md와 동일한 우선순위로 로드"됩니다. Zed 지침 파일에 "프론트엔드 작업 시..." 섹션이 있었다면, 이제 그 섹션은 항상 활성화되는 텍스트 대신 경로 범위 지정 규칙으로 전환할 수 있습니다.

그리고 자동으로 활성화되는 기능을 파악하세요. Claude Code에는 Zed에 없는 두 번째 메커니즘인 자동 메모리(auto memory)가 있습니다. 이 기능은 기본적으로 켜져 있으며, Claude가 스스로를 위해 작성한 노트를 ~/.claude/projects/<project>/memory/에 저장합니다. user, feedback, project, reference 등 네 가지 종류를 기록하며, "코드베이스에서 도출할 수 있는 모든 내용"과 "CLAUDE.md 파일에 이미 명시된 내용"은 제외합니다. 일주일 후에 /memory를 실행하여 읽어보세요. 일반적인 메커니즘은 why Claude Code forgets project context에서 다룹니다.

실제로 로드된 내용을 확인하려면 /context를 실행하고 Memory files 아래의 목록을 확인하세요. 이것이 가장 확실한 답변이며, 문서에서도 첫 번째 디버깅 단계로 이를 권장합니다. "거기에 파일이 없으면 Claude는 볼 수 없기 때문"입니다.

한 걸음 물러서서 이번 마이그레이션이 실제로 무엇이었는지 살펴보십시오. 파일 이름이 바뀌었고, 폴더가 이동했습니다. 그리고 동작이 소리 없이 변경되는 위험한 부분은 전적으로 로더가 어떤 파일을 선택했는가에 관한 것이었습니다.

이는 Zed나 Claude Code만의 문제가 아닙니다. 영구적인 지식이 도구마다 탐색 규칙이 다른 파일에 보관될 때 발생하는 현상입니다. Zed는 9개 목록 중 첫 번째 일치 항목을 선택합니다. Claude Code는 발견된 모든 것을 병합하고 모순되는 내용 중 임의로 선택합니다. 두 도구 모두 매 요청마다 항상 켜져 있는 콘텐츠를 함께 전송하므로 전송 용량에 제한을 둡니다.

이것이 바로 MemoryLake가 해결하는 부분입니다. 프로젝트의 영구적인 지식을 도구가 쿼리할 수 있는 레이어에 보관하므로, 파일 이름은 단지 선호도일 뿐 에이전트의 이해를 좌우하는 결정적인 요소가 되지 않습니다. 설정은 3단계로 진행됩니다.

1단계: API 키 생성

MemoryLake에 로그인하고 API 키를 생성합니다. 연결하는 도구 전반에 걸쳐 하나의 자격 증명만 사용하면 됩니다.

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

각각 하나의 사실만 담은 짧은 항목들입니다. 1단계의 점검 내용이 생생할 때 작성해야 할 사항은 다음과 같습니다:

우선순위에서 밀렸던 파일에 묻혀 있던 결정 사항들. 만약 .cursorrules가 6달 동안 AGENTS.md에 가려져 있었다면, 그 안에는 아무도 적용하지 않았던 제약 조건들이 포함되어 있습니다. 삭제하기 전에 꼭 읽어보세요.

이유가 첨부된 결정 사항들. "부하 발생 시 읽기 복제본의 지연이 발생하므로 마이그레이션은 추가 전용으로만 진행됩니다." 지침은 정책을 명시하며, 오직 이 방식만이 대안이 다시 제안되는 것을 방지합니다.

이 코드베이스에서 이미 거부된 접근 방식. 지침 파일이나 커밋 메시지에는 나타나지 않지만, 매 세션마다 새로 제안되는 범주의 내용입니다.

아무도 알려주지 않는 환경적 사실들. CI에서만 실패하는 테스트, 문서화되지 않은 속도 제한, 두 마이그레이션 간의 순서 요구 사항 등입니다.

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

사용 중인 도구를 연결합니다. MemoryLake는 MCP 및 API를 통해 액세스할 수 있으므로, Claude Code, Codex, OpenClaw를 포함한 MCP 네이티브 에이전트는 MCP 서버를 가리켜 연결하고, 다른 어시스턴트는 API를 통해 동일한 메모리를 읽습니다. 즉, 동일한 추론의 복사본 두 개를 유지 관리하지 않고도 동일한 리포지토리에서 Zed와 Claude Code를 나란히 실행할 수 있습니다.

세 가지 분명한 한계가 있습니다. MemoryLake는 사용자의 CLAUDE.md, AGENTS.md 또는 스킬을 작성하지 않습니다. 이것들은 각 도구를 조종하는 방법이며, 위의 로더 동작은 메모리 레이어가 변경할 수 없는 도구 자체의 영역입니다. MemoryLake는 사용자나 에이전트가 입력한 내용만 보관하므로 2단계는 수동으로 진행됩니다. 또한 지침은 강제된 구성이라기보다는 컨텍스트에 가깝습니다. 매번 반드시 지켜야 하는 사항에 대해 Claude Code가 제시하는 해답은 파일이 아니라 훅(hook)입니다.

"어떤 파일이 활성화되어 있는가?"를 한 줄로 확인할 수 있게 됩니다. Zed는 9개의 후보 중 첫 번째 일치 항목을 선택합니다. 이제 목록과 순서를 알게 되었습니다.

가려진 파일들이 더 이상 지뢰가 되지 않습니다. 우선순위에서 밀린 파일들을 읽고 중요한 내용을 병합하고 나면, 다음 사람을 혼란스럽게 만들 잊혀진 .cursorrules가 남지 않습니다.

스킬이 특정 도구에 종속되지 않습니다. 동일한 SKILL.md가 Zed, Claude Code, Cursor, Codex에서 실행됩니다. 한 번만 작성하면 됩니다.

지침 파일이 더 짧아집니다. 경로 범위 지정 규칙 덕분에 "X 작업 시" 섹션이 모든 메시지마다 로드되지 않습니다.

다른 에디터를 사용하는 팀원이 포크(fork)가 되지 않습니다. 하나의 권장 지침 파일과 쿼리 가능한 메모리 레이어를 결합하는 것이 서로 달라지는 두 개의 파일을 유지하는 것보다 훨씬 낫습니다. 이에 대한 자세한 내용은 what persistent memory actually means에서 다룹니다.

무엇이든 변경하기 전에 우선순위가 높은 파일을 찾으세요. Zed는 .rules부터 GEMINI.md까지 첫 번째 일치 항목을 읽으며, 그 뒤에 있는 모든 것은 비활성 상태였습니다.

가려진 파일들을 읽고 삭제하세요. 수개월 동안 적용되지 않았던 제약 조건이 포함되어 있을 수 있습니다.

CLAUDE.md로 이름을 바꾸거나, 거기서 AGENTS.md를 가져오세요. 다른 에이전트나 팀원이 여전히 AGENTS.md를 읽는다면 가져오기를 사용하고, 그렇지 않다면 이름을 바꾸세요.

스킬을 폴더 대 폴더로 이동한 다음 이름 충돌을 확인하세요. Claude Code에서는 개인 스킬이 프로젝트 스킬보다 우선하며, 이는 Zed의 지침 우선순위와 반대입니다.

개인 파일의 중요성이 낮아지는 것이 아니라 더 커질 것임을 예상하세요. Zed의 프로젝트 지침은 개인 파일을 덮어썼지만, Claude Code는 둘 다 병합합니다.

항상 활성화되는 텍스트를 경로 범위 지정 규칙으로 분할하세요. paths: 프런트매터 필드는 Zed에는 없던 컨테이너입니다.

메모리가 아닌 /context로 확인하세요. Memory files 목록이 실제로 로드된 내용입니다.

일주일 후에 자동 메모리 폴더를 열어보세요. 기본적으로 켜져 있으며, 지침 파일이 의도적으로 담지 않은 내용을 보관합니다.

지침 파일에서 추론 과정을 제외하세요. 두 도구 모두 전송 용량을 제한하며, 추론 과정이 가장 먼저 잘려 나갑니다. 이 일반적인 문제는 why agents ignore the instruction files you wrote에서 다룹니다.

Zed에서 Claude Code로의 전환은 단순한 이름 변경처럼 보이고 실제로도 대부분 그렇지만, 그 이름 변경에 위험이 도사리고 있습니다. Zed는 AGENTS.md가 CLAUDE.md보다 우선하는 9개 항목 목록에서 첫 번째로 일치하는 프로젝트 지침 파일을 선택하는 반면, Claude Code는 AGENTS.md가 아닌 CLAUDE.md를 읽습니다. 따라서 지금까지 에이전트를 조종해 온 파일이 내일 에이전트를 조종할 파일과 다를 수 있으며, Zed의 문서에서도 이미 해당 로더가 다른 에이전트를 제어한다고 가정하지 말라고 경고하고 있습니다.

스킬은 쉬운 부분입니다. 두 도구 모두 SKILL.md를 포함하는 폴더이므로 ~/.agents/skills/가 ~/.claude/skills/가 되고 설명도 계속 작동합니다. 우선순위가 뒤바뀌는 점(Zed에서는 프로젝트 지침이 이겼지만 Claude Code에서는 개인 스킬이 이김)에 주의하고, Zed의 호환성 파일 이름은 상대 도구에서 읽지 못한다는 점을 기억하세요.

어떤 파일이 활성화되어 있었는지 점검하고, 활성화되지 않았던 파일들을 병합하고, 이름을 바꿀지 가져올지 결정하고, 항상 활성화되는 텍스트를 경로 범위 지정 규칙으로 분할하고, 결정 사항과 거부된 접근 방식을 두 에디터가 모두 쿼리할 수 있는 곳에 보관하세요. 그러면 로더의 우선순위 목록을 더 이상 머릿속에 담아둘 필요가 없어집니다.