"Codex + Claude Code 병행 워크플로우 2026 — 한 레포에서 두 툴의 역할 분담 실전"

-

AGENTS.md ↔ CLAUDE.md 공유, 강점 매트릭스, 탐색·구현·리뷰 파이프라인, 충돌 회피

핵심 요약

  • 대상 독자: Codex와 Claude Code를 둘 다 유료 구독하고 있거나 팀에서 병행 중이라 역할 분담이 필요한 사용자.
  • 얻을 것: 두 툴의 공식 문서 기준 강점·약점 매트릭스, 한 레포에서의 충돌 회피(디렉터리·지침 파일·샌드박스), AGENTS.md를 CLAUDE.md로 import하는 단일 소스 전략, 대표적 2가지 파이프라인 패턴.
  • 선행 조건: Claude Code 설치와 Codex CLI 설치 완료. AGENTS.md와 CLAUDE.md 기초 이해.

1. 왜 둘 다 쓰는가

공식 문서 기준 두 툴은 다른 설계 타겟을 가진다.

관찰 포인트 Claude Code (공식) Codex (공식)
구현 언어 Node/네이티브 바이너리 (자동 업데이트) Rust 네이티브 바이너리
기본 인증 Claude Pro/Max/Team/Enterprise 또는 Console ChatGPT Plus/Pro/Business/Edu/Enterprise 또는 API Key
확장 시스템 Skills · Hooks · Subagents · Plugins · MCP Skills · Sandbox · MCP (Hooks는 experimental codex_hooks 플래그)
샌드박스 /sandbox 토글, OS-level 격리 (Linux seccomp / macOS sandbox-exec 등) 3모드 (read-only/workspace-write/danger-full-access) + Windows 네이티브 샌드박스
지침 파일 CLAUDE.md (advisory) AGENTS.md (프로젝트 첫 턴에 항상 주입)
비용 모델 구독 정액 또는 토큰 pay-as-you-go 구독 정액 또는 API key
모델 Claude (Sonnet / Opus / Haiku) GPT-5, GPT-5-Codex

이 차이에서 나오는 결론: 둘이 잘하는 영역이 다르다. 병행은 경쟁이 아니라 보완.

2. 강점 매트릭스 (관찰 기반)

공식 문서에서 제시하는 기능 + 실제 사용 경험을 근거로 정리. 완전 객관은 아니며 프로젝트·작업 성격에 따라 달라질 수 있다.

작업 성격 Claude Code 강점 Codex 강점
장시간 탐색 / 대화형 디자인 ✅ 서브에이전트 + /compact + Skills 상대적으로 덜 풍부
정확한 코드 수정 (특정 함수/버그) 가능 ✅ GPT-5-Codex가 short-form edit에 강점
테스트/린트 자동화 ✅ 훅으로 PostToolUse 포맷/린트 sandbox 내 auto-run + approval
CI/CD 스크립트 자동화 claude -p로 가능 ✅ codex exec + profile로 built-in
플러그인 · 커스텀 스킬 생태계 ✅ 5,000+ 커뮤니티 스킬 제한적
로컬 OSS 모델 (Ollama 등) MCP 경유 ✅ model_providers에 로컬 provider 직접 등록
Windows 네이티브 개발 지원 (Git for Windows 필요) ✅ PowerShell + Windows sandbox 1급 지원
장문 아키텍처 설계 ✅ Opus 4.7 + plan mode GPT-5 + plan mode
팩트체크·검증 파이프라인 ✅ Skills로 쉽게 구성 구성 가능하나 수고 더 든다

요약: 탐색·오케스트레이션 · 긴 리서치는 Claude Code가 유리, 정밀 코드 수정·CI 자동화·Windows 네이티브는 Codex가 유리. 절대 규칙은 아니고, 실제로는 시도해보고 판정.

3. 한 레포에서의 충돌 지점 — 사실 확인

두 툴이 같은 프로젝트에 공존할 때 구조적 충돌은 거의 없다. 각 툴이 쓰는 디렉터리·파일이 독립적.

리소스 Claude Code Codex 충돌?
설정 디렉터리 .claude/ .codex/ ❌
사용자 디렉터리 ~/.claude/ ~/.codex/ ❌
프로젝트 지침 CLAUDE.md AGENTS.md ❌ (파일명 다름)
세션 파일 .claude/sessions/... ~/.codex/sessions/... (SQLite) ❌
MCP 설정 .mcp.json 또는 .claude/settings.json config.toml의 [mcp_servers] ❌ (경로 다름)
샌드박스 OS-level TOML-configured ❌ (서로 간섭 없음)
/model, /mcp, /config 세션 내 명령 세션 내 명령 ❌ (각 세션 독립)

주의할 점이 하나 있다: 같은 파일을 동시에 수정하면 두 툴 중 나중 저장이 앞을 덮어쓴다. 병행 시 같은 파일을 동시 작업하지 않는 규칙 필요.

4. 지침 단일화 — AGENTS.md를 CLAUDE.md에서 import

공식 문서가 명시한 방법. 같은 내용을 두 파일에 중복 유지하지 않는다.

4.1 구조

AGENTS.md를 프로젝트 지침의 주 소스로 둔다.


## 개발 규칙
- TypeScript strict mode 필수
- 테스트는 `pnpm test` (npm 아님)
- 커밋 메시지 Conventional Commits

## 배포
- 스테이징은 자동, 프로덕션은 수동 승인

CLAUDE.md는 AGENTS.md를 먼저 import하고, 필요하면 Claude Code 전용 섹션을 덧붙인다:

@AGENTS.md

## Claude Code 전용

Plan 모드를 `src/billing/` 아래 변경에 사용.
큰 리팩터링은 서브에이전트로 delegate.

4.2 로딩 규칙 차이 기억

Claude Code Codex
디렉터리 탐색 현재 cwd에서 상위로 walk up, 전부 concat Git 루트에서 cwd까지 walk down, 각 디렉터리당 1개
우선순위 개별 파일은 concat (덮어쓰기 아님) 하위가 상위 override
오버라이드 전용 파일 CLAUDE.local.md (gitignore) AGENTS.override.md (팀 공유 가능)

같은 내용을 AGENTS.md에 두고 Claude 전용 섹션은 CLAUDE.md 아래에 추가 — 이 패턴이 혼동을 줄인다.

4.3 팀 공유 시 .gitignore

.claude/settings.local.json
CLAUDE.local.md
.codex/sessions/
~/.codex/history.jsonl  # 개인 레벨이라 레포에 안 들어가지만 참고

팀 공유할 것: CLAUDE.md, .claude/settings.json, .claude/skills/, AGENTS.md, .codex/config.toml (프로젝트 레벨이면).

5. 파이프라인 패턴 A — 탐색·구현 분리

가설: 긴 탐색과 설계는 Claude Code가 유리, 정확한 편집은 Codex가 유리.

5.1 워크플로우

Claude Code (탐색·플랜)
  ↓ 결과를 docs/spec-XXX.md 또는 brief로 저장
Codex exec (정밀 편집 자동 적용)
  ↓ diff/commit
Claude Code (리뷰·테스트)

5.2 실제 예

Step 1 — Claude Code로 플랜

/plan 사용자 인증 플로우에 rate limiting 추가.
기존 auth 레이어를 분석하고, rate-limit 전략 2~3개 비교해서 추천.
결과를 docs/plan/rate-limit.md로 저장.

Step 2 — Codex로 정밀 구현

codex exec "docs/plan/rate-limit.md에 정의된 스펙대로 \
  src/auth/rate-limit.ts 구현 + 테스트 추가. \
  테스트 100% 통과 후 diff 보여줘."

Step 3 — Claude Code로 리뷰

/review
다음으로 @docs/plan/rate-limit.md와 실제 구현 비교.
누락된 엣지 케이스 3개 찾아줘.

5.3 왜 이렇게 분리

  • 탐색은 파일 많이 읽어 컨텍스트 소모 큼 → Claude Code의 서브에이전트와 /compact 활용
  • 구현은 작은 범위의 정확한 diff 선호 → Codex의 sandbox + approval로 안전 보장
  • 리뷰는 다시 넓은 시야가 필요 → Claude Code로 복귀

6. 파이프라인 패턴 B — 이중 리뷰

가설: 동일 변경을 두 툴이 독립적으로 리뷰하면 맹점이 줄어든다. Anthropic 공식 best practices도 "Writer/Reviewer" 패턴을 권장(같은 툴 두 세션 기준).

6.1 워크플로우

개발자 (변경 푸시)
  ↓
Claude Code: /review (로컬) — 코드 스타일·버그·테스트 커버리지
Codex: codex exec "review" — 다른 관점에서 정밀 검토
  ↓
두 리뷰 비교 → 개발자가 수정

6.2 실제 명령

claude -p "주어진 diff를 검토. 버그와 엣지 케이스 중심으로."

codex exec "git diff HEAD~1 | 검토. 보안/성능 관점 중심."

두 결과를 붙여놓고 중복 지적은 높은 우선순위로 처리. 한쪽만 지적한 것은 교차 검증 필요.

7. 모델 라우팅 제안

모델 가격·성능을 고려한 역할 분담 예.

단계 툴 / 모델 이유
대화형 탐색 Claude Code + Sonnet 4.6 ($3/$15) 컨텍스트 큰 탐색에 경제적
플랜 (아키텍처) Claude Code + Opus 4.7 ($5/$25) 긴 reasoning에 강점
정밀 편집 Codex + GPT-5-Codex short-form edit 특화 모델
루틴 작업 (rename 등) Codex + Haiku급 모델 (MCP 경유 OSS) 비용 최소화
CI 린트/포맷 Codex codex exec --profile ci 자동화 + sandbox 안전

Claude Code 비용 구조는 토큰·캐시 해부 참고.

8. 흔한 질문 — "두 툴 구독료 다 내야 하나?"

절대적이지 않은 답:

  • 혼자 쓰는 개발자: 하나만 월정액, 다른 쪽은 API key로 pay-as-you-go. 캐주얼 사용 수준이면 월 $5~20 미만 추가.
  • 팀: 역할 분담이 명확하면 팀원별로 주 툴을 다르게 할당 (절반은 Claude, 절반은 Codex). 리뷰 단계에서 교차.
  • 엔터프라이즈: Bedrock/Vertex/Azure 중 이미 쓰는 클라우드가 있다면 해당 provider 경유로 통합.

9. 반대 시나리오 — 병행하지 말아야 할 때

  • 초보자가 이제 막 시작 → 두 툴을 동시에 익히면 혼선만 커진다. 하나에 3개월 익힌 뒤 다른 쪽 도입.
  • 팀이 이미 한 툴로 표준화 → 새 툴 도입은 표준 깨는 비용이 크다. 실험 프로젝트에서만 시도.
  • 같은 파일을 동시 편집하는 워크플로 → 병행의 이점보다 충돌 관리 비용이 크다. 시간대를 분리하거나 파일 범위를 나눈다.
  • 모델 선호가 명확 → 강하게 선호하는 모델이 한쪽에만 있으면 굳이 다른 쪽을 섞을 이유 없다.

10. 체크리스트 — 병행 시작 전 확인

  • [ ] .gitignore에 .claude/settings.local.json, CLAUDE.local.md, .codex/sessions/ 추가
  • [ ] AGENTS.md를 주 지침으로 하고 CLAUDE.md가 @AGENTS.md import
  • [ ] 같은 파일 동시 편집 금지 규칙 (팀 합의)
  • [ ] 두 툴 각자의 /memory·/mcp·/config로 현재 상태 점검
  • [ ] 첫 주는 Claude Code 탐색 → Codex 구현 파이프라인 시험
  • [ ] 비용은 각 툴의 /usage·/cost로 주간 체크

11. 다음 단계

Codex 파트는 이 글로 마무리. 다음은 OpenClaw 파트.

  1. OpenClaw 설치 → Discord 봇 30분 + ClawHub 안전 스킬 10선 (예정)
  2. Codex 설치 완전판 — 아직 Codex 미설치 시.
  3. Codex 고급 설정 — config.toml로 프로파일 전환 패턴.

참고

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 8/15 편입니다. 여기서 Codex 파트가 끝나고 다음 편부터 OpenClaw 파트로 넘어갑니다. last verified: 2026-04-25 (Claude Code 및 Codex 공식 문서 기준. 강점 매트릭스는 공식 사양 + 관찰 기반이며 절대적 기준 아님).

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »