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

규칙 내용은 거의 그대로 전송됩니다. Windsurf 규칙은 마크다운으로 작성된 모델에 대한 지침입니다. Claude Code는 CLAUDE.md를 읽습니다. 번역 레이어는 필요하지 않습니다. 텍스트가 위치하는 곳을 바꾸는 것일 뿐, 내용이 바뀌는 것은 아닙니다.

Windsurf의 수명 동안 수집하는 형태가 변경되었으므로 이를 파악해 두는 것이 좋습니다. 커뮤니티 문서에 따르면 두 가지 시스템이 공존하고 있습니다. 프로젝트 루트의 레거시 `.windsurfrules` 일반 텍스트 파일과 범위가 지정된 마크다운 규칙의 최신 `.windsurf/rules/` 디렉터리입니다. 현재 Devin Desktop 빌드는 .devin/rules/를 선호하고 .windsurf/rules/를 폴백으로 유지합니다. 이러한 파일 전체의 규칙은 합산하여 약 12,000자로 제한되는 것으로 보고되었습니다. 이러한 세부 정보는 현재 공식 참조가 아닌 실무자 가이드에서 제공되므로 자체 설치 환경에서 확인해 볼 가치가 있습니다.

이러한 폴백 동작 때문에 이번 마이그레이션이 선택 사항처럼 느껴지는 것입니다. 기존 규칙이 계속 읽히므로 눈에 띄게 저하되는 부분이 없고, 자산 점검도 일어나지 않습니다.

Cascade memory는 전송되지 않으며, 이것이 실제 손실입니다. 커뮤니티 가이드에서 말하는 중요한 차이점은 다음과 같습니다. 규칙은 사용자가 작성하고 버전 관리에 커밋하는 정적 지침인 반면, Cascade memory는 자동 생성되고 로컬에 저장됩니다. 에이전트는 세션의 컨텍스트를 기록하여 다시 묻지 않도록 하지만, memory는 팀원과 공유되지 않으며 의도적인 컨벤션을 두는 곳이 아닙니다.

이 부분을 주의 깊게 읽으십시오. 양날의 검이기 때문입니다. 이는 Windsurf에 실제로 memory 레이어가 있었고, 사용자가 인지하지 못했던 모든 "이미 알고 있네" 하는 순간들에서 실제 역할을 하고 있었음을 의미합니다. 또한 이 레이어는 세션에서 자동 생성되었고, 단일 머신에만 비공개였으며, 내보내도록 설계되지 않았음을 의미합니다. Claude Code에 전달할 수 있는 파일은 없습니다.

MCP 연결은 변환하는 것이 아니라 다시 추가해야 합니다. Windsurf에서 Devin으로의 리브랜딩 과정에서는 자동으로 유지되었지만, 다른 에디터로 이동할 때는 따라오지 않습니다. Claude Code는 MCP 서버를 지원하므로 무언가를 다시 작성하기보다는 구성을 다시 입력하는 작업에 가깝습니다. 하지만 각 서버에 필요했던 자격 증명과 환경 변수는 다시 사용자가 해결해야 할 문제입니다.

확장 프로그램, 키 바인딩, 요금제는 전혀 가져올 수 없습니다. 리브랜딩 시에는 동일한 에디터였기 때문에 인계되었습니다. Claude Code는 VS Code 포크가 아닌 CLI이므로, 이 부분은 마이그레이션이라기보다는 도구 카테고리의 변경에 가깝습니다. 놀라지 않도록 미리 언급해 둡니다.

스크립트와 자동화는 감사가 필요합니다. 리브랜딩으로 인해 .windsurf/tools/가 .devin/tools/로 이동했으며, 이 전환에 대해 널리 보고된 요약은 에디터 자체는 마이그레이션되었지만 스크립트는 마이그레이션되지 않았다는 것입니다. Windsurf 경로를 호출하는 모든 것은 이미 잠재적인 손상 상태이며, Claude Code로 이동하는 것은 새로운 원인을 만들기보다 이를 찾아내기에 좋은 기회입니다.

1단계: 규칙 수집 및 memory에 보관된 내용 재구성

파일부터 시작하세요. 이 부분은 기계적이기 때문입니다. 프로젝트 루트에서 .windsurfrules를 찾은 다음, .windsurf/rules/ 및 .devin/rules/에서 범위가 지정된 마크다운 파일을 찾으세요. 있는 줄도 잊고 있었던 파일들을 포함하여 모두 수집하세요. 합산 글자 수 제한 때문에 오래된 규칙은 삭제되기보다 잘려 나갔을 가능성이 높으며, 불완전한 규칙은 없는 것보다 못합니다.

찾은 내용을 실제 범위별로 분류하세요.

• 작업 전반에 걸친 글로벌 설정 — 출력 형식 지정 방법, 기본으로 사용하는 언어 및 버전, 모든 프로젝트에 적용되는 사항.
• 이 리포지토리에 대한 글로벌 설정 — 컨벤션, 아키텍처 제약 조건, 테스트 요구 사항.
• 특정 영역에 국한된 설정 — API 레이어, 데이터 레이어, 테스트에만 적용되는 규칙.

그 다음 기계적이지 않은 작업을 수행하세요. Cascade 또는 Devin Desktop을 열고 에이전트가 어디에도 기록되지 않은 채 알고 있는 것처럼 보이는 내용을 읽어보세요. 이를 표면화하는 실용적인 방법은 직접 물어보는 것입니다. 어떤 컨벤션을 따르고 있는지, 이 프로젝트에 대해 어떤 이야기를 들었는지, 무엇을 피하고 있는지 물어보세요. memory는 세션에서 자동 생성되기 때문에, 답변은 대개 지나가듯 한 번 말하고 기록해 두지 않은 것들일 가능성이 높습니다. 예를 들어 벤더의 특이한 점, 건드리지 말아야 할 디렉터리, 먼저 실행해야 하는 빌드 단계 등입니다.

이러한 내용을 일반 텍스트로 기록해 두세요. 이것이 마이그레이션에서 유일하게 대체 불가능한 시간입니다. 나머지는 파일을 복사하는 것뿐입니다. 또한 백업해 두지 않은 로컬의 머신별 저장소에 에디터의 유용성이 얼마나 많이 쌓여 있었는지 깨닫는 순간이기도 합니다.

2단계: 적절한 수준에서 CLAUDE.md로 재구축

Claude Code는 CLAUDE.md를 읽으며, 배치 위치에 따라 범위가 지정됩니다.

• 글로벌 기본 설정은 ~/.claude/CLAUDE.md에 들어갑니다.
• 리포지토리 컨벤션은 프로젝트 루트의 CLAUDE.md에 들어가며, 팀원들도 공유할 수 있도록 커밋합니다.
• 영역별 규칙은 해당 하위 디렉터리의 CLAUDE.md에 들어가거나 참조하는 문서에 유지됩니다.

세 번째 경우에 유용한 습관은 다음과 같습니다. 긴 영역별 규칙을 인라인으로 작성하는 대신 docs/에 파일로 보관하고, 루트 CLAUDE.md에 이를 가리키는 한 줄을 추가하는 것입니다. 예: "src/api/ 아래의 모든 항목을 건드리기 전에 docs/api-conventions.md를 읽으십시오." 또한 항상 불러오는 대신 관련이 있을 때 @path 임포트를 사용하여 특정 파일을 가져올 수도 있습니다.

빈 파일에서 시작하고 싶지 않다면, /init은 리포지토리에서 CLAUDE.md를 구성하고, /memory는 편집을 위해 memory 파일을 직접 엽니다. 둘 다 처음부터 작성하는 것보다 빠르며, 둘 다 나중에 편집하여 줄여야 할 결과물을 생성합니다.

짧게 유지하세요. 범위 내의 모든 항목은 모든 작업에서 로드되므로, 루트 파일이 길면 모든 요청에서 영원히 비용을 지불하게 됩니다. Windsurf의 합산 글자 수 제한과 달리 너무 길게 작성하는 것을 막는 장치가 없습니다. 그 제한이 오히려 도움이 되었던 셈입니다.

그 다음 기대치를 올바르게 설정하세요. 이 부분에서 사람들이 실망하기 때문입니다. 규칙 파일은 지식을 사용 가능하게 만들 뿐, 도구가 이를 기억하게 만들지는 않습니다. Claude Code는 각 세션을 파일에서 새로 시작하고 긴 세션에서는 컨텍스트를 압축합니다. 이 때문에 좋은 CLAUDE.md가 있더라도 세션 간에 프로젝트 컨텍스트를 잊어버리고, 지난주에 제공한 수정 사항이 반영되지 않은 채 돌아올 수 있습니다. 규칙은 이동했습니다. 하지만 방금 잃어버린 자동 생성된 memory 레이어를 대체하지는 못했으며, Claude Code는 이를 제공하지 않습니다.

방금 일어난 일의 형태를 주목해 보세요. memory 레이어가 머신에 로컬로 저장되어 있고 제품에 종속되어 있었기 때문에, 제품이 변경되면서(처음에는 리브랜딩으로, 그 다음에는 사용하던 에이전트의 종료로) 이를 잃게 되었습니다.

이것은 Windsurf의 실패가 아닙니다. 이 도구 내부에 존재하는 모든 지식에 일어나는 일입니다. 도구가 변경되기 전까지는 훌륭하지만, 변경되고 나면 복구할 수 없습니다. Cascade memory는 설계상 자동 생성되고 로컬에 저장되었습니다. 아무도 Cascade보다 오래 유지될 것이라 보장하지 않았습니다.

대안은 해당 레이어를 에디터 외부에 완전히 두는 것입니다. MemoryLake는 도구가 읽을 수 있는 memory 레이어입니다. 컨벤션, 결정 사항, 제약 조건이 하나의 저장소에 보관되며, MCP를 통해 Claude Code에서 액세스할 수 있고 API를 통해 다른 모든 도구에서 액세스할 수 있습니다. 다음에 에디터가 리브랜딩되거나, 에이전트가 종료되거나, 단순히 새로운 도구를 시도해보고 싶을 때, 지식은 재구성 작업이 아니라 구성 항목 입력만으로 해결됩니다.

파일의 장점도 공평하게 인정해야 합니다. CLAUDE.md는 저장소가 가지지 못한 확실한 장점이 있습니다. 일반 텍스트이고, 버전 관리에 포함되며, 풀 리퀘스트에서 검토되고, 팀원들이 자동으로 상속받습니다. 고정된 규칙은 여기에 보관하세요. 그것이 이 파일의 용도입니다. memory 레이어는 누적되는 항목들을 위한 것입니다. 벤더의 특이한 점, 결정의 배경 이유, 에디터를 삭제하기 전에 에이전트에게 물어보지 않았다면 발견하지 못했을 사항들입니다.

1단계: API 키 생성

키를 생성하고 약 30초 만에 첫 번째 요청을 수행하세요. 구성 파일에 인라인으로 작성하는 대신 환경 변수나 비밀 관리자에 보관하세요. 이번 이동을 위해 이미 MCP 자격 증명을 다시 입력하고 있으므로, 다음번에 찾지 않아도 되도록 안전한 곳에 보관하세요.

2단계: 첫 번째 memory 업로드

1단계에서 재구성한 내용이 담긴 문서, 이미지, 파일을 드롭하고, 규칙이 가리키고 있던 참조 자료(이유가 포함된 아키텍처 결정 사항, 빌드 특이 사항, 제약 조건)를 추가하세요. 가능한 경우 요약본보다는 원본 소스를 업로드하세요.

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

Claude, Codex, OpenClaw 및 기타 AI 에이전트가 MCP 또는 API를 통해 memory에 액세스할 수 있도록 하세요. Claude Code는 MCP 서버를 지원하므로 이는 하나의 구성 항목에 불과하며, 동일한 저장소를 사용하는 다른 모든 도구에서도 읽을 수 있습니다. 이것이 한 번만 설정하면 되는 이유입니다.

첫 번째 차이점은 1단계의 질문 작업이 마지막이 된다는 것입니다. 프로젝트에 대해 알게 된 내용이 내보낼 수 없는 머신별 저장소에 머무르지 않고, 읽을 수 있는 기록으로 남습니다.

두 번째는 머신 독립성입니다. Cascade memory는 로컬에 저장되었으며, 이를 대체한 대부분의 것들도 마찬가지입니다. Claude Code 자체의 지식은 체크아웃된 파일에 저장됩니다. 저장소를 사용하면 두 번째 노트북, 컨테이너 또는 팀원의 세션이 아무것도 없는 상태가 아니라 동일한 지식에서 시작할 수 있습니다.

세 번째는 여러 세션을 실행할 때 나타납니다. Claude Code는 이제 세션 간에 메시지를 주고받을 수 있어 협업에 유용하지만, 메시지는 두 개의 활성 세션 간에 전달되는 텍스트일 뿐 공유된 기반이 아닙니다. 저장소가 있어야 다음 주에 실행되는 네 번째 세션이 첫 번째 세션이 학습한 내용을 알 수 있습니다.

또한 다음 도구 변경 비용이 저렴해집니다. Cascade의 EOL(수명 종료)은 공지된 확정 날짜였지만, 여전히 사람들은 누적된 컨텍스트를 잃어야 했습니다. 반복하고 싶지 않은 마이그레이션 시나리오는 전환하는 대상 내부에 지식이 종속되어 있는 경우입니다.

에디터를 삭제하기 전에 기존 에이전트에게 질문하기

이 단계는 모두가 건너뛰는 단계이자 진정으로 되돌릴 수 없는 유일한 단계입니다. 자동 생성된 memory는 한 번 말했던 것들이 누적된 결과입니다. 에이전트에게 프로젝트에 대해 무엇을 알고 있는지, 어떤 컨벤션을 따르고 있는지, 무엇을 피하고 있는지 물어보고 설치 파일이 사라지기 전에 답변을 기록해 두세요.

폴백을 마이그레이션으로 오해하지 마세요

Devin Desktop이 .windsurf/rules/를 폴백으로 읽는다는 것은 기존 규칙이 여전히 작동함을 의미하므로 아무것도 할 필요가 없다고 믿기 쉽습니다. 다른 에디터로 떠나는 경우 이 폴백은 무의미합니다. Claude Code는 이러한 경로를 전혀 읽지 않습니다.

12,000자 제한을 지켜야 할 지침으로 취급하세요

Windsurf의 합산 규칙 제한은 선택을 강제했습니다. CLAUDE.md에는 그러한 강제성이 없으므로, 자연스럽게 모델이 모든 내용에 주의를 기울이지 못할 정도로 파일이 커지게 됩니다. 예산을 정하고 이를 의도적으로 고수하세요.

작업하는 동안 스크립트 감사하기

리브랜딩으로 인해 도구 경로가 이동했지만 스크립트는 따라가지 못했습니다. Windsurf 경로를 참조하는 모든 것은 이미 망가졌거나 망가지기 직전입니다. 의도적인 마이그레이션 중에 이를 수정하는 것이 CI에서 발견하는 것보다 훨씬 저렴합니다.

재구축 시 규칙과 지식 분리하기

CLAUDE.md는 모든 작업에서 로드되는 짧고 고정된 규칙을 위한 것입니다. 이유, 이력, 참조 자료는 문서나 관련이 있을 때 검색되는 저장소에 속해야 합니다. 모든 것을 하나의 긴 규칙 파일로 재구축하는 것은 글자 수 제한이 보호해 주었던 문제를 다시 발생시킵니다.

Windsurf에서 Claude Code로의 전환은 비용이 매우 다른 두 가지 작업입니다. 규칙을 이동하는 것은 기계적입니다. .windsurfrules, .windsurf/rules/, .devin/rules/를 수집하고, 범위별로 분류한 다음, ~/.claude/CLAUDE.md, 커밋된 루트 CLAUDE.md, 하위 디렉터리 파일 또는 참조 문서로 배치합니다. Cascade의 memory를 대체하는 것은 전혀 기계적이지 않습니다. 자동 생성되고 로컬에 저장되었으며, 내보내기 기능이 없으므로 복구할 수 있는 유일한 방법은 떠나기 전에 에이전트에게 알고 있는 내용을 물어보는 것뿐입니다.

Cascade의 7월 1일 수명 종료에서 얻을 수 있는 가치 있는 교훈은 Windsurf에 국한되지 않습니다. 제품 내부에 존재하는 memory 레이어는 해당 제품의 수명을 따릅니다. 에디터가 읽을 수 있는 저장소에 이를 보관하는 것이 다음 리브랜딩, 서비스 종료 또는 마음의 변화를 재구성 작업이 아닌 단순한 구성 변경으로 만드는 방법입니다.