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

스킬은 그대로 이전됩니다. 이것은 좋은 소식이며, 대부분의 도구 쌍보다 나은 점입니다. Windsurf는 워크스페이스 스킬을 .windsurf/skills/에, 글로벌 스킬을 ~/.codeium/windsurf/skills/에 보관하지만, 문서에는 다음과 같이 추가되어 있습니다. "크로스 에이전트 호환성을 위해 Devin Desktop은 .agents/skills/ 및 ~/.agents/skills/에서도 스킬을 검색합니다." Zed는 정확히 두 곳, 즉 글로벌용 ~/.agents/skills/와 프로젝트 로컬용 <worktree>/.agents/skills/에서 스킬을 로드합니다. 스킬이 이미 .agents/skills/에 있다면, 두 도구 모두 변환 없이 동일한 파일을 읽습니다.

또한 두 도구 모두 동일한 두 필드를 사용하여 점진적 공개(progressive disclosure)를 사용합니다. Windsurf: "기본적으로 스킬의 이름과 설명만 모델에 표시됩니다. 전체 SKILL.md 콘텐츠 및 지원 파일은 Cascade가 스킬을 호출하기로 결정할 때(또는 사용자가 @mention할 때)에만 로드됩니다." Zed: "시스템 프롬프트에서 설치된 모든 스킬의 카탈로그(이름 및 설명)를 확인하고, 작업이 스킬 설명과 일치할 때 skill 도구를 호출합니다." 동일한 메커니즘, 동일한 name 및 description 프론트매터(frontmatter), 양쪽 모두 동일한 disable-model-invocation 플래그를 사용합니다.

규칙 파일은 바이트 단위로 이전되지만 의미가 변경됩니다. Windsurf의 워크스페이스 규칙은 .devin/rules/*.md(권장) 또는 .windsurf/rules/*.md(폴백)에 파일당 하나씩 존재하며, 문서에서는 "워크스페이스 루트에 있는 레거시 단일 파일 .windsurfrules도 여전히 읽습니다"라고 확인해 줍니다. 루트 AGENTS.md는 "동일한 규칙 엔진에 의해 처리됩니다. 루트 수준 = 항상 켜짐(always-on), 하위 디렉터리 = 해당 디렉터리에 대한 자동 glob 패턴 적용."

Zed의 프로젝트 지침 로딩은 다르게 작동합니다. 문서에는 다음과 같이 명시되어 있습니다. "프로젝트 지침 파일은 현재 프로젝트에 적용됩니다. Zed는 이 목록에서 첫 번째로 일치하는 파일을 사용합니다:"

.rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md

순서를 세어보세요. .windsurfrules는 세 번째입니다. AGENTS.md는 일곱 번째입니다. 첫 번째로 일치하는 파일이 승리하며, 단 하나의 파일만 사용됩니다. 2025년의 .windsurfrules를 여전히 가지고 있는 리포지토리의 경우, Zed는 해당 파일을 읽고 오늘 아침에 작성한 AGENTS.md를 무시합니다. 경고도, 오류도, 확인해 볼 만한 로그 항목도 전혀 남지 않습니다.

활성화 모드는 이전되지 않습니다. Windsurf는 trigger 프론트매터 필드에 선언된 네 가지 모드를 문서화하고 있으며, 표를 통해 각 모드의 컨텍스트 비용을 제공합니다: always_on ("모든 메시지에서 시스템 프롬프트에 전체 규칙 콘텐츠가 포함됨"), model_decision ("시스템 프롬프트에는 설명만 표시됨. Cascade는 설명이 관련이 있다고 판단할 때 전체 규칙 파일을 읽음"), glob ("Cascade가 glob 패턴과 일치하는 파일을 읽거나 편집할 때 규칙이 적용됨"), 및 manual ("시스템 프롬프트에 규칙이 포함되지 않음. @rule-name을 입력하여 활성화함").

이 네 가지 모드는 Windsurf 사용자가 가장 많이 조정하는 제어 영역이며, 이 구분이 사라지는 것이 Windsurf forgetting your project rules에서 다룬 불만의 가장 흔한 원인입니다. 다만 여기서는 규칙이 여전히 디스크에 존재하지만 선언된 모드가 더 이상 존재하지 않을 뿐입니다.

Zed는 네 가지 대신 두 가지 영역을 가집니다. 지침(Instructions)은 "Zed Agent를 위한 항상 켜져 있는 컨텍스트"입니다. 스킬(Skills)은 카탈로그에서 에이전트에 의해 호출되거나, 슬래시 명령 또는 @skill 언급을 통해 수동으로 호출됩니다. Zed의 스킬 프론트매터는 name, description, disable-model-invocation 세 가지 필드를 문서화하고 있으며, 페이지에는 다음과 같이 적혀 있습니다. "가까운 시일 내에 Agent Skills 사양에서 권장하는 다른 필드들을 포함할 계획입니다." 따라서 현재로서는 glob 패턴으로 범위가 지정된 Windsurf 규칙을 Zed 측에서 유지할 수 있는 필드가 없으며, 에이전트가 매칭할 수 있는 설명(description)으로 다시 표현해야 합니다.

디렉터리 범위 지침은 범위를 잃게 됩니다. Windsurf에서 하위 디렉터리의 AGENTS.md는 "<directory>/**의 자동 생성된 패턴을 가진 glob 규칙"이 되므로, 모노레포는 영역별로 하나의 지침 파일을 추가 비용 없이 가질 수 있습니다. Zed의 지침 페이지는 해당 우선순위 목록에서 선택된 단일 프로젝트 지침 파일만 설명하며, 하위 디렉터리에서의 지침 파일 검색은 설명하지 않습니다. 네 개의 수준에 있는 네 개의 AGENTS.md 파일이 Zed에 도달하면, 그중 세 개는 문서화된 역할이 없게 됩니다.

자동 생성된 메모리는 원래 위치에 그대로 남습니다. Windsurf 자체 가이드는 이에 대해 단호합니다. 자동 생성된 메모리는 "생성된 워크스페이스와 연결되며 ~/.codeium/windsurf/memories/에 로컬로 저장"되고, "리포지토리에 커밋되지 않으며", "자동 생성된 메모리는 오직 사용자의 컴퓨터에만 존재합니다." Windsurf의 권장 사항은 다른 곳으로 이동하기 전에 의존하는 모든 것을 규칙이나 AGENTS.md로 승격시키는 것입니다. Zed의 문서는 지침과 스킬을 에이전트 컨텍스트의 영속성 영역으로 설명하며, 자동 생성된 메모리 저장소는 설명하지 않으므로 Zed 측에는 이러한 파일이 들어갈 자리가 없습니다. 이에 의존해 왔다면 먼저 승격시키세요. 이 조언의 배경이 되는 워크스페이스 범위 동작은 stopping Windsurf's Cascade from losing context의 주제입니다.

소스 문서를 읽을 때 브랜드명에 대한 한 가지 참고 사항: Windsurf의 문서에는 이제 전반적으로 Devin Desktop 이름이 사용되고 있으며, 메모리 페이지는 여전히 Cascade를 현재 시제로 설명하고 "Devin: Open Cascade Migration Wizard" 명령을 가리키고 있습니다. 비록 Devin Desktop 변경 로그에서 2026년 9월 8일에 Cascade가 제거되었음에도 불구하고 말이죠. 해당 페이지를 따르고 있다면, 현재 빌드에는 더 이상 존재하지 않는 에이전트에 대해 설명하고 있을 것입니다. 이 전환의 규칙 폴더 부분은 merging Windsurf and Devin rule folders에서 별도로 다루었습니다. 이 가이드는 Windsurf 내부의 재구성이 아니라 Zed로 떠나는 것에 관한 것입니다.

1단계: 단 하나의 프로젝트 지침 파일을 선택하고 미끼 파일 제거하기

새로운 것을 작성하기 전에, Zed의 우선순위 목록에 나타나는 리포지토리 루트의 모든 파일을 나열해 보세요. Windsurf 사용 이력이 있는 리포지토리라면 최소한 .windsurfrules, 어쩌면 .rules, 이전 도구에서 남은 .cursorrules, 그리고 AGENTS.md가 있을 것입니다.

어떤 파일이 신뢰할 수 있는 기준(authoritative)인지 결정하세요. AGENTS.md가 합리적인 답입니다. 이 파일은 Windsurf도 처리하는 파일이고, 다른 도구들도 인식하는 파일이며, Zed 목록에서 일곱 번째에 위치하므로 그 위의 모든 파일은 제거되어야 합니다. 우선순위가 높은 파일들을 삭제하거나 이름을 바꾸세요. 이름을 바꾸는 것이 더 안전합니다. .windsurfrules를 docs/legacy-windsurf-rules.md로 이동하면 로더에는 보이지 않으면서 콘텐츠는 여전히 읽을 수 있습니다.

그런 다음 통합하세요. Windsurf는 각 12,000자 제한이 있는 규칙당 하나의 파일을 제공했지만, Zed는 총 하나의 파일만 제공합니다. .devin/rules/*.md 본문을 AGENTS.md로 병합하되, 각 규칙의 제목을 유지하여 여전히 구분할 수 있도록 하세요. Windsurf에서 규칙이 always_on이었다면 여기에 속합니다. 그렇지 않았다면 다음 단계를 위해 보류해 두세요.

단순히 읽어보는 것보다 모순을 통해 검증하세요. AGENTS.md에 평소에는 사용하지 않는 의도적으로 특이한 명명 규칙 같은 줄을 추가하고, 에이전트에게 이를 적용해 달라고 요청해 보세요. 에이전트가 이를 무시한다면 우선순위가 더 높은 파일이 여전히 적용되고 있는 것입니다. 이는 why agents ignore your instruction files에서 권장하는 것과 동일한 확인 방법이며, 트리 전체를 감사하는 것보다 빠릅니다.

2단계: 세 가지 조건부 모드를 스킬로 전환하고 카탈로그 용량 제한 주의하기

모든 always_on이 아니었던 것들은 스킬이 됩니다. Zed 자체의 마이그레이션 노트에서도 단종된 Rules 기능에 대해 다음과 같이 언급하고 있습니다. "재사용 가능한 온디맨드 Rules는 Skills가 되고, 기본 설정인 상시 적용 Rules는 개인용 AGENTS.md가 됩니다."

변환은 어떤 모드에서 시작했는지에 따라 다릅니다. manual 규칙은 깔끔하게 매핑됩니다. 스킬이 되며, @rule-name을 입력했던 것처럼 /skill-name 또는 @skill-name을 입력하여 호출할 수 있습니다. model_decision 규칙도 두 도구 모두 설명(description)을 보고 결정하므로 깔끔하게 매핑되며, 설명 텍스트를 그대로 재사용할 수 있습니다. 다시 작성해야 하는 것은 glob 규칙입니다. 패턴이 문장으로 바뀌어야 합니다. **/*.test.ts는 테스트 파일을 작성하거나 수정할 때 스킬이 적용된다는 설명으로 바뀌며, Zed의 가이드는 이를 어떻게 표현해야 하는지 명확히 안내합니다. "구체적인 작업 유형과 트리거 문구를 포함하세요."

Zed 측의 세 가지 제약 조건은 Windsurf에 이에 상응하는 것이 없으며, 세 가지 모두 경고 없이 조용히 실패합니다.

카탈로그에는 용량 제한이 있습니다. "모든 스킬 이름과 설명의 총 크기는 50KB로 제한됩니다. 용량을 초과하는 스킬은 UI에 경고가 표시되며 카탈로그에서 제외됩니다." 설명은 "1024바이트 미만"으로 유지되어야 합니다. 장황한 Windsurf 규칙 설명을 수십 개씩 포팅하는 팀은 이 제한을 초과할 수 있습니다.

구조는 단일 수준(flat)이어야 합니다. "스킬은 스킬 루트의 직속 하위 항목이어야 합니다. ~/.agents/skills/group/my-skill/과 같은 중첩된 폴더는 검색되지 않습니다." Windsurf 스킬을 하위 폴더로 정리했다면 단일 수준으로 평탄화하세요.

그리고 프로젝트 로컬 스킬은 신뢰가 필요합니다. "프로젝트 로컬 스킬은 신뢰할 수 있는 작업 트리(worktree)에서만 로드됩니다. 새로 복제되었거나 신뢰할 수 없는 프로젝트의 스킬은 신뢰를 부여할 때까지 카탈로그 및 슬래시 명령에서 제외됩니다." 새로 복제한 경우 신뢰를 부여하기 전까지는 프로젝트 스킬이 단순히 존재하지 않게 됩니다. 이는 합리적인 보안 기본값이지만 처음 한 시간 동안은 혼란스러울 수 있습니다.

알아두면 좋을 두 가지 작은 차이점이 있습니다. Zed는 글로벌 우선 습관이 예상하는 것과 반대 방향으로 이름 충돌을 해결합니다. "글로벌 스킬과 프로젝트 로컬 스킬의 이름이 같으면 프로젝트 로컬 스킬이 우선합니다." 그리고 프로젝트 지침이 개인 지침보다 우선합니다. "프로젝트 지침과 개인 AGENTS.md가 충돌할 경우 프로젝트 지침이 우선합니다." 이는 개인 설정을 가장 높게 평가하는 도구들과는 반대입니다.

위의 마이그레이션은 파일을 이동할 뿐입니다. 이는 근본적인 문제를 해결하지 못하는데, 그 규칙들 뒤에 숨겨진 의사결정 배경(reasoning)이 처음부터 파일에 없었기 때문입니다.

작성하신 AGENTS.md에는 특정 HTTP 클라이언트를 사용하라고 되어 있을 것입니다. 하지만 아무도 원치 않는 재시도 동작 때문에 다른 클라이언트를 시도했다가 포기했다는 사실은 적혀 있지 않습니다. 통합 과정에서 규칙이 누락되면(12개의 파일을 하나로 통합하다 보면 일부 누락이 발생할 수밖에 없습니다), 규칙은 그것이 존재했던 이유와 함께 사라지고, 다음 엔지니어는 처음부터 다시 논쟁을 벌이게 됩니다.

MemoryLake는 이 두 번째 범주, 즉 결정 사항, 거부된 대안, 어떤 에디터가 열려 있든 상관없이 유효한 제약 조건을 보관합니다. 두 도구 모두의 외부에 존재하므로, 이와 같은 마이그레이션 시 설정은 이동하면서도 의사결정 배경은 그대로 유지할 수 있습니다. 여기서 시작하세요.

1단계: API 키 생성하기

프로젝트를 위한 워크스페이스를 생성하고 API 키를 생성합니다. 에디터가 아닌 프로젝트로 범위를 지정하여, 이번 도구 변경뿐만 아니라 다음 도구 변경 시에도 이 레이어가 유지되도록 하세요.

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

통합한 후가 아니라 통합하기 전에 이 작업을 수행하세요. .devin/rules/*.md 파일을 하나씩 살펴보며 각 규칙이 존재하는 이유를 기록하세요. AGENTS.md로 들어갈 규칙 자체가 아니라 그 뒤에 숨겨진 결정 배경을 기록하는 것입니다. 실제로 의존하고 있는 Windsurf 자동 메모리가 캡처한 내용도 추가하세요. 해당 파일들은 단 한 대의 컴퓨터에만 존재하며 어디에도 커밋되지 않습니다.

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

Zed의 에이전트를 연결하고, 전환 기간 동안 두 에디터를 모두 사용한다면 Windsurf도 연결하세요. 둘 다 동일한 결정 세트를 읽으므로, 아직 포팅하지 않은 규칙이라도 이미 전환한 에디터에서 그 의사결정 배경을 계속 사용할 수 있습니다.

조용한 오버라이드 문제가 단번에 명확해집니다. 우선순위 목록을 확인하고 미끼 파일을 제거하면 끝납니다. 3개월 후에 오래된 .windsurfrules가 모든 세션을 조용히 지배하고 있었다는 사실을 발견하는 대신 말이죠.

통합 과정에서 정보 손실이 발생하지 않습니다. 의사결정 배경이 다른 곳에 보관되어 있다면, 12개의 규칙 파일이 규칙당 하나의 섹션으로 구성된 하나의 AGENTS.md로 축소되어도 괜찮습니다. 하지만 파일이 유일한 기록이었다면 이는 진짜 손실입니다. 그리고 이는 깔끔한 전환과 Zed forgetting your project context에서 설명한 패턴(에디터는 올바르게 설정되었지만 지식 자체가 존재하지 않는 상황)의 차이입니다.

전환 기간 동안 두 에디터를 모두 실행해도 불일치(drift)가 발생하지 않습니다. 팀이 단 하루 오후 만에 전환하는 경우는 드뭅니다. 누군가는 한 스프린트 동안 Windsurf에 머물 수 있습니다. 하나의 공유 레이어를 사용하면, 지침 파일이 다르더라도 팀의 양쪽 모두 동일한 결정 세트를 바탕으로 작업할 수 있습니다.

테스트한 리포지토리뿐만 아니라 모든 리포지토리에서 우선순위 목록을 감사하세요. .cursorrules 및 .clinerules도 AGENTS.md보다 우선순위가 높으며, 세 가지 도구를 거친 모노레포에는 이 모든 파일이 포함되어 있을 수 있습니다.

스킬 설명은 요약이 아니라 트리거 조건으로 작성하세요. Zed의 가이드에 따르면 "PDF를 처리하거나, 텍스트를 추출하거나, 양식을 채울 때 사용"이 "PDF 처리를 도움"보다 낫습니다. 이제 설명이 이전의 glob 패턴이 하던 역할을 대신하므로, 이는 각 스킬에서 가장 영향력 있는 문장입니다.

의도적으로 카탈로그를 가볍게 유지하세요. 모든 설명이 동일한 50KB 용량을 두고 경쟁하며, 제외된 스킬은 UI에 경고로만 표시됩니다. 포괄적인 스킬보다 개수가 적고 명확한 스킬이 더 낫습니다.

Zed의 로더가 다른 에이전트를 제어하지 않는다는 점을 기억하세요. 지침 페이지에 다음과 같이 직접 명시되어 있습니다. "외부 에이전트 및 터미널 스레드는 자체 네이티브 지침 파일을 직접 읽을 수 있습니다. Zed의 지침 로더가 해당 에이전트들을 제어한다고 가정하지 마십시오." Zed를 통해 Claude나 Codex를 외부 에이전트로 실행하는 경우, 이들은 자체 파일을 읽습니다. 이는 giving Zed's external agents the context they don't inherit에서 정리한 경계입니다.

스킬 편집 시 캐시 세부 사항을 예상하세요. "스킬의 name 또는 description을 변경하면 현재 세션에 대한 모델의 프롬프트 캐시가 무효화됩니다." 세션 중간에 본문은 자유롭게 편집하되, 설명 재작성은 모아서 한 번에 처리하세요.

Windsurf와 Zed는 대부분의 도구 쌍보다 더 많은 부분에서 일치합니다. 스킬 경로, 스킬 형식, 점진적 공개 모델을 공유하므로, 이번 마이그레이션에서 스킬 부분은 거의 비용이 들지 않습니다.

하지만 사람들에게 며칠의 시간을 허비하게 만드는 한 가지 사항에서 의견이 다릅니다. Windsurf는 여러 규칙 파일을 발견하고 파일별로 주입 여부를 결정하는 반면, Zed는 고정된 9개 항목 목록에서 첫 번째로 일치하는 파일만 읽습니다. 이 가이드에서 단 하나의 행동만 취해야 한다면, 리포지토리 루트에서 AGENTS.md보다 우선순위가 높은 모든 파일을 제거하는 것으로 하세요. 그리고 두 번째 행동을 취한다면, 12개의 파일을 하나로 병합하기 전에 규칙이 왜 존재하는지 기록해 두는 것으로 하세요.