Claude Code vs OpenAI Codex 완전 가이드: 설치부터 실전 명령어·예시까지

이 글의 목표: "어느 게 더 좋나요?"가 아니라, 두 도구를 실제로 어떻게 설치·실행·활용하는지 명령어와 예시로 보여줍니다.

---

왜 지금 이 두 도구를 제대로 알아야 하는가?

Claude Code(Anthropic)와 OpenAI Codex CLI(OpenAI)는 2025~2026년에 등장한 터미널 기반 AI 코딩 에이전트입니다. 기존 GitHub Copilot 같은 IDE 자동완성 도구와 달리, 두 도구 모두 코드베이스 전체를 읽고, 파일을 직접 수정하고, 테스트를 실행하는 자율 에이전트입니다.

같은 카테고리지만 철학이 다릅니다. 그 차이를 명령어 수준에서 이해하면 상황에 맞는 선택이 가능해집니다.

---

Claude Code: 핵심 기능과 명령어

설치와 시작

# 설치 (Node.js 18+ 필요)
npm install -g @anthropic-ai/claude-code

# API 키 설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 버전 확인
claude --version

# 대화형 세션 시작
claude

# 현재 디렉토리 컨텍스트로 시작
cd my-project && claude

어떤 실행 모드가 있는가?

모드	명령어	설명
대화형	claude	인터랙티브 세션 (종료: /exit)
단발 실행	claude "프롬프트"	1회 실행 후 종료
파이프 모드	cat file | claude -p "..."	stdin 입력 처리, stdout 출력
세션 이어가기	claude --continue	마지막 세션 재개
세션 ID 지정	claude --resume <id>	특정 세션으로 복귀

# 단발 실행 — 한 줄로 작업 완료
claude "app/api/auth/route.ts 의 JWT 만료 처리 버그를 수정해줘"

# 파이프 모드 — git diff를 코드 리뷰에 활용
git diff main | claude -p "이 변경사항을 보안·성능·가독성 순으로 리뷰해줘"

# 에러 로그 분석
cat error.log | claude -p "이 에러의 근본 원인과 해결책을 알려줘"

인-세션에서 어떤 슬래시 명령어를 쓸 수 있는가?

대화형 세션(claude) 내에서 사용하는 명령어입니다.

명령어	역할
/init	현재 프로젝트 분석 후 CLAUDE.md 자동 생성
/clear	컨텍스트 초기화 (새 작업 시작 시)
/compact	대화 압축 — 토큰 절약, 긴 세션에서 유용
/cost	현재 세션 토큰 사용량·비용 확인
/model	모델 전환 (Haiku ↔ Sonnet ↔ Opus)
/memory	Auto-Memory 관리 — 저장된 컨텍스트 확인·토글 (v2.1.59+)
/permissions	허용된 도구 목록 확인·변경
/help	전체 명령어 목록
/btw [질문]	현재 컨텍스트에서 빠른 사이드 질문 — 대화 히스토리에 추가되지 않음 (v2.1.72+)
/vim	Vim 키 바인딩 토글

# 세션 내 사용 예시
$ claude
> /init
✓ CLAUDE.md 생성 완료 — 프로젝트 구조 분석 결과 반영됨

> /cost
세션 토큰: 입력 12,400 / 출력 3,200 | 예상 비용: $0.08

> /compact
✓ 대화 압축 완료 — 컨텍스트 40% 절약

> /btw 지금 분석 중인 auth.ts 에서 JWT 라이브러리 뭐 쓰고 있어?
↳ [사이드 질문 — 히스토리 미저장] jsonwebtoken 0.9.1 사용 중입니다.

/btw의 핵심 특성:

• 현재 컨텍스트를 그대로 보면서 답변 — 파일 읽기·명령 실행은 불가
• 답변이 대화 히스토리에 추가되지 않아 컨텍스트 오염 없음
• Claude가 작업 중일 때도 병렬 실행 가능
• 부모 대화의 프롬프트 캐시를 재사용해 추가 비용 최소

CLAUDE.md: 왜 설정 파일이 중요한가?

CLAUDE.md는 프로젝트 루트에 두는 프로젝트 전용 지시 파일입니다. Claude Code가 세션을 시작할 때 자동으로 읽어 코딩 규칙, 구조, 금지 사항을 반영합니다.

# CLAUDE.md 예시

## 프로젝트 스택
Next.js 16 App Router, TypeScript strict, Tailwind CSS, Drizzle ORM + Neon Postgres

## 코딩 규칙
- 함수형 컴포넌트만 사용 (class component 금지)
- `any` 타입 사용 금지 — unknown + 타입 가드 활용
- 컴포넌트 파일: PascalCase, util 파일: camelCase
- 새 API 라우트 추가 시 rate-limit 미들웨어 반드시 적용

## 테스트
- 테스트 러너: `node --experimental-strip-types --test`
- 새 유틸 함수에는 단위 테스트 파일 함께 작성

## 금지 사항
- `.env` 파일 수정 절대 금지
- `console.log` 미제거 커밋 금지
- `any` 캐스팅으로 타입 오류 우회 금지

CLAUDE.md가 없으면: 매 세션마다 프로젝트 규칙을 설명해야 합니다. CLAUDE.md가 있으면: 프로젝트 규칙을 한 번만 정의하면 모든 세션에 자동 적용됩니다.

Skills: 재사용 가능한 워크플로우 패키징 (v2.1+)

Skills는 자주 쓰는 작업을 SKILL.md 파일로 패키징해 재사용하는 기능입니다. .claude/skills/ 또는 ~/.claude/skills/ 아래에 두면 변경 즉시 핫리로드되며, Claude Code 2.1부터 / 입력 시 명령어와 통합 표시됩니다.

# .claude/skills/code-review.md
---
name: code-review
description: PR diff를 보안·성능·가독성 순으로 리뷰
user-invocable: true
---

`git diff HEAD~1`을 읽고 다음 순서로 리뷰해줘:
1. 보안 취약점 (인젝션, 인증 누락, 민감 정보 노출)
2. 성능 이슈 (N+1 쿼리, 불필요한 리렌더링)
3. 가독성·유지보수성

$ claude
> /code-review        # 세션 내 직접 호출 (user-invocable: true)
> /commit             # 스테이징된 변경사항 분석 후 커밋 메시지 생성

Skills 두 가지 호출 방식:

방식	frontmatter	트리거
User-invocable	user-invocable: true	/skill-name 으로 직접 호출
Auto-invocation	user-invocable: false	Claude가 description을 보고 자동 실행

context: fork 옵션을 추가하면 현재 세션과 격리된 서브에이전트에서 스킬이 실행됩니다 — 긴 분석 작업에서 현재 세션 토큰을 보호합니다.

Auto-Memory: 세션 간 컨텍스트 자동 저장 (v2.1.59+)

Auto-Memory는 Claude가 세션 중 배운 내용(빌드 명령, 디버깅 패턴, 아키텍처 노트, 코딩 스타일)을 자동으로 저장해 다음 세션에서 재활용하는 기능입니다. 기본 활성 상태입니다.

$ claude
> /memory

📁 ~/.claude/projects/my-project/memory/MEMORY.md
  - 빌드: pnpm build (Next.js 16)
  - 테스트: node --experimental-strip-types --test
  - 주의: .env 파일 수정 금지 (기록일: 2026-03-15)
  [auto-memory 토글: ON]

CLAUDE.md vs Auto-Memory 역할 구분:

항목	CLAUDE.md	Auto-Memory
작성 주체	개발자가 직접 작성	Claude가 자동 저장
내용	코딩 규칙·금지 사항	빌드 명령·디버깅 인사이트
공유 범위	팀 전체 (git 추적 가능)	개인 세션 컨텍스트
제어 방법	수동 편집	/memory 명령으로 토글

Hooks: 도구 실행 전후 자동화 (2026)

Hooks는 Claude Code 이벤트에 셸 명령을 연결합니다. .claude/settings.json에서 설정합니다.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "shell", "command": "pnpm run lint --fix" }]
    }],
    "Stop": [{
      "hooks": [{ "type": "shell", "command": "echo '세션 종료' >> .claude/session.log" }]
    }]
  }
}

주요 Hook 이벤트: PreToolUse (도구 실행 전) | PostToolUse (도구 실행 후) | PreCompact (압축 전) | Stop (세션 종료)

→ AI가 파일을 수정할 때마다 린터 자동 실행, 커밋 전 타입 체크 등 CI/CD 수준 자동화가 가능합니다.

실전 명령어 예시 4가지

1. 자율 버그 수정 루프

claude "app/api/auth/route.ts 의 JWT 만료 처리 버그를 찾아 수정하고,
관련 테스트를 실행해서 통과할 때까지 반복해줘"

Claude Code가 파일 읽기 → 버그 특정 → 수정 → 테스트 실행 → 실패 시 재수정을 자율 반복합니다.

2. AI 커밋 메시지 생성

git add -p          # 변경사항 스테이징
claude commit       # staged 변경사항을 분석해 커밋 메시지 생성

3. 대규모 리팩터링

claude "lib/ 디렉토리의 모든 Promise 체인(.then/.catch)을
async/await 패턴으로 변환해줘. TypeScript 타입이 깨지지 않도록 확인하면서 진행해줘"

4. 코드베이스 온보딩

claude "이 프로젝트의 인증 흐름을 처음 보는 개발자 기준으로
파일 경로와 함께 단계별로 설명해줘"

주요 플래그

# 허용 도구 제한 — 읽기 전용 분석만 허용 (수정 없음)
claude --allowedTools "Read,Grep,Glob" "보안 취약점 스캔만 해줘"

# 확인 없이 자율 실행 (신중하게 사용)
claude --dangerouslySkipPermissions "테스트 파일 전체 일괄 생성"

# 특정 모델 지정
claude --model claude-opus-4-6 "복잡한 시스템 설계 도와줘"
claude --model claude-haiku-4-5-20251001 "간단한 유틸 함수 작성"

---

OpenAI Codex: 핵심 기능과 명령어

설치와 시작

# 설치 (MIT 오픈소스, Node.js 22+ 권장)
npm install -g @openai/codex

# API 키 설정
export OPENAI_API_KEY="sk-..."

# 버전 확인
codex --version

# 대화형 세션 시작
codex

# 단발 실행
codex "components/Button.tsx 에 접근성 aria 속성을 추가해줘"

승인 모드란 무엇인가?

Codex의 핵심 차별점입니다. 실행 전 사용자 승인 수준을 3단계로 지정할 수 있습니다.

# suggest 모드 (기본값): 모든 변경 전 확인 요청
codex --approval-mode suggest "리팩터링해줘"

# auto-edit 모드: 파일 편집은 자동 승인, 명령어 실행은 확인
codex --approval-mode auto-edit "타입 오류 전부 수정해줘"

# full 모드: 파일 편집 + 명령어 실행 모두 자동 (주의 필요)
codex --approval-mode full "테스트 자동 실행 후 실패 수정"

모드	파일 편집	명령어 실행	추천 상황
suggest	확인 후	확인 후	낯선 코드베이스, 프로덕션
auto-edit	자동	확인 후	일상 개발 (권장 기본값)
full	자동	자동	테스트 환경, CI/CD

어떤 워크플로우에서 쓰이는가?

Codex는 샌드박스 실행 환경이 기본입니다. 명령어 실행 시 네트워크 접근을 제한하고 디스크 쓰기를 격리합니다. 보안이 중요한 기업 환경에 적합합니다.

# 멀티모달 — 스크린샷 전달
codex "이 스크린샷의 UI 버그를 재현하는 테스트 코드를 작성해줘" \
  --image ./screenshots/bug-report.png

# quiet 모드 — 스크립트/파이프에서 활용
cat legacy-code.js | codex -q "이 코드를 TypeScript로 변환해줘"

실전 명령어 예시 4가지

1. 함수 리팩터링

codex --approval-mode auto-edit \
  "components/Header.tsx 의 useState 3개를 useReducer 하나로 통합해줘"

2. 테스트 자동 생성

codex "lib/geo-probe.ts 의 공개 함수 전체에 대해
Vitest 단위 테스트를 작성해줘. edge case 포함"

3. GitHub Actions 작성

codex "현재 프로젝트(Next.js, pnpm, Node 22)에 맞는
CI 워크플로우 .github/workflows/ci.yml 을 작성해줘.
lint → typecheck → test → build 순서"

4. 코드 설명 (파이프 모드)

cat lib/geo-check-scoring.ts | codex -q \
  "이 점수 계산 로직을 주석 없이 한국어로 설명해줘"

Codex 설정 파일 (AGENTS.md)

Claude Code의 CLAUDE.md에 대응하는 Codex의 프로젝트 지시 파일입니다.

# AGENTS.md

## 프로젝트
Next.js 16, TypeScript strict, pnpm

## 규칙
- 기존 코드 스타일 변경 금지
- 테스트는 Vitest 사용
- PR 설명은 한국어로 작성

Agent Skills: 워크플로우 패키징

Codex도 SKILL.md로 반복 작업을 패키징합니다. CLI, IDE 확장, Codex 앱 모두에서 동일하게 동작하며, github.com/openai/skills에 커뮤니티 스킬 인덱스가 공개됩니다.

# .codex/skills/test-coverage.md
---
name: test-coverage
description: 커버리지 낮은 파일에 Vitest 테스트 자동 생성
---

lib/ 디렉토리에서 테스트 없거나 커버리지 70% 미만인 파일을 찾아
Vitest 단위 테스트를 작성해줘. edge case 포함.

codex /test-coverage      # 스킬 직접 호출

Multi-agent: 병렬 서브에이전트 (실험적)

멀티에이전트 워크플로우는 병렬 처리가 가능한 대규모 작업에 유리합니다. /experimental로 활성화합니다.

# 세션 내 멀티에이전트 활성화
> /experimental

# CSV 기반 병렬 팬아웃 — 여러 모듈을 서브에이전트로 나눠 동시 처리
codex "tasks.csv 의 각 모듈별 리팩터링을 병렬 에이전트로 처리해줘"

spawn_agents_on_csv를 사용하면 CSV 목록에서 작업을 팬아웃하고, 진행 상황·ETA를 한 화면에서 추적합니다. 서브에이전트에 닉네임을 붙여 어느 에이전트가 무슨 작업을 하는지 구분됩니다.

SWE-bench Verified (codex-1): 72.1% (1회 시도) / 83.8% (8회 시도)

2026년 신규 기능 요약

기능	내용
GPT-5.4 기본 지원	--model gpt-5.4 지정 또는 기본 모델로 사용
Codex-Spark	research preview (ChatGPT Pro 전용), 128K 컨텍스트
Fast mode 기본 활성	TUI 헤더에서 Fast/Standard 모드 실시간 표시
음성 입력	스페이스바 홀드 → 녹음·전사 (실험적: features.voice_transcription = true)
Windows 네이티브	PowerShell + Windows 샌드박스 (WSL 없이 동작)
/theme picker	세션 내 라이트·다크 테마 라이브 프리뷰 전환
TUI 코드 하이라이팅	펜스 코드 블록·diff 구문 강조

---

같은 작업을 어떻게 다르게 처리하는가?

시나리오 1: 버그 수정 + 테스트 자율화

Claude Code:

claude "app/api/auth/route.ts 의 세션 만료 버그를 수정하고,
실패 케이스 테스트 3개를 추가해서 모두 통과할 때까지 반복해줘"

→ 자율 루프: 파일 읽기 → 버그 파악 → 수정 → 테스트 실행 → 실패 시 재수정. 사람 개입 없이 완료까지 진행.

OpenAI Codex:

# 1단계: 버그 수정 (각 파일 변경 시 diff 확인 가능)
codex --approval-mode auto-edit \
  "app/api/auth/route.ts 세션 만료 처리 버그 수정"

# 2단계: 테스트 추가
codex --approval-mode auto-edit \
  "auth.test.ts 에 실패 케이스 3개 추가"

# 3단계: 테스트 실행 (명령어 실행은 확인 후)
codex --approval-mode full "pnpm test auth"

→ 단계별 확인: 각 파일 변경 diff를 보고 승인·거절 가능. 더 많은 제어권.

시나리오 2: 코드 리뷰

Claude Code:

git diff main | claude -p "이 PR 변경사항을 리뷰해줘.
보안 취약점, 성능 이슈, 가독성 순으로 정리해줘"

OpenAI Codex:

git diff main | codex -q "이 PR 변경사항을 리뷰해줘.
보안 취약점, 성능 이슈, 가독성 순으로 정리해줘"

두 도구 모두 파이프 모드로 동일하게 활용 가능합니다.

두 도구의 명령어는 어떻게 다른가?

작업	Claude Code	OpenAI Codex
자율 버그 수정	claude "찾아서 수정, 테스트 통과까지"	codex --approval-mode full "..."
안전한 탐색만	claude --allowedTools "Read,Grep,Glob"	codex --approval-mode suggest
파이프 입력	cat f | claude -p "..."	cat f | codex -q "..."
AI 커밋 메시지	claude commit	미지원 (수동 작성)
세션 재개	claude --resume <id>	세션 히스토리 (codex --history)
프로젝트 지시	CLAUDE.md	AGENTS.md
Skills	/skill-name (user-invocable·auto-invocation)	/skill-name (Agent Skills)
세션 메모리	Auto-Memory 자동 저장 + /memory	❌ (AGENTS.md 수동 관리)
Hooks 자동화	PostToolUse → 자동 린트·테스트	❌
멀티에이전트	context: fork 서브에이전트 포크	/experimental (실험적)
음성 입력	❌	✅ 실험적 (스페이스바 홀드)
모델 지정	--model claude-sonnet-4-6	--model gpt-5.4 또는 codex-spark

---

어떤 상황에서 무엇을 선택해야 하는가?

상황	추천	이유
대규모 코드베이스 전체 파악	Claude Code	1M 컨텍스트, 멀티파일 자율 편집
자율 버그 수정 루프	Claude Code	중단 없이 완료까지 반복 실행
변경 전 diff 확인·제어	Codex	--approval-mode 단계별 승인
보안 격리 환경 필요	Codex	샌드박스 기본 적용, 네트워크 제한
오픈소스·자체 수정 필요	Codex	MIT 라이선스
AI 커밋 메시지 자동화	Claude Code	claude commit 기본 지원
이미지/스크린샷 포함 작업	Codex	--image 멀티모달 지원
Claude API 이미 사용 중인 팀	Claude Code	동일 API 키, 통합 비용 최적화
세션 간 컨텍스트 자동 누적	Claude Code	Auto-Memory 기본 활성
CI/CD 자동화 파이프라인	Claude Code	Hooks로 린트·테스트 자동 연결
병렬 대규모 코드 작업	Codex	Multi-agent spawn_agents_on_csv
Windows 네이티브 환경	Codex	PowerShell 샌드박스 (WSL 불필요)

---

핵심 실행 요약

항목	Claude Code	OpenAI Codex CLI
설치	npm i -g @anthropic-ai/claude-code	npm i -g @openai/codex
API 키	ANTHROPIC_API_KEY	OPENAI_API_KEY
기본 모델	Claude Sonnet 4.6	GPT-5.4 / Codex-Spark
자율 실행 제어	--allowedTools / --dangerouslySkipPermissions	--approval-mode suggest/auto-edit/full
프로젝트 지시	CLAUDE.md	AGENTS.md
Skills	✅ SKILL.md (user-invocable + auto-invocation)	✅ SKILL.md (Agent Skills)
Auto-Memory	✅ 기본 활성 (v2.1.59+)	❌
Hooks	✅ 12개 이벤트 (PostToolUse 등)	❌
Multi-agent	✅ context: fork	✅ /experimental
커밋 지원	claude commit ✅	❌
샌드박스	선택적	기본 적용
오픈소스	❌	✅ MIT
음성 입력	❌	✅ 실험적
라이선스 모델	Anthropic API 사용량	OpenAI API 사용량

---

자주 묻는 질문 (FAQ)

관련 용어 (Glossary)

• AI 에이전트
• LLM (거대언어모델)
• 컨텍스트 윈도우
• 프롬프트 엔지니어링

---

함께 읽으면 좋은 글

• 이번 주 AI 시그널: 코드 90% AI 작성 예언의 파장
• AI 시대 개발자 생존 전략: 지금 당장 시작해야 할 5가지 전환
• 코드의 90%가 AI로 쓰이는 날: 개발자는 무엇으로 살아남는가
• AI 코딩 어시스턴트의 진화: 자동완성에서 자율 에이전트로

---

업데이트 기준

이 글은 2026년 3월 기준 Anthropic Claude Code 공식 문서 및 OpenAI Codex CLI GitHub README를 바탕으로 작성되었습니다. 두 도구 모두 빠르게 업데이트되므로 새 기능 출시 시 반영할 예정입니다.

---

참고 링크

• Anthropic: Claude Code 공식 문서
• Claude Code Skills 공식 문서
• Claude Code Memory 공식 문서
• Claude Code Changelog
• OpenAI Codex CLI GitHub
• OpenAI Codex Agent Skills 공식 문서
• OpenAI Codex Multi-agent 가이드
• Claude Code 명령어 레퍼런스