지난 글에서는 “규칙만 분리해 두면 도구가 바뀌어도 다시 만들 것은 많지 않다”는 원칙을 정리했다. 이번 글은 그 원칙을 Cursor → Claude Code로 실제 옮기며 부딪힌 구체 사례들이다. 사내 티켓·도메인·패키지·민감 정보는 빼고, 구조와 판단 기준만 남긴다.

지난번엔 GPT 계열로 넘어갔고, 이번엔 Claude Code로 옮겼다. 도구는 또 바뀌었지만 옮기는 비용은 여전히 작았다. 다만 도구마다 “다시 만들 것”의 종류가 달랐고, 그 차이가 이번 글의 핵심이다.

TL;DR

  • 스킬 포맷이 같았다. Cursor 스킬과 Claude 스킬은 둘 다 SKILL.md(frontmatter name/description) 규격이라, 44개를 그대로 복사하고 경로만 고치니 대부분 동작했다.
  • 원격 도구는 “커넥터”, 로컬 도구는 “설정 파일”. 원격 OAuth 서버는 설정 파일에 박아도 CLI에서 연결이 안 됐고, 결국 claude.ai 커넥터가 답이었다. 로컬 stdio(브라우저)는 설정 파일이 맞았다.
  • 같은 엔드포인트라도 transport 표기가 달랐다. Cursor가 관대하게 처리하던 sse를 Claude는 http로 명시해야 했다.
  • 중복은 하나로. 공식 플러그인이 내 설정 파일 MCP와 겹쳐 실패하고 있었다. 한 능력엔 한 소스만 남겼다.
  • 비공개는 끝까지 로컬. 투자용 개인 스킬은 업무 백업 repo에서 뺐다.

스킬 포맷이 같다는 건 생각보다 큰 이득

가장 먼저 확인한 건 “내가 쌓아 둔 스킬을 얼마나 다시 써야 하나”였다. 열어 보니 Cursor 스킬과 Claude 스킬은 같은 규격이었다. 폴더 안에 SKILL.md가 있고, 앞머리에 name과 description이 있고, 본문은 모델에게 주는 절차 설명이다.

그래서 이관은 “재작성”이 아니라 “복사 + 가지치기”가 됐다. 개인 스킬 폴더를 통째로 새 위치로 옮기고, 업무와 무관한 것만 걸러 냈다.

한 가지 함정이 있었다. 원본 스킬 폴더가 사실 심볼릭 링크 밭이었다. 실제 본문은 별도 개인 repo에 있고, 링크만 걸려 있었다. 그대로 복사하면 링크만 복사돼 새 환경에서 깨진다. 링크를 따라가 실제 내용을 복사(dereference)해야 독립적으로 동작했다.

저장 구조: 링크 밭 대신 “폴더 자체가 repo”

이전 도구에서는 설정 폴더가 별도 repo를 가리키는 링크 밭이었고, 동기화 스크립트와 설치 스크립트가 필요했다.

새 도구에서는 더 단순하게 갔다. 설정 폴더 자체를 git repo로 만들었다. 링크도, 별도 clone도, 동기화 스크립트도 없다. 그냥 git -C ~/.<tool> add/commit/push.

대신 함정이 하나 있다. 이 폴더에는 세션 기록·토큰·캐시가 잔뜩 들어 있다. 그래서 .gitignore를 화이트리스트 방식으로 짰다.

*                 # 기본은 전부 무시
!skills/          # 개인 스킬만 허용
!commands/
!README.md

커밋 전에는 항상 두 가지를 확인했다. (1) 허용 목록 밖이 스테이징됐는지, (2) 실제 토큰 문자열이 들어갔는지. 둘 다 0이어야 커밋했다.

원격 도구는 커넥터, 로컬 도구는 설정 파일

여기서 도구별 차이가 제일 컸다. 외부 도구 연결(이슈 트래커·메신저·저장소 등)을 설정 파일의 MCP 서버로 그대로 옮겼는데, 원격 OAuth 서버들이 CLI에서 연결되지 않았다. 로그에는 fetch failed만 반복됐다.

이상했던 건, 같은 머신에서 curl과 새로 띄운 스크립트는 그 엔드포인트에 정상 도달했다는 점이다. 즉 머신 문제가 아니라 그 순간의 프로세스가 원격 호스트에 fetch를 못 하는 상태였다. 세션 시작 시점의 네트워크 상태가 프로세스에 굳어 버린 것에 가깝다.

돌고 돌아 답은 설정 파일이 아니라 claude.ai 커넥터였다. 메신저·이슈 트래커·저장소를 커넥터로 붙이니 도구가 세션에 그대로 잡혔다. 반대로 로컬 stdio 서버(브라우저 자동화)는 설정 파일이 맞았다. 정리하면:

종류 붙이는 방법
원격 SaaS (메신저·이슈·저장소) 커넥터
로컬 실행 (브라우저 등) 설정 파일의 stdio 서버

같은 엔드포인트, 다른 표기

이관 초반에 헤맨 지점. 이전 도구 설정에서는 어떤 원격 MCP를 type: sse로 적어 두면 알아서 붙었다. 그대로 옮겼더니 실패했다. 알고 보니 그 엔드포인트는 streamable HTTP였고, 새 도구에서는 type: http로 명시해야 했다. 이전 도구가 관대하게 자동 판별하던 걸, 새 도구는 명시를 요구했다.

교훈: 설정을 옮길 때 “값”만 옮기면 안 되고, 각 도구가 그 값을 어떻게 해석하는지까지 확인해야 한다.

외부 API는 CLI 대신 “게이트웨이 + 기본 인증”

원격 MCP가 안 붙는 동안, 이슈 트래커는 REST API로 우회했다. 여기서도 표기가 문제였다. 커스텀 도메인에 토큰을 실어 보냈더니 계속 거절당했다. 실제로는 그 서비스가 클라우드(별칭 도메인) 였고, 커스텀 도메인이 아니라 표준 API 게이트웨이 호스트 + 기본 인증(이메일:토큰) 으로 보내야 통과했다.

“되던 방식”을 그대로 옮기지 말고, 대상의 실제 정체(온프레미스인 줄 알았는데 클라우드였다)를 먼저 확인하는 게 빨랐다.

옮기면서 가지치기: 중복 도구 정리

새 도구는 플러그인 생태계가 따로 있었다. 그런데 공식 플러그인 몇 개가 내가 설정 파일에 넣은 MCP와 정확히 겹쳤다. 브라우저·저장소 플러그인이 그랬고, 그중 하나는 아예 실패 상태로 떠 있었다.

한 능력에 소스가 셋(플러그인 + 설정 파일 MCP + CLI)이면 관리 지점만 늘고 충돌만 난다. 그래서 한 능력엔 한 소스만 남겼다. 예를 들어 저장소는 CLI + 커넥터로 충분하니 중복 플러그인과 설정 파일 MCP를 지웠고, 브라우저는 인증서 옵션까지 챙긴 내 설정 파일 쪽을 남기고 열등한 플러그인을 지웠다.

지우고 나니 도구 목록이 깔끔해졌다. “많이 붙여 둔 것”이 아니라 “겹치지 않게 하나씩”이 관리 비용을 낮춘다.

각색: 도구 이름은 같고, 전제만 갈아끼운다

스킬 본문에는 이전 도구를 전제한 부분이 남아 있었다. 이걸 새 도구용으로 고쳤는데, 예상보다 기계적이었다.

  • 브라우저 자동화: 이전 도구의 내장 브라우저를 전제했는데, 새 도구는 별도 브라우저 자동화 도구를 쓴다. 놀랍게도 도구 이름이 거의 같았다(browser_navigate, browser_take_screenshot …). “내장 브라우저” → “브라우저 자동화 도구”로 바꾸고, 그쪽에만 있던 잠금 스텝을 지우니 끝이었다.
  • 메신저: 스킬이 쓰던 함수 이름이 새 커넥터의 도구 이름과 그대로 일치했다. 구식 토큰 설정 안내만 폐기했다.
  • 동기화 스킬: 이전 도구의 설정 폴더를 별도 repo에 밀어 넣던 스킬은, “폴더 자체가 repo”인 새 구조에 맞게 다시 썼다.
  • 스크립트가 참조하던 경로: 이전 도구의 세션 기록 경로를 새 도구의 경로로 바꿨다.

포인트는, 각색이 “재설계”가 아니라 전제만 갈아끼우는 치환에 가까웠다는 것이다. 도구가 같은 관례(브라우저 도구 이름, SKILL.md 규격, 메신저 도구 이름)를 공유할수록 이 비용은 더 작아진다.

비공개는 끝까지 로컬

지난 글과 같은 원칙. 이관하던 스킬 중에는 개인 투자용처럼 업무와 무관한 것들이 섞여 있었다. 백업 repo가 비공개라도, 업무 자산과 개인 자산은 섞지 않는 게 낫다. 그래서 업무 백업 repo에서는 그 계열을 통째로 뺐다.

경계는 나중에 정하려 하면 이미 섞인 뒤다. 복사 시점에 걸러 내는 게 제일 쉽다.

배운 점

1. 포맷의 표준화가 이관 비용을 결정한다

스킬이 SKILL.md라는 공통 규격을 따르니, 도구가 바뀌어도 “복사 + 경로 수정”으로 끝났다. 반대로 규격이 도구마다 달랐다면 44개를 다 다시 썼을 것이다. 자산을 만들 때 표준 포맷을 쓰는 게 미래의 이관 비용을 미리 깎는다.

2. “값”이 아니라 “해석”을 옮겨야 한다

같은 sse/http, 같은 토큰, 같은 URL이라도 도구마다 해석이 다르다. 설정을 복붙하지 말고, 새 도구가 그 값을 어떻게 읽는지 한 번씩 확인해야 한다.

3. 원격은 커넥터, 로컬은 설정 파일

원격 SaaS를 설정 파일에 직접 박는 것보다, 도구가 공식 제공하는 커넥터가 훨씬 안정적이었다. 로컬 실행 도구는 반대로 설정 파일이 맞다. 이 구분만 잡아도 “왜 안 붙지”로 태우는 시간이 줄어든다.

4. 한 능력엔 한 소스

플러그인·설정 파일 MCP·CLI가 같은 능력을 중복 제공하면 충돌과 관리 비용만 늘어난다. 겹치는 걸 지우는 게 새로 붙이는 것보다 이득일 때가 많다.

5. 비공개 경계는 복사 시점에

지난 글의 결론과 같다. 섞인 뒤에 분리하는 것보다, 옮기는 순간에 거르는 게 압도적으로 싸다.

지금의 결론

도구는 또 바뀔 것이다. 이번에 확인한 건, 바뀌는 게 도구지 규칙이 아니라는 점이 두 번째 도구에서도 유지됐다는 사실이다.

한 줄로 줄이면: 포맷은 표준으로, 원격은 커넥터로, 중복은 하나로, 비공개는 로컬로.