Molayo

© 2026 Molayo

Zenn헤드라인2026. 05. 18. 20:02

Codex와 Claude Code의 협업을 위한 cross-agent-harness 개발

요약

OpenAI의 Codex와 Anthropic의 Claude Code를 동일한 리포지토리에서 병용할 때 발생하는 협업 충돌을 해결하기 위한 'cross-agent-harness' 개발 사례를 소개합니다. 이 도구는 규칙, handoff 템플릿, skills, 도입 스크립트를 포함한 경량 키트로, 여러 AI 에이전트 간의 작업 경계를 명확히 하고 작업 이력을 체계적으로 관리할 수 있게 돕습니다.

핵심 포인트

  • Codex와 Claude Code 간의 작업 범위 중복 및 정보 누락 문제 해결
  • 공통 규칙과 프로젝트별 고유 설정을 분리하여 이식성 확보
  • handoff 프로토콜과 공유 로그를 통한 에이전트 간 작업 연속성 유지
  • PowerShell 스크립트를 이용한 간편한 프로젝트 도입 방식 제공

서론

Claude Code와 Codex를 동일한 리포지토리(Repository)에서 사용하다 보면, 모델의 성능과는 별개의 문제로 난관에 부딪히게 됩니다.

여기서 Codex는 OpenAI의 Codex CLI를, Claude Code는 Anthropic의 Claude Code를 의미합니다. 둘 다 터미널에서 동작하는 코딩 에이전트(Coding Agent)이며, 이 기사는 두 에이전트를 동일한 리포지토리에서 병용한다는 전제하에 작성되었습니다.

어느 쪽이 무엇을 수정해도 되는가. 리뷰 결과는 어디에 남길 것인가. merge나 publish 전에 무엇을 확인해야 하는가. 한쪽 AI가 만든 변경 사항을 다른 쪽이 모르는 상태에서 되돌리지 않으려면 어떻게 해야 하는가.

지금까지는 프로젝트별로 AGENTS.md, CLAUDE.md, CLAUDE_CODE_HANDOFF.md에 그때그때 규칙을 추가해 왔습니다. Zenn에서도 해당 운영 방식에 대해 몇 가지 기사를 작성한 바 있습니다.

  • Claude Code의 운영을 rules와 skills로 나눈 이야기 - AI 2대의 크로스 리뷰(Cross-review)로 기술 기사의 맹점을 찾아낸 이야기
  • AI와의 설계 판단을 My-Skill-Graph에 남겨 재사용한 이야기

하지만 여러 프로젝트에서 같은 작업을 반복하다 보니, 이를 각 리포지토리에 수동으로 흩뿌려 놓기보다는 이식 가능한 키트(Kit)로 만드는 것이 좋겠다고 느꼈습니다.

그래서 만든 것이 harness17/cross-agent-harness입니다.

cross-agent-harness는 Codex와 Claude Code를 동일한 리포지토리에서 운용하기 위한 경량 공동 개발 하네스(Harness)입니다. 앱 본체가 아니라 규칙(Rule), handoff 템플릿, skills, 도입 스크립트를 모아둔 키트입니다.

무엇을 해결하기 위한 리포지토리인가

AI 에이전트를 여러 개 사용하면 편리한 반면 경계가 모호해집니다.

예를 들어, 저의 운영 방식에서는 다음과 같은 문제들이 발생했습니다.

  • Claude Code가 설계한 내용을 Codex가 어디까지 구현해도 되는지 알 수 없음
  • Codex가 구현 후 실행한 verify 결과가 다음 리뷰 담당자에게 전달되지 않음
  • 리뷰 담당자가 요청하지 않은 파일까지 덤으로 수정해 버림
  • merge / publish 해도 되는 조건이 대화 흐름에 따라 흔들림
  • 프로젝트마다 동일한 handoff 형식을 매번 다시 만듦

이는 단순히 "AI에게 더 자세히 설명하는 것"만으로는 안정화되지 않았습니다. 필요한 것은 작업 전, 작업 중, 작업 후에 확인하는 장소를 고정하는 것이었습니다.

cross-agent-harness에서는 그 고정되는 부분을 다음과 같이 나누었습니다.

  • 공통 규칙: .claude/rules/cross-agent-harness.md
  • handoff 서식: .claude/rules/handoff-protocol.md
  • 프로젝트 고유 설정: .claude/rules/project-collaboration-profile.md
  • Claude Code 측 skill: codex-handoff / cross-review
  • Codex 측 skill: implement-task
  • 공유 로그: CLAUDE_CODE_HANDOFF.md

공통 규칙과 프로젝트 고유 설정을 분리한 것이 핵심입니다. 어떤 프로젝트에서든 지켜야 할 작업 계약은 공통 규칙에 두고, verify 명령, 주의 영역, 중대 지적 사항은 프로젝트별 profile에 둡니다.

설치 스크립트로 대상 프로젝트에 이식하기

도입은 PowerShell 스크립트로 진행합니다.

.\install.ps1 -TargetPath C:\Projects\MyApp -ProjectName MyApp

PowerShell 7이 있다면 macOS / Linux에서도 동일한 스크립트를 사용할 수 있습니다.

pwsh ./install.ps1 -TargetPath /path/to/my-app -ProjectName MyApp

기존의 project-collaboration-profile.md와 CLAUDE_CODE_HANDOFF.md는 -Force 옵션을 붙이지 않는 한 덮어쓰지 않습니다. 이 부분은 의도적으로 보수적으로 설계했습니다. 공동 작업 로그나 프로젝트 고유 profile은 덮어쓰기 사고가 발생했을 때의 영향이 크기 때문입니다.

실제로 복사되는 파일은 다음과 같습니다.

.claude/rules/cross-agent-harness.md
.claude/rules/handoff-protocol.md
.claude/rules/project-collaboration-profile.md
...

install.ps1

의 핵심은 템플릿 내의 {{PROJECT_NAME}}과 {{TARGET_PATH}}를 치환하여 대상 프로젝트에 배치하는 처리입니다.

$content = [System.IO.File]::ReadAllText($template, [System.Text.UTF8Encoding]::new($false, $true))
$content = $content.Replace("{{PROJECT_NAME}}", $ProjectName)
$content = $content.Replace("{{TARGET_PATH}}", $targetRoot.Path.Replace("\", "/"))
...

작은 처리이지만, 매번 수동으로 파일을 만드는 것보다 사고를 줄일 수 있습니다. 특히 CLAUDE_CODE_HANDOFF.md와 프로파일 (profile)의 초기 형태가 갖춰지는 점이 효과적이었습니다.

project-collaboration-profile에 프로젝트 고유의 판단을 두기

하네스 (harness)를 공통화할 때 주의한 점은, 모든 것을 공통 규칙으로 밀어 넣지 않는 것입니다.

ASP.NET Core MVC, Electron + React, Chrome 확장 프로그램, Zenn 기사 리포지토리(repository)는 살펴봐야 할 리스크가 다릅니다.

예를 들어 ASP.NET Core MVC라면 인가 (authorization), 소유자 체크, Identity, 마이그레이션 (migration), appsettings.Development.json, 샘플 (Sample) 간 의존성이 중요합니다. 반면 Electron 앱이라면 린트 (lint), 테스트 (test), 빌드 (build), 서명, 배포 경로, SmartScreen 관련 확인이 중심이 됩니다.

그래서 프로젝트별 차이점은 project-collaboration-profile.md에 모았습니다.

## 담당 경계
| 조건 | 전달 대상 |
|------|--------|
...

이 표가 있으면 "이번에는 Codex에 맡겨야 할지, Claude Code로 설계를 구체화해야 할지"를 매번 대화로 결정할 필요가 없습니다.

물론 표만으로 판단이 완전히 자동화되는 것은 아닙니다. 다만, 망설여질 때 돌아갈 곳이 생깁니다.

handoff를 공유 로그로 만들기

CLAUDE_CODE_HANDOFF.md는 Codex와 Claude Code의 공유 작업 로그입니다.

여기에는 작업 의뢰, 작업 가능 범위, 완성 조건, 검증 (verify) 결과, 리뷰 관점, 다음 액션 (next action)을 남깁니다.

### 완성 조건 (스프린트 컨트랙트)
- Claude Code가 Codex로 구현 의뢰를 생성할 수 있다.
- Codex가 handoff로부터 구현 · 검증 (verify) · handoff 업데이트로 진행할 수 있다.
...

이전 기사 「AI 2대 크로스 리뷰로 기술 기사의 맹점을 포착하기」에서는 작성자와 리뷰어 (reviewer)를 나누는 운용법을 다루었습니다. cross-agent-harness에서는 그 사고방식을 기사 작성뿐만 아니라 구현, 리뷰, 검증으로 확장했습니다.

특히 중요하게 여기는 것은 머지 (merge) / 퍼블리시 (publish) 조건입니다.

1. 셀프 검증 (self verify) 완료
2. 상대측 리뷰 완료
3. 중대한 지적 사항 없음
...

AI 에이전트 (agent)가 "괜찮아 보이므로 공개하겠습니다"라고 진행하지 않도록, 최종 판단은 사용자의 명시적 행위에 가깝게 두었습니다. 이는 Zenn 기사의 published: true 게이트 (gate)에서 효과를 보았던 사고방식을 그대로 공동 개발에 가져온 것입니다.

Claude Code 측과 Codex 측의 스킬 (skill) 분리

이 하네스에서는 Claude Code 측과 Codex 측의 스킬 역할도 나누고 있습니다.

Claude Code 측에는 Codex로 전달하기 위한 codex-handoff와, 반대편의 변경 사항을 리뷰하는 cross-review를 둡니다.

Codex 측에는 handoff로부터 한정된 태스크 (task)를 구현하는 implement-task를 둡니다.

시작 시

  1. CLAUDE_CODE_HANDOFF.md의 최신 섹션을 읽는다.
  2. .claude/rules/project-collaboration-profile.md를 읽는다.
    ...

여기서 하고자 하는 것은 만능 자동화가 아닙니다. 작업 시작 시 읽어야 할 항목을 고정하는 것입니다.

Codex가 갑자기 구현에 들어가는 것이 아니라, handoff, profile, 미커밋 변경 사항을 확인한 후 한정된 범위를 다룹니다. Claude Code는 설계나 리뷰 관점을 handoff에 남깁니다. 이렇게 역할을 분담하면 동일한 리포지토리(Repository)에서 작업하더라도 충돌이 발생하기 어려워집니다.

이미 도입한 프로젝트

README에는 현재 시점의 도입 실적도 기재되어 있습니다.

프로젝트종류확인한 verify
DevNextASP.NET Core MVC templatedotnet build DevNext.slnx / dotnet test .\Tests\Tests.csproj
PhycockASP.NET Core MVC health management app기존 profile / handoff 운용 확인
YouTomElectron + React desktop appnpm run lint / npm run test / npm run build
GoogleChromeExtensionsManifest V3 Chrome extensions containernode .\verify-detect.mjs

이 목록은 단순한 실적 메모가 아닙니다.

자신이 어떤 종류의 프로젝트에서 이 harness를 테스트했는지 남김으로써 profile의 사례를 늘릴 수 있습니다. ASP.NET Core MVC용으로는 examples/aspnetcore-mvc-profile.md도 마련해 두었습니다.

향후 다른 종류의 리포지토리에 도입할 때는 공통 규칙(Common rules)을 늘리기보다 profile의 사례를 먼저 늘리는 방침입니다. 공통 규칙이 비대해지면 모든 프로젝트에서 읽어야 한다는 부담이 커지기 때문입니다.

기존 기사와의 연결성

cross-agent-harness는 지금까지의 기사들을 재정리한 것이기도 합니다.

「Claude Code 운용을 몇 달간 검토하여 rules와 skills로 나눈 이야기」에서는 거대한 CLAUDE.md를 분할하여, 작업 영역별 규칙과 skill로 나누는 방침을 썼습니다. 이번 harness에서는 그 분할을 프로젝트 횡단 형태로 만들었습니다.

「AI 2대 크로스 리뷰로 기술 기사의 맹점을 포착하기」에서는 작성자와 리뷰어를 분리함으로써 사실 오인이나 보안 리스크를 포착한 이야기를 썼습니다. 이번 harness에서는 그 역할 분담을 기사뿐만 아니라 구현 태스크(Task)로도 확장했습니다.

「AI와의 설계 판단을 My-Skill-Graph에 남겨 재사용하기」에서는 대화 로그가 아닌 판단을 남기는 이야기를 썼습니다. 이번 harness에서는 handoff에 작업 결과와 다음 액션(Next action)을 남기고, 필요한 판단은 Skill Graph로 보낼 수 있도록 했습니다.

즉, cross-agent-harness는 새로운 발상이라기보다, 실제로 효과가 있었던 운용 방식을 이식 가능한 형태로 정리한 것입니다.

요약

cross-agent-harness는 Codex와 Claude Code를 동일한 리포지토리에서 사용하기 위한 공동 개발 키트입니다.

핵심은 AI를 자동으로 똑똑하게 만드는 메커니즘이 아니라, 작업 경계, handoff, verify, 리뷰, merge / publish 게이트(Gate)를 명문화하는 것입니다.

현재까지 자신의 운용에서 효과를 보고 있는 점은 다음 세 가지입니다.

  • 공통 규칙과 프로젝트 고유 profile을 분리한다.
  • CLAUDE_CODE_HANDOFF.md에 의뢰, 구현, verify, 리뷰를 집약한다.
  • merge / publish는 셀프 verify, 반대편 리뷰, 중대한 지적 없음, 사용자 명시라는 4가지 조건에서 멈춘다.

AI 에이전트를 여러 개 사용하면 대화만으로 운용을 유지하기는 어려워집니다. 작업 계약을 리포지토리에 두고, 차이(Diff)를 통해 키워 나갑니다. 이를 위한 작은 키트로서 cross-agent-harness를 만들었습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0