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

먼저, 어떤 OpenCode로 이동할지 확인하세요

OpenCode의 마이그레이션 가이드에 따르면 "OpenCode 1과 OpenCode 2는 모두 opencode 명령어를 사용하며, 더 이상 기본적으로 병렬 설치되지 않습니다." 두 버전은 동일한 설정 위치를 읽으며, 가이드에서는 지원되는 V1 동작이 "V1과의 호환성을 유지하도록 의도되었습니다"라고 설명합니다. 하지만 Claude Code 파일에 대해서는 두 버전이 다르게 동작하므로, 아래 내용을 신뢰하기 전에 현재 실행 중인 버전을 확인하세요.

지침: CLAUDE.md

V1의 경우, CLAUDE.md가 폴백으로 작동합니다. OpenCode는 프로젝트에 AGENTS.md가 없으면 프로젝트의 CLAUDE.md를 읽고, 글로벌 OpenCode AGENTS.md가 없으면 ~/.claude/CLAUDE.md를 읽습니다. 규칙은 "각 카테고리에서 가장 먼저 일치하는 파일이 우선권을 가집니다"입니다. 따라서 프로젝트에 AGENTS.md를 추가하면 해당 프로젝트의 CLAUDE.md는 비활성화됩니다.

또한 V1은 이 호환성을 제어할 수 있는 스위치를 제공합니다. "Claude Code 호환성을 비활성화하려면 다음 환경 변수 중 하나를 설정하세요." OPENCODE_DISABLE_CLAUDE_CODE는 모든 .claude 지원을 끄고, OPENCODE_DISABLE_CLAUDE_CODE_PROMPT와 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS는 각각 글로벌 CLAUDE.md와 스킬을 개별적으로 끕니다.

V2의 경우, 폴백이 없습니다. V2는 글로벌 AGENTS.md를 로드한 다음 "현재 작업 공간 디렉터리부터 홈 디렉터리 방향으로 있는 모든 AGENTS.md"를 로드하며, 프로젝트 더 깊은 곳에 있는 파일들은 에이전트가 해당 영역을 읽을 때 로드됩니다. 또한 하나를 선택하는 대신 파일들을 누적하여 적용합니다: "OpenCode는 파일들을 결합하며, 파일 간의 충돌을 해결하지 않습니다."

V2 마이그레이션 가이드는 Claude Code 사용자들에게 직접적으로 다음과 같이 안내합니다: "V1 설정이 CLAUDE.md 폴백에 의존했다면, 해당 지침을 해당하는 AGENTS.md로 이동하세요." 또한 "V2는 현재 AGENTS.md만 감지합니다"라고 덧붙이며, V1 동작과의 호환성을 유지하기 위해 "영향을 받는 프로젝트 세부 정보와 함께 호환성 이슈를 제보해 달라"고 요청합니다. '현재'라는 단어가 중요합니다. 이는 향후 변경될 수 있지만, 지금으로서는 V2가 스스로 CLAUDE.md를 로드하지 않습니다.

두 버전 모두에서 가장 안전한 방법은 동일합니다. 지침을 AGENTS.md에 작성하는 것입니다. Claude Code의 AGENTS.md 기본값에 대한 가이드에서 설명하듯이 Claude Code도 이 파일을 읽을 수 있으므로, 하나의 파일로 두 도구를 모두 지원할 수 있습니다.

임포트 및 경로 범위 규칙

Claude Code의 CLAUDE.md는 다른 파일을 가져올 수 있습니다. "가져온 파일은 실행 시 이를 참조하는 CLAUDE.md와 함께 확장되어 컨텍스트에 로드됩니다." 만약 여러분의 CLAUDE.md가 주로 @docs/... 라인의 목록으로 구성되어 있다면, 대부분의 지침은 해당 다른 파일들에 있는 것입니다.

OpenCode V1 규칙 문서에 따르면 "opencode가 AGENTS.md의 파일 참조를 자동으로 파싱하지는 않지만, 두 가지 방법으로 유사한 기능을 구현할 수 있습니다"라고 합니다. 권장하는 방법은 opencode.json 내의 instructions 필드를 사용하는 것입니다. V2에서도 이 방식이 유지됩니다: "감지된 AGENTS.md 파일과 함께 파일, glob 패턴 또는 HTTP(S) URL을 추가하려면 instructions 배열을 사용하세요." 여기에 원격 URL을 나열하는 경우, 가져오기(fetch)가 느려질 때 발생하는 상황은 OpenCode 원격 지침 파일 미러링 가이드에서 다룹니다.

Claude Code는 규칙을 특정 파일에만 제한하는 paths: 프런트매터(frontmatter)가 포함된 .claude/rules/ 내의 규칙도 지원합니다. OpenCode의 지침 문서에는 AGENTS.md 파일과 instructions 배열만 설명되어 있으며, .claude/rules/는 나열된 위치에 포함되어 있지 않습니다. 가장 유사한 OpenCode 패턴은 해당 규칙이 적용되는 디렉터리에 중첩된 AGENTS.md를 두는 것입니다. V2에서 중첩된 파일은 에이전트가 프로젝트의 해당 부분을 읽을 때 "가장 가까운 것부터 우선 로드(nearest-first)"됩니다.

스킬

스킬은 가장 쉽게 이동할 수 있는 부분입니다. 두 버전 모두 Claude Code의 스킬 폴더를 읽습니다. V2는 OpenCode 자체의 .opencode/skills와 함께 ~/.claude/skills를 글로벌 호환성 소스로, .claude/skills를 프로젝트 호환성 소스로 목록에 올렸습니다.

V2는 Claude Code 필드 중 하나도 이해합니다. 해당 테이블에는 disable-model-invocation이 나열되어 있으며, "opencode/autoinvoke: false와 동일한 효과를 내려면 true로 설정하세요"라는 설명이 붙어 있습니다. 오픈 스킬 표준의 필드들도 허용되지만, "V2는 license 및 compatibility와 같은 이식성 필드를 수락하지만 해석하지는 않습니다."

V2의 스킬 문서에 나열된 필드는 name, description, metadata.opencode/autoinvoke, disable-model-invocation입니다. context, paths, hooks, model과 같은 Claude Code의 다른 스킬 필드는 포함되어 있지 않으므로, 이러한 필드에 의존하는 스킬은 재작성해야 합니다. 알아두어야 할 차이점이 하나 더 있습니다. V2에서는 "파일 경로가 스킬 ID를 결정합니다. 프런트매터의 name은 표시용 레이블일 뿐입니다."

서브에이전트 및 명령어

Claude Code 서브에이전트는 ~/.claude/agents/ 또는 프로젝트의 .claude/agents/에 위치합니다. OpenCode의 에이전트 파일은 ~/.config/opencode/agents/<name>.md 또는 .opencode/agents/<name>.md에 위치하며, 프런트매터는 OpenCode 자체 규격을 사용하여 mode: subagent 설정과 권한 목록을 포함합니다. OpenCode에서 "마크다운 본문이 에이전트의 시스템 프롬프트가 되기" 때문에 마크다운 본문은 깔끔하게 그대로 유지됩니다.

커스텀 명령어 역시 동일한 패턴을 따릅니다. Claude Code의 .claude/commands/ 파일은 .opencode/commands/<name>.md가 되며, 글로벌 명령어의 경우 ~/.config/opencode/commands/가 됩니다. OpenCode 명령어도 $ARGUMENTS를 사용하며, "마크다운(.md) 파일만 감지됩니다"라는 점에 유의하세요.

서브에이전트를 많이 사용하는 경우, 각 서브에이전트가 무엇을 보는지 다루는 Claude Code 서브에이전트가 메모리를 공유하지 않는 문제에 대한 가이드를 참고하여 이동 후 다시 확인해 보는 것이 좋습니다.

남겨지는 항목

자동 메모리(Auto memory). Claude Code는 스스로 노트를 작성합니다: "자동 메모리를 통해 Claude는 사용자가 아무것도 작성하지 않아도 세션 전반에 걸쳐 지식을 축적할 수 있습니다." 이 정보는 사용자의 컴퓨터에 저장되며, "각 프로젝트는 ~/.claude/projects/<project>/memory/에 자체 메모리 디렉터리를 가집니다." OpenCode 문서에는 이 디렉터리를 읽는다는 설명이 없습니다. 사용자의 수정 사항, 선호도, 프로젝트 사실 등 Claude가 그곳에서 학습한 모든 내용은 수동으로 이동하지 않는 한 Claude Code에 그대로 남게 됩니다. Claude Code에서 Cursor로 마이그레이션하는 가이드에서도 다른 도구로 전환할 때 발생하는 동일한 공백을 다루고 있습니다.

세션. OpenCode V1 CLI는 세션 데이터를 JSON으로 내보내고 가져올 수 있지만, 이 명령어들은 OpenCode 자체 세션에만 해당합니다. Claude Code 대화는 Claude Code에 그대로 남습니다. 이를 보존하는 방법은 Claude Code 세션을 다른 기기로 내보내는 가이드에서 다룹니다.

훅(Hooks) 및 플러그인. Claude Code 훅은 설정 내에 존재합니다. 반면 OpenCode는 플러그인을 통해 기능을 확장하며, V2 가이드에서는 "V1 플러그인 구현은 V2에서 실행되지 않습니다"라고 경고합니다. 훅은 복사할 대상이 아니라 새로 구축해야 할 대상으로 취급하세요.

MCP 서버. 이들은 설정으로 이동합니다. OpenCode는 이를 opencode.json에 정의하며, V2는 servers 키 아래에 그룹화합니다. 각 서버를 다시 연결하고 필요한 경우 다시 로그인하세요.

1단계: 두 버전의 OpenCode가 모두 읽을 수 있는 단일 AGENTS.md 구축

먼저 이 프로젝트에서 Claude의 작동 방식을 결정하는 모든 요소를 수집하는 것부터 시작하세요:

• 프로젝트 루트, .claude/CLAUDE.md, 하위 디렉터리 및 ~/.claude/CLAUDE.md에 있는 여러분의 CLAUDE.md 파일들.
• @ 기호로 가져오는 모든 임포트 파일들.
• paths:를 사용하는 파일이 무엇인지 유의하며 여러분의 .claude/rules/ 파일들 확인.
• 여러분의 자동 메모리. ~/.claude/projects/<project>/memory/를 열고 MEMORY.md 및 이 파일이 가리키는 주제 파일들을 읽어보세요.

그런 다음 결과를 AGENTS.md에 작성합니다:

• 프로젝트 전반의 지침은 루트 AGENTS.md에 작성합니다. 가져온 파일의 내용을 직접 복사해 넣거나, 붙여넣지 않고 로드되도록 opencode.json의 instructions 배열에 나열하세요.
• 경로 범위 규칙은 해당 규칙이 적용되는 디렉터리의 AGENTS.md에 작성합니다.
• 자동 메모리 노트를 정리합니다. 여전히 유효한 수정 사항과 프로젝트 사실은 지침으로 변환합니다. 여러 프로젝트에 걸쳐 적용되는 개인 선호도는 ~/.config/opencode/AGENTS.md로 보냅니다. 오래된 내용은 남겨둡니다.
• ~/.claude/CLAUDE.md에 있던 글로벌 지침은 ~/.config/opencode/AGENTS.md로 이동합니다.

동일한 리포지토리에서 Claude Code를 계속 사용할 예정이라면, CLAUDE.md를 Claude가 AGENTS.md를 가리키도록 하는 짧은 파일로 유지하여 두 도구 모두 하나의 지침 세트를 읽도록 하세요. CLAUDE.md를 AGENTS.md로 마이그레이션하는 가이드에서 이 패턴을 다룹니다.

V2는 발견된 모든 AGENTS.md를 충돌 해결 없이 결합하므로, 작업이 끝나면 파일들을 함께 읽어보고 모순되는 내용을 제거하세요.

2단계: 스킬, 에이전트, 명령어를 이동하고 폴백 없이 테스트하기

스킬은 OpenCode가 .claude/skills/ 및 ~/.claude/skills/를 읽으므로 그대로 둘 수 있습니다. 각 SKILL.md를 열고 프런트매터를 확인하세요. name, description, disable-model-invocation은 유지합니다. Claude Code 전용 필드에 의존하는 내용은 재작성하고, V2에서는 경로가 스킬 ID를 설정하므로 각 폴더 이름을 일정하게 유지하세요.

서브에이전트는 .claude/agents/에서 .opencode/agents/로 이동합니다. 마크다운 본문은 유지하고, mode: subagent를 설정한 뒤, 도구 제한 사항을 OpenCode의 권한(permissions)으로 변환하세요.

명령어는 .claude/commands/에서 .opencode/commands/로 이동합니다. 각 템플릿의 $ARGUMENTS 사용이 여전히 유효한지 확인하세요.

그 다음 테스트를 진행합니다. V1의 경우, 세션 환경 변수에 OPENCODE_DISABLE_CLAUDE_CODE를 설정하고 에이전트가 여전히 지침을 잘 따르는지 확인하세요. 이 변수는 .claude/skills도 비활성화하므로, 해당 위치에 남겨둔 스킬은 해당 세션 동안 사라집니다. 누락된 지침이 있다면 아직 이동하지 않은 Claude Code 파일에서 온 것입니다. V2의 경우 폴백이 없으므로 이러한 테스트가 필요하지 않습니다. 세션을 시작하고 에이전트에게 현재 적용 중인 지침을 요약해 달라고 요청한 뒤, 이를 AGENTS.md와 비교해 보세요. 테스트 시 유의할 V2 세부 사항: "중첩된 파일에 대한 편집은 로드된 후 자동으로 감지되지 않습니다." 파일을 변경한 후에는 새 세션을 시작하세요.

1단계는 이번 마이그레이션에서 가장 까다로운 부분이며, 작업의 상당 부분은 자동 메모리 노트와 임포트된 파일들, 즉 Claude Code가 명시적인 단일 파일 없이 축적해 온 컨텍스트를 정리하는 일입니다. 이를 AGENTS.md로 이동하면 이번 마이그레이션은 해결되지만, 다음 마이그레이션에는 도움이 되지 않으며 리포지토리가 아닌 사용자 개인에게 속한 컨텍스트는 다루지 못합니다.

MemoryLake는 사용자가 관리하는 단일 목록에 결정 사항과 선호도를 보관하여, Claude Code 및 연결된 다른 어시스턴트에서 사용할 수 있도록 지원하는 메모리 레이어입니다.

사용자가 직접 자신의 언어로 항목을 작성합니다. CLAUDE.md 파일, Claude Code의 자동 메모리, OpenCode 설정 또는 기타 벤더의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않습니다. 리포지토리 외부에 프로젝트 세부 정보를 저장하기 전에 조직의 보안 정책을 확인하세요.

1단계: API 키 생성

로그인한 후 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 작업 공간에 속하며, Anthropic 계정 및 모델 제공업체와는 별개입니다.

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

리포지토리 규칙이 아닌 자동 메모리에서 발견한 내용부터 시작하세요. 여러분의 선호도, 결정의 배경이 된 논리, 배제한 접근 방식 등을 날짜와 함께 항목당 하나의 결정으로 작성합니다.

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

사용 중인 어시스턴트를 연결하세요. 그러면 컨텍스트가 처음 학습된 도구에 종속되지 않고, 여러분이 작업하는 모든 곳에서 사용할 수 있게 됩니다.

첫 번째 차이점은 복잡한 폴백 체인 대신 단 하나의 지침 파일만 사용한다는 것입니다. AGENTS.md가 마련되면 OpenCode V1 및 V2가 지침을 읽을 수 있으며, Claude Code도 동일한 파일을 읽을 수 있습니다.

두 번째는 중요한 내용이 Claude의 자동 메모리에만 고립되어 남지 않는다는 점입니다. 마이그레이션 과정에서 이를 검토함으로써, Claude가 스스로 작성한 노트를 사용자가 직접 보고 편집할 수 있는 지침으로 전환할 수 있습니다.

세 번째는 반복 가능한 테스트가 가능하다는 점입니다. V1 호환성을 끄거나 V2를 실행하면 OpenCode가 무엇을 읽는지 정확히 확인할 수 있으므로, 마이그레이션이 완료되었는지 막연히 추측하는 대신 확실히 파악할 수 있습니다.

먼저 OpenCode 버전을 확인하세요. V1은 CLAUDE.md를 폴백으로 읽지만, V2는 읽지 않습니다.

CLAUDE.md가 아닌 AGENTS.md를 작성하세요. 두 버전 모두와 Claude Code에서 작동합니다.

임포트를 해결하세요. 가져온 콘텐츠를 직접 붙여넣거나 instructions 배열을 사용하세요.

떠나기 전에 자동 메모리를 읽어보세요. 사용자가 아닌 Claude가 직접 작성한 유일한 소스입니다.

원한다면 스킬을 .claude/skills/에 그대로 두어도 좋습니다. OpenCode가 이를 읽지만, 프런트매터를 확인하세요.

에이전트와 명령어를 .opencode/로 이동하세요. Claude Code 폴더는 OpenCode의 감지 목록에 없습니다.

테스트와 함께 폴백을 끈 상태로 진행하세요. 어떤 부분이 여전히 Claude Code 파일에 의존하고 있는지 보여줍니다.

OpenCode 문서는 처음부터 Claude Code 사용자를 고려해 왔으며, 스킬의 경우 이동이 여전히 쉽습니다. 두 버전 모두 .claude/skills를 읽기 때문입니다. 지침의 경우 버전에 따라 다릅니다. V1은 AGENTS.md가 없을 때 CLAUDE.md를 읽습니다. V2는 AGENTS.md만 인식하며, 마이그레이션 가이드에서는 지침을 직접 이동하라고 안내합니다.

어느 쪽이든 가장 확실한 방법은 동일합니다. CLAUDE.md 파일, 임포트 파일, 경로 범위 규칙, 그리고 Claude가 스스로 기록한 자동 메모리를 취합하여 AGENTS.md를 구축하세요. 서브에이전트와 명령어를 .opencode/로 이동하고, 스킬 프런트매터를 확인한 뒤, 폴백을 끈 상태로 테스트를 진행하세요. 이렇게 하면 어떤 버전을 실행하든 OpenCode가 여러분의 컨텍스트를 바탕으로 원활하게 작동할 것입니다.