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

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.

3단계 보강: Skill 하나를 실제로 옮겨 보기

옵션만 고르고 나면 다음 질문이 바로 온다 — 그래서 파일을 어떻게 바꾸는가. Skill 한 개를 끝까지 변환해 보면 나머지는 복제다.

Claude Code 쪽 원본은 이런 구조다.

.claude/skills/pr-review/
├── SKILL.md          ← 프론트매터 + 본문
└── checklist.md      ← 본문이 참조하는 부속 파일

SKILL.md 는 프론트매터로 언제 로드될지를 선언한다. 이게 Codex 로 옮길 때 사라지는 부분이다.

---
name: pr-review
description: PR 리뷰 요청이 오면 이 절차를 따른다
---

1. 변경 파일 목록을 먼저 뽑는다
2. checklist.md 의 8개 항목을 파일별로 대조한다
3. 지적은 파일:줄 형식으로 남긴다

AGENTS.md 부록으로 옮길 때는 프론트매터의 description 을 본문 조건문으로 바꾸는 것이 핵심이다. 자동 로딩이 없으니 조건을 사람이 읽을 문장으로 적어야 모델이 그때만 따른다.

## 부록 A — PR 리뷰 절차

**PR 리뷰를 요청받았을 때만 이 절을 따른다. 그 외 작업에서는 무시한다.**

1. 변경 파일 목록을 먼저 뽑는다
2. 아래 8개 항목을 파일별로 대조한다
   (원래 checklist.md 였던 내용을 여기 인라인으로 붙인다)
3. 지적은 파일:줄 형식으로 남긴다

변환에서 실제로 손이 가는 곳은 세 가지다.

부속 파일 인라인화가 토큰 비용의 주범이다. Skill 이 5개인데 각각 부속 파일을 2개씩 달고 있으면 AGENTS.md 가 수천 토큰으로 불어나고, 그게 매 요청에 실린다. 그래서 Tier-0 3~5개만 A 옵션으로 올리고 나머지는 B 옵션(on-demand) 으로 두라는 앞의 권고가 나온다.

한 가지 현실적인 절충이 있다. Skill 본문을 그대로 두고 AGENTS.md 에는 목록과 조건만 적는 방식이다.

## 부록 A — 작업별 참조 문서

아래 상황이면 해당 파일을 먼저 읽고 그 절차를 따른다.

- PR 리뷰 요청 → `prompts/pr-review.md`
- 배포 작업 → `prompts/deploy.md`
- 장애 대응 → `prompts/incident.md`

이러면 상시 토큰은 몇십 토큰으로 줄고, 모델이 스스로 파일을 읽는다. 자동 로딩만큼 확실하지는 않지만 비용 대비 적중률이 가장 좋은 지점이었다.

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/

서브에이전트는 어떻게 대체하나

앞 비교표에서 난이도 「높음」으로 꼽은 셋 중 Skills·Hooks 는 위에서 다뤘다. 남은 하나가 서브에이전트다. 실무에서는 이쪽이 가장 크게 체감된다 — 병렬 탐색과 컨텍스트 격리가 한꺼번에 사라지기 때문이다.

Claude Code 의 서브에이전트가 실제로 주는 것은 두 가지다.

1. 컨텍스트 격리 — 서브에이전트가 파일 20개를 읽어도 그 내용이 메인 대화에 쌓이지 않는다. 결론만 돌아온다.
2. 병렬 실행 — 독립적인 탐색을 동시에 던진다.

Codex 에는 이에 대응하는 1급 기능이 없으므로 바깥에서 만들어야 한다. 세 가지 방식이 있고, 잃는 것이 각각 다르다.

대부분의 팀에는 세 번째가 답이다. 서브에이전트를 쓰던 작업의 상당수는 "코드베이스에서 관련 지점을 찾아라"인데, 그건 원래 검색으로 푸는 문제였고 에이전트가 편해서 쓰던 것이다. 범위를 먼저 좁히면 단일 세션으로도 충분하다.

두 번째가 필요한 경우는 분명하다 — 결론이 서로 독립인 작업이 5개 이상 동시에 있을 때다. 코드 리뷰를 관점별로 나누거나, 여러 모듈을 같은 기준으로 감사하는 작업이 그렇다. 이때는 셸 스크립트로 프로세스를 띄우고 각 출력을 파일로 받아 마지막에 합치는 구조가 된다. 구현은 반나절이면 되지만, 실패한 프로세스를 어떻게 다룰지를 정해 두지 않으면 부분 결과로 잘못된 결론을 낸다.

첫 번째는 임시 방편이다. 옮긴 직후 한두 주는 이걸로 버티면서 실제로 서브에이전트가 필요한 작업이 무엇인지 세어 보길 권한다. 세어 보면 생각보다 적다. 그 목록이 나온 뒤에 두 번째를 만들지 결정하는 편이 낫다.

마이그레이션 후 흔한 실패 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배 빠른 납기를 만듭니다.