Claude Code → Codex 마이그레이션 가이드 2026 — 7단계 절차·도구 비교

# 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 서버 목록을 전부 추출한다.

```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에 없다. 대체 방법:

핵심은 "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가지

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 팀 방법론 — 멀티 도구 운영의 조직 구조

도구를 바꾸는 이유가 성능이 아니라 자원이라면 하네스 자체를 비교해 보는 편이 빠릅니다. 세션당 메모리와 기동 시간 실측은 Claude Code RAM 사용량 비교에 정리했습니다.

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로 돌아오거나 하이브리드로 재구성합니다.

---

코딩 에이전트 전환은 도구를 바꾸는 일이 아니라 개발 루프를 다시 설계하는 일입니다. 어떤 작업을 에이전트에 맡기고 어디서 사람이 검증할지가 정해져야 속도가 납니다.

나무숲은 팀원 전원이 Claude Code Max 플랜을 기본 개발 환경으로 쓰는 AI-Native Team입니다. Brainstorming·Writing-plans·Subagent·TDD 스킬을 실전 루프에 적용해 일반 외주 대비 2~3배 빠른 납기를 만듭니다.