요약

진행 중인 Claude Code 대화를 Codex로 옮길 수는 없습니다. 두 도구는 세션을 따로 저장하고, 어느 쪽도 상대의 채팅 기록을 가져오지 않습니다. 옮길 수 있는 건 중요한 모든 것입니다. 단, 그것이 저장소 안에 있어야 합니다.

1. 두 에이전트가 함께 읽는 지시 파일 하나: 프로젝트 규칙을 AGENTS.md에 둡니다. Codex는 기본으로 읽고, 현재 Claude Code도 읽습니다(직접, 또는 CLAUDE.md의 @AGENTS.md 가져오기를 통해).
2. 전환할 때마다 새로 만드는 인계 메모: 교대하는 에이전트에게 HANDOFF.md를 쓰게 합니다(목표, 끝난 일, 다음 할 일, 시도했다가 실패한 것, 열린 질문).
3. 기준은 git: 전환하기 전에 WIP 브랜치에 커밋하거나 stash해서, 이어받는 에이전트가 내 기억이 아니라 diff를 읽게 합니다.

그러면 전환은 2분 정도면 끝나고, 새 에이전트는 텅 빈 저장소가 아니라 글로 된 브리핑에서 시작합니다.

문제

보통 이렇게 됩니다. Claude Code로 리팩터링을 두 시간째 하다가 5시간 한도에 걸리고, 다른 요금제의 Codex가 바로 옆에 있습니다. 또는 Claude가 버그 하나를 두고 계속 같은 자리를 맴돌아서 다른 모델에게 보여 주고 싶습니다.

같은 폴더에서 Codex를 열면 동작은 하지만, 처음 10분은 다시 설명하는 데 씁니다. 무엇을 만들고 있는지, 어떤 방법은 이미 버렸는지, 저 테스트는 왜 일부러 건너뛰는지. 게다가 이어받은 에이전트는 방금 다른 에이전트에게 하지 말라고 한 일을 태연하게 다시 합니다.

해결책은 영리한 도구가 아닙니다. 맥락은 채팅이 아니라 파일에 둔다고 정하는 것입니다.

흔한 방법

• Claude 대화 기록의 마지막 부분을 Codex에 붙여 넣기. 한 번은 됩니다. 하지만 잡음(도구 출력, 버린 계획)도 함께 들어가고, 스크롤로 밀려난 내용은 빠집니다.
• Codex에게 "git log를 보고 알아서 파악해"라고 하기. 끝난 작업에는 괜찮지만, 반쯤 된 작업이나 코드로 남지 않은 결정에는 쓸모가 없습니다.
• 지시 파일 두 개를 손으로 관리하기. CLAUDE.md와 AGENTS.md는 일주일도 안 돼 어긋났습니다.

1단계: 두 에이전트를 위한 지시 파일 하나

Codex는 저장소(와 그 상위 디렉터리)에서 AGENTS.md를 읽습니다. Claude Code의 경우, 2026-10-11 기준 Anthropic의 메모리 문서는 다음과 같이 설명합니다.

• 저장소에 AGENTS.md가 있고 작업 디렉터리나 그 상위에 CLAUDE.md나 CLAUDE.local.md가 없으면, Claude Code는 AGENTS.md를 직접 읽습니다(Claude Code v2.1.277 이상 필요).
• CLAUDE.md가 있으면, Claude는 기본적으로 CLAUDE.md만 읽습니다. 이 부분은 조심하세요. 개인 메모용으로 CLAUDE.local.md를 추가하기만 해도 Claude가 AGENTS.md를 읽지 않게 됩니다.
• CLAUDE.md는 @path 구문으로 다른 파일을 가져올 수 있고, 가져온 AGENTS.md도 함께 로드됩니다.

이전 버전의 Claude Code를 포함해 두 도구 모두에서 동작하는 구성:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude-only notes
- (anything that genuinely only applies to Claude Code, e.g. hook or subagent notes)

그리고 공유할 내용은 모두 AGENTS.md에 둡니다. 빌드와 테스트 명령, 코드 스타일, "migrations/는 손으로 건드리지 않기", 문서 위치 같은 것들입니다. 짧게 유지하세요. Anthropic은 파일당 200줄 미만을 권장하며, 지시 파일이 길면 두 에이전트 모두 덜 따르게 됩니다.

CLAUDE.md를 두고 싶지 않다면 지우고 Claude가 AGENTS.md를 직접 읽게 해도 됩니다. 어떤 파일이 로드되는지 모르겠다면 Claude Code에서 /config를 실행하고 Project instructions 설정을 확인하세요. 세션이 시작될 때 Claude는 파일을 읽으면 AGENTS.md loaded: ... 같은 줄을 출력합니다.

2단계: 전환 전에 인계 메모 쓰기

교대하는 에이전트가 맥락을 잃기 전에(한도가 다가오는 게 보인다면 한도에 걸리기 전에) 메모를 쓰게 하세요. 재사용할 수 있는 프롬프트:

Write HANDOFF.md at the repo root for another coding agent taking over this task.
Sections, in this order:
1. Goal (one paragraph, what "done" means)
2. Current state (what works, what's half-done, which files)
3. Next steps (numbered, smallest first)
4. Tried and rejected (approach + why it failed, so it isn't retried)
5. Gotchas (env vars, flaky tests, things that look wrong but are intentional)
6. Open questions for the human
Only facts you verified in this session. No code blocks longer than 10 lines; point to files instead.

메모를 쓸모 있게 만드는 규칙 두 가지:

• 전환할 때마다 새로 만들기. 계속 덧붙이지 마세요. 오래된 인계 메모는 없느니만 못합니다.
• 커밋할지 정하기. 혼자 쓰는 브랜치라면 WIP 브랜치에 HANDOFF.md를 커밋해 두면 편합니다. 공유 저장소라면 .git/info/exclude에 추가해서 PR에 들어가지 않게 하세요.

3단계: 작업을 git에 넣기

git checkout -b wip/refactor-auth     # if you aren't on a branch already
git add -A
git commit -m "WIP: auth refactor, handoff to codex" --no-verify

이제 이어받는 에이전트는 git log -p -1이나 git diff main...을 실행해, 요약을 믿는 대신 무엇이 바뀌었는지 정확히 볼 수 있습니다. (PR을 열기 전에 WIP 커밋은 squash하세요.)

4단계: 명확한 첫 프롬프트로 Codex 시작하기

codex

Read AGENTS.md and HANDOFF.md, then run `git diff main...` to see the work so far.
Summarize back to me in 5 bullets what you think the task is and what you'll do next.
Don't change any files until I confirm.

"먼저 요약해서 돌려받기" 단계는 값싼 보험입니다. 요약이 틀렸다면 대화가 아니라 HANDOFF.md를 고치세요. 그래야 다음 전환에도 도움이 됩니다.

나중에 다시 돌아갈 때도 같은 루프를 거꾸로 하면 됩니다. Codex에게 HANDOFF.md를 다시 쓰게 하고, 커밋하고, Claude Code를 시작합니다(이전 맥락도 원한다면 claude --continue로 그 폴더의 이전 Claude 대화를 이어 갈 수 있습니다).

Happier의 역할: 전환하는 두 가지 방법

휴대폰을 벗어나지 않고 에이전트를 전환하고 싶다면, Happier는 휴대폰, 데스크톱, 웹에서 Claude Code, Codex 등 에이전트를 크로스 디바이스로 실행하고 오케스트레이션하는 오픈 소스 앱입니다. 에이전트를 전환할 때는 두 가지 방법이 있습니다.

방법 1: 저장소 파일 방식 (위의 1~4단계)

Happier가 있든 없든 어디서나 통하는 범용 방법입니다.

• 얻는 것: 완전한 제어, 도구 간 이식성, 그리고 팀이 볼 수 있는 git에 맥락이 남음
• 언제 쓰나: 머신 간 전환, 팀 내 인계, 또는 이어받는 에이전트가 명확한 브리핑을 들고 새로 시작하길 원할 때

실제 일을 하는 건 파일(AGENTS.md, HANDOFF.md, WIP 커밋)입니다. Happier를 쓴다면 노트북으로 돌아가지 않고 휴대폰에서 새 세션을 시작할 수 있다는 것뿐입니다.

방법 2: Happier 안에서 그 자리에서 전환

Happier 0.2.11부터 Continue with another Agent로 기존 Happier 세션을 그 자리에서 다른 에이전트로 전환할 수 있습니다.

• 넘어가는 것: 최근 대화 턴을 일정 분량으로 제한한 텍스트 요약. 이미지, 파일 내용, 도구 출력은 넘어가지 않습니다.
• 알아 둘 점: 이건 대화 브리핑이지, 제공자 간에 공유되는 메모리가 아닙니다. 이어받은 에이전트는 "방금 무슨 얘기를 하고 있었는지"는 알지만, 전체 세션 기록이나 이전 결정의 이유는 알지 못합니다.
• 언제 쓰나: 빠르게 다른 의견을 듣고 싶을 때("Codex는 어떻게 생각해?"), 버그에 막혔을 때, 같은 생각의 흐름을 다른 모델로 이어 가고 싶을 때

함께 쓰기: 그 자리에서 전환하더라도 1~3단계는 여전히 중요합니다. AGENTS.md는 지시를 일관되게 유지하고, HANDOFF.md는 대화 턴에 묻히면 안 되는 결정을 담고, WIP 커밋은 이어받은 에이전트가 무엇이 바뀌었는지 정확히 보게 해 줍니다.

계정 풀 (같은 에이전트, 다른 계정)

에이전트 전환과는 별개입니다. 전환하는 이유가 사용량 한도이고, 같은 에이전트에 내가 소유한 두 번째 계정(개인 구독과 업무 구독처럼 둘 다 내 것이고 둘 다 내 이름으로 로그인한 계정)이 있다면, Happier의 계정 풀로 세션을 다른 계정으로 바꿔 이어 갈 수 있습니다. 직접 의도해서 풀을 만들기 전에는 아무것도 전환되지 않으며, 풀이 한도를 늘리거나 재설정 시간을 앞당기지는 않습니다.

이런 분께

• Claude와 ChatGPT 요금제를 모두 갖고 있고, 한쪽을 다 쓰면 전환하는 분
• 두 번째 에이전트를 리뷰용이나, 막힌 버그를 "새로운 눈"으로 보게 하는 용도로 쓰는 분
• 같은 저장소에서 사람마다 선호하는 에이전트가 다른 팀

흔한 실수

• 손으로 관리하는 지시 파일 두 개. 복사하지 말고 가져오세요.
• CLAUDE.local.md가 Claude에서 AGENTS.md를 조용히 무력화함 (1단계 참고).
• 붙여 넣은 코드로 가득한 인계 메모. 파일과 줄 범위를 가리키세요. 이어받은 에이전트가 직접 읽을 수 있습니다.
• 편집 도중에 전환하기. 현재 턴이 끝날 때까지 기다리지 않으면, 설명 없이 반쯤 쓴 파일을 넘기게 됩니다.
• diff보다 요약을 믿기. 메모는 에이전트가 했다고 생각하는 것을 말하고, git diff는 실제로 한 것을 말합니다.

문제 해결

Claude Code가 AGENTS.md를 무시함

폴더나 상위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 있는지 확인하세요. 있다면 Claude는 기본적으로 그 파일을 읽습니다. 거기에 @AGENTS.md를 추가하거나 /config에서 Project instructions를 바꾸세요.

Codex가 AGENTS.md 규칙을 따르지 않음

Codex를 저장소 안에서 실행해 파일을 찾을 수 있게 했는지 확인하세요. 파일이 아주 길면 덜 따르게 되니 줄이세요. 일회성 작업 세부 사항은 HANDOFF.md로 옮기세요.

새 에이전트가 이미 버린 작업을 다시 함

"Tried and rejected" 섹션이 없거나 모호합니다. 방법과 이유를 각각 한 줄로 분명히 적으세요.

자주 묻는 질문

Claude Code 대화를 Codex로 가져올 수 있나요?

대화 형태로는 안 됩니다. 세션을 따로 저장합니다. 맥락은 파일(AGENTS.md, HANDOFF.md)과 git으로 옮기세요.

Codex는 CLAUDE.md를 읽나요?

Codex의 규칙은 AGENTS.md입니다. CLAUDE.md를 읽을 거라고 기대하지 말고, AGENTS.md를 공유 파일로 삼아 CLAUDE.md에서 가져오게 하세요.

HANDOFF.md를 커밋해야 하나요?

개인 WIP 브랜치라면 괜찮고 유용합니다. 공유 브랜치에서는 .git/info/exclude로 로컬에서 제외하세요.

OpenCode, Gemini CLI 등에서도 되나요?

이 패턴은 통합니다. 이제 대부분의 에이전트 CLI가 AGENTS.md를 읽거나 파일을 지정할 수 있게 해 줍니다. 정확한 파일 이름은 각 도구의 문서를 확인하세요.

관련 가이드

• 휴대폰에서 Codex 사용하는 방법
• 노트북이 절전 모드여도 Claude Code, Codex, OpenCode를 계속 실행하는 방법
• 휴대폰으로 Linux 서버의 Codex 원격 제어하는 방법