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

규칙 내용은 그대로 이전됩니다. 두 도구 모두 일반 Markdown 지침을 가져와 모델에 제공합니다. Cursor는 이 메커니즘을 명확하게 설명합니다. "대형 언어 모델은 완료(completion) 간에 메모리를 유지하지 않습니다. 규칙은 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공합니다." 또한 "규칙이 적용되면 규칙 내용이 모델 컨텍스트의 시작 부분에 포함됩니다." opencode의 프레임워크도 거의 동일합니다. AGENTS.md는 "특정 프로젝트에 맞게 동작을 맞춤화하기 위해 LLM의 컨텍스트에 포함될 지침"을 담고 있으며, 문서에서도 이 개념이 "Cursor의 규칙과 유사하다"고 명시하고 있습니다.

루트의 AGENTS.md는 별도의 작업 없이 이전됩니다. Cursor가 .cursor/rules의 "간단한 대안"으로 제시한 AGENTS.md 옵션을 이미 사용하고 있었다면, opencode가 이를 직접 읽습니다. opencode의 프로젝트 루트 규칙은 "이 디렉토리 또는 하위 디렉토리에서 작업할 때만 적용"됩니다.

glob 패턴만 올바르게 설정하면 .mdc 규칙 파일이 파일 형태로 그대로 이전됩니다. opencode의 instructions 배열은 파일 경로와 glob 패턴을 허용하므로, 파일들을 .cursor/rules/ 내의 원래 위치에 그대로 둘 수 있습니다. 파일을 이동하는 것이 아니라 가리키기만 하면 됩니다. 이는 규칙을 새로 작성하는 것보다 훨씬 편리하며, 모든 것을 하나의 파일로 병합하는 대신 이 방식으로 마이그레이션을 진행해야 하는 이유이기도 합니다.

Frontmatter는 이전되지 않습니다. 이것이 가장 뼈아픈 손실입니다. Cursor의 네 가지 규칙 유형은 Always Apply, Apply Intelligently("설명을 기반으로 Agent가 관련이 있다고 판단할 때"), Apply to Specific Files("파일이 지정된 패턴과 일치할 때"), Apply Manually("채팅에서 @로 언급될 때")입니다. 이는 세 가지 frontmatter 필드의 상호작용으로 결정됩니다. alwaysApply: false이고 globs가 제공되면 규칙은 "일치하는 파일이 컨텍스트에 있을 때 자동 첨부"되며, alwaysApply: false이고 description이 있지만 globs가 없으면 "Agent가 설명을 읽고 관련이 있을 때 규칙을 가져옵니다." 둘 다 없으면 "채팅에서 규칙을 @로 언급할 때만 포함"됩니다.

opencode에는 이에 대응하는 문서화된 기능이 없습니다. opencode 문서에는 "모든 지침 파일이 AGENTS.md 파일과 결합된다"고 명시되어 있습니다. 이전에는 src/components/**를 수정할 때만 나타나던 규칙이 이제는 모든 요청에 나타나며, 거의 사용되지 않는 마이그레이션 체크리스트라 수동으로 설정해 두었던 규칙도 마찬가지로 매번 포함됩니다. 에러가 발생하며 멈추지는 않지만, 프롬프트가 훨씬 커지고 집중도가 떨어지게 됩니다. 이는 에이전트가 지침 파일을 무시하는 이유에서 설명한 실패 패턴과 일치합니다.

규칙 내부의 @file 참조는 이전되지 않습니다. Cursor 규칙은 인라인으로 다른 파일을 참조할 수 있습니다. 예를 들어 @migration-template.sql로 끝나는 규칙은 해당 템플릿을 불러옵니다. opencode의 문서는 단호합니다. "opencode는 AGENTS.md의 파일 참조를 자동으로 파싱하지 않습니다." 지원되는 두 가지 해결 방법은 참조된 파일을 instructions에 직접 나열하거나, 에이전트에게 해당 파일을 읽으라고 명시적인 텍스트로 지시하는 것입니다.

Team Rules는 이전되지 않습니다. Cursor의 Team Rules는 Team 및 Enterprise 플랜의 Cursor 대시보드에서 관리되며, 다른 규칙 유형보다 "우선순위"를 가집니다. 또한 "Customize에서 비활성화할 수 없음"으로 표시할 수 있습니다. 이는 파일이 아니라 조직 차원의 제어 영역입니다. 이러한 규칙들이 담고 있는 내용은 커밋된 파일로 다시 표현되어야 하며, 이는 더 이상 동일한 방식으로 강제할 수 없음을 의미합니다.

Cursor에는 있고 opencode에는 없는 것, 그리고 그 반대. Cursor의 문서화된 지속성 메커니즘은 네 가지 형태의 규칙입니다. Cursor 문서 인덱스를 검색해도 스스로 기록하는 메모리 저장소에 대한 내용은 나오지 않으므로, 이에 대응하는 문서화된 기능은 없다고 보는 것이 정확합니다. opencode의 문서화된 메커니즘은 AGENTS.md 파일, instructions 배열, 그리고 /init 명령입니다. 두 도구 모두 작업하면서 학습한 내용을 누적하는 저장소에 대해서는 문서화하고 있지 않으며, 이것이 바로 이 가이드가 계속해서 강조하는 세 번째 범주입니다.

1단계: glob 패턴을 수정하고 그 위에 /init 실행하기

프로젝트의 opencode.json에 있는 instructions 배열부터 시작하세요. 문서화된 예제는 .md를 사용하지만, 여러분의 규칙은 .mdc이며 Cursor는 .cursor/rules/frontend/components.mdc와 같은 하위 디렉토리를 지원합니다. 따라서 중첩된 규칙 폴더까지 감지할 수 있는 .cursor/rules/**/*.mdc 패턴을 사용하는 것이 좋습니다. Cursor는 무시했지만 opencode가 읽기를 원하는 일반 Markdown 문서가 해당 디렉토리에 있다면 목록에 .md도 남겨두세요. Cursor는 이러한 파일을 제외하지만 opencode는 제외하지 않으므로, 흔치 않지만 실제로 유용한 케이스입니다.

기존 Cursor 규칙에서 @로 참조하던 파일들을 추가하세요. 마이그레이션 후에는 이러한 참조가 더 이상 추적되지 않기 때문입니다. 만약 @migration-template.sql을 가리키는 규칙이 있었다면, 해당 템플릿을 instructions에 포함하거나 텍스트로 명시해야 합니다.

그 다음 /init을 실행하세요. 이 단계는 사람들이 자주 건너뛰지만 가장 가치 있는 단계입니다. opencode의 /init은 "저장소의 중요한 파일을 스캔하고, 코드베이스만으로 답을 얻을 수 없을 때 몇 가지 구체적인 질문을 던진 후, 프로젝트에 특화된 간결한 가이드라인으로 AGENTS.md를 생성하거나 업데이트"하며, "Cursor 또는 Copilot 규칙과 같은 기존 지침 소스에 대한 참조"를 명시적으로 고려합니다. 중요한 점은 이 작업이 파괴적이지 않다는 것입니다. "이미 AGENTS.md가 있는 경우, /init은 이를 무작정 덮어쓰는 대신 그 자리에서 개선합니다." instructions를 연결한 후 이를 실행하면, 도구가 처음부터 다시 만드는 대신 기존에 가지고 있는 설정을 파악할 수 있습니다.

파일을 생성하기 전에 알아두어야 할 우선순위 규칙이 있습니다. opencode는 "현재 디렉토리에서 상위 디렉토리로 이동하며 로컬 파일(AGENTS.md, CLAUDE.md)을 찾고", ~/.config/opencode/AGENTS.md에서 글로벌 파일을 찾습니다. 그리고 "각 카테고리에서 가장 먼저 일치하는 파일이 적용됩니다. 예를 들어 AGENTS.md와 CLAUDE.md가 모두 있는 경우 AGENTS.md만 사용됩니다." 저장소가 CLAUDE.md를 기반으로 작동하고 있었다면, AGENTS.md를 생성하는 순간 CLAUDE.md는 비활성화됩니다. 글로벌 설정도 동일한 패턴이 적용되어 ~/.config/opencode/AGENTS.md가 ~/.claude/CLAUDE.md보다 우선합니다.

2단계: 각 무조건부 규칙의 비용 결정하기

이제 방금 지정한 .mdc 파일들을 훑어보며 frontmatter만 읽어보세요. 그리고 세 가지 그룹으로 분류합니다.

alwaysApply: true가 설정된 규칙은 추가 비용이 들지 않습니다. Cursor에서도 무조건 적용되었고 opencode에서도 무조건 적용되므로 따로 조치할 필요가 없습니다.

globs가 설정된 규칙은 특정 파일 유형이나 디렉토리로 범위가 제한되어 있었습니다. 하지만 opencode에서는 이제 항상 활성화됩니다. 5줄짜리 TypeScript 컨벤션처럼 짧은 규칙이라면 항상 켜두어도 괜찮으며, 하나로 합치는 것이 올바른 선택입니다. 하지만 긴 규칙의 경우 두 가지 실질적인 옵션이 있습니다. 모든 요청마다 비용을 지불할 가치가 있는 부분만 남기고 축소하거나, instructions에서 제외하고 해당 영역에서 작업할 때만 의도적으로 로드하는 것입니다. 조건부 적용을 유지할 수 있는 세 번째 방법은 없으며, 그렇지 않은 척 방치하는 것이 지침 파일의 크기가 소리 없이 세 배로 늘어나는 원인이 됩니다.

description이 있고 globs가 없는 규칙은 가장 흥미로운 그룹입니다. Cursor는 이 설명을 검색 신호로 사용했기 때문입니다("Agent가 설명을 읽고 관련이 있을 때 규칙을 가져옴"). 이 메커니즘은 opencode에 존재하지 않습니다. 여러분이 보존할 수 있는 것은 의도입니다. 결합된 프롬프트를 훑어보는 사람이 용도를 파악할 수 있도록 설명 텍스트를 규칙의 첫 줄로 유지하고, 이 규칙이 정말 '규칙'인지 아니면 '학습된 사실'인지 고민해 보세요. 후자인 경우가 아주 많으며, 이는 instructions가 아니라 다음 섹션에 속해야 함을 의미합니다.

두 필드가 모두 없는 규칙은 수동으로 @ 언급을 통해서만 사용되던 규칙입니다. 대개 체크리스트나 템플릿이 이에 해당합니다. 이 규칙들은 instructions에서 완전히 제외하고, 필요할 때 경로로 참조하세요. opencode 문서에서도 외부 파일에 대해 정확히 이 패턴을 권장합니다. 처음부터 로드하는 대신 특정 조건이 충족될 때 에이전트가 파일을 읽도록 유도하는 것입니다.

이 작업을 수행하는 동안 Cursor의 모범 사례 권장 사항을 적용하는 것이 좋습니다. "규칙을 500줄 미만으로 유지할 것", "큰 규칙은 조합 가능한 여러 개의 규칙으로 분할할 것", "콘텐츠를 복사하는 대신 파일을 참조할 것 — 이를 통해 규칙을 짧게 유지하고 코드가 변경됨에 따라 규칙이 낡아지는 것을 방지할 것"입니다. opencode에는 과도한 정보를 흡수해 줄 조건부 레이어가 없기 때문에 이 세 가지 모두 Cursor에서보다 opencode에서 훨씬 더 중요합니다. 조건부 적용을 전혀 잃고 싶지 않다면, 스코핑 방식이 다르게 작동하는 대상을 다룬 Cursor 규칙을 Codex로 마이그레이션하기나 Cursor에서 Claude Code로 마이그레이션하기를 참고하세요.

frontmatter 그룹을 분류하다 보면 다소 불편한 사실을 마주하게 됩니다. .cursor/rules 콘텐츠의 상당 부분이 규칙이 아니라 '이력(history)'이라는 점입니다. "조정 작업에는 배치 엔드포인트를 사용하지 마세요. 10,000행이 넘어가면 타임아웃이 발생합니다." "인증 토큰은 1분기까지 레거시 서비스에서 발급하므로 여기에 스코프를 추가하지 마세요." 이것들은 누군가 겪어가며 배운 사실들이며, 도구가 제공하는 유일한 영구 보관 장소에 기록해 둔 것입니다.

두 도구 모두에서 규칙은 이러한 정보를 담기에 적절한 그릇이 아닙니다. Cursor 스스로도 규칙은 매번 다시 전송되는 "프롬프트 수준의 지속적이고 재사용 가능한 컨텍스트"라고 말합니다. 지난 7월에 알게 된 사실은 프롬프트 수준의 설정이 아닙니다. 그것은 지식이며, 한계 없이 축소되거나 확장되며, 작성되는 것이 아니라 발견되는 것입니다.

MemoryLake는 바로 그 절반의 정보가 가야 할 곳입니다. 이는 두 도구의 외부에 위치하며, 팀이 일하는 방식이 아니라 팀이 확립한 지식을 보관하고, 현재 사용 중인 클라이언트가 무엇이든 MCP나 API를 통해 읽을 수 있습니다. 이 마이그레이션에서 얻을 수 있는 실질적인 효과는 instructions 배열을 충분히 짧게 유지하여 조건부 적용 기능의 상실이 타격을 주지 않도록 하는 것입니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 보내보세요. 하나의 키로 모든 환경을 커버할 수 있으며, 이것이 바로 핵심입니다. 지식은 특정 에디터에 종속되어서는 안 됩니다.

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

프로젝트의 기정의된 결정사항을 담고 있는 문서, 이미지, 파일과 함께, 방금 컨벤션이 아닌 이력으로 분류한 규칙 파일들을 업로드하세요. 매번 다시 설명하기 지겨웠던 내용부터 시작하는 것이 좋습니다.

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

Claude, Codex, OpenClaw 및 기타 에이전트에 MCP 또는 API를 통해 액세스 권한을 부여하세요. opencode 세션에서 이는 확립된 사실들이 결합된 지침 프롬프트를 영구적으로 차지하는 대신 필요할 때만 검색됨을 의미합니다.

instructions 배열이 작게 유지되므로 조건부 적용 기능이 없어도 충분히 감당할 수 있습니다. Cursor의 조건부 레이어가 존재했던 이유는 규칙 디렉토리가 계속 커지기 때문이었습니다. 그 성장이 다른 곳으로 분산된다면 단순한 배열 구조로도 충분히 훌륭하게 작동합니다.

Team Rules가 더 이상 마이그레이션의 걸림돌이 되지 않습니다. Cursor 대시보드에 있던 조직 콘텐츠가 깔끔하게 분리됩니다. 강제해야 하는 컨벤션은 커밋된 파일이 되고, 확립된 결정사항은 도구나 플랜 등급에 관계없이 모든 팀원의 에이전트가 읽을 수 있는 메모리가 됩니다.

도구를 다시 전환하는 비용이 저렴해집니다. opencode의 instructions 배열과 Cursor의 .mdc frontmatter는 모두 특정 도구에 종속된 포맷입니다. 반면 MCP를 통해 접근 가능한 저장소는 그렇지 않으므로, 다음 전환 시에는 지식 감사를 할 필요 없이 설정만 변경하면 됩니다.

그리고 사람들이 규칙을 작성하게 만드는 특유의 짜증 나는 상황 — 같은 실수를 두 번 지적받거나, 에이전트에게 저장소 내 파일 구조를 다시 가르쳐야 하는 상황 — 이 올바른 레이어에서 해결됩니다. 이는 결코 규칙의 문제가 아니었습니다. 프롬프트로 해결하려 했던 메모리의 문제였습니다.

Verify the glob matched something. instructions를 연결한 후, opencode에 로드된 가이드를 요약해 달라고 요청해 보세요. Cursor 규칙이 누락되었다면 확장자를 가장 먼저 확인해야 합니다.

Run /init after wiring, not before. 이는 기존 AGENTS.md를 그 자리에서 개선하므로, 실제 설정을 파악할 수 있도록 하세요.

Keep one instruction home per directory. 동일한 위치에서 AGENTS.md는 CLAUDE.md를 무력화하므로, 사용하지 않는 파일은 삭제하여 혼선을 방지하세요.

Be careful with remote instruction URLs. opencode는 URL에서 지침을 로드할 수 있으며, "원격 지침은 5초의 타임아웃으로 가져옵니다." 이는 공유 팀 규칙 파일을 가능하게 하지만, 세션이 호스트의 가동 상태에 의존하게 만듭니다.

Do not recreate @ references by pasting content. 파일을 instructions에 추가하거나 텍스트로 명시하세요. 붙여넣기는 복사본이 낡아지기 때문에 Cursor 자체 가이드에서도 경고하는 방식입니다.

Move history out before you flatten. 조건부 규칙을 병합하는 것은 규칙이 실제로 '컨벤션'일 때만 안전합니다. 무용담처럼 읽히는 모든 내용은 메모리 레이어로 가야 합니다.

이 마이그레이션에 대해 솔직히 요약하자면, opencode의 instructions 배열은 이미 작성한 규칙 파일을 재사용할 수 있어 새로 작성하는 것보다 훨씬 낫다는 점에서 정말 좋은 아이디어입니다. 하지만 공개된 예제에서 경고하지 않는 두 가지 문서상의 공백이 있습니다. 하나는 알고 나면 사소한 것입니다. Cursor는 .cursor/rules 내의 일반 Markdown을 무시하므로 규칙이 모두 .mdc여야 하며, 따라서 glob 패턴은 .md가 아니라 .mdc여야 합니다. 다른 하나는 구조적인 문제입니다. instructions는 제공된 모든 것을 결합하므로, Cursor의 Always / Intelligently / By-File / Manual 구분이 모두 '항상 활성화(always-on)'로 축소됩니다.

두 가지 모두 관리 가능하며, 특히 두 번째 문제는 규칙 디렉토리를 채우고 있던 내용의 상당수가 애초에 규칙이 아니었어야 했기 때문에 해결하기 쉽습니다. glob 패턴을 올바르게 지정하고, 그 위에 /init을 실행하고, frontmatter를 비용이 들지 않는 것, 비용이 드는 것, 필요할 때만 쓰는 것으로 분류한 다음, 누적된 이력을 두 도구 모두 소유할 필요가 없는 레이어로 이동시키세요. 남는 것은 이 저장소에서 일하는 방법을 설명하는 짧은 지침 파일뿐이며, 이는 규칙 시스템이 원래 가장 잘하는 역할이기도 합니다.