두 에이전트 CLI를 하나의 저장소에서 사용하기: Claude Code와 Codex 간의 컨텍스트 공유 방법

저는 매일 macOS 환경에서 동일한 코드베이스에 대해 Claude Code와 Codex를 실행합니다. 처음 한 달 동안은 두 도구가 서로의 작업을 덮어쓰는 바람에, 코드를 작성하는 시간보다 컨텍스트를 전달하는 데 더 많은 시간을 소비했습니다.

핵심 요약.

• 하나의 저장소에서 작동하는 두 에이전트 CLI는 분리되는 두 개의 파일이 아니라 하나의 공유 지침 파일을 필요로 합니다.

• Git worktree를 사용하면 각 에이전트가 자체 체크아웃을 가지게 되어 편집 충돌을 막을 수 있습니다.

• 핸드오프(handoff) 파일은 컨텍스트 재설명보다 효과적이며, 얻는 이득은 마법 같은 것이 아니라 작업당 몇 분의 시간 절약입니다.

문제점: 두 에이전트, 하나의 저장소, 중복된 컨텍스트.

저는 Claude Max와 Codex 플랜을 각각 별도로 비용을 지불합니다. Claude Code는 다중 파일 리팩토링(refactors)에 더 빠릅니다. 반면, Codex는 작고 범위가 명확한 편집에서 더 안정적입니다. 그래서 저는 두 도구를 동일한 저장소에서 동시에 실행했습니다.

세 가지 문제가 발생했습니다.

중복된 컨텍스트. 저는 Claude Code를 위한 CLAUDE.md와 Codex를 위한 AGENTS.md라는 두 개의 지침 파일을 유지했습니다. 이 파일들은 일주일 만에 서로 달라졌습니다. 제가 한 파일의 빌드 명령을 수정했지만 다른 파일에는 반영하지 않았습니다. 그러자 두 에이전트 모두 오래된 규칙을 따랐고, 테스트가 실패하기 전까지 어떤 파일이 최신인지 알 수 없었습니다.

충돌하는 편집. 동일한 작업 트리(working tree)에 두 프로세스가 있었습니다. Claude가 모듈을 리팩토링하는 동안 Codex는 해당 모듈을 가져오는 테스트 파일을 수정했습니다. 한쪽의 쓰기 작업이 다른 쪽을 덮어썼습니다. git status를 읽기가 어려워졌습니다.

저 자신이 메시지 버스 역할. Claude가 계획(plan)을 생성하면, 제가 그것을 Codex에 붙여넣었습니다. Codex는 diff를 생성했고, 저는 그 요약본을 다시 붙여넣었습니다. 지난주 동안 이 핸드오프 과정을 여섯 번 측정했는데, 평균적으로 순수한 복사-붙여넣기와 재방향 설정에만 11분이 걸렸습니다. 일주일에 클립보드로 존재하는 데 소비하는 시간이 대략 66분에 달했습니다.

제가 먼저 시도했던 것과 실패한 점.

• 두 개의 지침 파일. CLAUDE.md와 AGENTS.md를 수동으로 동기화해야 했습니다. 이 방식은 유지보수(drift)가 어려웠습니다. 알고 보니 Claude Code는 AGENTS.md를 직접 읽어들입니다 (v2.1.277 이상), 따라서 중복 파일 자체가 필요하지 않았습니다.

• 하나의 터미널, 두 개의 세션. 시도하기 가장 저렴했지만, 실패하는 것도 가장 빨랐습니다. 동일한 파일을 사용하고 같은 체크아웃을 했더니 한 시간 만에 충돌이 발생했습니다.

• 두 에이전트가 함께 작성한 공유 노트 파일. 문제의 원인 자체가 노트 파일이었습니다. 두 에이전트가 서로에게 산문(prose)으로 글을 쓰는 것이, 두 에이전트가 서로에게 코드를 쓰는 것보다 더 심각했습니다.

• CLAUDE.md를 AGENTS.md로 심링크(Symlinking) 처리하는 방법.** 절반만 작동했습니다. Claude는 링크를 통해 내용을 읽어들이지만, 그 편집 및 작성 도구(Edit and Write tools)는 심링크를 통해 쓰기를 거부하며, Git에 커밋된 심링크는 Windows에서 일반 텍스트로 체크아웃됩니다.

이 패턴은 돌이켜보면 명확합니다. 저는 프롬프트 계층(prompt layer)만 수정하고 파일 시스템 계층(filesystem layer)을 무시하고 있었습니다.

작동하는 설정.

두 에이전트가 모두 읽는 하나의 지침 파일.

저장소 루트에 AGENTS.md를 배치합니다. 두 CLI가 이 파일을 읽습니다. 여기에는 모든 세션에서 속해야 하는 사실들만 담겨야 합니다. 그 외의 것은 아무것도 없어야 합니다.

# AGENTS.md

## Repo
...

여기에는 두 가지 엄격한 제한이 있습니다. Claude Code는 CLAUDE.md 파일이 200줄 미만이기를 원합니다. 더 긴 파일은 컨텍스트를 소모하고, 신뢰성 있게 따라가지 못하게 만듭니다. Codex는 결합된 지침 크기(combined instruction size)를 project_doc_max_bytes, 기본값 32 KiB로 제한합니다. 두 제한 모두 모든 것을 설명하려는 파일을 처벌합니다. 공유 파일은 간결하게 유지하고, 세부 사항은 경로별 규칙(path-scoped rules)과 스킬(skills)에 배치해야 합니다.

내용을 가져오는(importing) 간결한 CLAUDE.md.

Claude Code는 기본적으로 작업 디렉터리 위에 CLAUDE.md가 없을 때만 AGENTS.md를 읽습니다. 저는 Claude 전용 몇 줄이 필요해서, 공유 파일을 가져오는 작은 CLAUDE.md를 유지합니다:

@AGENTS.md

## Claude Code
...

이렇게 임포트하면 로드가 먼저 되고, 제가 추가한 내용이 나중에 읽힙니다. @AGENTS.md는 심볼릭 링크(symlink)보다 휴대성이 좋은 선택지입니다. AGENTS.md 사양은 파일 자체를 다루며, 임포트는 Codex가 무시하는 유일한 부분입니다.

가정하기보다는 실제로 로드되었는지 확인하세요. Claude Code에서는 /context를 실행하고 Memory files 목록을 확인합니다. Codex의 경우, 명령어 체인(instruction chain)이 매번 실행될 때 재구축되므로 codex --ask-for-approval never "List the instruction sources you loaded"는 우선순위 순서를 보여줍니다.

에이전트당 하나의 작업 트리(worktree).

이것이 충돌을 막아준 핵심입니다. 각 에이전트는 동일한 저장소에서 자체 체크아웃과 브랜치를 사용하며, 일반 git worktree를 이용합니다:

# main checkout: 여기서 diff를 검토합니다
git worktree add ../repo-codex -b agent/codex-auth
cd ../repo-codex
...

Claude Code는 기본 체크아웃에 머무르고, Codex는 작업 트리에서 실행됩니다. 이들은 git 히스토리를 공유하지만 파일은 공유하지 않습니다. 세 번째 에이전트가 필요하면, 세 번째 작업 트리를 추가합니다. Conductor는 병렬 Claude Code 세션을 위해 동일한 패턴을 문서화했으며, Claude Code 자체에도 작업 트리 가이드가 있습니다.

알아두면 좋은 2026년의 세부 사항이 하나 있습니다: Claude Code의 자동 메모리 디렉터리는 git 저장소별로 키(key)가 지정되므로, 동일한 저장소의 모든 작업 트리가 하나의 메모리 디렉터리를 공유합니다. 연속성에는 좋지만, 두 에이전트가 별도의 학습을 유지하기를 원한다면 좋지 않습니다.

작업이 끝난 첫 번째 에이전트에 의해 작성된 핸드오프 파일(handoff file).

메시지 버스 문제(message-bus problem)는 기록(transcript)이 아닌 파일을 필요로 했습니다. 각 작업의 끝에서 재작성되는 .agent/HANDOFF.md입니다:

# .agent/HANDOFF.md
owner: codex
branch: agent/codex-auth
...

AGENTS.md의 규칙은 한 줄입니다. 무언가를 건드리기 전에 이것을 읽으세요. 저는 계획(plan)을 붙여넣지 않았는데도 Claude가 Codex가 멈춘 곳에서 이어서 작업합니다. 또한 files touched 목록은 각 에이전트에게 파일 경계(file-boundary)가 어디에 있는지 알려주며, 이것이 실제 충돌 방지 장치입니다.

토큰과 시간 비용 분석.

벤치마크가 아닌 제가 직접 실행해 본 수치들입니다.

• 인계(Handoffs). 이전에는 약 11분 걸렸지만, 이제는 그보다 훨씬 짧습니다. 파일이 짧기 때문에 컨텍스트 비용은 붙여넣은 계획을 사용하는 것보다 읽어들이는 데 필요한 몇백 개의 토큰 수준입니다.

• 프롬프트 캐싱(Prompt caching). 일반적인 Claude Code 세션에서는 입력 토큰의 약 90%가 캐시에서 제공되는 것을 볼 수 있습니다 (문서 자체 예시에서는 91%). 짧고 안정적인 명령어 파일은 이 접두사(prefix)를 캐싱할 수 있게 유지합니다.

• 유휴 백그라운드 작동(Idle background). Claude Code는 사용자가 타이핑하지 않을 때도 요약 및 명령어 확인에 세션당 0.04달러 미만을 소비합니다.

• 실제 비용. 계획 모드(plan mode)로 실행되는 에이전트 팀은 표준 세션보다 약 7배 많은 토큰을 소비합니다. 하나의 기능에 두 개의 에이전트를 사용하는 것이 공짜는 아니며, 작업을 잘못 분할하면 동일한 코드 라인에 대해 대략 두 배의 비용을 지불하게 됩니다.

자체 구독으로 로컬에서 실행하기.

두 CLI 모두 제가 이미 결제하고 있는 요금제의 저로 인증됩니다. API 키가 제3자에게 전달되지 않으며, 계정이 공유되지 않고, 토큰이 재판매되지 않습니다. Max의 경우, Claude Code가 /usage에서 출력하는 달러 금액은 청구가 아니라 API 목록 가격으로 계산된 추정치이며, 사용량은 요금제의 누적 할당량(rolling allowance)을 사용합니다. 전체 워크플로우가 제 노트북에서 실행되므로 불안정한 연결이 작업을 막는 일이 없습니다.

제가 다르게 할 것들.

• 첫날부터 worktree를 사용하세요. 단일 git worktree add 명령 하나로 해결할 수 있는 파일 충돌 문제 때문에 첫 달을 허비했습니다.

• 지침 파일은 두 개 이상 유지하지 마세요. AGENTS.md 하나만 만들고, 그것을 가져오는(import) 방식으로 충분합니다.

• 기능별이 아닌 파일 경계별로 작업을 분할하세요. "Codex가 apps/auth를 소유하고, Claude가 apps/api를 소유한다"는 방식은 유지했지만, "Codex가 백엔드를 담당하고, Claude가 프론트엔드를 담당한다"는 방식은 그렇지 못했습니다. 왜냐하면 경계가 매시간 움직였기 때문입니다.

• 자동화하기 전에 일주일 동안 수동으로 인수인계 파일을 작성하세요. 제가 필요하다고 생각했던 필드가 중요했던 필드는 아니었습니다. 중요한 것은 '수정된 파일 목록(files touched)'과 '다음 작업(next)'이었습니다.

다음 단계

저는 이 인수인계가 공유 사서함이 아니라 진정한 '인수인계'가 되기를 원합니다. 따라서 다음 단계는 작은 오케스트레이터입니다. 하나의 캔버스, 각 CLI를 자체 터미널 창에 배치하고, 하나의 컨텍스트 파일(context file), 그리고 창들 사이에서 보이는 인수인계 과정이 필요합니다. 이것이 제가 이 워크플로우 주변으로 구축한 도구이며, starkomand.com에서 에이전트 오케스트레이션 작업 공간을 제공합니다. 사용자가 이미 가지고 있는 구독 환경 위에서 각 CLI를 로컬로 실행하며, 중간에 키나 계정이 필요하지 않습니다.

만약 먼저 수동 버전을 시도해 보고 싶다면, 전체 설정은 세 개의 파일과 하나의 명령어로 이루어집니다:

git worktree add ../repo-codex -b agent/next-task

지침 파일과 인수인계 파일이 나머지를 처리합니다. 제가 오케스트레이터를 작성할 때는 아직 문제가 발생하는 부분을 지나서 진행할 것이며, dev.to에 anthropic 태그를 달아 크로스 포스팅하겠습니다 (해당 플랫폼은 게시물당 최대 4개의 태그만 허용합니다: https://dev.to/help/writing-editing-scheduling). 만약 한 리포지토리에서 두 개의 에이전트 CLI를 실행해 본 적이 있다면, 제가 가장 알고 싶은 것은 파일 경계가 어디서 무너졌는지입니다.