Claude Code에서 Codex로 옮길 때 — 실전 마이그레이션 가이드 2026
Claude Code 기반 워크플로우를 OpenAI Codex CLI로 옮기려는 팀이 늘고 있다. 모델 가격, 멀티 벤더 리스크 분산, 특정 코딩 워크로드의 성능 차이 등 이유는 다양하다. 그런데 두 도구는 같은 "AI 코딩 에이전트"라는 카테고리에 속해도 컨벤션·확장 메커니즘이 다르다. 무작정 옮기면 자동화 파이프라인의 절반이 깨진다.
이 가이드는 Claude Code → Codex 마이그레이션을 실제로 끝내본 팀이 어떤 순서로 무엇을 옮기고, 무엇을 포기하고, 무엇을 대체했는지 정리한다. 자동 변환 툴(claude2codex)을 어디서 쓰고 어디서 안 쓰는지, 일주일 점검 체크리스트, 양쪽을 분기 사용하는 하이브리드 패턴까지 다룬다.
마이그레이션 전 의사결정 — 옮길지 말지부터
옮기는 게 모두에게 정답은 아니다. 다음 세 질문에 모두 "예"여야 본격 마이그레이션을 권한다.
현재 Claude Code 비용의 60% 이상이 일상적인 코드 편집·리뷰에서 발생하는가? (Codex의 GPT-5-codex가 단가 우위를 보이는 영역) — 만약 디자인·기획·문서 분량이 큰 워크플로우라면 Claude를 유지하는 게 합리적이다.
Skills·Hooks·서브에이전트 같은 Claude 고유 기능에 의존하지 않는가? 의존도가 높다면 마이그레이션 비용이 비용 절감을 초과한다.
하나의 벤더 락인을 줄이는 게 중요한 전략적 우선순위인가? 멀티 벤더 운영은 그 자체로 관리 비용이 든다.
세 질문 중 하나라도 "아니오"라면, 통째 마이그레이션 대신 하이브리드 분기 사용(아래 5절)이 더 낫다.
Claude Code와 Codex의 핵심 차이 비교
| 영역 | Claude Code | OpenAI Codex CLI | 마이그레이션 난이도 |
|---|---|---|---|
| 메인 모델 | claude-opus-4-7 / sonnet-4-6 / haiku-4-5 | GPT-5 / GPT-5-codex / o1 계열 | 낮음 (모델 교체) |
| 컨벤션 파일 | CLAUDE.md | AGENTS.md (멀티 벤더 표준) | 낮음 (rename + 어조 조정) |
| 확장 메커니즘 | Skills (markdown SKILL.md + 메타데이터) | 별도 표준 없음, 수동 컨텍스트 로딩 | 높음 (가장 큰 갭) |
| 자동화 훅 | Hooks (PreToolUse, SessionStart, UserPromptSubmit 등) | 라이프사이클 이벤트 미지원 | 높음 (외부 wrapper 필요) |
| 슬래시 커맨드 | /명령 형태 + 인자 파싱 | CLI 인자로 대체 | 중간 |
| MCP 서버 | 1급 지원, 자동 도구 노출 | 일부 지원, 설정 형식 다름 | 중간 |
| 서브에이전트 | Agent tool (subagent_type) | 외부 오케스트레이션 필요 | 높음 |
| 권한 모드 | acceptEdits / plan / dontAsk 등 | --auto / --confirm 류 | 낮음 |
가장 큰 갭 세 곳: 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 자동 변환 적용 (반나절)
오픈소스 — 자동 변환 툴 소개와 release 노트
— 멀티 도구 운영의 조직 구조
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로 돌아오거나 하이브리드로 재구성합니다.
SOCIAL SHARE CARD GENERATOR