Claude Code와 Codex 병행 워크플로 — 역할 분담으로 쓰는 법

Claude Code와 Codex(오픈AI의 터미널 코딩 도구) 중 어느 쪽이 더 나은지 고르는 대신, 둘을 같은 프로젝트에서 함께 쓰는 방식이 소개되고 있습니다. 한쪽이 코드를 구현하면 다른 쪽이 그 결과를 검토하는 식으로 역할을 나누는 방식인데, 같은 모델이 자기가 쓴 코드를 스스로 검토하면 놓치기 쉬운 문제를, 다른 모델이 교차 검토해서 잡아낸다는 것이 이 방식이 쓰이는 이유입니다. 이 글은 "어떤 도구가 더 좋은가"를 비교하는 글이 아니라, 두 도구를 실제로 같이 쓰려는 사람을 위해 설치부터 역할 분담, 자주 막히는 지점까지 실전 순서로 정리했습니다. 처음 설정한다면 30분 안팎이면 두 도구를 나란히 켜 놓고 첫 번째 구현-리뷰 사이클을 돌려볼 수 있습니다.

이 글로 할 수 있게 되는 것

이 글을 따라 하면 Claude Code와 Codex를 한 프로젝트 안에서 나란히 실행하고, "구현은 Claude Code, 리뷰는 Codex" 같은 역할 분담 사이클을 최소 한 번 완성할 수 있습니다. 두 도구가 이미 각각 설치돼 있다면 역할 분담 설정과 첫 사이클까지 20~30분 정도 걸립니다. 둘 다 처음 설치하는 경우라면 계정 로그인까지 포함해 40분 정도로 잡는 것이 안전합니다.

시작 전 준비물

시작하기 전에 아래 항목을 확인해 두면 중간에 막히지 않습니다.

• 운영체제 — macOS 또는 Linux 권장. Windows에서는 Codex가 기본적으로 자체 샌드박스를 쓰지만, 저장소가 이미 WSL2(Windows용 리눅스 환경) 안에 있거나 자체 샌드박스가 동작하지 않을 때는 WSL2를 선택하도록 안내되어 있습니다. 정확한 선택 기준은 설치 화면 안내를 확인하세요.
• Node.js/npm — 두 도구 모두 npm(Node.js 패키지 관리자)으로 설치할 수 있으므로 미리 설치돼 있어야 합니다.
• Claude 계정 — Claude Code는 Free·Pro(월 $20)·Max(월 $100 또는 $200) 등 Claude 요금제 계정으로 로그인합니다.
• ChatGPT 계정 — Codex는 ChatGPT 계정으로 로그인합니다. Codex 이용에 필요한 정확한 요금제 조건은 OpenAI 공식 페이지에서 확인하세요.
• 터미널 사용 기초 — 두 도구 모두 명령줄(터미널)에서 실행하는 CLI(커맨드라인 인터페이스 — 화면 클릭 대신 글자 명령으로 프로그램을 조작하는 방식) 도구입니다.

용어 빠른 풀이

• CLI — 커맨드라인 인터페이스. 터미널에 명령어를 입력해 프로그램을 실행·조작하는 방식입니다.
• 서브에이전트 — 메인 작업과 별도의 독립된 공간에서 특정 하위 작업만 맡아 처리하고 결과만 돌려주는 보조 에이전트입니다.
• AGENTS.md — Codex를 비롯한 여러 AI 코딩 도구가 공통으로 읽도록 만들어진 프로젝트 안내 파일 표준입니다. "이 프로젝트에서는 이렇게 작업해 주세요"를 적어 두는 파일입니다.
• CLAUDE.md — Claude Code가 프로젝트 루트에서 읽는 자체 안내 파일입니다.
• 확증편향 — 같은 도구(모델)가 자신이 만든 결과물을 다시 검토할 때, 스스로의 실수나 사각지대를 놓치기 쉬운 경향을 말합니다.
• diff — 코드가 변경되기 전과 후의 차이를 보여주는 결과물입니다.

왜 두 도구를 병행하는가 — 역할 분담의 핵심

두 도구를 병행하는 핵심 이유는 "구현한 도구가 자기 코드를 다시 검토하면 같은 사각지대를 반복할 수 있다"는 점 때문입니다. Codex의 /review 명령은 작업 파일을 직접 건드리지 않고 읽기 전용으로 diff를 분석해 문제를 짚어 주는 기능으로 공식 문서에 소개돼 있는데, 이 기능을 Claude Code로 구현한 코드에 대한 2차 검토로 쓰는 조합이 실제 사용 사례로 소개되고 있습니다. 반대로 Codex가 먼저 구현하고 Claude Code가 검토하는 순서도 같은 원리로 가능합니다. 어느 쪽을 구현 담당으로 둘지는 팀의 익숙함이나 작업 성격에 따라 정하면 됩니다.

두 도구가 프로젝트 규칙을 각자 다르게 이해하면 역할 분담의 의미가 떨어지므로, 프로젝트 안내 파일을 하나로 맞춰 두는 것이 좋습니다. Codex는 AGENTS.md를 기본으로 읽고 Claude Code는 CLAUDE.md를 읽으므로, CLAUDE.md 안에서 AGENTS.md 내용을 불러오거나(가져오기 구문 사용) 두 파일을 심볼릭 링크(운영체제 차원에서 한 파일을 다른 이름으로도 가리키게 하는 연결)로 묶어 두면 한 번의 수정으로 두 도구 모두에 같은 규칙을 전달할 수 있습니다. 정확한 가져오기 구문은 Claude Code 공식 메모리 문서 화면에서 확인하는 것이 안전합니다.

단계별 실행

1. 두 CLI를 설치합니다. 터미널에서 아래 명령을 각각 실행합니다.

   npm install -g @anthropic-ai/claude-code
   npm install -g @openai/codex

   Codex는 npm 대신 Homebrew(brew install codex)나 공식 설치 스크립트로도 설치할 수 있습니다. 이렇게 보이면 성공 — 터미널에 claude --version과 codex --version을 입력했을 때 각각 버전 번호가 출력됩니다.

2. 각 도구에 로그인합니다. 프로젝트 폴더에서 claude를 실행해 Claude 계정으로 로그인하고, codex를 실행해 ChatGPT 계정으로 로그인합니다. 이렇게 보이면 성공 — 로그인 후 각 도구의 대화형 화면(프롬프트)이 뜨고 별도의 오류 메시지가 없습니다.

3. 프로젝트 안내 파일을 하나로 정리합니다. 프로젝트 루트에 CLAUDE.md를 작성한 뒤, AGENTS.md도 함께 쓰고 있다면 두 파일을 연결합니다.

   ln -s AGENTS.md CLAUDE.md

   또는 CLAUDE.md 안에 AGENTS.md를 가져오는 구문을 추가하는 방법도 있습니다(정확한 구문은 Claude Code 공식 메모리 문서 화면에서 확인하세요). 이렇게 보이면 성공 — cat CLAUDE.md로 열었을 때 AGENTS.md의 내용이 함께 보이거나 반영됩니다.

4. 역할을 정합니다. 예를 들어 "Claude Code가 기능을 구현하고, Codex가 리뷰한다"로 정했다면 이 순서를 팀 안에서 문서화해 둡니다. 구현이 오래 걸리는 작업이라면 Claude Code의 서브에이전트(.claude/agents/ 폴더에 설정)로 하위 작업을 나눠 병렬로 처리할 수도 있습니다.

5. 구현 담당 도구로 기능을 작성합니다. 터미널에서 claude를 실행하고 원하는 기능을 요청합니다. 작업이 끝나면 변경 사항을 커밋해 둡니다. 이렇게 보이면 성공 — git status에 의도한 파일만 변경된 것으로 표시됩니다.

6. 리뷰 담당 도구로 검토합니다. 같은 프로젝트에서 codex를 실행한 뒤 /review 명령을 입력합니다. 이 명령은 읽기 전용으로 동작해 작업 파일을 직접 바꾸지 않고, 방금 만든 diff(변경분)를 분석해 우선순위가 매겨진 지적 사항을 돌려줍니다. 이렇게 보이면 성공 — 리뷰 결과 목록이 출력되고, 실행 후 git status로 확인해도 파일이 추가로 바뀌어 있지 않습니다.

7. 지적 사항을 반영합니다. Codex가 짚은 문제를 다시 Claude Code 세션으로 가져와 수정을 요청하고, 필요하면 5~6단계를 한 번 더 반복한 뒤 최종 커밋합니다.

자주 막히는 지점과 해결

병행 워크플로를 처음 설정할 때 걸리기 쉬운 지점은 대부분 두 도구가 서로 다른 파일 규칙과 실행 환경을 갖고 있다는 데서 나옵니다.

• Claude Code가 AGENTS.md 내용을 반영하지 않는다 — Claude Code는 AGENTS.md를 기본으로 읽지 않습니다. 3단계의 심볼릭 링크나 가져오기 설정이 됐는지 다시 확인하세요.
• 두 도구가 같은 파일을 동시에 고쳐 충돌한다 — 두 CLI를 같은 프로젝트에서 동시에 켜 두고 나란히 작업하면 같은 파일에 서로 다른 변경이 겹칠 수 있습니다. 구현 담당 도구의 작업을 커밋한 뒤 리뷰 담당 도구를 실행하는 순차 방식이 더 안전합니다.
• Windows에서 Codex 설치·실행이 불안정하다 — 저장소가 WSL2 환경에 있거나 자체 샌드박스가 동작하지 않는 경우 WSL2 경로를 선택하도록 안내되어 있습니다. 설치 화면의 안내 문구를 따라가세요.
• 리뷰에 쓰이는 모델을 바꾸고 싶다 — Codex는 설정 파일(~/.codex/config.toml)의 review_model 항목으로 리뷰 전용 모델을 지정할 수 있다고 안내되어 있습니다. 값을 지정하지 않으면 현재 세션 모델이 그대로 쓰입니다. 정확한 옵션명은 버전에 따라 달라질 수 있으니 화면·문서에서 최종 확인하세요.

응용과 다음 단계

기본 사이클(구현 → 리뷰 → 반영)에 익숙해졌다면, Claude Code 쪽에서 .claude/agents/ 폴더에 목적별 서브에이전트를 등록해 구현 단계 자체를 더 잘게 나눠 병렬로 처리할 수 있습니다. Codex도 여러 개의 서브에이전트를 동시에 띄울 수 있는 기능이 있으므로, 리뷰 담당 쪽에서도 "보안 검토"·"성능 검토"처럼 관점을 나눠 병렬로 돌리는 응용이 가능합니다. 다만 서브에이전트 병렬 실행의 정확한 개수 제한이나 옵션명은 버전에 따라 바뀔 수 있으니 실행 전 각 도구의 공식 문서로 확인하는 것이 안전합니다. 두 도구를 오래 병행하다 보면 Claude Code 쪽 사용량 한도를 신경 써야 할 때도 있는데, 플랜별 한도는 Claude 사용량 한도 가이드에서 확인할 수 있습니다.

자주 묻는 질문

Q. Claude Code와 Codex를 같이 쓰면 요금이 이중으로 드나요?
네, 두 도구는 별도 계정·별도 요금 체계입니다. Claude Code는 Free·Pro·Max 같은 Claude 요금제로, Codex는 ChatGPT 계정으로 각각 인증하고 각자의 요금 정책을 따르므로, 정확한 금액은 각 공식 요금 페이지에서 확인하는 것이 안전합니다.

Q. 굳이 두 도구를 나눠 써야 하나요? 한 도구로 구현과 리뷰를 다 하면 안 되나요?
한 도구만으로도 작업은 가능하지만, 같은 모델이 자신이 쓴 코드를 스스로 다시 검토하면 같은 사각지대를 반복해서 놓치기 쉽다는 점이 병행 워크플로가 소개되는 이유입니다. 서로 다른 모델이 교차 검토하면 이런 확증편향을 줄일 수 있습니다.

Q. CLAUDE.md와 AGENTS.md를 둘 다 따로 관리해야 하나요?
아니요, 하나로 합쳐서 관리할 수 있습니다. Codex는 AGENTS.md를, Claude Code는 CLAUDE.md를 기본으로 읽으므로, 심볼릭 링크나 가져오기 설정으로 두 파일을 연결해 두면 한 번의 수정으로 양쪽 도구에 같은 프로젝트 규칙을 전달할 수 있습니다.

Q. 두 도구를 같은 프로젝트에서 동시에 실행해도 되나요?
기술적으로는 가능하지만, 같은 파일을 두 도구가 동시에 고치면 충돌이 생기기 쉽습니다. 구현 담당 도구의 작업을 커밋으로 매듭지은 뒤 리뷰 담당 도구를 실행하는 순차 방식을 권합니다.