Claude Code에서 Codex로 마이그레이션하는 가이드 2026

2026년 5월 3일, 저는 로컬 에이전트 설정 항목 744개를 목록화한 뒤 그중 691개를 운영상 중요도에 따라 순위를 매겼어요.¹ 숫자는 커 보였지만, 더 중요한 것은 구조였어요. 대략 20개의 파일이 시스템을 떠받치고 있었어요.

Claude Code에서 Codex로 마이그레이션할 때는 파일 트리를 복사하는 대신 운영 계약을 옮겨야 해요. CLAUDE.md 규칙은 계층화된 AGENTS.md로, 재사용 가능한 절차는 Codex 스킬로, 결정론적 관문은 집중된 훅으로, 위험 태도는 프로필로, 브라우저와 소스 도구는 명시적인 MCP로 옮기세요. Claude의 훅 격자를 Codex에 그대로 복사하지 마세요. 증명 의무를 옮기세요.

요약

제 Codex 환경에는 이미 비공개 글쓰기와 검증 스택이 있어요. 부족했던 것은 스킬 내용이 아니었어요. 부족했던 것은 공개 운영 매뉴얼이었어요. 재사용 가능한 스킬이 어디에 있어야 하는지, Codex가 그것들을 어떻게 선택해야 하는지, 공개 글쓰기에는 어떤 프로필을 써야 하는지, Claude 시절의 어떤 관문을 비공개 작업 방식의 세부 내용을 드러내지 않으면서 Codex 네이티브 규칙으로 바꿔야 하는지가 빠져 있었어요.

첫 번째 실제 Codex 작업은 마이그레이션 규칙을 바꿨어요. 비공개 작업 흐름은 옮기는 순간 기본 동작으로 만들면 안 돼요. 단계적으로 올려야 해요. 제 사이트 전용 글쓰기 경로는 이제 명시적으로 호출할 때만 시작하고, 마이그레이션 작업 흐름은 실제 로컬 사용을 위한 사용자 스킬이자 로컬 테스트용 비공개 Codex 패키지 후보로 남아 있어요. 그 패키지는 오픈 소스도 아니고 일반 공개 상태도 아니에요. 마이그레이션 작업 흐름을 테스트하고 싶다면 저에게 연락하세요. 로컬 설치 항목이 있다는 이유만으로 그 패키지가 기본 실행 경로가 되어서는 안 돼요. 의미 있는 설치 파일럿이 되려면 패키지 검증, 플러그인 설치 확인, 네임스페이스가 붙은 스킬 발견, 중복 정리, 새 Codex 작업 맥락이 아직 필요해요. 그래야 어떤 작업 흐름이 기본 동작이 되기 전에 시스템이 실제 작업에서 배울 수 있어요.¹⁸¹⁰¹⁴

모든 Claude 훅을 Codex에 복제하는 것부터 시작하지 마세요. Codex 계약을 쓰는 것부터 시작하세요.

• 오래 유지될 저장소 공통 정책은 ~/.codex/AGENTS.md에 두세요.
• 저장소 정책은 AGENTS.md에 두고, 더 좁은 덮어쓰기는 작업 위치 가까이에 두세요.
• 재사용 가능한 절차는 .agents/skills 또는 $HOME/.agents/skills에 두세요.
• 공개 글쓰기는 careful-review 또는 전용 public-writing 프로필로 승격하세요.
• 결정론적 관문은 훅으로 유지하되, 훅을 안전 모델 전체가 아니라 하나의 가드레일로 다루세요.

첫 번째 성공적인 마이그레이션 산출물은 스스로를 설명할 수 있는 글이어야 해요. 이 산출물은 시스템이 자기 자신을 설명하고, 최신 문서를 인용하고, 정제된 로컬 목록을 사용하고, 그 뒤의 비공개 장치를 공개하지 않은 채 Codex 제어 아래에서 공개 작업을 만들 수 있음을 증명해요.

저는 스택의 Claude 쪽을 인프라로서의 Claude Code에서, 지시 파일 쪽을 AGENTS.md 패턴에서, 스킬 부패 문제를 정적 스킬은 죽은 스킬입니다에서 다뤘어요. 아래 마이그레이션은 그 글들의 흐름을 제가 실제로 쓰는 Codex 실행 환경과 연결해요.

관련 배경으로는 Codex CLI 가이드, Claude Code 대 Codex, Codex 대 Claude Code 2026, Claude Code 훅 튜토리얼, 사용자 지정 스킬 만들기, Jiro 품질 철학을 읽어보세요. 이 글들은 여기서 조립하는 마이그레이션의 부품들을 설명해요.

마이그레이션 목록화에서 무엇을 확인했나요?

로컬 시스템에는 3개의 무게중심이 있었어요.

사용 데이터도 같은 결론을 가리켰어요. 제 프로필 라우팅 로그에서는 검토가 많은 작업이 일상적인 실행의 대부분을 차지했어요.¹ 진짜 핵심은 가장 긴 파일도, 가장 영리한 스크립트도 아니었어요. 핵심은 위험 수준을 고르고, 철학을 불러오고, 완료 전에 증거를 강제하는 결정 계층이었어요.

이 발견은 이전 방식 자체를 바꿔요.

중요한 사실이 “Claude에는 훅이 많다”였다면 마이그레이션은 훅을 복사했을 거예요. 중요한 사실이 “시스템에는 철학이 있다”였다면 마이그레이션은 산문을 복사했을 거예요. 하지만 목록화 결과는 다른 답을 보여줬어요. 중요한 것은 알맞은 순간에 작동하는 작은 계약이에요.

공개하기 전에 무엇을 했나요?

이 글 자체가 첫 번째 마이그레이션 연습이 되었어요.

먼저 성숙한 Claude Code 설정의 구조를 매핑했어요. 어떤 부분이 동작을 지배하는지, 어떤 부분은 선호를 문서화할 뿐인지, 어떤 부분은 비공개로 남아야 하는지를 구분했어요. 그다음 현재 Codex 동작을 공식 문서와 로컬 CLI에 대조했어요. 마이그레이션 가이드는 오래된 플래그나 지원되지 않는 설정 형태를 물려받으면 금방 낡기 때문이에요. 그런 뒤 실제 마이그레이션을 염두에 두고 이 글을 초안으로 썼지만, 공개 세부 내용은 정제된 아키텍처로 줄이고 비공개 구현은 제외했어요.

다음 단계는 발행 전에 일어나요. 이 가이드를 사용해 Codex 설정을 구축한 뒤, 실제로 바뀐 내용을 바탕으로 글을 수정하는 것이에요. 공개 글은 마이그레이션 패턴과 수락 기준을 보여줘야 해요. 비공개 프롬프트, 비공개 글쓰기 작업 흐름, 정확한 훅 내부 구조, 민감한 경로, 독자가 비공개 시스템을 재구성할 수 있게 만드는 내용은 공개하면 안 돼요.

실제 작업은 공개해도 안전한 증명 표를 만들었어요. 저는 비공개 프롬프트, 정확한 훅 본문, 글쓰기 작업 흐름 내부가 아니라 계약, 활성화 상태, 수락 신호만 공개해요.

Codex 마이그레이션을 훅으로 시작해야 할까요?

Claude은 저에게 생명주기 이벤트로 생각하는 법을 가르쳤어요. UserPromptSubmit 훅은 프로젝트 맥락을 주입할 수 있어요. PreToolUse 훅은 민감한 경로를 차단할 수 있어요. Stop 훅은 약한 완료를 거부할 수 있어요. 이 패턴은 Claude에서 잘 작동해요. 제 로컬 스택이 여러 작은 스크립트를 하나의 순서 있는 이벤트 파이프라인으로 바꾸는 디스패처를 중심으로 자랐기 때문이에요.¹¹

Codex에도 훅이 있어요. 하지만 현재 Codex는 훅을 항상 켜진 훅 디렉터리가 아니라 기능 플래그가 걸린 생명주기 시스템으로 다뤄요. OpenAI 훅 문서는 config.toml에 [features] codex_hooks = true를 보여주고, 제 로컬 codex features list는 Codex CLI 0.130.0에서 hooks가 안정 상태이고 활성화되어 있다고 보고해요.²⁸ OpenAI는 훅 입력을 stdin의 JSON으로 문서화하며, 세션 ID, 작업 디렉터리, 이벤트 이름, 활성 모델 같은 공통 필드를 설명해요.² Codex는 SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop 같은 이벤트를 지원해요. PreToolUse는 Bash, apply_patch, MCP 도구 호출을 가로챌 수 있어요.²

같은 문서에는 마이그레이션에서 중요한 경고도 있어요. PreToolUse는 여전히 가드레일이지 완전한 강제 경계가 아니에요. 문서는 가로채기가 모든 셸 경로를 포괄하지 않으며, 웹 검색이나 다른 비셸, 비MCP 도구 호출을 가로채지 않는다고 설명해요.²

이 제한이 Codex 훅을 약하게 만들지는 않아요. 다만 훅이 전체 이전을 짊어져서는 안 된다는 뜻이에요. OpenAI는 같은 이벤트에 대해 여러 일치 명령 훅이 동시에 실행된다고도 말해요. 따라서 순서가 필요한 Codex 이전에는 여전히 디스패처 또는 하나의 결합 훅 명령이 필요해요.²

Codex에서는 좁고 결정론적인 확인에 훅을 쓰고 싶어요.

• 명백히 파괴적인 셸 명령을 차단하기.
• 자격 증명처럼 보이는 경로에 경고하기.
• 작은 세션 시작 맥락을 추가하기.
• 공개 글쓰기 실행의 증거를 기록하기.
• 필요한 산출물이나 검증 명령이 없을 때 stop 이벤트를 실패시키기.

글쓰기 목소리, 인용 정책, 철학, 라우팅, 프로젝트 원칙을 훅에 맡기고 싶지는 않아요. Codex에는 이미 그것들에 더 나은 자리가 있어요.

Claude 산출물은 Codex에서 어디로 가야 하나요?

각 Claude 산출물을 그 역할에 가장 잘 맞는 Codex 기본 요소로 옮기면 마이그레이션이 훨씬 깔끔해져요.

OpenAI의 AGENTS.md 문서는 첫 번째 행을 마이그레이션의 척추로 만들어요. Codex는 작업 전에 AGENTS.md 파일을 읽고, Codex 홈 디렉터리의 전역 지침을 계층화한 뒤, 프로젝트 루트에서 현재 디렉터리까지 걸어가며 더 가까운 파일이 이전 지침을 덮어쓰게 해요.³ 이 동작은 제가 CLAUDE.md에서 실제로 필요로 하는 것과 맞아요. 지속적인 작업 합의와 프로젝트 로컬 세부 사항이에요.

중요한 움직임은 규칙을 운영 방식으로 다시 쓰는 거예요. “신중하게 써라”는 AGENTS.md에 어울리지 않아요. “공개 글은 인용을 먼저 모으고, URL을 검증하고, 금지 문구 검사를 실행하고, 검증되지 않은 주장을 보고하라”는 거기에 어울려요.

비공개 글쓰기 스킬은 Codex로 어떻게 옮겨야 하나요?

블로그 작성자 스택은 이미 올바른 형태를 갖고 있어서 깔끔하게 이전돼요. Codex 스킬은 frontmatter와 지침이 들어 있는 SKILL.md 파일을 가진 폴더예요. Codex는 사용자가 스킬을 명시적으로 호출하거나 작업이 스킬 설명과 맞을 때 스킬을 활성화할 수 있어요.⁴ Codex는 저장소, 사용자, 관리자, 시스템 위치에서 스킬을 읽어요. 여기에는 repo .agents/skills, $HOME/.agents/skills, /etc/codex/skills가 포함돼요.⁴

여기서 Claude Code 마이그레이션은 미묘하게 잘못될 수 있어요. Codex 스킬은 Claude slash 명령이 아니에요. 명시적 호출을 위한 공식 Codex 스킬 경로는 스킬 선택기 또는 $skill-name 언급이에요. 반면 Codex CLI slash 명령은 상태, 권한, 모델 변경, 플러그인, 세션 제어 같은 내장 동작을 위한 별도의 대화형 제어 표면이에요.⁴¹⁵ /cave 같은 프롬프트는 스킬 설명이 그것을 인식하거나 래퍼가 Use $cave ...로 바꾸면 여전히 유용한 줄임말이 될 수 있어요. 하지만 slash 텍스트 자체가 오래갈 계약은 아니에요. 마이그레이션 증명에서는 $skill-name을 테스트하세요. 그런 다음 그 호환성을 약속하려면 /name을 별도로 테스트하세요.

즉 새 Codex 네이티브 글쓰기 스킬은 비공개 스킬 이름이나 내용을 공개하지 않은 채 공식 스킬 경로로 정규화해야 해요.

$HOME/.agents/skills/source-verifier/SKILL.md
$HOME/.agents/skills/public-post-writer/SKILL.md
$HOME/.agents/skills/site-specific-writer/SKILL.md

제 로컬 실행 환경에는 이전 위치의 작동 중인 사용자 스킬도 있어요.¹ 공개 문서가 .agents/skills를 말한다고 해서 그것들을 바로 지우면 안 돼요. 안전한 마이그레이션은 다음과 같아요.

1. 하나의 스킬을 $HOME/.agents/skills로 복사하거나 symlink하세요.
2. Codex를 다시 시작하세요.
3. Codex가 스킬을 나열하고 활성화하는지 확인하세요.
4. 파일럿 중에는 스킬을 명시적 호출 전용으로 만드세요.
5. 발견과 파일럿 사용이 작동한 뒤에만 나머지를 옮기세요.
6. 기존 세션과 스크립트가 더 이상 의존하지 않을 때까지 이전 경로를 남겨두세요.

저는 첫 번째 비공개 글쓰기 작업 흐름에 이 경로를 택했어요. 사이트 전용 writer를 모든 콘텐츠 작업의 기본 writer로 만들기보다 명시적 호출 전용 비공개 스킬로 단계화했어요. 그래서 마이그레이션은 더 나은 테스트를 갖게 되었어요. 그 스킬이 비공개 과정을 새어 나가게 하지 않으면서 이 글과 다음 공개 글쓰기 실행을 개선한다면 명시적 호출 전용에서 파일럿으로 옮길 수 있어요. 혼란을 더한다면 범위를 좁힌 상태로 남아요.

브랜드별 writer는 기본 사이트 writer가 되면 안 돼요. 비공개 제품 writer가 같은 인용과 검토 기준을 공유할 수는 있지만, 독자, 제품 사실, 행동 유도, 목소리 규칙은 해당 제품에 묶여 있어야 해요. 올바른 이전은 브랜드 어댑터를 분리해 두고 blakecrosley.com을 위한 얇은 site-specific writer를 만드는 것이에요.

그 사이트용 스킬은 얇게 유지해야 해요.

---
name: site-specific-writer
description: Write public technical posts for a specific site. Use for articles that need verified sources, internal links, site voice, and publication checks.
---

# Site-Specific Writer

Use the private writing, source-verification, and AI-discoverability skills for every public technical article.

Required proof before final:
- External technical claims have citations.
- Current Codex claims cite OpenAI docs.
- Internal claims link to existing posts or author analysis.
- The post includes a TL;DR, role-specific takeaways, and reader questions when useful.

Codex 스킬 문서는 name과 description을 수동 스킬 frontmatter 필드로 보여주며, description이 암묵적 활성화의 트리거가 된다고 설명해요.⁴ 본문은 Codex에게 비공개 동반 스킬을 사용하라고 말할 수 있어요. 로컬 도구 체인이 추가 메타데이터를 넣지 않는 한, 조합 방식은 지침에 속해요. 일반 스택은 글쓰기 규칙을 소유해요. 사이트 래퍼는 목소리, 링크 패턴, 증명을 소유해요.

같은 분리는 마이그레이션 작업 흐름 자체에도 적용돼요. OpenAI 플러그인 문서는 아직 하나의 개인 작업 흐름을 반복 개선하는 중이라면 로컬 스킬로 시작하고, 안정된 패키지를 팀에 공유하거나 더 많은 통합을 묶고 싶을 때 플러그인을 만들라고 권해요.¹⁰ 그래서 활성 경로는 분명했어요. 먼저 사용자 스킬, 그다음 비공개 패키지 파일럿이에요. 저는 마이그레이션 스킬을 오픈 소스로 공개하지 않았고 공개 릴리스도 약속하지 않았어요. 테스트하고 싶다면 저에게 연락하세요. 플러그인 캐시 확인에서는 설치된 플러그인 스킬이 단독 스킬 이름이 아니라 플러그인 네임스페이스 아래에 나타난다는 것을 확인했어요. 따라서 패키지 문서는 직접 스킬 사용과 플러그인으로 설치된 스킬 사용을 구분해야 해요.⁸

비공개 패키지에는 출시 이야기보다 검증기가 먼저 필요해요. 최신 작업에서 저는 marketplace JSON, 플러그인 manifest, 스킬 frontmatter, 필수 참조, citation-checker 문법, 설치 정책, 활성 훅 또는 MCP manifest의 부재, 생성 파일, 명백한 비공개 경로 또는 secret-fixture 누출을 확인하는 검증기를 추가했어요. 이 확인은 더 넓은 활성화보다 앞에 있어야 해요. OpenAI 플러그인 문서는 marketplace를 불안정한 비공개 작업 흐름의 임시 작업장이 아니라 설치 표면으로 만들기 때문이에요.⁸¹⁰

AGENTS.md는 공개 글쓰기 규칙을 어떻게 담아야 하나요?

가장 강력한 Codex 마이그레이션 변화는 훅이 아니라 AGENTS.md에 있어요. 공개 글쓰기는 기본 위험 등급이 필요해요.

전역 또는 프로젝트 파일 상단 가까이에 두고 싶은 규칙은 이것이에요.

## Public Writing Is Product Work

Public articles, guides, landing pages, docs that shape user understanding, and product copy use `default` profile at minimum. Promote to `careful-review` when claims, citations, brand, money, safety, security, or user trust are at stake.

Before finishing public writing:
- Gather citations before drafting.
- Cite official product docs for current tool behavior.
- Label author analysis clearly.
- Run a banned-phrase scan.
- Verify internal links.
- Report any claim that could not be verified.

이 규칙은 라우터 목록화에서 발견한 결함을 고쳐요. 일부 콘텐츠 작업은 라우터가 “콘텐츠”를 값싼 작업으로 다뤘기 때문에 빠른 실행 쪽으로 흘렀어요. 공개 글쓰기는 사람들이 믿고, 사고, 설치하고, 실행하는 것을 바꿀 때 값싼 작업이 아니에요. 블로그 초안, 가이드, 제품 페이지는 일상적인 코드 편집보다 더 많은 검토를 받을 자격이 있어요. 실패 양상이 로컬 테스트 실패가 아니라 공개 신뢰의 손상이기 때문이에요.

지금 읽고 있는 글이 그 예예요. 이 글은 현재 Codex 동작에 대해 현재 Codex 문서를 인용해요. 로컬 목록화 주장을 저자 분석으로 표시해요. 마이그레이션이 빈 기계에서 시작하는 척하지 않고 실제 스택을 사용하지만, 비공개 구현 세부 내용은 공개 글 밖에 두어요.

Codex 프로필은 위험을 어떻게 표현해야 하나요?

OpenAI 설정 참조는 profile을 시작 시 기본 프로필로 정의하고, 지원되는 설정 키에 대해 프로필 범위 덮어쓰기를 지원해요.⁵ 같은 참조는 model_reasoning_effort, approval_policy, sandbox_mode를 명시적인 설정 제어로 정의해요.⁵

그래서 Codex에는 위험을 표현할 자연스러운 자리가 생겨요.

[profiles.public-writing]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "live"

정확한 모델은 바뀔 수 있어요. 정책은 바뀌면 안 돼요. 공개 글쓰기는 더 높은 추론, 사실이 바뀔 수 있을 때의 실시간 소스 확인, 작업 공간으로 제한된 실행, 안전한 작업 경로를 벗어나는 동작에 대한 사람의 승인이 필요해요.

라우터는 다음과 같은 작업을 public-writing 또는 careful-review로 매핑해야 해요.

• 블로그 글, 가이드, 홈페이지 변경.
• 인용이 있는 모든 글.
• 도구나 공급업체를 비교하는 모든 콘텐츠.
• 현재 Codex, Claude Code, OpenAI, Anthropic, Apple, Google 또는 다른 빠르게 움직이는 제품을 언급하는 글.
• 스키마, llms.txt, SEO, analytics, 공개 메타데이터를 건드리는 모든 작업.

프로필은 분위기가 아니에요. 프로필은 위험 예산이에요.

어떤 Codex 훅이 여전히 중요한가요?

Codex 훅은 런타임에서 반드시 일어나야 하는 작은 것들을 강제해야 해요.

공개 글쓰기 stop 훅은 변경된 파일을 확인하고 공개 Markdown 글에 정의 없는 각주 참조가 있으면 완료를 거부할 수 있어요. 사전 도구 훅은 에이전트가 글을 쓰는 중에 .env, analytics 자격 증명, 생성된 번역 캐시를 편집하려고 하면 경고할 수 있어요. 세션 시작 훅은 현재 날짜를 추가하고 Codex에게 “latest” 주장은 검증이 필요하다고 상기시킬 수 있어요.

훅 payload는 작게 유지하세요. OpenAI는 systemMessage, continue, 이벤트별 필드를 포함해 훅의 JSON 출력 형태를 문서화해요.² 정확한 실패를 차단하거나 경고하는 데 그 필드를 사용하세요. Codex 실패 데이터가 필요성을 증명하기 전까지는 Claude 디스패처 격자 전체를 다시 만들지 마세요.

설정 테스트만으로는 승격할 수 없어요. 훅이 파일럿에서 벗어나려면 실제 사용 관찰 패스가 3가지를 보여줘야 해요. 의도한 상황에서 작동하는지, 평범한 작업을 통과시키는지, 비공개 콘텐츠가 아니라 안전한 집계 텔레메트리를 기록하는지예요. 차단이 발생하면 이유는 사용자에게 다음에 무엇을 해야 하는지 알려줘야 해요.²⁸

첫 번째 실제 작업 이후의 실무 훅 backlog는 다음과 같아요.

1. SessionStart: 압축된 현재 날짜, 최신성, 프로젝트, 공개/비공개 경계 맥락을 파일럿으로 유지하세요.
2. PreToolUse:Bash: 좁은 파괴 명령 및 자격 증명 읽기 가드를 파일럿으로 유지하세요.
3. PostToolUse:apply_patch: 변경된 코드/설정 패치 줄에 대한 비차단 품질 shadow를 유지하세요.
4. Stop: 변경된 공개 Markdown 인용 관문을 파일럿으로 유지하세요.
5. Stop: 최종 검증 계약을 기존 quality Stop 파일럿에 접어 넣으세요. 실제 실패가 필요성을 증명하기 전까지 별도의 요약 훅을 만들지 마세요.

이 묶음은 수개월간의 Claude 전용 의식을 가져오지 않으면서 안전 동작을 옮겨요.

MCP와 브라우저 도구는 어디에 맞아야 하나요?

제 현재 Codex 설정은 이미 비공개 MCP 기반 브라우저 자동화 경로를 사용해요.¹ Codex도 CLI와 config.toml을 통해 MCP 서버를 지원해요. codex mcp add는 stdio 서버를 등록할 수 있고, [mcp_servers.<server-name>] 테이블은 command, args, environment, URLs, enabled_tools, disabled_tools, timeouts를 정의할 수 있어요.⁶

공개 글쓰기에서 MCP는 두 곳에 속해요.

• 라이브 렌더링 페이지, 스크린샷, 로컬 미리보기를 확인하는 브라우저 자동화.
• 특정 제공자가 신뢰할 수 있는 MCP 서버를 제공할 때의 소스 발견 또는 문서 검색.

MCP가 소스 추적 경로를 숨기면 안 돼요. 블로그 작성자에게는 세션 안에만 존재했던 비공개 도구 결과가 아니라 독자가 클릭할 수 있는 인용이 필요해요. MCP는 사실을 찾는 데 도움을 줄 수 있어요. 최종 글에는 여전히 공개 소스가 필요해요.

Claude Code에서 Codex로의 마이그레이션은 어떻게 시작하나요?

첫 번째 Codex 네이티브 산출물은 이전 자체를 설명하면서 그 이전을 사용해야 해요.

대화형 부트스트래핑 루프는 다음과 같아요.

codex -p careful-review --search \
  "Inventory the local Codex and Claude migration surface, then create a citation bank for a sanitized post about moving the setup to Codex."

codex -p careful-review \
  "Draft content/blog/claude-code-to-codex-migration.md using the local inventory, official Codex docs, and existing internal posts. Label author analysis clearly."

codex -p careful-review \
  "Review the draft for unsupported claims, stale Codex flags, broken internal links, and AGENTS.md operational value."

비대화형 작업에서는 codex exec를 사용하고, 대화형 --search 플래그를 복사하기보다 실시간 검색을 설정/프로필 관심사로 만드세요. OpenAI는 스크립트 또는 CI 스타일 실행을 위해 codex exec를 문서화하며, --profile, --sandbox, --config 덮어쓰기를 설명해요. 제 로컬 Codex CLI 0.130.0 도움말도 그 플래그를 확인해 주고 codex exec --search는 거부해요.⁷⁸

codex exec -p careful-review -c 'web_search="live"' \
  "Create a citation bank for content/blog/claude-code-to-codex-migration.md from official Codex docs and sanitized local inventory."

codex exec -p careful-review \
  "Review content/blog/claude-code-to-codex-migration.md for unsupported Codex claims, stale flags, broken internal links, and AGENTS.md operational value."

명령줄 세부 사항은 중요해요. OpenAI는 --full-auto를 더 이상 권장하지 않는 호환성 플래그로 표시하고 대신 --sandbox workspace-write를 권장해요.⁷ --full-auto를 중심에 둔 오래된 가이드가 새 자동화를 지배해서는 안 돼요.

이 글이 수락 테스트가 돼요. Codex가 다음을 할 수 있다면:

• 글쓰기 스킬을 불러오기.
• careful-review를 사용하기.
• 현재 OpenAI 문서를 인용하기.
• 비공개 구현 세부 내용을 노출하지 않으면서 로컬 목록을 사용하기.
• AGENTS.md, 스킬, 훅, 프로필, MCP에서 무엇이 바뀌는지 설명하기.
• 사이트 저장소에 깨끗한 Markdown 글을 만들기.

그렇다면 글쓰기 이전은 작동해요.

Claude Code에서 Codex로 마이그레이션 체크리스트

Codex 설정:

• 전역 작업 합의를 담아 ~/.codex/AGENTS.md를 추가하거나 업데이트하세요.
• 공개 글쓰기를 위한 저장소 AGENTS.md 규칙을 추가하세요.
• public-writing을 만들거나 공개 글쓰기를 careful-review로 라우팅하세요.
• careful-review가 공개 주장에 대해 실제로 high 또는 xhigh 추론을 쓰게 하세요.
• 가이드, 블로그 글, 문서, 제품 카피를 공개 표면 작업으로 다루는 라우터 규칙을 추가하세요.

스킬:

• 비공개 글쓰기 스킬을 한 번에 하나씩 $HOME/.agents/skills로 옮기거나 미러링하세요.
• 플러그인 패키지를 런타임 경로로 다루기 전에, 활발히 테스트 중인 마이그레이션 작업 흐름을 사용자 스킬로 유지하세요.
• $skill-name을 표준 명시적 호출 테스트로 사용하세요. /name은 편의 래퍼 또는 선택 습관으로만 다루고, Codex 스킬이 불러와졌다는 증거로 삼지 마세요.
• Marketplace 활성화 전에 패키지 준비도 검증기를 추가하세요.
• 승격 전에 AGENTS 참조, 프로필, 스킬, 훅, 패키지 상태, 레지스트리 형태, 활성화 상태를 증명하는 운용 체계 상태 관문을 추가하세요.
• 설치 파일럿에서는 marketplace add, 플러그인 read/install, 플러그인 listing, 스킬 listing, 새 세션 스킬 가시성, 중복 marketplace cleanup을 검증하세요.
• 암묵적 활성화를 허용하기 전에 파일럿 스킬을 명시적 호출 전용으로 유지하세요.
• 일반 글쓰기 기준과 사이트별 목소리를 분리하세요.
• 소스 검증을 단단한 사실 관문으로 유지하세요.
• AI 발견 가능성 확인을 저자 목소리와 분리하세요.
• 브랜드별 writer를 재사용하는 대신 얇은 site-specific writer 스킬을 만드세요.
• 각 이동 뒤 Codex가 스킬을 발견하는지 확인하세요.

여러 에이전트 협업:

• Codex를 루프의 소유자로 유지하세요.
• 검토를 실제 파일 또는 맥락 산출물에 고정하세요.
• 기준점이 없거나 출력이 비어 있거나 두 번째 에이전트가 시간 초과되면 실패로 닫으세요.
• 지원되지 않는 두 번째 에이전트 발견은 로컬 증거로 거부하세요.
• 근거 있는 발견만 받아들이고, 가장 작은 수정을 적용하고, 정적 검토를 다시 실행한 뒤 Codex 소유 확인을 실행하세요.

훅:

• 먼저 결정론적 확인만 옮기세요.
• 좁은 관문에는 SessionStart, PreToolUse, PostToolUse, Stop을 사용하세요.
• 더 많은 관문을 추가하기 전에 실패를 기록하세요.
• Shadow 훅에서는 원시 비공개 콘텐츠 대신 범주를 기록하세요.
• 승격 전에 known-bad fixture 1개와 known-noisy fixture 1개를 테스트하세요.
• 이전된 확인을 강제하기 전에 깨끗한 실패와 정리 부채를 분리하세요.
• 훅을 런타임 확인으로 다루고, 표준 원칙 저장소로 다루지 마세요.

글쓰기 작업 흐름:

• 초안을 쓰기 전에 인용을 모으세요.
• 현재 Codex 동작에는 공식 문서를 사용하세요.
• 로컬 목록과 경험에는 저자 분석을 사용하세요.
• 이미 개념을 설명하는 내부 글이 있다면 링크하세요.
• 최종 전에 검증을 실행하세요.
• 가이드 유지보수에서는 소스 및 런타임 주장을 검증하고, 파생 공개 표면을 동기화하고, 발견 파일을 재생성하고, 건너뛴 번역, 배포, 라이브 확인을 명명하세요.
• 번역된 가이드에서는 선택한 번역 제공자, 차등 묶음 또는 섹션 수, 값 없는 자격 증명 상태, 쓰기/업로드 여부, 로캘 검증, 실행이 막혔을 때의 쓰지 않은 이유를 기록하세요.
• 비밀값과 로그 위생에서는 실행 가능한 소스, 문서, 생성된 캐시, 세션 기록, 셸 스냅샷, 로그, 의도적인 비밀 저장소를 분리하세요. 이전된 작업 흐름을 안전하다고 다루기 전에 기록을 가리고 보조 도구를 환경 필수 설정으로 바꾸세요.
• 배포 후에는 canonical URL, 구조화 데이터, 사이트맵, llms-full.txt, 배포 상태, CDN 최신성, 변경 콘텐츠 표시를 프로덕션에서 검증하세요.
• CDN 캐시가 오래된 콘텐츠를 제공하면 기존 배포 경로를 통해 영향을 받은 공개 URL만 삭제한 뒤 변경 표시를 다시 확인하세요.

FAQ

비공개 글쓰기 스킬은 공개해야 하나요?

아니요. 마이그레이션 글은 비공개 스킬 이름, 프롬프트, 점수 세부 사항, 브랜드별 어댑터를 공개하지 않고도 글쓰기 시스템의 형태를 설명할 수 있어요. 공개 교훈은 그 스킬이 어디에 있어야 하고 Codex가 그것들을 어떻게 활성화해야 하는지예요.

마이그레이션 스킬도 같은 규칙을 따라요. 오늘 기준으로 비공개이며 오픈 소스 패키지가 아니에요. 작업 흐름을 테스트하고 싶다면 저에게 연락하세요.

Claude Code에서 Codex로 마이그레이션할 때 브랜드별 writer를 재사용해야 하나요?

아니요. 브랜드별 writer는 브랜드별로 남아야 해요. 개인 사이트나 회사 사이트에는 다른 제품의 독자, 사실, 행동 유도를 물려받지 않으면서 검증 기준을 공유하는 얇은 사이트 어댑터가 필요해요.

모든 Claude Code 훅을 Codex로 복사해야 하나요?

아니요. 그 뒤에 있는 계약을 식별한 뒤에만 동작을 복사하세요. 자격 증명 차단은 훅에 속해요. 글쓰기 rubric은 스킬에 속해요. 위험 규칙은 프로필 또는 라우터에 속해요. 철학은 AGENTS.md와 집중 스킬에 속해요.

Codex 스킬은 어디에 있어야 하나요?

새 Codex 네이티브 작업에는 공식 스킬 위치를 사용하세요. 프로젝트 스킬은 repo .agents/skills, 사용자 스킬은 $HOME/.agents/skills예요.⁴ 기존 로컬 설정이 ~/.codex/skills도 사용한다면, Codex 발견이 새 위치가 작동한다고 확인할 때까지 유지하세요.

Codex에서 /skill 프롬프트가 가끔 실패하는 이유는 무엇인가요?

/skill은 표준 Codex 스킬 호출 계약이 아니기 때문이에요. Codex 스킬은 스킬을 명시적으로 선택하거나 $skill-name처럼 언급할 때, 또는 작업이 스킬 설명과 맞을 때 활성화돼요.⁴ Codex CLI slash 명령은 별도의 내장 명령 표면이에요.¹⁵ 결정론적 스킬 활성화가 필요하면 $skill-name을 사용하세요. /name은 편의 래퍼, 선택 습관, 또는 자체 증명이 필요한 프롬프트 문구로만 유지하세요.

Claude Code에서 Codex로 마이그레이션할 때 핵심은 무엇인가요?

핵심은 훅, 스킬, 프로필 중 하나가 아니에요. 핵심은 작업이 시작되기 전에 4가지 질문에 답하는 결정 계층이에요. 어떤 종류의 작업이 들어왔는가, 어떤 위험 프로필이 실행되어야 하는가, 어떤 지침이 지배하는가, 완료 전에 어떤 증명이 있어야 하는가예요.

핵심 정리

Codex 사용자에게: 디렉터리가 아니라 계약을 옮기세요. AGENTS.md, 프로필, 스킬, MCP, 훅에는 각각 할 일이 있어요. Codex가 가장 직접적으로 지킬 수 있는 위치에 각 규칙을 두세요.

Claude Code에서 넘어오는 사용자에게: Codex 훅을 성숙한 Claude 디스패처 시스템의 완전한 대체물이 아니라 가드레일로 다루세요. AGENTS.md와 스킬부터 시작한 뒤 런타임 강제가 중요할 때 훅을 추가하세요.

공개 글을 쓰는 사람에게: 블로그 글쓰기는 높은 검토 프로필에 속해요. 현재 주장은 현재 소스가 필요해요. 잘 다듬어진 틀린 글은 망가진 로컬 스크립트보다 신뢰를 더 빠르게 해쳐요.

제 스택에 대해: 비공개 글쓰기 시스템은 이제 실질적으로만 이전된 것이 아니에요. 첫 번째 site-specific writer는 명시적 호출 전용으로 단계화되었고, 마이그레이션 작업 흐름은 사용자 스킬로 활성화되었으며, 비공개 플러그인 패키지는 공개 릴리스가 되지 않은 채 로컬 설치 파일럿을 통과했어요. Codex 원칙은 이제 품질과 취향을 운영 규칙으로 만들어요. 최종 검증 요약은 수동 shadow review로 남았고, 좁은 결정론적 확인은 별도 훅이 아니라 기존 quality Stop 파일럿에 접혔어요. 압축된 SessionStart 맥락 훅은 파일럿 중이고, 첫 번째 활성 품질 훅은 apply_patch 변경을 shadow mode로 지켜보고, 첫 번째 pre-Bash safety guard는 좁은 차단 파일럿으로 실행되고, 인용 검사기는 이제 변경된 공개 Markdown Stop 파일럿으로 실행돼요. 가이드 유지보수 패스는 실제 공개 문서에서 소스부터 렌더링까지 이어지는 루프를 증명했고, 한 패스는 오래된 소스-검증 체계 수치를 보존하지 않고 낡은 정확한 수치 주장을 바로잡았으며, 또 다른 패스는 생성된 AI 발견 경로와 제공된 AI 발견 경로의 불일치를 잡았어요. 최근 패스는 모델/매개변수 호환성, 벤치마크/모델 카드 변동, 빠르게 바뀌는 플러그인 릴리스 변동, 렌더링된 FAQ 구조화 데이터 변동, 크레딧 계산 변동, 서드파티 전용 API/법적/기능 최저선 주장, frontmatter-slug 경로 변동을 고쳤고, 최신 Codex 가이드 패스는 가이드 번역을 제공자 선택 가능하게 만들고, Codex 소유 작업의 기본 제공자로 Codex를 사용하고, 캐시 쓰기 전에 잘린 번역 출력을 거부하고, 로캘 쓰기를 완료하고, 로캘 경로를 검증하고, 낡은 CDN 응답을 표적 삭제로 해결했어요. 제한된 비밀값/로그 위생 패스는 교체, 가림, 예방 훅 빈틈을 기록하기 전에 소스, 문서, 생성된 캐시, 세션 기록, 셸 스냅샷, 로그, 의도적인 비밀 저장소를 분리했어요. 릴리스 루프는 이제 로컬 확인, 배포 상태, CDN 최신성, 라이브 변경 표시 증명을 별도의 관문으로 다뤄요. 소스 정보 수집 패스는 비공개 메모리 쓰기 전에 dry-run/쓰기 분량 규율을 증명했고, 회사 블로그 온보딩 경로는 대상/경로/접수 증거가 명시적이지 않으면 파일 생성 전에 멈추고, 블로그 번역기는 D1 자격 증명 또는 명시적 대상이 없으면 쓰기 실행 전에 멈추며 자격 증명이 있을 때도 잔여 영어가 많은 Codex 출력을 발행 전에 거부해요. 여러 에이전트 협업 루프는 권한을 두 번째 에이전트에 넘기지 않고 검토/수정/재검증을 증명했고, 수동 운용 체계 상태 관문은 더 넓은 활성화 전에 결정론적 승격 표면을 확인해요. 다음 작업은 남은 명시적 호출 전용 프로덕션 절차를 계속 증명하고, 공개 릴리스 경계를 계속 보류해 두며, 어떤 관문도 넓히기 전에 실제 공개 글쓰기와 엔지니어링 작업을 단계화된 경로로 계속 실행하는 것이에요.

참고 문헌