Claude Code 크로스세션 메시징: AI 에이전트끼리 알아서 소통하게 만드는 법 (code.claude.com)

한줄 요약

Claude Code 세션들이 ListAgents·SendMessage 두 도구로 서로 메시지를 주고받아, 개발자가 터미널 사이를 오가며 복붙할 필요 없이 멀티 에이전트 작업을 자동 조율한다.

어떤 상황에서 필요한가?

멀티 에이전트 개발 자동화를 실제로 해본 사람이라면 공통적으로 겪는 문제가 있다. 세션 A가 공유 모듈을 수정했는데 세션 B는 그 사실을 모른 채 빌드를 진행하다 뒤늦게 충돌을 발견하는 상황이다. 결국 개발자가 직접 두 터미널을 오가며 상황을 설명하는 낭비가 반복된다.

Claude Code의 크로스세션 메시징은 이 문제를 에이전트 레벨에서 끊는다. 한 세션이 breaking change를 만들거나 블로킹 이슈의 답을 찾으면, Claude가 스스로 판단해 관련 세션에 메시지를 보낸다. 개발자는 개입하지 않아도 된다.

특히 유용한 시나리오는 네 가지다.

• 병렬 worktree 조율: 같은 레포를 여러 worktree에서 동시 작업할 때, 한 세션이 머지한 내용을 다른 세션에 즉시 알린다.
• 발견 사항 인계: 한 세션이 찾아낸 버그나 설계 결정을 담당 세션에 요약해서 전달한다. 개발자가 다시 설명할 필요가 없다.
• 장기 작업 상태 리포트: 마이그레이션이나 테스트 실행 세션이 완료 시점에 감시 중인 세션으로 결과를 보낸다.
• 크로스 머신 응답: Remote Control이 연결된 상태에서 다른 기기의 세션에서 온 메시지에 답장할 수 있다. 단, 첫 메시지를 원격 세션으로 먼저 보내는 것은 불가능하다.

핵심 구현 방법

두 도구가 전부다. ListAgents로 도달 가능한 세션 목록을 파악하고, SendMessage로 이름을 지정해 전달한다. 개발자가 이 도구를 직접 호출하는 일은 없다. Claude가 알아서 쓴다.

세션 이름은 /rename 명령어나 --name CLI 플래그로 지정한다. 이름을 따로 설정하지 않으면 작업 디렉터리 폴더명 기반으로 자동 부여된다(myapp-3f 같은 형식). 현재 세션에서 어떤 세션을 찾을 수 있는지 확인하려면 /list-agents 명령어를 실행하면 된다.

메시지로 전달되는 건 텍스트뿐이다. 대화 히스토리나 파일을 넘기려면 크로스세션 메시징이 아니라 세션 재개(resume) 기능을 써야 한다. 이 구분이 헷갈리면 메시징을 잘못 쓰게 된다.

Claude 스스로 메시지를 보내도록 두는 것도 가능하고, 직접 프롬프트로 요청할 수도 있다. "저쪽 세션에 현재 API 스펙 변경 내용을 요약해서 보내줘" 같은 지시면 충분하다. 메시지 내용을 직접 작성할 필요 없이 Claude가 알맞게 구성한다.

실전에서 주의할 점

메시지 수신 보장은 전제하지 마라. 수신 세션은 인바운드 컨트롤 설정에 따라 메시지를 전달(Delivered), 보류(Held), 거부(Refused) 중 하나로 처리한다. 보류된 메시지는 명시적으로 승인하거나 설정이 바뀌어야 Claude에 전달된다. 기본 설정의 일반 인터랙티브 세션끼리는 전달이 되지만, 커스텀 설정 환경에서는 반드시 확인이 필요하다.

권한 경계는 세션별로 독립된다. 한 세션에서 거부된 작업을 메시지로 다른 세션에 요청하는 건 Claude 내부 지침으로 차단된다. 수신 세션 쪽에서도 자체 권한 규칙이 그대로 적용된다. 메시지를 통해 권한을 우회하는 건 설계적으로 막혀 있다.

크로스세션 메시징의 적용 범위를 명확히 잡아야 한다. Claude Code에는 비슷해 보이는 기능이 여럿 있다. Claude가 직접 스폰하고 관리하는 세션 묶음은 agent teams, 여러 세션을 한 곳에서 모니터링하는 건 agent view, CI 결과 같은 외부 이벤트를 세션으로 밀어넣는 건 channels다. 크로스세션 메시징은 개발자가 독립적으로 시작하고 직접 조종하는 세션들 사이의 조율에 쓴다. 용도를 혼동하면 구조가 복잡해진다.

외주 개발이나 협업 프로젝트에서 여러 AI 에이전트를 병렬로 돌리는 팀이라면, 이 기능을 도입했을 때 사람의 조율 비용이 실질적으로 줄어드는 구간이 분명히 존재한다. 단, 세션 명명 규칙과 인바운드 컨트롤 정책을 팀 단위로 먼저 정리해두는 게 전제 조건이다.