Claude Code 세션 협업, 뭘 써야 할까
Claude Code 세션끼리는 서로 메시지를 보낼 수 있습니다. 다만 “서로 부른다”는 말에는 독립 세션 메시징, Agent Teams, 서브에이전트라는 세 가지 방식이 섞여 있어요. 결과만 받아오면 서브에이전트, 동료끼리 토론해야 하면 Agent Teams, 내가 따로 띄운 세션을 연결하려면 cross-session messaging을 고르면 됩니다.
30초 요약
- 서브에이전트는 한 세션 안에서 집중 작업을 맡고 결과를 호출자에게 돌려줍니다.
- Agent Teams는 독립 컨텍스트의 teammate들이 공유 작업 목록과 메시지로 협업합니다.
- 따로 실행한 세션끼리는 cross-session messaging으로 텍스트를 전달할 수 있습니다.
- Agent Teams는 실험 기능이며 기본 비활성화 상태입니다.
- 같은 파일을 여러 에이전트가 고치는 작업은 병렬화보다 파일 소유권 분리가 먼저입니다.
Claude Code 세션끼리 정말 서로 부를 수 있나요?
가능합니다. Claude Code 공식 문서의 cross-session messaging은 한 세션이 다른 세션을 찾아 텍스트 메시지를 보내는 기능입니다. macOS와 Linux에서는 v2.1.224 이상, 네이티브 Windows에서는 v2.1.234 이상이 필요합니다.
여기서 오해하기 쉬운 부분이 하나 있습니다. 메시지로 넘어가는 것은 Claude가 작성한 텍스트이지, 보낸 세션의 전체 대화 기록이나 파일이 아닙니다. 전체 맥락을 이어가려면 다른 세션에 메시지를 던지는 대신 기존 세션을 resume하는 편이 맞습니다.
공식 문서에 따르면 Claude는 ListAgents로 도달 가능한 세션을 찾고 SendMessage로 내용을 전달합니다. 사용자는 도구 이름을 직접 실행하기보다 “다른 터미널의 API 작업 세션에 스키마 변경이 끝났다고 알려줘”처럼 요청하면 됩니다.
문서 기반 입력→출력 예시는 이렇습니다.
입력: @api-worker에게 스키마 마이그레이션이 끝났다고 알려줘
출력: api-worker 세션에 변경 요약이 텍스트 메시지로 전달됨
수신 세션이 작업 중이면 실행 중인 도구가 끝난 뒤 메시지를 읽고, 쉬고 있으면 새 턴이 시작됩니다. 메시지 안의 슬래시 명령은 명령으로 실행되지 않고 평문으로 전달됩니다.
Agent Teams와 서브에이전트는 무엇이 다른가요?
생활 비유로 줄이면 서브에이전트는 “자료를 조사해 보고서로 올리는 담당자”에 가깝고, Agent Teams는 “각자 방을 쓰면서 공용 칸반과 메신저로 맞춰 가는 프로젝트팀”에 가깝습니다. 둘 다 별도 컨텍스트를 쓰지만 조정 방식이 다릅니다.
| 판단 기준 | 서브에이전트 | Agent Teams |
|---|---|---|
| 관계 | 한 세션 안의 위임 작업 | 리드와 독립 teammate 세션 |
| 결과 전달 | 호출자에게 결과 반환 | teammate끼리 직접 메시지 가능 |
| 조정 | 메인 에이전트가 관리 | 공유 작업 목록과 메시지로 자율 조정 |
| 잘 맞는 일 | 탐색, 로그 분석, 집중 리뷰 | 병렬 조사, 경쟁 가설 검증, 분리된 기능 구현 |
| 비용·복잡도 | 비교적 낮음 | 토큰과 조정 비용이 더 큼 |
서브에이전트는 조사 결과나 긴 로그가 메인 대화를 가득 채우지 않게 해 줍니다. 반복해서 쓸 역할은 .claude/agents/ 또는 ~/.claude/agents/ 아래 Markdown 파일로 정의하고, YAML frontmatter에서 설명·도구·모델·권한 등을 제한할 수 있습니다.
Agent Teams에서는 한 세션이 리드가 되고 teammate마다 독립 컨텍스트가 생깁니다. 이들은 작업을 나눠 맡고 서로 메시지를 보내며, Task 도구가 있는 세션에서는 공유 작업 목록도 씁니다. 리드의 이전 대화가 teammate에게 통째로 복사되지는 않으므로, spawn 요청에 대상 경로와 산출물, 금지 사항을 넣어야 합니다.
따로 띄운 세션과 Agent Teams는 같은 기능인가요?
아닙니다. 직접 띄운 독립 세션은 cross-session messaging으로 연락만 연결하고, Agent Teams는 리드가 teammate를 만들고 감독하는 협업 구조입니다.
예를 들어 프런트엔드와 백엔드 세션을 사람이 각각 열어 두었다면, 한쪽의 API 변경을 다른 쪽에 알리는 데 cross-session messaging이 잘 맞습니다. 반대로 한 가지 버그의 원인을 세 방향에서 동시에 검토하고 서로 반박하게 하려면 Agent Teams가 더 자연스럽습니다.
서브에이전트는 이보다 가볍습니다. “인증 코드에서 위험한 부분만 찾아 요약해 줘”처럼 결과물 하나가 필요하고, 작업자끼리 대화할 이유가 없다면 팀을 꾸릴 필요가 없습니다. 회의가 필요 없는 일에 회의실부터 예약하는 셈이니까요.
Agent Teams는 어떻게 켜고 구성하나요?
2026년 9월 15일 확인한 공식 문서에서 Agent Teams는 실험 기능이며 기본적으로 꺼져 있습니다. settings.json 또는 셸 환경에 다음 변수를 설정합니다.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
그다음 대화형 Claude Code 세션에서 역할을 자연어로 요청합니다. 다음은 실제 실행 결과가 아니라 공식 문서의 작동 방식을 바탕으로 다듬은 예시입니다.
이 로그인 오류를 세 방향에서 조사해 줘.
- auth-flow: 토큰 갱신 흐름과 재현 조건
- test-reviewer: 빠진 회귀 테스트
- skeptic: 앞선 두 가설의 반례
Agent Team으로 구성하고, 각자 findings/auth-flow.md,
findings/tests.md, findings/counterexamples.md만 작성해.
리드는 세 결과가 끝난 뒤 findings/summary.md에 합쳐 줘.
검증 명령은 npm test -- auth로 통일해.
이 프롬프트의 핵심은 멋진 역할명이 아닙니다. 파일 소유권, 완료 조건, 검증 명령, 합치는 책임이 분명하다는 점입니다. 같은 src/auth.ts를 셋이 동시에 수정하게 두면 협업이 아니라 덮어쓰기 경주가 됩니다.
기본 표시 모드는 한 터미널 안에서 teammate를 전환하는 in-process 방식입니다. 분할 창은 tmux 또는 iTerm2 구성이 필요하며 teammateMode로 선택할 수 있습니다. -p 비대화형 모드와 Agent SDK 세션에서는 teammate를 생성하지 않는다는 제한도 확인해야 합니다.
서브에이전트는 어떻게 작게 시작하나요?
처음부터 팀을 꾸리기보다 읽기 전용 코드 리뷰 역할 하나로 시작하는 편이 안전합니다. 아래는 공식 문서 형식을 따른 문서 기반 예시이며, 현재 프로젝트에서 실행해 검증한 파일은 아닙니다.
---
name: auth-reviewer
description: 인증 변경 뒤 보안과 회귀 위험을 검토합니다
tools: Read, Grep, Glob
model: sonnet
---
인증 관련 변경 파일을 읽고 다음만 보고하세요.
- 위험 위치와 파일 경로
- 재현 가능한 실패 조건
- 추가할 테스트
코드는 수정하지 마세요.
프로젝트에서 함께 쓰려면 .claude/agents/auth-reviewer.md, 내 여러 프로젝트에서 재사용하려면 ~/.claude/agents/auth-reviewer.md에 둡니다. 설명은 언제 이 역할을 불러야 하는지 짧고 구체적으로 적고, 쓰기 작업이 필요 없다면 도구 목록에서도 빼는 편이 낫습니다.
이후 “auth-reviewer를 사용해 이번 변경을 검토해 줘”라고 명시적으로 위임할 수 있습니다. 조사 결과를 메인 세션에 요약해 돌려받는 것만으로 충분하다면 여기서 멈추면 됩니다.
실제 협업은 어떻게 나누면 덜 꼬이나요?
가장 먼저 작업의 관계를 그려 보세요. 서로 기다려야 하는 일이 많은지, 독립적으로 끝낼 수 있는지에 따라 도구 선택이 갈립니다.
- 독립 조사 세 건 → 서브에이전트 병렬 실행 또는 Agent Teams
- 조사 결과를 서로 반박해야 함 → Agent Teams
- 사람이 이미 띄운 두 세션 사이에 결정 전달 → cross-session messaging
- 한 파일을 순서대로 고쳐야 함 → 단일 세션
- 긴 탐색 결과만 메인 컨텍스트에서 치우고 싶음 → 서브에이전트
병렬 구현이 필요하면 파일 경계를 먼저 나눕니다. 프런트엔드, API, 테스트처럼 산출물이 겹치지 않는 단위가 좋고, 공통 타입이나 설정 파일은 마지막 통합 담당자 한 명에게 맡기는 편이 안전합니다.
작업마다 “완료했습니다” 대신 확인 가능한 신호도 붙여야 합니다. 테스트 명령, 빌드 결과, 린트, 생성되어야 할 파일을 지정하면 리드가 말뿐인 완료와 실제 완료를 구분할 수 있습니다.
언제 Agent Teams를 쓰지 않는 편이 낫나요?
작업이 순차적이거나 같은 파일에 집중돼 있다면 Agent Teams의 조정 비용이 이익보다 커질 수 있습니다. 공식 문서도 routine task에는 단일 세션이 더 경제적이며, teammate 수가 늘수록 토큰 사용과 조정 비용이 함께 증가한다고 설명합니다.
또 Agent Teams는 아직 실험 기능입니다. 세션 재개, 작업 조정, 종료 동작에 알려진 한계가 있으므로 장시간 무인 실행의 기본값으로 보기 어렵습니다. 먼저 조사·리뷰처럼 경계가 분명하고 코드 충돌이 적은 작업에서 시험하는 편이 좋습니다.
cross-session messaging도 만능 공유 폴더는 아닙니다. 메시지는 파일을 첨부하거나 대화 기록을 옮기지 않으며, 다른 세션의 권한 승인을 대신할 수도 없습니다. 수신 세션의 권한과 crossSessionInbound 설정은 그대로 적용됩니다.
2026년 9월 15일 확인 당시 Anthropic GitHub Releases의 최신 표시는 v2.1.271입니다. 다만 기능별 최소 버전과 세부 동작이 빠르게 달라지고 있으니, 설치된 버전을 확인한 뒤 현재 공식 문서의 버전 조건을 다시 맞추는 것이 마지막 단계입니다.
핵심 정리: 다섯 가지 질문과 답
Q. Claude Code 독립 세션끼리 대화할 수 있나요?
가능합니다. 지원 버전에서는 cross-session messaging으로 텍스트를 주고받지만, 전체 대화 기록이나 파일이 자동으로 넘어가지는 않습니다.
Q. 결과만 받아오고 싶다면 무엇을 써야 하나요?
서브에이전트가 알맞습니다. 별도 컨텍스트에서 집중 작업을 처리하고 요약된 결과를 메인 세션에 돌려줍니다.
Q. Agent Teams가 필요한 순간은 언제인가요?
작업자끼리 직접 정보를 교환하거나 서로의 가설을 검토해야 할 때입니다. 독립된 작업 경계가 있어야 병렬화의 이익도 살아납니다.
Q. 여러 에이전트가 같은 파일을 고쳐도 되나요?
피하는 편이 좋습니다. 파일 소유권을 나누고 공통 파일은 통합 담당자 한 명이 마지막에 반영하는 구성이 안전합니다.
Q. 협업 구성에서 가장 먼저 정할 것은 무엇인가요?
역할명보다 산출물, 파일 경계, 완료 조건, 검증 명령을 먼저 정해야 합니다. 그래야 리드가 결과를 합치고 실제 통과 여부를 확인할 수 있습니다.
공식 자료
'AI > AI 최신 기술' 카테고리의 다른 글
| When2Think, 쉬운 질문까지 길게 답하는 AI를 어떻게 멈출까 (0) | 2026.09.20 |
|---|---|
| WeVisDoc 평가, 표 점수만 보면 놓치는 것 (1) | 2026.09.19 |
| EvoSafeHarness, 보안 규칙을 고정하지 않고 어디까지 맡길까 (0) | 2026.09.14 |
| NCP-ArchPreview, 다음 토큰만 맞혀선 부족한 이유 (0) | 2026.09.14 |
| 토큰이 녹는다, Codex·Claude Code 토큰 최적화, 파일을 덜 읽게 만드는 설정 (0) | 2026.09.14 |
댓글