Claude와 Codex를 한 레포에서 같이 쓰는 법: 두 AI 에이전트 역할 분담 워크플로우 (id.news.hada.io)

한줄 요약

Claude Code가 코드를 쓰고, Codex가 advisory로 리뷰하는 역할 분담 구조로 단일 에이전트의 blind spot을 메운다.

어떤 상황에서 필요한가?

AI 코딩 도구를 하나만 쓸 때 가장 크게 느끼는 불편함이 있다. 같은 모델이 코드를 작성하고 스스로 리뷰하면, 자신이 세운 가정을 그대로 받아들이는 경향이 강해서 논리적 허점이 그냥 통과된다. race condition이나 null check 누락 같은 버그가 "이미 잘 작성됐다"는 확신과 함께 머지되는 상황이다.

이 문제는 사실 인간 코드 리뷰와 동일한 구조다. 한 사람이 PR을 작성하고 혼자 리뷰하면 regrssion을 잡기 어렵다. 그래서 팀에서는 다른 사람이 리뷰한다. AI 에이전트도 마찬가지다. 핵심은 "어떤 모델이 더 뛰어난가"가 아니라 "서로 다른 모델이 상대방의 가정을 검증할 수 있는가"다.

Claude Code의 slash command와 sub-agent 기능, Codex의 review/exec 분리, 그리고 AGENTS.md 같은 컨텍스트 파일이 갖춰진 지금이 이 구조를 실제로 도입할 수 있는 현실적인 시점으로 보인다.

핵심 구현 방법

역할 분리 원칙

Claude Code는 주 작성자, Codex는 advisory 리뷰어로 고정한다. 중요한 건 advisory는 절대 blocker가 되어서는 안 된다는 점이다. Codex가 CRITICAL 이슈를 발견해도 push는 통과된다. 한 번이라도 blocker로 바꾸면, 모델이 다운됐을 때 전체 작업이 멈추고, false positive 하나가 나오는 순간 사람들은 --no-verify로 hook 전체를 우회하기 시작한다. hook이 형식적 존재로 전락하는 순간이다.

CLAUDE.md와 AGENTS.md는 내용이 달라야 한다

두 파일의 내용이 80% 이상 겹친다면 역할 분담이 실제로 작동하지 않고 있다는 신호다. CLAUDE.md는 "어떻게 만들 것인가"에 집중하고, AGENTS.md는 "무엇을 의심해야 하는가"에 집중해야 한다. 작성자 입장의 지침과 리뷰어 입장의 체크리스트는 본질적으로 다르다.

codex review --base vs codex exec 선택 기준

codex review --base는 git을 직접 읽어서 깔끔하지만, 대형 PR에서는 token이 급격히 늘어난다. codex exec는 diff를 직접 prompt에 넣을 수 있어서 비용 통제가 가능하다. 변경 파일이 100개를 넘는 경우에는 exec 방식으로 전환하는 것이 실용적이다.

pre-push hook 이중 방어 구조

보안 파일 처리는 advisory 원칙과 별개다. .env, *.pem, secrets/ 같은 파일 패턴은 push 자체를 차단하고, sk-, ghp_, AKIA 같은 인라인 regex는 경고만 준다. 모델 output에 대한 "never block" 규칙과, 시크릿 파일이 외부로 나가는 보안 사고는 다른 범주다. 후자는 차단이 맞다.

graceful degradation wrapper

JSON envelope을 기본으로 하고 --raw 옵션으로 Markdown 출력을 지원한다. bash native timeout과 항상 exit 0으로 종료하는 구조를 유지하면, 호출하는 쪽은 status 값만 보고 분기하면 된다. 어느 한 에이전트가 응답하지 않아도 파이프라인이 죽지 않는다.

실전에서 주의할 점

한 달간 직접 운영한 경험을 담은 원문 내용에서 가장 인상적인 변화는 세 가지다.

첫째, merge 직전 버그 발견율이 올라간다. Claude가 자신 있게 "잘 작성됐다"고 판단한 코드에서 Codex가 race condition이나 null check 누락을 잡아내는 케이스가 실제로 반복된다.

둘째, self-review 피로감이 줄어든다. 다음 날 아침 자신이 쓴 코드를 보며 "왜 이렇게 썼지?"라는 감각이 거의 사라진다. 리뷰 시점에 이미 다른 관점이 한 번 들어갔기 때문이다.

셋째, SQL 마이그레이션이나 결제 흐름처럼 롤백이 어려운 변경에서 심리적 안전감이 다르다. 실행 전에 다른 모델이 한 번 더 봤다는 사실 자체가 의사결정의 질을 바꾼다.

구조 전체를 관통하는 핵심 통찰은 하나다. 두 에이전트가 서로의 gate가 되는 순간 이 워크플로우는 망가진다. 가치는 "서로를 막는 것"이 아니라 "서로의 blind spot을 겹쳐서 보완하는 것"에서 나온다.