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

Why Teams Are Making the Move

비용이 동기의 핵심이다. Claude Code 비용의 60% 이상이 일상적인 코드 편집·리뷰에서 발생한다면, Codex의 GPT-5-codex 모델이 단가 우위를 보인다. 여기에 벤더 락인을 줄이고 싶은 전략적 의도까지 더해지면 마이그레이션 의사결정은 간단해진다. 그러나 세 가지 질문 중 하나라도 "아니오"라면 통짜 마이그레이션보다 하이브리드 분기 사용이 더 현실적이다—현재 Claude Code 비용의 60% 이상을 일상 코딩에서 쓰고 있는지, Skills·Hooks·서브에이전트 같은 고유 기능에 의존하지 않는지, 멀티 벤더 운영의 관리 비용을 감당할 수 있는지가 그 판단 기준이다.

The Three Biggest Gaps

마이그레이션의 실제 장벽은 세 곳에만 집중된다. 첫 번째, Skills—Claude Code에서 "필요할 때 자동 로드되는 작업 패턴 가이드" 역할을 하는 이 메커니즘은 Codex에 동등한 개념이 없다. 두 번째, Hooks—PreToolUse, SessionStart, UserPromptSubmit 같은 라이프사이클 이벤트 기반 자동화가 Codex에서는 동작하지 않는다. 세 번째, 서브에이전트—Claude의 Agent tool로 구현하는 하위 에이전트 패턴은 Codex에서 외부 오케스트레이션을 별도로 구축해야 한다. 이 세 가지(Skills·Hooks·서브에이전트)에 깊이 의존하는 팀은 마이그레이션 ROI가 마이너스로 나올 확률이 높다. 반면 컨벤션 파일(CLAUDE.md → AGENTS.md), 슬래시 커맨드, MCP 서버 설정 등은 자동 변환 툴로 빠르게 처리할 수 있는 영역이다.

The 7-Step Migration Playbook

1단계: 자산 인벤토리(1일). .claude/ 디렉토리 전체를 추출하고, CLAUDE.md, hook 설정, MCP 서버 목록을 migration/inventory.txt에 기록한다. "그냥 옮기면 되겠지"는 거의 반드시 일주일 후 장애로 돌아온다. 2단계: claude2codex 자동 변환 적용(반나절). 오픈소스 claude2codex 툴이 CLAUDE.md → AGENTS.md, 슬래시 커맨드 → CLI 별칭, MCP 서버 설정 → Codex 호환 포맷을 자동으로 처리한다. 다만 Skills와 Hooks는 1:1 대응 개념이 없어 변환하지 않으므로 다음 단계에서 수동 대체해야 한다. 3단계: Skills 대체 전략 결정(2~3일). 옵션 A—핵심 Skill 3~5개를 AGENTS.md 부록에 항상 로드(토큰 비용 증가), 옵션 B—prompts/ 디렉토리에 두고 --load-prompt로 온디맨드 주입, 옵션 C—트리거 wrapper 스크립트로 자동 주입. 대부분 팀에는 A+B 조합이 현실적이다. 4단계: Hooks 대체(2일). 핵심 원칙은 "Codex 안에서 처리"가 아니라 "Codex 호출 전후에 외부에서 처리"로 패러다임을 옮기는 것이다. 세션 시작 시 컨텍스트 로딩은 쉘 별칭으로, 도구 호출 전 권한 검사는 --require-approval 정책으로, 자동 commit/push는 Codex 종료 후 git hook 또는 CI 스크립트로 대체한다. 5단계: 하이브리드 분기 패턴(선택). 워크로드별로 도구를 나누는 것이 실측상 가장 큰 비용·품질 개선을 낸다. Claude Code 유지 대상: 아키텍처 설계, 멀티파일 리팩토링, Skills·Hooks 의존 워크플로우, 한국어 문서 작성. Codex 전환 대상: 일상적 코드 편집·디버깅, 단위 테스트 생성, 짧은 함수 작성.

Common Failures to Avoid

"Skills 없어도 되겠지" → 일주일 안에 컨벤션 일관성 깨짐. 핵심 3~5개는 반드시 AGENTS.md에 포함해야 한다. "Hooks 의존 자동화 방치" → 자동 커밋·자동 검증이 조용히 빠지면서 디버깅 정보 손실 발생. 외부 wrapper 패턴 적용이 필수다. MCP 서버 호환성을 가정하지 말고 각 서버의 Codex 호환성을 개별 확인해야 하며, "Codex가 더 싸니까 막 쓰자"는 호출 빈도 증가로 오히려 비용이 폭증하는 함정이다. 6단계: 일주일 점검 체크리스트. 마이그레이션 직후 일주일은 거의 확실히 무언가가 깨진다. 자동화 파이프라인 실행 여부, 실제 비용 절감 발생 여부, Skill 의존 작업 품질 저하 여부, 팀원의 "Claude로 돌아가고 싶다" 빈도를 매일 확인해야 한다. 3회 이상 발생하면 하이브리드 비율 재조정이 필요하다. 7단계: 롤백 가능 상태 유지. .claude/ 디렉토리는 삭제하지 말고 tar -czf migration/claude-config-backup-$(date +%Y%m%d).tar.gz .claude/로 압축 보관한다. 마이그레이션 후 약 20%의 AI-Native 팀이 6주 안에 Claude로 돌아가거나 하이브리드로 재구성하므로, 즉시 되돌릴 수 있는 상태를 유지하는 것이 필수다.

Key Takeaways

  • Skills·Hooks·서브에이전트 의존도가 높은 워크플로우는 통짜 마이그레이션보다 하이브리드가 유리
  • claude2codex 자동 변환은 전체 작업의 약 절반만 처리, 나머지는 수동 대체 전략 필요
  • "3,000 토큰 이하 단순 작업 = Codex, 그 외 = Claude" 휴리스틱이 의사결정 비용을 최소화
  • 마이그레이션 후 안정화에는 최소 2주 소요, 첫 주는 깨진 자동화 복구로 소비됨

The Bottom Line

Claude Code에서 Codex로의 마이그레이션은 단순 CLI 교체가 아니다. 확장 메카니즘이 도구 안(Skills/Hooks)에 있느냐, 도구 밖(외부 wrapper)에 있느냐의 패러다임 차이다. 이 본질적 차이를 인지하고iqa하면 실패율은 크게 떨어진다. 자동 변환 툴로 첫 절반을 빠르게 처리하고, Skills·Hooks 대체는 각 팀 워크플로우 분석으로 해결하는 7단계 접근법이 가장 현실적인 경로다.