Claude Code 설정 가져오기: /import 미리보기와 검토 기준

AI 코딩 도구를 바꿀 때 가장 번거로운 일은 프로그램 설치보다 기존 설정 이전입니다. Codex에서 연결한 MCP 서버, Gemini CLI의 훅, Cursor의 Rules와 Skills를 Claude Code 형식에 맞춰 하나씩 다시 만들려면 어디까지 자동으로 옮길 수 있는지부터 판단해야 합니다.

Claude Code /import는 Codex·Gemini CLI·Cursor 설정을 찾아 호환되는 항목을 가져오는 기능입니다. 지침 파일, MCP 서버, 명령어, 서브에이전트, 스킬을 스캔하지만 모든 설정을 기계적으로 복사하지는 않습니다. 먼저 --dry-run을 붙이면 파일을 쓰지 않은 채 자동 매핑 항목과 수동 이전 항목을 구분할 수 있습니다.[1][2]

터미널 셸에서는 claude import …를 실행하고, Claude Code 대화 화면에서는 /import …를 입력합니다. 여기서 지침은 AI가 계속 따를 작업 규칙, MCP는 외부 도구 연결, 훅은 특정 시점에 자동 실행되는 명령, 스킬은 지침과 스크립트를 묶은 기능 단위입니다.

이 글은 Linux에서 @anthropic-ai/claude-code@2.1.273의 가져오기 미리보기를 실행해 세 소스의 매핑 범위를 확인했습니다. 세 소스는 기존 설정이 있는 사용자 프로필에서 실행했고, Codex는 별도의 임시 HOME에서도 추가 확인했습니다. 실제 설정 적용은 하지 않았으므로 본문 결과는 적용 완료 사례가 아니라 가져오기 전 판단 기준입니다. 확인일은 2026년 9월 16일입니다.

/import가 필요한 이유

Codex, Gemini CLI, Cursor는 비슷한 이름의 기능을 제공해도 저장 위치와 설정 형식이 다릅니다. 예를 들어 세 도구 모두 훅을 지원할 수 있지만 이벤트 이름, 전달되는 데이터, 스크립트 종료 코드의 의미가 같다는 보장은 없습니다.

설정 폴더를 통째로 복사하면 다음 문제가 생길 수 있습니다.

• 경로와 JSON·TOML 구조가 달라 Claude Code가 읽지 못함

• 같은 MCP 서버가 중복 등록되거나 기존 이름과 충돌함

• Cursor Skill 안의 스크립트와 지침이 검토 없이 활성화됨

• Codex 권한 정책을 Claude Code 권한 설정으로 잘못 해석함

• 훅 이름만 비슷하고 payload가 달라 실행 시점에 실패함

/import의 역할은 “모든 설정을 완벽하게 번역”하는 것이 아니라 현재 머신에서 발견한 항목을 호환 가능 여부에 따라 분류하는 것에 가깝습니다. 그래서 실제 쓰기보다 미리보기가 먼저입니다.

지원 버전과 사용 불가 환경

공식 문서가 안내하는 최소 버전은 다음과 같습니다.[1][2]

먼저 설치 버전을 확인합니다.

claude --version

이 글에서 고정 실행한 버전은 다음과 같습니다.

2.1.273 (Claude Code)

최소 버전을 충족해도 모든 환경에서 사용할 수 있는 것은 아닙니다. 공식 문서에는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform, Claude apps gateway에서 사용할 수 없다고 나옵니다. 가져오기 기능 플래그가 꺼진 환경도 마찬가지입니다.[1][2]

--dry-run으로 설정 미리보기

가장 먼저 실행할 명령은 실제 가져오기가 아니라 --dry-run입니다.

claude import codex --dry-run
claude import gemini --dry-run
claude import cursor --dry-run

세 명령은 각각 해당 도구의 로컬 구성을 스캔합니다. --dry-run이 붙으면 발견한 항목과 매핑 결과를 설명하지만 Claude Code 설정에는 쓰지 않습니다.

출력에서는 숫자보다 다음 세 분류가 중요합니다.

1. 자동 가져오기 가능: Claude Code 형식으로 매핑할 수 있는 항목

2. 검토 필요: 가져올 수 있지만 스크립트나 지침을 먼저 읽어야 하는 항목

3. 자동 매핑 불가: 제품별 차이 때문에 직접 다시 작성해야 하는 항목

스캔 결과에 나오는 개수와 이름은 예시를 그대로 따라 하면 안 됩니다. 내 머신에 설치된 MCP, Skill, Rules, Hooks에 따라 달라집니다.

이번 실습 프로필의 결과만 요약하면 다음과 같습니다.

Codex 설정 스캔

Codex 설정은 다음 명령으로 미리 봅니다.

claude import codex --dry-run

2.1.273 실습 프로필에서는 사용자 범위 MCP 서버 10개가 자동 가져오기 가능 항목으로 잡혔습니다. 반면 다음 여섯 종류는 자동 매핑되지 않았습니다.

hooks
default_permissions
projects
tui
marketplaces
plugins

이번 프로필의 MCP 서버 10개는 자동 가져오기 가능으로 판정됐지만, 다른 전송 방식·인증 참조·프로젝트 범위 구성도 동일하게 처리된다고 일반화할 수는 없습니다. 반면 Codex의 권한과 UI·플러그인 체계는 Claude Code 설정으로 추측해 바꾸지 않았습니다.

특히 hooks는 직접 옮기기 전에 두 제품의 이벤트를 대조해야 합니다. 이벤트 이름뿐 아니라 입력 payload, 성공·실패 판단, 명령 실행 위치를 함께 확인하고 작은 테스트 훅으로 검증하는 편이 안전합니다.

Codex 자체 설치가 먼저라면 WSL에 OpenAI Codex CLI 설치하기에서 기본 실행 환경을 확인할 수 있습니다. MCP가 어떤 연결인지 낯설다면 MCP 처음 연결하기를 먼저 보는 편이 이해하기 쉽습니다.

Gemini CLI 설정 스캔

Gemini CLI는 다음처럼 확인합니다.

claude import gemini --dry-run

같은 프로필에서 자동으로 가져올 수 있는 항목은 0개였고, Gemini settings.json의 hooks 한 종류가 수동 이전 대상으로 표시됐습니다.

이 결과는 Gemini CLI에서 아무것도 가져올 수 없다는 일반 규칙이 아닙니다. 이번 로컬 설정에서 대응 가능한 항목이 발견되지 않았다는 뜻입니다. 다른 사용자는 MCP 서버, 지침 파일, 명령어처럼 자동 매핑되는 구성을 갖고 있을 수 있습니다.

자동 항목이 0개라면 억지로 실제 가져오기를 실행할 이유가 없습니다. 먼저 Gemini 설정 파일을 열어 필요한 훅이 무엇을 하는지 파악하고, Claude Code의 훅 문서에 맞춰 별도로 다시 작성합니다.

Gemini CLI 설치 위치와 첫 실행이 아직 준비되지 않았다면 Gemini CLI 처음 설치하고 WSL에서 실행해보기에서 환경부터 점검할 수 있습니다.

Cursor 설정 스캔

Cursor 가져오기는 Claude Code 2.1.265 이상이 필요합니다.[1] 미리보기 명령은 다음과 같습니다.

claude import cursor --dry-run

2.1.273 실습에서는 사용자 범위 Skill 2개가 자동 가져오기 후보로 잡혔지만 둘 다 경고 표시와 함께 기본 선택이 해제됐습니다. Skill 폴더를 그대로 복사하면 그 안의 스크립트와 지침도 Claude Code에서 사용될 수 있기 때문입니다.

자동 매핑되지 않은 항목은 12개였습니다.

• Cursor 훅 8개

• 앱이나 대시보드에 저장된 User Rules·Team Rules·Memories 3개

• Custom Modes 1개

일부 Cursor 훅은 Claude Code에 비슷한 이름의 이벤트가 있어도 스크립트 자체는 자동 번역되지 않았습니다. 예를 들어 preToolUse와 Claude Code의 PreToolUse가 대응해 보여도 payload와 종료 코드 계약을 다시 맞춰야 합니다.

Cursor Rules와 Memories처럼 앱 상태나 대시보드에 있는 정보는 로컬 파일 스캔만으로 모두 가져올 수 없습니다. 필요한 규칙을 골라 사용자 ~/.claude/CLAUDE.md, 프로젝트 .claude/CLAUDE.md, 조직 관리 범위 중 알맞은 곳에 직접 배치합니다.

항목별 검토 기준

MCP 서버

서버 이름만 보지 말고 전송 방식, 실행 명령, 환경 변수, 인증 정보 참조를 확인합니다. 가져오기 후에는 /mcp에서 연결 상태를 보고 읽기 전용 요청부터 시험합니다. 토큰이나 비밀값을 글·로그·저장소에 복사하지 않습니다.

지침과 Rules

모든 프로젝트에 필요한 개인 습관인지, 특정 저장소의 빌드·검증 규칙인지 구분합니다. 사용자 전체 규칙을 프로젝트 설정으로 옮기거나 그 반대로 배치하면 불필요한 컨텍스트와 충돌이 생깁니다.

명령어와 서브에이전트

이름이 같아도 사용할 수 있는 도구와 권한 범위가 다를 수 있습니다. 가져온 뒤에는 파일을 쓰지 않는 작은 작업으로 프롬프트, 도구 목록, 결과 전달 방식을 먼저 확인합니다.

스킬

SKILL.md만 읽고 끝내지 말고 같은 폴더의 스크립트와 참조 파일도 확인합니다. 셸 명령, 네트워크 요청, 파일 쓰기 경로가 포함돼 있다면 신뢰할 수 있는 출처인지 판단한 뒤 선택합니다.

훅과 권한

자동 매핑되지 않는 것이 오히려 안전한 경우입니다. 훅은 실행 시점과 입력 형식이 다르고, 권한은 각 도구의 샌드박스·승인 모델과 연결됩니다. 키 이름을 바꿔 복사하지 말고 Claude Code 문서에 맞춰 다시 설계합니다.

대화형 선택과 실제 적용

공식 문서는 /import에 --yes 옵션이 있으며, 비대화형 미리보기가 확인용 명령을 제공한다고 설명합니다.[1] 2.1.273 실습 출력의 확인 명령에는 환경별 식별값이 --yes=<digest> 형태로 포함됐습니다.

Claude Code 입력창에서 실제 적용으로 진행할 때는 미리보기에 나타난 다음 형태의 명령을 사용합니다.

/import codex --yes=<preview에서 발급된 digest>

<digest>는 방금 확인한 미리보기 결과를 식별하는 값입니다. 문서나 다른 사람의 예시를 복사하지 말고 내 환경에서 방금 실행한 미리보기 출력을 사용해야 합니다.

이번 실습 출력에서 --yes=<digest> 경로는 선택한 항목뿐 아니라, 자동 매핑되지 않은 설정을 정리한 skills/import-to-claude-code/ 참조 스킬도 Claude 설정 디렉터리에 작성한다고 안내했습니다. 실제 쓰기 범위는 내 미리보기 출력에서 다시 확인합니다.

모든 항목을 한 번에 적용하기보다 개별 선택이 필요하면 터미널에서 대화형 피커를 엽니다.

claude import

소스를 고른 뒤 체크박스에서 필요한 항목만 선택합니다. 기존 Claude 설정과 이름이 겹치는 MCP, 경고가 붙은 스킬, 실행 스크립트가 포함된 항목은 우선 해제하고 내용을 검토합니다. 프로젝트 범위 항목을 다루거나 참조 스킬 쓰기를 피하려면 이 경로가 더 적합합니다.

실제 적용 전에는 Claude 설정을 백업하고 저장소 상태도 확인합니다.

umask 077
backup=$(mktemp -d "$HOME/.claude.backup-before-import.XXXXXX")
cp -a -- "$HOME/.claude/." "$backup/"

~/.claude에 인증 정보가 포함될 수 있으므로 백업 폴더를 Git 저장소 안에 만들거나 공유 드라이브에 올리지 않습니다. backup 변수는 같은 터미널에서 이후 비교할 때 사용합니다.

가져오기 후 변경 사항 검증

실제 가져오기로 진행했다면 완료 메시지만으로 이전이 끝났다고 판단하지 않습니다. 항목별 동작을 검증합니다.

1. 변경 파일 확인

diff -qr -- "$backup" "$HOME/.claude"

출력된 파일만 대상으로 변경 내용을 검토합니다. 세션 로그처럼 가져오기와 무관한 파일도 달라질 수 있으며, 비밀값이 포함된 설정 원문을 외부 diff 서비스에 올리지는 않습니다.

2. MCP 연결 확인

Claude Code를 열어 /mcp에서 서버 상태를 확인합니다. 연결 성공 뒤에도 바로 쓰기 작업을 시키지 말고, 목록 조회나 상태 확인처럼 되돌리기 쉬운 읽기 요청부터 시험합니다.

3. 지침 적용 범위 확인

사용자 지침과 프로젝트 지침이 의도한 폴더에서만 적용되는지 새 세션으로 확인합니다. 이전 세션의 컨텍스트가 남으면 가져온 설정의 효과와 구분하기 어렵습니다.

4. Skill과 Agent 읽기 전용 테스트

가져온 Skill이나 Agent에 파일 수정, 셸 실행, 네트워크 접근이 포함돼 있다면 작은 샘플 폴더에서 읽기 전용 작업부터 실행합니다. 스크립트가 예상하지 못한 상위 경로나 홈 디렉터리를 다루지 않는지 봅니다.

5. 훅 단위 테스트

수동으로 다시 만든 훅은 이벤트마다 한 개씩 켭니다. 여러 훅을 동시에 옮기면 어떤 이벤트의 payload나 종료 코드가 잘못됐는지 찾기 어렵습니다.

claude import가 보이지 않을 때

별도의 임시 HOME에서 같은 2.1.273 패키지를 실행했을 때는 다음 메시지가 나왔습니다.

`claude import` is not yet available in this build.
Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

같은 버전이 현재 사용자 프로필에서는 세 소스를 정상 스캔했으므로, 이 한 줄만 보고 “2.1.273에 기능이 없다”고 결론 내리면 안 됩니다. 다만 이 로그만으로 임시 HOME에서 기능이 막힌 원인도 특정할 수 없습니다. 먼저 공식 제외 배포 환경과 가져오기 기능 플래그 상태를 확인합니다.[1][2]

확인 순서는 다음이 실용적입니다.

1. claude --version으로 최소 버전 충족 여부 확인

2. claude import --help에 codex, gemini, cursor, --dry-run이 보이는지 확인

3. Bedrock·Foundry·게이트웨이처럼 공식 제외 환경인지 확인

4. 조직 환경이라면 관리자에게 가져오기 기능 플래그 상태 확인

5. 자동 이전이 막히면 /mcp와 settings.json을 이용해 필요한 항목만 수동 구성

안전한 이전 순서

설정 이전은 다음 순서로 진행하면 되돌리기 쉽습니다.

1. Claude Code 버전과 실행 경로 확인

2. 기존 ~/.claude 백업

3. 소스별 --dry-run 실행

4. 자동 매핑·경고·수동 이전 항목 분류

5. Skill과 스크립트 내용 검토

6. 대화형 피커에서 필요한 항목만 선택

7. MCP 읽기 테스트

8. 지침·Agent·Skill을 새 세션에서 확인

9. 훅은 하나씩 수동 이전하고 단위 테스트

--dry-run으로 자동 매핑·검토 필요·수동 이전 항목을 나누고, 선택한 설정만 작은 범위에서 검증하면 기존 Claude Code 환경을 크게 흔들지 않고 이전할 수 있습니다.

Claude Code 자체 설치와 인증이 먼저라면 Claude Code 처음 설치하고 실행해보기부터 시작할 수 있습니다. 응답 형식까지 옮기려는 목적이라면 Claude Code Output Styles 사용법에서 프로젝트용 스타일과 CLAUDE.md의 차이도 함께 확인하세요.

참고 자료

[1] Claude Code 명령어: /import
[2] Claude Code CLI 참조: claude import
[3] Claude Code v2.1.273 릴리스
[4] Claude Code 설정