Chapter 3: Codex 첫걸음 — Claude Code 사용자를 위한 빠른 적응 가이드

3.1 처음 실행하는 사람을 위해

claude 명령에는 익숙하다. 이제 처음으로 codex 명령을 실행하려 한다. 무엇이 같고 무엇이 다른가?

이 챕터는 그 질문에 답한다. 세 가지를 설치하고, 세 가지 멘탈 모델을 전환하고, 가장 자주 쓰는 명령을 대응표로 정리한다.

3.2 설치 — 세 가지

1. Codex CLI 설치

npm install -g @openai/codex

또는 Homebrew를 선호한다면:

brew install openai-codex

이 책의 최신 보강 기준은 Codex CLI 0.128.0 이상이다. 0.128.0은 2026-04-30에 /goal, 권한 프로필, 외부 에이전트 세션 import, 더 명시적인 multi-agent 설정을 추가했다 ^[13]. 확인:

codex --version

버전이 낮으면 codex update 또는 npm update -g @openai/codex로 업그레이드한다 ^[13].

2026년 6월 기준으로는 버전 번호 하나보다 표면 선택이 더 중요하다. CLI는 로컬 checkout에서 빠르게 시작하기 좋고, Codex app의 Worktree는 같은 repo에서 독립 thread를 안전하게 돌리기 좋으며, Cloud/automation은 장기·반복 작업에 맞다 ^[13]. 처음 설치 직후에는 CLI 또는 app Local로 시작하고, Worktree와 automation은 검증 루프가 익숙해진 뒤 켠다.

2. ~/.codex/config.toml 작성

처음 실행하면 자동으로 기본 파일이 생성되지만, GPT-5.5를 쓰려면 직접 설정해야 한다:

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# Claude Code repo를 당장 삭제/이전하지 않고 읽게 하는 보수적 브릿지
project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 65536

model을 설정하지 않으면 환경과 계정에 따라 기본 모델이 선택된다. model_reasoning_effort는 minimal / low / medium / high / xhigh 중 선택한다 (모델별 가용 옵션 차이 있음). 일상 작업에는 medium, 복잡한 리팩터링에는 high를 권장한다 ^[13].

project_doc_fallback_filenames = ["CLAUDE.md"]는 실제 마이그레이션 전의 안전장치다. Codex는 AGENTS.md를 우선하지만, 아직 AGENTS.md를 만들지 않은 repo에서는 기존 CLAUDE.md를 읽을 수 있다. 이것은 Claude 하네스를 삭제하라는 뜻이 아니다. "Codex가 repo를 이해할 때 참고할 수 있게 한다"는 뜻이다.

3. 첫 AGENTS.md 작성

프로젝트 루트에 AGENTS.md를 만든다. 최소한 이 정도면 시작할 수 있다:

# Project Rules

## Stack
- Node.js / TypeScript
- Express.js API
- PostgreSQL

## Code Style
- Use ESLint + Prettier (configs in repo)
- TypeScript strict mode
- Functions < 40 lines

## Testing
- Jest for unit tests
- Run `npm test` before any commit

AGENTS.md의 역할: "이번 대화에서 Claude에게 말하는 것"을 "Codex가 모든 태스크에서 따르는 규칙"으로 바꾸는 것이다 ^[13]. 한번 써두면 매 태스크마다 반복하지 않아도 된다.

3.3 멘탈 모델 전환 — 세 가지

전환 1: "이번 대화" → "규칙 파일"

Claude Code에서: 매 대화 시작에 컨텍스트를 주거나 CLAUDE.md에 전역 설정을 써둔다.

Codex에서: AGENTS.md가 그 역할을 한다. 차이점은 AGENTS.md가 더 구조화되어 있고, 프로젝트 루트뿐 아니라 서브디렉토리에도 둘 수 있으며, Amp·GitHub Copilot·Google Jules 같은 다른 AI 도구도 같은 파일을 읽는다 ^[5].

전환 2: "터미널 세션" → "diff 단위의 태스크"

Claude Code에서: 터미널을 열고 대화하며 작업한다. 세션이 끝나면 맥락이 사라진다.

Codex에서: 태스크를 작게 쪼개고, 각 태스크가 만든 diff를 검토한다. CLI는 현재 checkout에서 바로 diff를 만든다. App의 Worktree 모드를 쓰면 Codex가 관리하는 Git worktree에서 독립 thread를 실행할 수 있고, Cloud 모드는 원격 환경에서 장기 작업을 돌릴 수 있다 ^[13]:

# 태스크 실행
codex exec "refactor the auth module to use JWT"

# 병렬 실험은 CLI 백그라운드보다 Codex app Worktree 모드를 우선 고려한다

전환 3: "도구별 권한" → "sandbox 레벨"

Claude Code에서: 매 도구 실행 시 허용할지 묻거나, allowedTools로 미리 허용한다.

Codex에서: sandbox_mode로 한 번에 설정한다. workspace-write가 기본 시작점이다 — 현재 작업 디렉토리 내에서만 파일을 쓸 수 있다 ^[13].

3.4 명령어 대응표 — Claude Code → Codex

Claude Code에만 있는 것: /ultrareview, Claude 전용 remote-control 경험, Agent Teams의 SendMessage 런타임 협업.

Codex에만 있는 것: /goal, app의 Local/Worktree/Cloud 모드, TOML 기반 에이전트, Linux Foundation AGENTS.md 표준 호환.

3.5 Claude Code로 만든 로컬 GitHub repo 이어받기

이미 로컬에 프로젝트들이 모여 있고, 대부분 Claude Code로 작성됐으며, GitHub repo와 연결되어 있다면 이 절차를 따른다. 핵심은 "한 번에 이전"이 아니라 "Claude Code가 계속 돌아가는 상태에서 Codex가 작은 작업 하나를 이어받게 하기"다.

1. 읽기 전용으로 시작: /permissions에서 Read Only를 선택하고, Codex에게 repo 구조, .claude/, CLAUDE.md, scripts, test command만 조사하게 한다.
2. 삭제 금지 원칙 명시: 첫 프롬프트에 "CLAUDE.md, .claude/, hooks, skills, subagents는 삭제하거나 rename하지 말라"고 쓴다.
3. handoff 파일 작성: HANDOFF.md 또는 docs/codex-handoff-YYYY-MM-DD.md에 현재 상태, 빌드 명령, 위험 파일, 다음 작업을 기록한다.
4. 최소 AGENTS.md 추가: 기존 CLAUDE.md의 범용 규칙만 복사한다. Claude 전용 hook, slash command, memory 설정은 그대로 둔다.
5. 작은 작업 하나만 실행: 예를 들어 오타 수정, 테스트 하나 추가, README 한 섹션 보강처럼 되돌리기 쉬운 작업을 시킨다.
6. 검증 후 확장: /diff, /review, 테스트를 확인하고, 문제가 없을 때만 다음 태스크로 넘어간다.

공식 import를 쓸 수 있다면 순서는 조금 달라진다. Settings → General → Import other agent setup으로 먼저 탐지를 실행하고, Codex가 가져온 AGENTS.md, config.toml, skills, MCP, hooks, subagents를 읽는다 ^[13]. 그 다음 아래 세 가지를 사람이 직접 확인한다.

1. 권한이 넓어지지 않았는가: danger-full-access, broad network allow, production 명령 자동 승인 금지.
2. hook과 slash command가 의미를 유지하는가: shell interpolation, path placeholder, credential env var가 Codex에서 같은 방식으로 동작한다고 가정하지 않는다.
3. subagent가 너무 넓지 않은가: Codex subagent는 병렬 탐색·검증에 쓰고, repo 소유권 결정은 main thread가 통합한다.

처음 프롬프트 예시:

이 repo는 Claude Code 하네스를 이미 사용한다.
절대 CLAUDE.md, .claude/, 기존 hooks/skills/subagents를 삭제하거나 rename하지 마라.
먼저 repo 구조와 Claude Code 하네스를 읽고, Codex로 안전하게 이어받기 위한
AGENTS.md/HANDOFF.md 최소 초안을 제안해라. 파일 수정은 아직 하지 마라.

승인 후 첫 수정 프롬프트:

방금 세운 계획 중 1단계만 수행해라.
AGENTS.md를 새로 추가하되, Claude 전용 파일은 건드리지 마라.
변경 후 /diff로 볼 수 있게 요약하고, 테스트는 아직 실행하지 마라.

이 절차는 하네스를 강하게 쓰는 repo일수록 더 중요하다. 가장 복잡한 repo를 첫 번째 실험 대상으로 삼지 말고, 문서 중심 repo나 작은 개인 프로젝트에서 Codex의 diff/review/test 루틴을 먼저 익힌 뒤 마지막에 이전한다.

3.6 처음 태스크 실행하기

설치가 완료됐으면 바로 실행해보자. Saladi의 "Codex 101" ^[7]에서 뽑은 바로 쓸 수 있는 프롬프트:

리팩터링:

codex exec "refactor src/auth.ts — extract token validation into a pure function, add JSDoc"

테스트 추가:

codex exec "write Jest tests for UserService.createUser(), mock the database"

버그 수정:

codex exec "fix the race condition in connection pool — see issue #42"

프롬프트가 구체적일수록 결과가 좋다. "리팩터링해줘"보다 "src/auth.ts의 토큰 검증 로직을 순수 함수로 분리하고 JSDoc을 추가해줘"가 더 좋은 결과를 낸다 ^[10].

3.7 Claude Code 사용자가 처음 묻는 FAQ

"Claude Code를 지우고 Codex로 시작해야 하나요?": 아니다. 첫 단계에서는 CLAUDE.md, .claude/, hooks, skills, subagents를 그대로 둔다. Codex는 추가 실행면으로 붙이고, 실패하면 Claude Code로 바로 돌아갈 수 있어야 한다.

"CLAUDE.md를 AGENTS.md로 이름만 바꾸면 되나요?": 아니다. CLAUDE.md에는 Claude 전용 지시와 프로젝트 공통 규칙이 섞여 있는 경우가 많다. Codex가 읽어야 하는 것은 공통 규칙, 빌드/테스트 명령, 금지 사항이다. Claude 전용 hook, slash command, memory 규칙은 CLAUDE.md와 .claude/에 남긴다. 임시로는 project_doc_fallback_filenames = ["CLAUDE.md"]를 둘 수 있지만, 장기적으로는 핵심 규칙을 AGENTS.md로 분리한다 ^[13].

".claude/agents, hooks, skills는 Codex 형식으로 전부 옮겨야 하나요?": 아니다. 처음부터 1:1 이식하려고 하면 실패하기 쉽다. 먼저 "이 하네스가 왜 필요한가"를 적고, 자주 반복되는 작업만 Codex skill, subagent, wrapper script로 재구성한다. 강한 Claude Code 하네스일수록 이식보다 공존이 먼저다.

"Claude Code의 Plan Mode처럼 먼저 계획만 받고 싶으면?": Codex에서도 가능하다. Read Only로 두고 "계획만 세우고 파일 수정은 하지 마라"라고 명시한다. 계획을 읽은 뒤 다음 프롬프트에서 "1단계만 수행하라"처럼 작은 diff 하나를 승인한다. 작업 중 현재 모델, 권한, writable root가 헷갈리면 /status를 확인한다 ^[13].

"Claude Code에서 이어오던 긴 대화 맥락은 어떻게 넘기나요?": 대화 전체를 넘기려 하지 말고 HANDOFF.md로 줄인다. 현재 상태, 최근 결정, 남은 작업, 위험 파일, 검증 명령만 적으면 충분하다. 공유 링크나 과거 세션은 참고자료일 뿐, Codex가 안정적으로 이어받는 작업 단위는 repo 안의 평문 파일이다.

"CLI, App, Cloud 중 어디서 시작해야 하나요?": Claude Code 사용자가 로컬 repo를 이어받는 첫 실험은 CLI나 App의 Local 모드가 가장 단순하다. 현재 checkout의 diff를 직접 보고 되돌릴 수 있기 때문이다. App Worktree와 Cloud는 병렬 실험이나 장기 작업에 좋지만, 처음부터 쓰면 GitHub 환경, branch, PR까지 동시에 배워야 한다 ^[13].

"공식 import를 돌리면 수동 migration은 끝인가요?": 아니다. import는 변환기가 아니라 초안 생성기다. 직접 가져올 수 있는 항목은 가져오고, 애매한 항목은 migrate-to-codex skill이 열린 thread에서 후속 작업으로 넘긴다 ^[13]. 안전한 절차는 import → 사람이 권한/비밀/명령 검토 → 작은 diff 하나 적용 → /review → 테스트다.

"Codex 결과가 Claude Code보다 별로면 전환 실패인가요?": 아니다. 이 책의 기본 전략은 하이브리드다. Claude Code가 더 좋은 설계와 대화형 판단을 내면 그대로 쓴다. Codex는 작은 diff, 독립 리뷰, sandbox 실행, Worktree/Cloud 작업에서 가치가 있을 때만 역할을 넓힌다.

5장에서는 AGENTS.md를 실제로 잘 쓰는 법과 서브에이전트 셋업을 다룬다. 지금은 "기존 Claude 하네스를 보존한다", "계획과 작은 diff를 분리한다", "handoff를 평문 파일로 남긴다"는 세 가지면 충분하다.

참고문헌

1. OpenAI, "Codex CLI changelog," 2026. [OpenAI, 2026]
2. OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
3. OpenAI, "Codex config basic setup," 2026. [OpenAI, 2026]
4. OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
5. AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
6. DeployHQ, "Codex CLI getting started guide," 2026. [DeployHQ, 2026]
7. Saladi, "Codex 101: 33 ready-to-use prompts," 2026. [Saladi, 2026]
8. TechBytes, "Claude Code command cheatsheet," 2026. [TechBytes, 2026]
9. Augment, "How to write a great AGENTS.md," 2026. [Code, 2026]
10. Zack Proser, "Codex daily-use review," 2026. [Proser, 2026]
11. OpenAI, "Migrate to Codex," Codex manual, 2026. [OpenAI, 2026]
12. OpenAI, "Codex app worktrees," Codex manual, 2026. [OpenAI, 2026]
13. OpenAI, "Codex automations," Codex manual, 2026. [OpenAI, 2026]