한 개발자가 수개월 동안 사용해 온 Claude Code 워크플로우를 OpenCode로 옮겼다가 파일 처리, 규칙 로딩, 도구 인벤토리, 스킬 메타데이터, 세션 간 메모리가 모두 망가지는 것을 발견했습니다. 그가 기록한 해결 방법은 Claude 생태계에서 오픈 소스 대안으로 전환하려는 모든 이들을 위한 실질적인 체크리스트 역할을 합니다.
마이그레이션이 중요했던 이유
Claude Code 사용자는 AI 기반 코딩 어시스턴트를 원활하게 실행하기 위해 규칙, 스킬 정의, 메모리 로그와 같이 긴밀하게 묶인 파일 세트에 의존합니다. 저자의 설정이 규칙을 로드하지 못하고, 파일을 혼동하며, 토큰 사용량이 급증하면서 그의 일상적인 코딩 도우미는 신뢰할 수 없게 되었습니다. OpenCode는 "권한 우선 보안(permission-first security)", OpenRouter를 통한 모델 불가지론적(model-agnostic) 접근, 그리고 사용한 만큼 지불하는(pay-as-you-go) 가격 정책을 약속하며 매력적인 대안으로 다가옵니다. 하지만 전환 과정은 단순한 복사-붙여넣기가 아닙니다. OpenCode가 기대하는 형식에 맞춰 모든 구성 요소를 다시 선언해야 합니다.
문제가 발생한 원인
Claude Code는 CLAUDE.md라는 파일을 사용하지만, OpenCode는 이를 무시하고 대신 추가 메타데이터를 위해 AGENTS.md를 읽습니다. 저자는 두 시스템이 서로 호환될 것이라고 가정했고, 그 결과 여러 핵심 요소가 OpenCode에서 보이지 않게 되었습니다.
구체적인 실패 사례 및 해결 방법
규칙 파일 무시
OpenCode는 CLAUDE.md를 전혀 읽지 않으며, 오직 AGENTS.md만 파싱합니다. 파일 이름을 바꾸는 것만으로는 부족합니다. 콘텐츠를 새로운 형식에 맞춰 다시 선언해야 하기 때문입니다.
해결 방법: 새로운 AGENTS.md를 생성하고 규칙 텍스트를 복사한 뒤, 새로운 OpenCode 세션을 시작하여 에이전트에게 “What are my rules?”라고 물어보세요. 만약 에이전트가 규칙을 인용하지 못한다면 규칙이 로드되지 않은 것입니다.도구 인벤토리 누락
스킬과 MCP(multi-cloud platform) 서버를 복사하기로 되어 있던 마이그레이션 명령이 실패했습니다. OpenCode는 한 번도 등록되지 않은 도구의 인벤토리를 파악할 수 없기 때문입니다.
해결 방법: Claude Code 도구들이 여전히 작동하는 동안, 모든 스킬과 명령어를 수동으로 나열하세요. 어떤 것을 OpenCode에서 다시 구축할지, 어떤 것을 버릴지 결정해야 합니다.스킬의 프론트매터(front-matter) 삭제
이전된 스킬 파일들은 모델 할당 및 도구 처리 지침을 포함한 프론트매터의 대부분을 잃었습니다. OpenCode는 소수의 필드만 지원하므로, 가져온 스킬들이 예측 불가능하게 동작했습니다.
해결 방법: 가져온 모든 스킬을 오류가 있는 것으로 간주하세요. 가장 자주 사용하는 세 가지 스킬을 처음부터 다시 만들어, 지원되는 필드만 포함되도록 하세요. 사용하지 않는 스킬 파일은 삭제하십시오.세션 간 메모리 부재
Claude Code는 저자가 컨텍스트 유지를 위해 의존했던 지속적인 히스토리를 유지했습니다. OpenCode는 세션 간 메모리를 유지하지 않으므로, 전환 바로 다음 날 어시스턴트가 모든 것을 “잊어버렸습니다”.
해결 방법: AGENTS.md에 명시적인 지침을 추가하세요: “At the end of every session, append a short summary to session-log.md covering what was done, what is pending, and decisions made.” 이렇게 하면 세션 로그가 연속성을 위한 단일 진실 공급원(single source of truth)이 됩니다.
득과 실: 무엇을 얻고 무엇을 잃는가
이점 (Wins)
- 권한 우선 보안: OpenCode는 작업을 실행하기 전에 권한을 요청하므로, 실수로 코드가 변경되는 것을 줄여줍니다.
- 모델 자유도: 단일 API 키로 OpenRouter를 통해 수십 개의 모델을 사용할 수 있어, 설정 파일을 변경하지 않고도 다양한 모델을 실험할 수 있습니다.
- 비용 제어: 사용량 기반 과금 방식이므로, 토큰 소비가 급증할 때 비용이 많이 들 수 있는 정액제 구독을 피할 수 있습니다.
손실 (Losses)
- 내장된 장기 메모리가 없으므로 수동 로그를 유지해야 합니다.
- 제한된 스킬 메타데이터로 인해 대부분의 커스텀 도구를 다시 구축해야 합니다.
실질적인 마이그레이션 체크리스트
- AGENTS.md를 먼저 생성하세요 – 다른 파일을 가져오기 전에 필요한 모든 규칙을 선언하세요.
- 세션 로그 지침을 추가하세요 – AGENTS.md 상단에 “요약 추가” 규칙을 삽입하세요.
- 상위 3개 스킬을 다시 구축하세요 – 지원되는 필드만 복사하고, 각 스킬을 개별적으로 테스트하세요.
- MCP를 수동으로 다시 선언하세요 – 여전히 연결이 필요한 각 서버나 클라우드 엔드포인트를 나열하세요.
- 검증하세요 – 새로운 OpenCode 세션을 시작하고 어시스턴트에게 규칙, 스킬 목록 및 메모리 상태를 질문하여 확인하세요.
요약
Claude Code에서 OpenCode로 마이그레이션하는 것은 단순히 파일을 옮기는 것이 아니라, 어시스턴트를 구동하는 선언(declarations)을 재설계하는 과정에 가깝습니다. 이 과정은 핵심 규칙으로 단순화하고, 필수 스킬을 재구축하며, 수동 메모리 로그를 채택하도록 강제하지만, 동시에 더 저렴하고 모델에 구애받지 않는 AI 지원의 문을 열어줍니다. 편의성을 제어권과 맞바꿀 준비가 되었다면, 위의 체크리스트를 따르고 가져온 모든 구성 요소를 새롭게 시작한다는 마음가짐으로 임하십시오.