Claude Code에서 Codex로 옮길 때 — 실전 마이그레이션 가이드 2026

Claude Code 기반 워크플로우를 OpenAI Codex CLI로 옮기려는 팀이 늘고 있다. 모델 가격, 멀티 벤더 리스크 분산, 특정 코딩 워크로드의 성능 차이 등 이유는 다양하다. 그런데 두 도구는 같은 "AI 코딩 에이전트"라는 카테고리에 속해도 컨벤션·확장 메커니즘이 다르다. 무작정 옮기면 자동화 파이프라인의 절반이 깨진다.

이 가이드는 Claude Code → Codex 마이그레이션을 실제로 끝내본 팀이 어떤 순서로 무엇을 옮기고, 무엇을 포기하고, 무엇을 대체했는지 정리한다. 자동 변환 툴(claude2codex)을 어디서 쓰고 어디서 안 쓰는지, 일주일 점검 체크리스트, 양쪽을 분기 사용하는 하이브리드 패턴까지 다룬다.

마이그레이션 전 의사결정 — 옮길지 말지부터

옮기는 게 모두에게 정답은 아니다. 다음 세 질문에 모두 "예"여야 본격 마이그레이션을 권한다.

1. 현재 Claude Code 비용의 60% 이상이 일상적인 코드 편집·리뷰에서 발생하는가? (Codex의 GPT-5-codex가 단가 우위를 보이는 영역) — 만약 디자인·기획·문서 분량이 큰 워크플로우라면 Claude를 유지하는 게 합리적이다.
2. Skills·Hooks·서브에이전트 같은 Claude 고유 기능에 의존하지 않는가? 의존도가 높다면 마이그레이션 비용이 비용 절감을 초과한다.
3. 하나의 벤더 락인을 줄이는 게 중요한 전략적 우선순위인가? 멀티 벤더 운영은 그 자체로 관리 비용이 든다.

세 질문 중 하나라도 "아니오"라면, 통째 마이그레이션 대신 하이브리드 분기 사용(아래 5절)이 더 낫다.

Claude Code와 Codex의 핵심 차이 비교

가장 큰 갭 세 곳: Skills · Hooks · 서브에이전트. 이 세 가지에 깊이 의존하는 팀은 마이그레이션 ROI가 마이너스로 나올 수 있다.

마이그레이션 절차 — 7단계

1단계: 자산 인벤토리 (1일)

.claude/ 디렉토리, CLAUDE.md, 프로젝트 루트의 slash command 정의, hook 설정, MCP 서버 목록을 전부 추출한다.

find . -path "*/.claude/*" -type f > migration/inventory.txt
ls .claude/skills/ .claude/hooks/ .claude/commands/ 2>/dev/null >> migration/inventory.txt
cat .claude/settings.json | jq '.mcpServers // {}' > migration/mcp.json

이 파일들이 모두 변환되거나, 대체되거나, 폐기되는지 명시적으로 매핑되어야 한다. "그냥 옮기면 되겠지"는 거의 항상 일주일 후 장애로 돌아온다.

2단계: claude2codex 자동 변환 적용 (반나절)

오픈소스 claude2codex 마이그레이션 툴이 자동으로 처리하는 것:

• CLAUDE.md → AGENTS.md (어조·헤더·도구 참조 조정)
• 슬래시 커맨드 정의 → CLI 별칭 또는 스크립트
• MCP 서버 설정 → Codex 호환 포맷

자동 변환의 한계: Skills와 Hooks는 1:1 대응되는 개념이 Codex에 없으므로 변환 안 함. 다음 단계에서 수동 대체.

3단계: Skills 대체 전략 결정 (2~3일)

Claude의 Skills는 "필요할 때 자동 로드되는 작업 패턴 가이드"다. Codex에는 동등한 기능이 없으므로 세 가지 옵션 중 선택한다.

• 옵션 A — 수동 컨텍스트 로딩: Skill 내용을 AGENTS.md의 부록 섹션으로 옮긴다. 항상 로드되니 토큰 비용 증가. 자주 쓰는 핵심 3~5개 Skill에만 적용.
• 옵션 B — 외부 prompt 라이브러리: Skill markdown을 prompts/ 디렉토리에 두고, 작업 시작 시 사용자가 명시적으로 --load-prompt skill-name으로 주입. 토큰 효율적이나 호출이 강제되지 않음.
• 옵션 C — 트리거 wrapper 스크립트: 사용자 입력을 가로채는 사전 처리 스크립트로 Skill을 자동 주입. 가장 Claude 같은 경험이지만 구현 비용 큼.

대부분 팀은 A+B 조합이 현실적이다. Tier-0 핵심 워크플로우는 A로 항상 로드, 나머지는 B로 on-demand.

4단계: Hooks 대체 (2일)

Claude의 PreToolUse, SessionStart, UserPromptSubmit 등은 Codex에 없다. 대체 방법:

핵심은 "Codex 안에서 처리"가 아니라 "Codex 호출 전후에 외부에서 처리"로 패러다임을 옮기는 것. 자동화 보장 수준은 약간 떨어지지만 멀티 벤더 호환성은 높아진다.

5단계: 하이브리드 분기 패턴 (선택)

전부 옮기지 말고 워크로드별로 도구를 나누는 게 실측상 가장 큰 비용·품질 개선을 낸다. AI-Native 개발팀의 실제 분기 예시:

• Claude Code 유지: 아키텍처 설계, 멀티파일 리팩토링, Skills·Hooks 의존 워크플로우, 한국어 문서 작성
• Codex로 전환: 일상적 코드 편집·디버깅, 단위 테스트 생성, 짧은 함수 작성, 대량의 단순 작업

분기 운영의 관리 비용을 줄이려면 한 가지 규칙으로 정렬한다 — "3,000 토큰 이하의 단순 작업 = Codex, 그 외 = Claude" 같은 단순한 휴리스틱이 실측에서 의사결정 비용을 가장 적게 만든다.

6단계: 일주일 점검 체크리스트

마이그레이션 직후 일주일은 거의 확실히 무언가 깨진다. 다음 항목을 매일 확인한다.

• 자동화 파이프라인(예: 일일 빌드, 코드 리뷰 자동화, 문서 생성)이 의도대로 끝까지 실행되는가?
• 비용 모니터링: 예상 절감이 실제로 나오는가? (Codex의 토큰 단가 × 사용량 vs 직전 Claude 사용량)
• Skill 의존하던 작업의 품질이 떨어지지 않았는가? (대체 옵션 재조정 필요)
• 팀원의 "그냥 Claude로 돌아가고 싶다" 빈도 — 3회 이상 발생하면 하이브리드 비율 재조정.

7단계: 롤백 가능 상태 유지

.claude/ 디렉토리는 삭제하지 말고 압축 보관한다. 마이그레이션이 ROI 마이너스로 판명되면 즉시 되돌릴 수 있어야 한다.

tar -czf migration/claude-config-backup-$(date +%Y%m%d).tar.gz .claude/

마이그레이션 후 흔한 실패 4가지

1. "Skills 없어도 되겠지" → 일주일 안에 컨벤션 일관성 깨짐. 핵심 3~5개는 반드시 AGENTS.md에 포함.
2. Hooks 의존 자동화 방치 → 자동 커밋·자동 검증 등이 조용히 빠지면서 디버깅 가능 정보 손실. 5단계 외부 wrapper 패턴 적용 필수.
3. MCP 서버 호환성 가정 → 일부 MCP 서버는 Claude 전용 API 패턴 사용. 마이그레이션 전 각 MCP 서버의 Codex 호환성 개별 확인.
4. "Codex가 더 싸니까 더 막 쓰자" → 호출 빈도 증가로 결과적으로 더 비싸짐. 1단계 인벤토리에서 의도한 사용량 시나리오를 유지.

마이그레이션 = 도구 교체가 아니라 패러다임 이동

Claude Code에서 Codex로의 마이그레이션은 단순한 "CLI 교체"가 아니다. 확장 메커니즘이 도구 안(Skills/Hooks)에 있느냐, 도구 밖(외부 wrapper)에 있느냐의 패러다임 차이다. 이 차이를 인지하고 옮기면 실패율이 크게 떨어진다.

자동 변환 툴은 첫 절반의 작업(컨벤션·MCP·슬래시 커맨드)을 빠르게 끝내준다. 나머지 절반(Skills·Hooks·서브에이전트 대체)은 각 팀의 워크플로우 분석이 필요한 본질적 작업이다. 이걸 두 번째 변환 툴이 처리해주길 기대하지 말고, 위 7단계로 한 번에 끝내는 게 빠르다.

관련 자료

• Claude Code → Codex 마이그레이션 툴 오픈소스 공개 — 자동 변환 툴 소개와 release 노트
• Claude Code·Codex·Gemini로 비디오 전사 자동화 — 멀티 벤더 분기 운영 실제 사례
• AI-Native 팀 방법론 — 멀티 도구 운영의 조직 구조

FAQ

Q1. claude2codex 자동 변환 툴만 돌리면 마이그레이션 끝나나요?
아니오. 자동 변환은 컨벤션 파일(CLAUDE.md → AGENTS.md), MCP 설정, 슬래시 커맨드 매핑 등 약 절반을 처리합니다. Skills·Hooks·서브에이전트 의존 워크플로우는 수동 대체 전략(3·4·5단계)이 별도로 필요합니다.

Q2. 단순한 일부 워크로드만 Codex로 옮기는 게 더 안전한가요?
대부분의 팀에 그렇습니다. 전체 마이그레이션보다 하이브리드 분기 운영(5단계)이 실측 ROI가 더 큽니다. "3,000 토큰 이하 단순 작업 = Codex, 그 외 = Claude" 같은 단순 휴리스틱 하나만 도입해도 비용 20~30% 절감 사례가 있습니다.

Q3. Skills 대체로 가장 효과적인 방법은?
"Tier-0 핵심 워크플로우 3~5개는 AGENTS.md에 항상 포함(옵션 A), 나머지는 prompts/ 디렉토리에 두고 on-demand 로딩(옵션 B)" 조합이 가장 실용적입니다. 모든 Skill을 AGENTS.md에 넣으면 토큰 비용이 폭증합니다.

Q4. 마이그레이션 후 며칠 안에 ROI 평가가 가능한가요?
최소 2주입니다. 첫 1주는 깨진 자동화 복구로 소요되고, 2주차에 비로소 안정 운영 비용이 측정됩니다. 이 시점에서 예상 절감이 실측과 30% 이상 차이나면 6단계 체크리스트로 원인 추적이 필요합니다.

Q5. Claude로 다시 돌아갈 수 있나요?
네. 7단계의 .claude/ 백업을 유지하면 언제든 롤백 가능합니다. AI-Native 팀의 약 20%는 한 번 Codex로 전환했다가 Skills·Hooks 부재의 불편함 때문에 6주 안에 Claude로 돌아오거나 하이브리드로 재구성합니다.