Claude Code에서 Codex로 갈아타는 전략 7가지

Claude Code에서 Codex로 갈아타는 전략 7가지

AI 코딩 에이전트를 갈아탈 때 진짜 삽질은 프롬프트를 다시 쓰는 데서 끝나지 않는다. 오히려 더 위험한 구간은 설정, 권한, 외부 도구 연결, 자동 실행 규칙을 옮기는 순간에 생긴다. 평소에는 잘 보이지 않던 작은 설정 하나가 파일 삭제 권한, 배포 스크립트 실행, 사내 문서 접근, 이슈 트래커 호출 같은 실제 행동으로 이어지기 때문이다.

내 판단은 이렇다. Codex 앱의 “Migrate to Codex” 기능은 Claude Code에서 쓰던 설정을 Codex로 옮길 때 반복 작업을 크게 줄여준다. 그러나 이 기능을 “마이그레이션 완료 버튼”으로 보면 위험하다. 더 정확히는 “검수 가능한 초안을 만들어주는 기능”에 가깝다. 특히 권한, MCP, hooks, skills와 agents처럼 실행 흐름에 직접 영향을 주는 항목은 자동 변환 이후 반드시 사람이 확인해야 한다.

왜 지금 이 기능을 봐야 하나

OpenAI는 2026년 6월 9일 Codex app 26.608 변경 내역에서 “Migrate to Codex” 흐름을 추가했다고 밝혔다. Codex 앱의 Settings > General > Import other agent setup에서 다른 에이전트 설정을 가져오는 방식이다. 공식 문서 기준으로 Claude Code와 Claude Cowork 설정 가져오기를 지원한다.

이 기능이 중요한 이유는 명확하다. Claude Code를 이미 꽤 깊게 쓰던 사람일수록 단순한 지시문 몇 줄만 갖고 있지 않다. 프로젝트 지침 파일, 사용자 설정, MCP 서버, hooks, slash commands, subagents, 최근 세션까지 작업 습관 전체가 설정에 묻어 있다. 이걸 수동으로 다시 구성하면 빠뜨리기 쉽고, 빠뜨린 사실도 실제 작업 중에야 드러난다.

다만 적용 범위는 분명히 잡아야 한다. 이 글에서 다루는 기능은 Codex 앱 중심의 가져오기 흐름이다. Codex CLI만 쓰는 독자라면 같은 메뉴와 경험을 그대로 기대하면 안 된다. CLI 환경에서도 설정을 참고해 수동 이관할 수는 있겠지만, 여기서 말하는 “Migrate to Codex” 버튼 기반 흐름과는 다르다.

자동으로 가져오는 것과 검수해야 하는 것

공식 마이그레이션 문서에 따르면 Codex는 Claude Code 쪽의 여러 항목을 Codex 형식으로 변환한다. 핵심 매핑은 다음처럼 이해하면 된다.

Claude Code 쪽 항목	Codex 쪽 변환 대상	검수 포인트
instruction files, 예: CLAUDE.md	AGENTS.md	프로젝트 지침의 우선순위, 금지 작업, 빌드·테스트 명령이 그대로 의미를 유지하는지 확인
settings.json	config.toml	권한, 승인 정책, 모델·환경 설정이 Codex 실행 방식에 맞게 해석되는지 확인
MCP config	Codex MCP config	인증 토큰, 서버 주소, 도구 스키마, 접근 범위가 실제로 동작하는지 확인
hooks	Codex hooks	작업 전후 자동 실행 규칙이 Codex의 이벤트 흐름에서 같은 의미인지 확인
slash commands	Codex skills	명령어가 단순 텍스트 치환인지, 실제 파일·명령 실행을 포함하는지 확인
subagents	Codex agents	별도 context, tool, permissions가 안전하게 분리되는지 확인
recent sessions	최근 30일 세션	참고용 맥락으로만 보고, 운영 설정으로 착각하지 않기

여기서 MCP는 외부 도구와 데이터에 연결하기 위한 프로토콜이다. 예를 들어 GitHub, 이슈 트래커, 사내 문서, 데이터베이스 조회 도구를 에이전트가 호출하게 만드는 연결 계층으로 보면 된다. hooks는 작업 전후에 자동으로 실행되는 규칙이다. 예를 들어 파일 수정 전 경고를 띄우거나, 작업 후 포맷터와 테스트를 돌리거나, 특정 명령 실행을 막는 식의 자동화가 여기에 해당한다.

문제는 이 항목들이 단순 설정 파일이 아니라 실제 행동의 경로라는 점이다. AGENTS.md로 지침이 옮겨졌다고 해서 팀의 의도가 완전히 옮겨진 것은 아니다. config.toml이 만들어졌다고 해서 권한 정책이 안전하다는 뜻도 아니다. MCP 설정이 들어왔다고 해서 인증이 정상이고, 접근 범위가 적절하며, 민감한 도구가 과하게 노출되지 않았다는 뜻도 아니다.

Import 성공은 운영 가능과 다르다

내가 보기엔 이 기능을 가장 안전하게 쓰는 관점은 “잘 옮겼나?”가 아니라 “이 상태로 실행해도 안전한가?”다. 마이그레이션 도구는 형식을 바꿔줄 수 있다. 그러나 조직이나 개인이 어떤 위험을 감수할 수 있는지까지 판단하지는 못한다.

예를 들어 Claude Code의 hooks에서 테스트 명령을 자동으로 실행하던 규칙이 있었다고 하자. 이 규칙이 Codex hooks로 변환된 것 자체는 편리하다. 하지만 그 hook이 실제로 어떤 디렉터리에서 실행되는지, 실패 시 작업을 멈추는지, 네트워크나 배포 명령까지 건드리는지 확인하지 않으면 위험하다. 특히 기존에는 수동 승인 아래에서만 실행되던 명령이 새 환경에서는 더 넓은 권한으로 실행될 수 있다면, 마이그레이션은 생산성 개선이 아니라 사고 지점이 된다.

또 하나 주의할 점은 one-to-one mapping이 없는 항목이다. OpenAI는 공식 curated skill로 migrate-to-codex를 제공하며, 자동 매핑이 깔끔하지 않은 항목의 후속 정리를 돕는 경로를 안내한다. 이 말은 곧 모든 설정이 100% 자동 변환된다고 기대하면 안 된다는 뜻이다. 자동 가져오기가 끝난 뒤에도 사람이 읽고, 실행하고, 실패를 관찰하고, 필요한 경우 추가 마이그레이션을 해야 한다.

마이그레이션 후 꼭 검수할 7가지

1. AGENTS.md에 옮겨진 지침이 실제 작업 기준으로 충분한가

Claude Code의 CLAUDE.md나 instruction files는 Codex에서 AGENTS.md로 옮겨질 수 있다. 여기서는 단순히 파일이 존재하는지보다 내용의 작동 방식을 봐야 한다. 프로젝트 구조 설명, 코딩 스타일, 테스트 명령, 금지 명령, 배포 주의사항, 보안 규칙이 빠지지 않았는지 확인한다.

특히 “절대 실행하지 말 것”, “사용자 확인 전 배포 금지”, “마이그레이션 파일 자동 생성 금지” 같은 문장은 Codex가 실제로 참고할 수 있는 위치와 표현으로 남아 있어야 한다. 내 판단은 지침 파일 검수의 핵심이 문장 수가 아니라 실행 가능성이라는 점이다. 모호한 원칙보다 “수정 후 npm test 실행”, “프로덕션 DB 접속 금지” 같은 명확한 규칙이 더 중요하다.

2. config.toml의 권한과 승인 정책을 보수적으로 다시 잡았는가

settings.json이 config.toml로 옮겨졌다면 가장 먼저 볼 곳은 권한과 승인 정책이다. 파일 쓰기, 셸 명령 실행, 네트워크 접근, 특정 디렉터리 접근이 어떤 수준으로 열려 있는지 확인해야 한다. 기존 Claude Code 설정에서 안전했던 값이 Codex에서도 같은 위험 수준이라는 보장은 없다.

처음에는 과감한 자동 실행보다 보수적인 승인 흐름이 낫다. 읽기는 넓게 허용하더라도 쓰기와 명령 실행은 좁게 시작하는 편이 안전하다. 특히 rm, 배포, 데이터베이스 마이그레이션, 토큰 출력, 클라우드 리소스 변경과 관련된 명령은 명시적으로 막거나 승인 대상으로 두는 것이 좋다.

3. MCP 인증과 도구 범위가 실제로 맞는가

MCP 설정은 가져왔다고 끝나지 않는다. 서버 주소, 실행 명령, 환경 변수, 인증 토큰, OAuth 상태, 로컬 소켓, 컨테이너 경로가 새 환경에서 그대로 맞는지 확인해야 한다. 마이그레이션은 설정의 형태를 옮길 수 있지만, 만료된 토큰을 살려내거나 로컬 경로 차이를 자동으로 해결한다고 기대하면 안 된다.

검수할 때는 MCP 도구 목록을 확인하고, 민감한 도구를 먼저 분류한다. 읽기 전용 도구, 쓰기 가능한 도구, 외부 시스템을 변경하는 도구를 나눈다. 그다음 가장 안전한 읽기 호출부터 테스트한다. 이슈 목록 조회나 문서 검색처럼 부작용이 없는 호출이 성공한 뒤에야 쓰기 도구를 검토하는 순서가 맞다.

4. hooks가 같은 타이밍과 같은 권한으로 실행되는가

hooks는 작업 전후 자동 실행 규칙이다. 편리하지만 사고를 만들기도 쉽다. Claude Code의 hook lifecycle과 Codex hooks의 이벤트 흐름이 완전히 동일하다고 가정하면 안 된다. 언제 실행되는지, 어떤 입력을 받는지, 실패하면 작업이 중단되는지, 어떤 권한으로 명령을 실행하는지 확인해야 한다.

특히 pre-command, post-edit, post-task 성격의 자동화는 작은 차이가 크다. 포맷터 실행은 대체로 안전하지만, 자동 커밋, 자동 푸시, 자동 배포, 데이터 정리 스크립트 실행은 별도 검수 대상이다. 첫 마이그레이션 직후에는 hooks를 전부 켜고 큰 작업을 시키기보다, 로그를 남기는 방식으로 한 번씩 동작을 확인하는 편이 낫다.

5. slash commands가 skills로 바뀌며 의미가 달라지지 않았는가

Claude Code의 slash commands는 Codex skills로 옮겨질 수 있다. 여기서도 이름과 파일만 확인하면 부족하다. 어떤 명령어가 단순 템플릿인지, 실제 명령 실행을 유도하는지, 여러 파일을 한꺼번에 수정하는지, 외부 도구를 호출하는지 확인해야 한다.

예를 들어 /fix-tests 같은 명령이 있었다면 Codex skill로 옮겨진 뒤에도 테스트 실패 로그를 읽고, 최소 수정하고, 다시 테스트하는 흐름이 유지되는지 봐야 한다. 반대로 /deploy-preview처럼 외부 시스템에 영향을 주는 명령은 기본 비활성화하거나 승인 단계를 넣는 편이 안전하다. 기술적으로 옮겨졌는지보다 운영상 허용 가능한지 판단해야 한다.

6. subagents가 agents로 바뀔 때 context와 permissions가 분리되는가

Claude Code의 subagents는 별도 context, tool, permissions를 가질 수 있다. Codex agents로 옮겨질 때 이 분리가 제대로 유지되는지 확인해야 한다. 역할 이름만 옮겨지고 실제 권한 경계가 흐려지면 위험하다.

예를 들어 코드 리뷰 전용 agent는 읽기와 코멘트 중심이면 충분하다. 빌드 수정 agent는 파일 쓰기와 테스트 실행이 필요할 수 있다. 릴리스 준비 agent는 changelog와 버전 파일을 만질 수 있지만 배포 명령은 막아야 할 수 있다. 이렇게 역할별 권한을 다시 나누지 않으면 “전문화된 에이전트”가 아니라 “권한이 넓은 자동 실행 단축키”가 된다.

7. 최근 30일 세션을 맥락으로만 취급하는가

공식 문서상 recent sessions는 last 30 days, 즉 최근 30일 기준으로 가져올 수 있다. 이 데이터는 이전 작업 흐름을 회상하는 데는 도움이 된다. 하지만 설정의 근거로 삼기에는 조심해야 한다. 세션에는 임시 판단, 실패한 시도, 당시 환경에만 맞던 명령, 지금은 폐기된 결정이 섞여 있을 수 있다.

따라서 최근 세션은 “왜 이런 설정이 있었는지”를 이해하는 보조 자료로만 봐야 한다. 운영 정책, 보안 규칙, 팀 표준은 세션 로그가 아니라 명시적인 설정 파일과 문서로 확정해야 한다.

후츠릿식 안전 이관 워크플로우

내가 추천하는 순서는 빠르게 가져오되, 느리게 실행하는 방식이다. 마이그레이션 자체는 자동화의 도움을 받는다. 그러나 실제 작업 투입 전에는 작은 단위로 검증한다.

1. 현재 Claude Code 설정을 백업한다. 원본 파일을 임의로 고치지 말고, 비교 가능한 상태로 보존한다.
2. Codex 앱에서 Settings > General > Import other agent setup을 실행한다. 가져오기 대상과 범위를 확인한다.
3. 생성된 AGENTS.md와 config.toml을 먼저 읽는다. 파일 존재 여부가 아니라 위험한 권한과 누락된 지침을 찾는다.
4. MCP는 읽기 전용 호출부터 테스트한다. 인증 실패, 경로 문제, 과도한 도구 노출을 확인한다.
5. hooks는 로그 중심으로 한 번씩 실행해 본다. 자동 배포나 자동 푸시는 검수 전 비활성화한다.
6. skills와 agents는 위험도별로 분류한다. 읽기, 파일 수정, 외부 시스템 변경을 나눠 승인 정책을 다르게 둔다.
7. 작은 샘플 작업으로 end-to-end 검증한다. 예를 들어 문서 한 줄 수정, 포맷, 테스트까지의 루프를 먼저 확인한다.
8. one-to-one mapping이 안 된 항목은 후속 migrate-to-codex skill로 정리한다. 자동 변환이 애매한 부분을 그대로 방치하지 않는다.

이 흐름의 핵심은 “이관 성공”이라는 이벤트에 속지 않는 것이다. 파일이 생겼고 메뉴가 완료됐다고 해서 운영 준비가 끝난 게 아니다. 최소 한 번은 실제 저장소에서 작은 변경을 만들고, Codex가 어떤 지침을 읽고 어떤 도구를 호출하며 어떤 명령을 실행하는지 확인해야 한다.

바로 써먹는 검수 체크리스트

아래 항목에 모두 답할 수 없다면 아직 실작업에 투입하기 이르다.

• AGENTS.md에 프로젝트별 금지 작업과 필수 검증 명령이 명확히 적혀 있는가?
• config.toml의 파일 쓰기, 셸 실행, 네트워크 접근 권한이 보수적으로 설정됐는가?
• MCP 서버별 인증이 정상이며, 쓰기 가능한 도구가 과도하게 열려 있지 않은가?
• hooks가 언제, 어디서, 어떤 권한으로 실행되는지 로그로 확인했는가?
• skills로 변환된 명령 중 외부 시스템을 변경하는 항목을 별도 승인 대상으로 뒀는가?
• agents로 변환된 역할마다 context, tool, permissions 경계가 유지되는가?
• 최근 30일 세션을 정책이 아니라 참고 맥락으로만 보고 있는가?
• 자동 매핑이 안 된 항목을 별도 후속 정리 대상으로 기록했는가?

결론: 마이그레이션은 시작점이지 완료점이 아니다

Codex의 “Migrate to Codex”는 Claude Code 사용자에게 꽤 현실적인 편의 기능이다. instruction files를 AGENTS.md로, settings.json을 config.toml로, MCP config를 Codex MCP config로, hooks를 Codex hooks로, slash commands를 Codex skills로, subagents를 Codex agents로 옮겨주는 흐름은 반복 작업을 확실히 줄인다. 최근 30일 세션까지 가져올 수 있다는 점도 이전 작업 맥락을 잃지 않는 데 도움이 된다.

하지만 이 기능의 가치는 자동화 자체보다 검수 가능한 출발점을 만들어준다는 데 있다. AI 코딩 에이전트의 설정은 문서가 아니라 실행 권한의 지도다. 지도에 길이 그려졌다고 해서 그 길이 안전한지는 별개의 문제다.

내 판단은 명확하다. “Migrate to Codex”를 쓰되, 바로 큰 작업을 맡기지 말아야 한다. 먼저 권한을 좁히고, MCP를 읽기부터 확인하고, hooks를 로그로 검증하고, skills와 agents의 권한 경계를 다시 잡아야 한다. 그 다음 작은 작업으로 한 바퀴 돌려본 뒤에야 본격적인 개발 작업에 투입하는 것이 맞다. 이 정도 절차를 거치면 마이그레이션은 위험한 점프가 아니라 통제 가능한 전환이 된다.

참고 자료

• OpenAI Codex changelog: Codex 2026-06-09 app 26.608, “Migrate to Codex” flow 추가
• OpenAI Codex migration guide: Settings > General > Import other agent setup 및 항목별 매핑
• OpenAI curated skill: migrate-to-codex
• Anthropic Claude Code settings documentation
• Anthropic Claude Code memory documentation
• Anthropic Claude Code hooks documentation
• Anthropic Claude Code MCP documentation
• Anthropic Claude Code sub-agents documentation