Part I: 왜, 무엇이 다른가

Chapter 1: 서론 — 왜 지금 Codex를 검토하는가

집필일: 2026-04-28 최종수정일: 2026-06-11

1.1 잘 쓰고 있는데도, 왜 다시 검토하는가

Claude Code를 잘 쓰고 있다면 Codex를 검토해야 할 이유가 없어 보인다. 이미 claude를 열면 repo를 읽고, CLAUDE.md를 따르고, 긴 대화 속에서 설계와 구현을 이어간다. 익숙한 도구를 두고 새 도구를 배우는 것은 비용이다. 특히 Claude Code로 만든 프로젝트가 여러 개라면 "Codex로 넘어간다"는 말은 기대보다 부담으로 먼저 들린다.

그런데 Claude Code를 오래 쓸수록 작은 불편도 같이 쌓인다. 세션이 길어지면 무엇이 컨텍스트에 남아 있는지 불안하고, limit이나 peak-time 품질 변동에 작업 리듬이 끊기며, 잘 만든 prompt와 하네스가 특정 도구의 관습 안에 묶인다. 여러 repo를 오가다 보면 각 프로젝트의 현재 상태, 다음 작업, 검증 명령이 대화 안에 흩어져 "다음 에이전트가 이어받기 좋은 상태"로 남아 있지 않은 경우도 많다.

그래서 질문은 "Claude Code가 나쁘니 Codex로 바꾸자"가 아니다. 더 정확한 질문은 이것이다. Claude Code로 쌓아온 작업 방식을 깨지 않으면서, Codex의 장점인 작은 diff, 독립 리뷰, sandbox, Worktree/Cloud 같은 운영 표면을 옆에 붙일 수 있는가?

이 전환이 막막하게 느껴지는 것은 당연하다. CLAUDE.md는 어떻게 할지, .claude/ 하네스는 남겨야 하는지, AGENTS.md는 무엇을 담아야 하는지, 기존 repo를 Codex가 읽게 했다가 망가뜨리면 어떻게 되돌릴지부터 막힌다. 이 책은 바로 그 지점에서 시작한다. Claude Code를 이미 잘 쓰는 사람이 기존 workflow를 보존한 채 Codex를 평가하고, 필요한 부분만 안전하게 가져오기 위한 서베이다.

1.2 지금이라는 신호

Codex를 검토해야 하는 이유를 "GPT-5.5가 Codex에 먼저 들어왔기 때문"이라고만 말하면 설득력이 부족하다. 최신 모델이 중요하지 않다는 뜻은 아니다. 2026년 4월 GPT-5.5가 API보다 Codex 제품 표면에 먼저 도착한 사건은 분명한 신호였다 [7]. 하지만 그것은 결론이 아니라 출발점이다.

더 큰 변화는 모델의 성능 자체보다, 모델이 전달되는 방식이다. Claude Code는 이미 "좋은 모델 + 좋은 터미널 하네스"가 개발자의 실제 workflow를 바꿀 수 있음을 보여주었다 [1]. Codex가 흥미로운 이유도 같은 선상에 있다. 이제 frontier 모델은 API endpoint로만 오는 것이 아니라, sandbox, 권한, diff, review, worktree, cloud 실행이 묶인 제품 표면으로 온다 [9].

따라서 "왜 지금인가?"에 대한 답은 세 가지다.

이유 Claude Code 사용자가 느끼는 문제 Codex를 검토할 지점
운영 리스크 limit, throttling, peak-time 품질 변동이 작업 리듬을 끊는다. 한 도구에 모든 작업을 묶지 않는 보조 실행면을 둔다.
검증 단위 긴 대화 끝에 나온 큰 변경은 검토와 rollback이 어렵다. 작은 diff, /review, sandbox 실행으로 변경을 작게 만든다.
지식 종속성 규칙과 현재 상태가 CLAUDE.md, 대화, 도구 전용 메모리에 흩어진다. AGENTS.md, HANDOFF.md, TASKS.md로 도구 독립 작업면을 만든다.

2026년 6월 현재는 네 번째 신호가 추가됐다. Codex가 더 이상 "GPT-5.5를 먼저 쓰는 별도 CLI"에 머물지 않고, 다른 에이전트 설정을 가져오는 공식 migration surface를 갖췄다는 점이다. Codex app의 Import other agent setup은 instruction files를 AGENTS.md로, settings.json을 config.toml로, skills·MCP·hooks·slash command·subagents를 Codex 쪽 구성으로 가져오며, 남은 항목은 migrate-to-codex skill이 열린 새 thread에서 이어서 처리하게 한다 [9]. 이 변화 때문에 "전환"의 첫 단계는 더 이상 수동 복붙이 아니다. 공식 import로 초안을 만들고, 사람이 위험한 권한·hook·MCP·subagent를 리뷰한 뒤, 작은 diff로 받아들이는 절차가 표준에 가까워졌다.

즉 Codex는 "더 최신 모델을 쓰는 통로"이기 전에, repo를 더 작고 검증 가능한 단위로 운영할 수 있는 두 번째 표면이다. 이 차이를 이해해야 이후 장에서 다룰 명령어, 설정, 하네스 이전이 단순한 기능 비교로 흐르지 않는다.

Figure 1.1: Claude Code 우세에서 GPT-5.5의 Codex 탑재까지 — 하네스가 API보다 먼저 배달 채널이 된 순간. illustration by author Gemini assisted

1.3 사람들이 말하는 "전환"의 실제 의미

2026년 봄 이후 Claude Code에서 Codex로 "넘어간다"고 말하는 글과 영상이 늘었다. 하지만 자세히 보면 대부분은 완전한 교체를 말하지 않는다. 더 현실적인 의견은 다섯 갈래로 나뉜다.

의견 핵심 주장 이 책의 해석
하이브리드론 Claude Code는 설계와 판단, Codex는 구현과 검증 worker로 쓴다 [2]. 완전 전환보다 역할 분담이 먼저다.
운영 안정성론 Claude Code의 limit, throttling, peak-time 품질 변동 때문에 Codex를 보조/대체 수단으로 둔다 [3]. 한 도구에 모든 작업을 묶는 것은 운영 리스크다.
검증 루프론 Codex는 sandbox, /diff, /review, Worktree처럼 변경을 검토 가능한 단위로 만드는 장치가 명확하다 [9]. 로컬 repo가 많을수록 작은 diff와 독립 리뷰가 중요하다.
표준화론 CLAUDE.md에 묶인 지식을 AGENTS.md, HANDOFF.md, TASKS.md로 옮기면 도구 종속성이 줄어든다 [5]. 이전의 핵심은 도구 교체가 아니라 지식 외부화다.
유보론 Claude Code가 여전히 설계, 맥락, 대화형 작업에서 더 낫다는 평가도 많다 [6]. 첫 단계는 "갈아타기"가 아니라 병행 실험이다.

여기서 중요한 점은 감정적인 도구 교체 서사가 아니라 작업의 분해다. Claude Code가 잘하는 설계, 탐색, 긴 대화형 판단은 유지할 수 있다. Codex가 잘 맞는 작은 구현 diff, 독립 리뷰, sandbox 실행, Worktree 병렬 실험, Cloud 장기 작업은 별도의 표면으로 붙일 수 있다.

그러므로 이 책에서 "전환"은 한 번에 도구를 바꾸는 사건이 아니다. 이미 굴러가는 workflow 옆에 검증 가능한 실행면을 하나 더 붙이고, 실제 repo에서 충분히 작게 검증한 뒤 역할을 넓힐지 결정하는 과정이다.

실제 사용 경험도 이 방향으로 수렴한다. 5월 이후 커뮤니티의 "Claude에서 Codex로 옮긴다"는 말은 대개 계정 하나를 해지한다는 뜻이 아니라, Claude Code의 대화형 설계와 Codex의 diff/Worktree/Cloud 실행을 나눠 쓰겠다는 뜻이다 [9]. 특히 Codex subagent는 기본적으로 사용 가능하지만 자동으로 난사되는 기능이 아니며, 사용자가 병렬 agent work를 명시할 때 쓰는 고비용 병렬화 수단으로 문서화됐다 [9]. 그래서 이 책의 조언도 바뀐다. "Codex를 써볼까?"가 아니라 "어떤 작업을 Claude Code에서 계속하고, 어떤 작업을 Codex에 넘기며, 둘 사이의 handoff 파일을 어디에 둘 것인가?"가 첫 질문이다.

1.4 이 책의 원칙: 대체가 아니라 병행 운영

가장 먼저 정해야 할 원칙은 간단하다. 기존 Claude Code workflow는 계속 돌아가야 한다. Codex를 검토한다는 이유로 CLAUDE.md, .claude/, hooks, skills, subagents를 삭제하거나 이름을 바꾸면 안 된다. Codex가 기대보다 맞지 않거나 특정 repo에서 품질이 낮으면 즉시 Claude Code로 돌아갈 수 있어야 한다.

이 원칙은 보수적인 태도가 아니라 운영 안전성이다. 이미 Claude Code로 만든 repo에는 코드만 있는 것이 아니다. 프로젝트 규칙, 작업 습관, 검증 루틴, slash command, hook, subagent가 함께 쌓여 있다. 이 하네스는 많은 시행착오의 결과물이다. Codex를 검토하는 단계에서 그것을 부수는 것은 마이그레이션이 아니라 장애를 만드는 일이다.

따라서 Codex의 첫 역할은 "대체자"가 아니라 "보조 실행면"이다. 처음에는 repo를 읽고, 구조를 설명하고, 위험 파일을 찾고, 작은 diff 하나를 만들고, 그 diff를 리뷰하는 정도면 충분하다. Codex가 좋은 결과를 반복해서 내면 그때 역할을 넓힌다. 반대로 불편하거나 위험하면 중단한다.

이 책이 권하는 성공 조건은 네 가지다.

  1. Claude Code로 기존 작업을 그대로 이어갈 수 있다.
  2. Codex가 만든 변경은 /diff, /review, 테스트로 검증 가능한 크기다.
  3. 프로젝트 규칙과 현재 상태는 도구 독립 파일로 남는다.
  4. 실험이 실패해도 git과 기존 하네스로 되돌아갈 수 있다.

이 네 조건을 만족하지 못하면 아직 "전환"이 아니라 "모험"이다.

1.5 전환의 최소 단위는 repo가 아니라 지식이다

Claude Code에서 Codex로 넘어갈 때 가장 비싼 작업은 코드 수정이 아니다. 지식의 위치를 바꾸는 일이다.

많은 Claude Code 프로젝트에서 중요한 지식은 세 군데에 흩어져 있다. 대화 기록, Claude 전용 메모리, 그리고 CLAUDE.md와 .claude/ 하네스 파일이다. 이 지식이 Claude Code 안에만 머물러 있으면 Codex는 repo를 이어받기 어렵다. 반대로 프로젝트 규칙, 현재 상태, 남은 작업, 검증 명령이 평문 파일로 내려오면 Codex뿐 아니라 다른 도구도 이어받을 수 있다.

이 책에서 반복해서 등장하는 파일은 세 가지다.

파일 역할
AGENTS.md 도구 독립 프로젝트 규칙, 빌드/테스트 명령, 코드 스타일, 금지 사항
HANDOFF.md 현재 상태, 최근 결정, 위험 요소, 다음 작업, 검증 결과
TASKS.md 작게 쪼갠 backlog, 의존성, 완료 조건

이 세 파일은 Claude Code를 대체하기 위한 파일이 아니다. Claude Code와 Codex가 모두 읽을 수 있는 공용 작업면이다. 좋은 전환은 CLAUDE.md를 지우는 것이 아니라, 그 안의 범용 지식을 AGENTS.md로 옮기고 Claude 전용 지시는 그대로 남기는 것이다.

이 관점에서 보면 마이그레이션의 최소 단위는 repo 전체가 아니라 "다음 에이전트가 이어받을 수 있는 지식 한 조각"이다. 빌드 명령 하나, 테스트 명령 하나, 금지된 파일 하나, 최근 결정 하나가 명확히 적힐 때마다 도구 종속성이 줄어든다.

Figure 1.2: 지식 외부화의 의미 — AGENTS.md·HANDOFF.md·TASKS.md처럼 평문으로 외부화된 것만 마이그레이션을 통과한다. 도구 전용 메모리와 대화 속 맥락은 다시 쌓아야 한다. illustration by author Gemini assisted

1.6 첫 실험은 가장 쉬운 repo에서

Codex를 처음 붙일 때 가장 피해야 할 실수는 가장 복잡한 하네스 repo부터 실험하는 것이다. 하네스가 강한 repo일수록 Claude Code로 돌아갈 수 있는 경로를 보존해야 한다. 따라서 순서는 이렇게 잡는다.

  1. 작은 repo에서 시작한다. 문서 수정, 테스트 추가, 작은 버그 수정처럼 되돌리기 쉬운 작업을 고른다.
  2. Read Only로 읽힌다. Codex에게 먼저 repo 구조, CLAUDE.md, .claude/, build/test 명령만 조사하게 한다.
  3. 삭제 금지 원칙을 명시한다. CLAUDE.md, .claude/, hooks, skills, subagents는 건드리지 않는다.
  4. 최소 scaffold만 추가한다. AGENTS.md, HANDOFF.md, TASKS.md 중 필요한 것만 작게 만든다.
  5. 작은 diff 하나만 맡긴다. 수정 범위를 좁히고 /diff, /review, 테스트로 확인한다.
  6. 그 다음 repo로 넘어간다. 가장 복잡한 하네스 repo는 마지막에 이전한다.

이 순서는 Codex를 과소평가해서가 아니다. 좋은 도구일수록 안전한 도입 순서가 필요하다. Codex가 기대보다 좋으면 역할을 넓히면 된다. 기대보다 나쁘면 아무것도 잃지 않고 Claude Code로 돌아가면 된다.

1.7 이 책의 지도

이 책은 네 Part로 구성된다.

Part I: 왜, 무엇이 다른가 (Ch 1-3)

Codex를 왜 검토하는지, Claude Code와 무엇이 다른지, 기존 repo에 안전하게 첫 진입하는 법.

Part II: Codex에서 하네스 엔지니어링 새로 배우기 (Ch 4-6)

하네스의 기본 개념, AGENTS.md와 설정, 검증 가능한 바이브 코딩 루프.

Part III: GPT-5.5 시대의 Codex 실전 가이드 (Ch 7-9)

최근 모델/CLI 변화, 커뮤니티가 발견한 하이브리드 패턴, Worktree, /goal, 메타하네스.

Part IV: LLM Wiki에서 AI Scientist로 (Ch 10-12)

개인 지식 관리, 외장 메모리, 분야별 연구 자동화 workflow.

Figure 1.3: 책의 지도 — 4 Part × 12 챕터. Part I이 도입, Part II가 Codex에서의 신규 학습, Part III가 GPT-5.5 시대 실전, Part IV가 LLM Wiki에서 AI Scientist로의 확장. illustration by author Gemini assisted

처음 읽는다면 1장부터 3장까지 읽고, 실제 repo에 들어가기 전에 5장과 6장의 AGENTS.md와 검증 루프를 먼저 확인하라. 이미 Claude Code로 운영 중인 repo가 많다면 3장의 "로컬 GitHub repo 이어받기"와 5장의 "Claude Code 하네스를 Codex로 재구성하기"를 특히 주의해서 읽어야 한다.

이 책은 Codex 찬양서가 아니다. Claude Code를 잘 써온 사람이 자기 repo를 망가뜨리지 않고 Codex를 평가하기 위한 절차서다.

참고문헌

  1. Dev.to, "Claude Code authored ~4% of all public GitHub commits in March 2026," 2026-03. [DEV Community, 2026]
  2. Fountain City, "Claude Code and Codex Together: Driver/Worker Orchestration in Production," 2026-04-30. [Fountain City, 2026]
  3. Reddit r/ClaudeCode, "We have it good, just tried Codex," 2026-04-23. [Reddit, 2026]
  4. OpenAI, "Codex CLI changelog and slash commands," 2026. [OpenAI, 2026]
  5. Daniel Vaughan, "Migrating a Workflow from Claude Code to Codex CLI," 2026-03-26. [Vaughan, 2026]
  6. DevGENT, "GPT-5.5 Codex Review: Pro $100, Claude Max," 2026-04-25. [DevGENT, 2026]
  7. Willison, Simon, "GPT-5.5," simonwillison.net, 2026-04-23. [Willison, 2026]
  8. OpenAI, "Migrate to Codex," Codex manual, 2026. [OpenAI, 2026]
  9. OpenAI, "Codex subagents," Codex manual, 2026. [OpenAI, 2026]
  10. Anthropic, "Claude Code changelog," 2026. [Anthropic, 2026]