Claude Code → Codex 마이그레이션 실전 가이드 2026 — 7단계 절차·도구 비교·하이브리드 패턴
Claude Code에서 OpenAI Codex로 옮길 때 무엇을 자동 변환하고, Skills·Hooks는 어떻게 대체하며, 어느 워크로드는 분기 사용하는 게 나은지 — AI-Native 팀이 실제 마이그레이션에서 검증한 7단계 절차.
# 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 서버 목록을 전부 추출한다.
```bash
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에 없다. 대체 방법:
| Hook 용도 | Codex 대체 |
| 세션 시작 시 컨텍스트 로딩 | 쉘 별칭으로 Codex 호출 전 `cat context.md` |
| 도구 호출 전 권한 검사 | Codex의 `--require-approval` 정책 활용 |
| 사용자 입력 검증/주입 | 외부 wrapper CLI에서 입력 가공 후 Codex에 전달 |
| 자동 commit / push | Codex 종료 후 별도 git hook 또는 CI 스크립트 |
핵심은 "Codex 안에서 처리"가 아니라 "Codex 호출 전후에 외부에서 처리"로 패러다임을 옮기는 것. 자동화 보장 수준은 약간 떨어지지만 멀티 벤더 호환성은 높아진다.
5단계: 하이브리드 분기 패턴 (선택)
전부 옮기지 말고 워크로드별로 도구를 나누는 게 실측상 가장 큰 비용·품질 개선을 낸다. AI-Native 개발팀의 실제 분기 예시:
- Claude Code 유지: 아키텍처 설계, 멀티파일 리팩토링, Skills·Hooks 의존 워크플로우, 한국어 문서 작성
- Codex로 전환: 일상적 코드 편집·디버깅, 단위 테스트 생성, 짧은 함수 작성, 대량의 단순 작업
분기 운영의 관리 비용을 줄이려면 한 가지 규칙으로 정렬한다 — "3,000 토큰 이하의 단순 작업 = Codex, 그 외 = Claude" 같은 단순한 휴리스틱이 실측에서 의사결정 비용을 가장 적게 만든다.
6단계: 일주일 점검 체크리스트
마이그레이션 직후 일주일은 거의 확실히 무언가 깨진다. 다음 항목을 매일 확인한다.
- 자동화 파이프라인(예: 일일 빌드, 코드 리뷰 자동화, 문서 생성)이 의도대로 끝까지 실행되는가?
- 비용 모니터링: 예상 절감이 실제로 나오는가? (Codex의 토큰 단가 × 사용량 vs 직전 Claude 사용량)
- Skill 의존하던 작업의 품질이 떨어지지 않았는가? (대체 옵션 재조정 필요)
- 팀원의 "그냥 Claude로 돌아가고 싶다" 빈도 — 3회 이상 발생하면 하이브리드 비율 재조정.
7단계: 롤백 가능 상태 유지
`.claude/` 디렉토리는 삭제하지 말고 압축 보관한다. 마이그레이션이 ROI 마이너스로 판명되면 즉시 되돌릴 수 있어야 한다.
```bash
tar -czf migration/claude-config-backup-$(date +%Y%m%d).tar.gz .claude/
```
마이그레이션 후 흔한 실패 4가지
- "Skills 없어도 되겠지" → 일주일 안에 컨벤션 일관성 깨짐. 핵심 3~5개는 반드시 `AGENTS.md`에 포함.
- Hooks 의존 자동화 방치 → 자동 커밋·자동 검증 등이 조용히 빠지면서 디버깅 가능 정보 손실. 5단계 외부 wrapper 패턴 적용 필수.
- MCP 서버 호환성 가정 → 일부 MCP 서버는 Claude 전용 API 패턴 사용. 마이그레이션 전 각 MCP 서버의 Codex 호환성 개별 확인.
- "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로 돌아오거나 하이브리드로 재구성합니다.