Claude에서 Codex로 넘길 때, 대화만 복사하면 부족한 이유

TL;DR

• 다음 에이전트에는 대화뿐 아니라 같은 작업 사본, 시작 기준, 현재 파일과 diff, 실행 결과가 필요합니다.
• Agent Hub는 이 정보를 공통 패킷으로 만들고 매번 새 CLI 호출에 전달합니다. Claude의 네이티브 세션을 Codex로 옮기는 기능은 아닙니다.
• /compact와 /exclude는 다음 입력의 범위를 줄입니다. 원문 기록이나 실제 파일을 삭제하지 않습니다.
• 중단·재접속 때도 남은 파일과 실행 상태를 확인합니다. 정상 종료와 테스트 통과는 별개의 정보입니다.

들어가며

Claude가 작성한 코드를 Codex에게 검토하게 한다고 가정해보겠습니다. 대화를 복사하면 무엇을 요청했고 어떤 답변을 받았는지는 전할 수 있습니다. 하지만 “수정했습니다”라는 문장만으로는 어느 파일이 바뀌었는지, 테스트가 실행됐는지, 중간에 실패한 변경이 남았는지 알기 어렵습니다.

Agent Hub 소개와 Git 작업 격리 글에서는 에이전트를 연결하고 작업을 분리하는 구조를 다뤘습니다. 이번에는 다음 담당자가 무엇을 알아야 일을 이어갈 수 있는가에 집중해보겠습니다. 설명은 manual-cli.md와 같은 커밋의 구현을 기준으로 합니다.

담당자가 바뀌어도 작업의 기준은 이어져야 합니다

수동 CLI 세션에서는 맨 앞의 @claude, @codex, @cursor로 다음 담당자를 고릅니다. 한 명의 이름만 입력하면 호출 없이 담당자만 바꾸고, 요청을 함께 쓰면 실행합니다. 본문에 들어 있는 멘션은 호출 대상이 아닙니다.

세 에이전트는 세션에 준비된 같은 작업 사본을 사용합니다. 일반 폴더 방식은 시작 시점의 파일 스냅샷을, Git 방식은 시작 커밋을 기준으로 변경을 비교합니다. 따라서 다음 담당자가 먼저 알아야 하는 것은 원본 프로젝트 이름보다 실제로 읽고 고칠 작업 사본의 경로와 비교 기준입니다.

이 기준 위에 manual_context.py가 공통 패킷을 구성합니다.

수정되지 않은 관련 파일도 /include 상대경로로 넣을 수 있습니다. UTF-8 본문과 diff 외에 삭제된 파일, 바이너리 파일의 크기와 해시도 구분합니다. 모든 파일의 내용을 무조건 프롬프트에 넣는 방식은 아닙니다.

파일 지문과 컨텍스트 해시는 다른 대상을 봅니다

파일 지문은 작업 파일 상태를 비교하기 위한 값입니다. 패킷을 만들기 전에 저장된 지문과 현재 파일을 대조하고, 본문과 diff를 수집한 뒤에도 다시 비교합니다. 수집 도중 파일이 바뀌면 서로 다른 순간의 정보를 묶어 전달하지 않고 중단합니다.

컨텍스트 해시는 패킷을 정렬된 JSON으로 직렬화한 UTF-8 바이트에서 계산합니다. 파일 상태가 같은지 확인하는 값과, 전달할 문맥을 식별하는 값은 역할이 다릅니다. 같은 파일에서도 새 요청이나 대화가 추가되면 패킷은 달라집니다. 담당자를 바꾼 모든 턴의 해시가 항상 같다는 의미는 아닙니다.

실행 직전에도 파일 지문을 확인하고, 종료 뒤에는 변경 파일과 전후 지문을 기록합니다. 외부 편집기로 사본을 고쳤다면 내용을 확인한 뒤 /sync로 새 기준을 받아들여야 합니다. 이 검사는 외부 편집기를 막는 OS 수준의 잠금까지 제공하지는 않습니다. 패킷 생성과 실행 전후 처리에 이 경계가 나뉘어 있습니다.

“테스트했습니다”보다 명령과 종료 코드가 필요합니다

앞선 에이전트의 설명은 판단에 참고할 기록입니다. 실제 검증을 대신하는 증거로 취급해서는 안 됩니다. 공통 지침에도 다른 에이전트의 말을 자신의 행동이나 성공의 증거로 받아들이지 말고, 파일과 기록된 검증 결과에 대조하도록 적어뒀습니다.

빌드와 테스트는 /check 명령으로 호스트가 실행합니다. 명령의 출력과 종료 코드가 다음 컨텍스트에 들어가므로, 담당자가 바뀌어도 실패 내용을 이어서 볼 수 있습니다. 검증 명령이 파일을 만들거나 고치면 그 결과 역시 작업 사본에 남습니다. 읽기 전용 세션에서는 /check를 실행하지 않습니다.

반면 턴의 completed는 CLI가 정상적으로 끝났다는 상태입니다. 요구사항을 충족했다거나 테스트가 통과했다는 선언은 아닙니다. /check의 종료 코드가 0이어도 그 명령이 검사하지 않은 동작까지 보장하지는 않고요. manual.py에서는 답변, 도구 이벤트, 검증 결과와 턴 상태를 따로 기록합니다.

문맥을 줄여도 원문은 남깁니다

대화가 짧아도 파일 읽기 도구의 출력이나 큰 diff 때문에 입력이 커질 수 있습니다. 공통 패킷 한도는 UTF-8 기준 192KB, 개별 파일 본문은 64KB입니다. 모델별 토큰 한도와 같은 값은 아닙니다. 초과하면 조용히 잘라 보내지 않고 호출 전에 오류를 냅니다.

이때 줄이는 방법도 나눴습니다.

/compact는 요약 모델을 호출하는 명령이 아닙니다. “이전 내용 요약”이라고 입력하면 그 문장 자체가 요약으로 저장됩니다. 보존할 요구사항, 수정한 파일, 실제 검증 여부와 다음 작업을 직접 적어야 합니다. 구현은 요약과 그 시점의 기록 번호를 저장하며 원문을 삭제하지 않습니다.

또한 /exclude는 접근 금지 기능이 아닙니다. 다음 에이전트가 파일 도구로 해당 파일을 읽을 수 있습니다. 처음부터 사본에 복사하지 않을 파일은 일반 폴더 모드의 .agent-hub-ignore로 정해야 하며, 이 규칙은 세션 시작 때 고정됩니다.

중단했다면 남은 파일부터 확인합니다

Ctrl+C는 실행 프로세스의 종료를 요청합니다. 취소 전에 작성된 파일을 자동으로 되돌리지는 않습니다. 서버 재시작으로 실행 상태를 잃었다면 이전 CLI가 종료됐는지와 파일 변경을 확인하고 /sync로 계속해야 합니다.

--resume은 Hub에 저장된 세션으로 돌아오는 기능입니다. 작업 폴더와 담당자, 권한을 유지하며, 진행 중인 턴은 새 호출 없이 출력을 다시 보여줍니다. 통신 실패를 이유로 요청을 자동 재전송하거나 중단된 턴을 자동으로 다시 실행하지 않습니다. /status와 재접속으로 먼저 상태를 확인할 수 있습니다.

실제 모델 호출은 매번 새 CLI 실행입니다. manual_runner.py는 공통 지침과 패킷을 전달하지만 이전 네이티브 세션을 resume하지 않습니다. CLI별 시스템 지침과 도구 설정, 모델 내부 추론까지 같아지는 것도 아닙니다. 이어받는 것은 Hub가 보관한 명시적인 기록과 작업 파일입니다.

모델 호출 없이 인계 구조를 확인하려면

아래 명령은 해당 커밋의 Agent Hub 저장소 루트에서 실행할 수 있습니다. Python 3.11 이상이 필요하며, 가짜 실행기와 임시 작업 사본을 사용하는 테스트입니다.

PYTHONPATH=src python -m unittest discover -s tests -p 'test_manual*.py' -v

test_manual.py는 담당자 인계, 공통 패킷, 실제 임시 파일 변경과 검증 명령, 요약 후 원문 보존, 취소·재접속 등을 확인합니다. test_manual_folder.py는 Git 호출이 금지된 일반 폴더 방식도 검사합니다.

이번 작성 환경에서는 37개 중 36개가 통과했고 Windows 실행기 테스트 1개는 운영체제 조건으로 건너뛰었습니다. 외부 모델 호출은 하지 않았습니다. 따라서 실제 로그인된 Claude·Codex CLI의 응답 품질이나 현재 제공자 연결까지 확인한 결과는 아닙니다.

마치며

다음 에이전트에게 필요한 것은 앞선 답변의 그럴듯함보다 현재 파일, 그 파일이 만들어진 과정, 실제 검증 결과와 남은 일입니다. 대화는 의도와 판단을 설명하고, 파일과 실행 기록은 그 판단을 다시 확인할 근거가 됩니다.

공통 패킷이 인계의 정확성을 자동으로 보장하지는 않습니다. 요약에서 중요한 조건을 빠뜨릴 수도 있고, 다음 에이전트가 기록을 잘못 해석할 수도 있습니다. 그래도 무엇을 넘겼는지 남기고 실제 상태와 대조할 수 있어야, 담당자가 바뀐 뒤에도 같은 작업을 이어갈 수 있다고 생각합니다.