Claude Code에서 기능 개발을 시작합니다. 까다로운 타입 에러에 막혀서, 같은 저장소를 그런 작업에 더 강한 Codex에 넘깁니다. Codex가 문제를 해결했지만, 이제 이 기능이 무엇을 위한 것인지, 어떤 파일을 건드리지 않기로 했는지, 여기서 "완료"가 무엇을 의미하는지 전혀 알지 못합니다. 기억을 더듬어 처음부터 다시 설명합니다. 10분 후 다시 Claude Code로 돌아오면, Claude Code도 까먹고 있습니다. 코드는 앞으로 나아갔지만, 맥락은 그렇지 못했습니다.
이것이 코딩 에이전트를 둘 이상 운영할 때 치르는 세금입니다. 각 도구는 자신만의 형식과 세션에 기억을 저장하기 때문에, 작업이 한 에이전트에서 다른 에이전트로 넘어가는 순간 diff를 제외한 모든 것이 바닥에 떨어집니다. 코딩 에이전트를 전환할 때 맥락을 유지한다는 것은, 그 맥락을 특정 에이전트 바깥 어딘가에, 다음 에이전트가 당신의 설명 없이 읽을 수 있는 형태로 살아 있게 만드는 일입니다.
이 글에서는 그 방법을 Sharkly를 워크플로로 사용해 살펴봅니다. Sharkly는 코딩 에이전트 위에 자리하는 레이어로, 요청부터 릴리스까지 맥락, 진행 상황, 블로커, 결과, 사람의 리뷰를 모두 보이게 유지합니다. 당신에게는 이미 코딩 에이전트가 있습니다. 문제는 그들 사이의 이음새이고, 에이전트를 추가할 때마다 그 틈은 더 벌어집니다.
맥락이 에이전트 사이를 이동하지 못하는 이유
코딩 작업의 맥락은 세 곳에 존재하며, 그중 이식 가능한 곳은 하나뿐입니다.
첫째는 지시 파일입니다: CLAUDE.md, AGENTS.md, GEMINI.md. 상시 규칙, 관례, 테스트 실행 명령 등입니다. 둘째는 세션 상태입니다. 당신과 에이전트가 방금 나눈 대화, 시도한 것, 배제한 것의 스크롤백입니다. 셋째는 산출물 자체, 즉 디스크의 diff나 브랜치입니다.
공짜로 이동하는 것은 셋째뿐입니다. 다른 에이전트는 코드를 읽을 수 있지만, 자신이 참여하지 않은 대화는 읽을 수 없고, 다른 도구를 향해 쓰인 지시 파일은 읽지 않습니다. 이 경계는 분명히 짚고 넘어갈 만합니다. 에이전트를 전환하면 코드는 보존되고 추론은 사라집니다. 커밋은 살아남습니다. "왜"는 한 에이전트가 봤고 다음 에이전트는 결코 보지 못할 스크롤백 버퍼 안에 있었습니다.
그래서 전환 사이에 맥락을 유지하는 일은 사실상 두 가지 작업입니다. 상시 규칙을 모든 에이전트가 읽을 수 있게 만들고, 라이브 작업 상태를 한 도구의 기억이 아닌 다른 무엇으로 존재하게 만드는 것. 다음 섹션에서 순서대로 다룹니다. (같은 에이전트를 여러 번 실행하는 사이에 맥락을 잃는 것이 문제라면, 이는 관련 있지만 별개의 문제이며 AI 세션 간 맥락 유지하기에서 다룹니다.)
상시 규칙을 모든 에이전트가 읽는 하나의 파일로 만들기
쉬운 승리부터 시작합시다. Claude Code는 CLAUDE.md를 읽고, Codex는 AGENTS.md를, Gemini CLI는 GEMINI.md를 읽습니다. 같은 역할인데 파일 이름만 세 개입니다. 이들을 따로 관리하면 서로 어긋나게 되고, 전환한 에이전트는 이제 낡은 규칙을 따르는데 당신은 그렇지 않다고 착각하게 됩니다.
규칙은 한 번만 작성하고 나머지 파일 이름이 그것을 가리키게 하세요. macOS나 Linux에서는:
# AGENTS.md is the source of truth; the others are aliases
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
git add AGENTS.md CLAUDE.md GEMINI.md
이제 저장소를 여는 모든 에이전트가 같은 규칙을 읽고, 규칙이 바뀌면 업데이트할 파일은 하나뿐입니다. 짧고 사실적으로 유지하세요. 테스트 명령, 손대면 안 되는 디렉터리, 리뷰 규칙, 커밋 메시지 형식 등입니다. 이것은 어떤 에이전트로 전환하든, 시작하는 순간 각 에이전트가 물려받는 공유 계약입니다.
경계해야 할 실패 유형은 이 파일에 작업별 세부 사항을 넣는 것입니다. 지시 파일은 저장소의 모든 작업에 걸쳐 참인 규칙을 위한 곳입니다. "우리는 Jest가 아니라 Vitest를 쓴다"는 여기에 속합니다. "체크아웃 재시도 로직을 끝내고 인증 미들웨어는 건드리지 마라"는 속하지 않습니다. 이는 이번 주 한 작업에만 참이고 다음 주에는 틀립니다. 이 둘을 섞으면 모든 에이전트가 이미 출시된 작업을 위해 쓰인 지시를 읽게 됩니다.
규칙뿐 아니라 작업 맥락도 함께 옮기기
규칙 파일은 새 에이전트를 출발선에 세워줍니다. 하지만 진행 중인 작업에 대해서는 아무 말도 하지 않습니다. 무엇이 결정됐는지, 무엇이 반쯤 끝났는지, 무엇이 아직 불확실한지. 바로 이 지식이 전환할 때 증발합니다. 오직 이전 에이전트의 세션에만 존재했기 때문입니다.
수동 해결책은 핸드오프 노트입니다. 에이전트를 전환하기 전에, 현재 에이전트에게 자신이 어디에 있는지 적게 하세요. 목표, 변경한 파일, 검증한 것, 그리고 확신하지 못한 한 가지. 이것을 다음 에이전트의 첫 메시지로 붙여 넣습니다. 효과가 있고, 한 번의 전환이라면 충분합니다. 이 패턴은 그 자체로 익힐 가치가 있으며, 좋은 핸드오프 노트의 형태는 에이전트 핸드오프 템플릿에서 다룹니다.
실패 유형은 그 노트가 어디에도 지속적으로 남지 않는다는 점입니다. 곧 닫을 터미널 속 한 단락이거나, 매번 다시 입력하는 메시지일 뿐입니다. 두 번 왔다 갔다 하면 세 도구에 걸쳐 머릿속으로 핸드오프 노트를 수작업으로 관리하게 됩니다. 맥락은 존재하지만, 당신이 그 맥락을 저장하는 데이터베이스가 되어버린 것입니다. 이는 한 작업에는 통합니다. 여러 작업을 동시에 돌릴 때는 통하지 않으며, 여기서 DIY 접근이 한계에 부딪힙니다.
DIY 설정이 확장을 멈추는 지점
심볼릭 링크 규칙에 붙여 넣는 핸드오프 노트를 더하면, 저장소 하나와 에이전트 둘로는 꽤 멀리 갈 수 있습니다. 에이전트를 하나 더 추가하거나, 저장소를 하나 더 추가하거나, 하루에 걸친 작업을 하면 계산이 틀어집니다. 모든 전환이 수동 내보내기와 다시 가져오기입니다. 모든 작업에는 마지막 에이전트가 남긴 곳에만 존재하는 "무엇이 끝났는지"의 스레드가 따로 있습니다. 백엔드 에이전트가 프론트엔드 에이전트가 기다리는 엔드포인트를 완료했다는 것을 알려주는 것은 아무것도 없습니다. "알려주기"란 아무도 지켜보지 않는 터미널 속 메시지였기 때문입니다.
그 시점에서 해결책은 더 나은 노트가 아닙니다. 작업 맥락을 에이전트에서 완전히 떼어내 모든 에이전트와 사람이 함께 읽고 쓰는 공유 Task로 옮기는 것입니다. Sharkly의 Task는 목표, 수용 기준, diff, 블로커, 논의를 하나의 레코드에 담습니다. 실행, 블로커, 결과, 후속 조치가 그 Task 타임라인으로 돌아가므로, 에이전트 전환은 아예 내보내기가 아니게 됩니다. Task를 재할당하면, 다음 에이전트가 이전 에이전트가 쓴 것과 같은 레코드를 읽습니다.
여기서 사람과 에이전트의 분업도 깔끔해집니다. 에이전트는 조사하고, 실행하고, 테스트하고, Task에 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 승인합니다. 팀의 판단이 필요한 지점에서 자동화가 멈추고, 다음 작업자가 읽는 레코드는 리뷰어가 읽는 것과 동일합니다. 이는 맥락이 더 이상 세션에 갇혀 있지 않기 때문에 가능합니다.
다음은 솔직한 결정 기준입니다. 한 터미널에서 한 저장소에 에이전트 하나를 돌린다면, 이 모든 것이 필요 없습니다. 맥락이 떠나지 않으니 보존할 것도 없습니다. 에이전트 간, 에이전트와 사람 간, 혹은 그저 내일 아침의 나 자신으로의 전환이든, 맥락이 전환을 견뎌야 하는 순간 공유 Task를 찾으세요. 하나의 생태계에 확정하기보다 여러 코딩 에이전트를 계속 쓰고 싶다면, 그 이식성이 핵심입니다. 맥락이 어느 에이전트 안에도 저장되지 않았기 때문에, 다음에 어떤 에이전트를 고르든 당신의 워크플로는 살아남습니다. 이는 또한 하나의 코드베이스에서 Claude Code와 Codex를 함께 실행하는 설정이기도 하며, 핸드오프 시점에 어느 쪽도 눈이 멀지 않게 해주고, 작업당 하나의 체크아웃인 워크트리와 자연스럽게 맞물려 병렬 에이전트가 충돌하지 않게 합니다.
오늘 바로 실행할 수 있는 체크리스트
순서대로 진행하세요. 처음 세 가지는 비용이 들지 않고, 네 번째는 처음 세 가지가 더는 따라가지 못할 때 넘어가는 단계입니다.
- 규칙 파일을 통합하세요.
CLAUDE.md,AGENTS.md,GEMINI.md를 하나의 소스로 심볼릭 링크하세요. 저장소 전반의 관례만 담고, 작업 세부 사항은 넣지 마세요. - 전환 전마다 핸드오프 노트를 작성하세요. 목표, 변경한 파일, 검증한 것, 미해결 질문. 현재 에이전트가 초안을 잡고, 당신이 다음 에이전트에 붙여 넣으면 됩니다.
- 습관이 아니라 작업을 기준으로 전환을 결정하세요. 열려 있는 터미널을 기본으로 삼기보다 라우팅 가이드를 활용해 눈앞의 작업에 에이전트를 맞추세요.
- 노트가 확장되지 않을 때 맥락을 에이전트 밖으로 옮기세요. 에이전트나 저장소를 두어 개 이상 굴리게 되면, 목표, 상태, 리뷰를 공유 Task에 올려 전환이 재설명이 아닌 재할당이 되게 하세요.
이미 여러 에이전트를 돌리면서 전환할 때마다 같은 맥락을 다시 설명하고 있다면, 그것이 바로 Sharkly가 겨냥하는 문제입니다. 각 에이전트의 작업, 진행 상황, 결과가 한곳에서 계속 보이므로, 맥락이 전환보다 오래 살아남습니다.
