Claude Code 에이전트 팀이 컨텍스트를 공유하지 않는 이유와 해결 방법 (2026)

우선 솔직히 짚고 넘어갑시다: 이 기능은 실험적이며 기본적으로 비활성화되어 있습니다

무엇보다 먼저, 에이전트 팀 기능은 직접 켜지 않으면 비활성화되어 있습니다. 문서에는 이 기능이 "실험적이며 기본적으로 비활성화되어 있다"고 경고하고 있으며, 설정이나 환경 변수에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정해야 활성화됩니다. 또한 "이 변수가 없으면 세션 시작 시 팀이 구성되지 않고, 팀 디렉터리가 생성되지 않으며, Claude가 팀원을 생성하거나 제안하지 않습니다."

따라서 약속을 어긴 것은 아닙니다. 문서화된 제한 사항이 있는 초기 단계의 기능이며, 컨텍스트 경계는 실수라기보다는 의도된 설계 결정입니다.

협업은 공유되지만, 대화는 공유되지 않습니다

아키텍처 섹션에 설명된 팀의 구성 요소를 살펴보십시오. 팀 리드, 팀원, 공유 작업 목록, 그리고 사서함이 있습니다. 사서함은 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json에 있는 JSON 파일입니다. 작업 목록은 ~/.claude/tasks/{team-name}/ 아래에 위치합니다.

이 두 가지(작업과 메시지)가 공유되는 기반의 전부입니다. 팀원들은 작업 상태를 확인하고, 할당 가능한 작업을 가져가고, 서로의 이름을 지정해 메시지를 보낼 수 있습니다. 하지만 서로의 추론 과정이나 사용자의 추론 과정은 볼 수 없습니다.

문서에서 직접 비교하듯 서브에이전트(subagents)와 비교해 보겠습니다. 서브에이전트는 고유한 컨텍스트 창을 가지고 호출자에게 결과를 보고합니다. 반면 팀원은 고유한 컨텍스트 창을 가지며 "완전히 독립적"이어서 상위 에이전트에 보고하는 대신 서로 메시지를 주고받습니다. 두 모델 모두 컨텍스트를 격리합니다. 팀은 단지 채널을 하나 더 추가할 뿐입니다.

생성 프롬프트가 브리핑의 전부입니다

이것이 실질적인 결과이며, 규칙으로 명시할 가치가 있습니다. 팀원이 알기를 바라는 모든 내용은 생성 프롬프트에 포함되거나, 팀원이 로드하는 파일에 있거나, 나중에 누군가가 보내는 메시지에 있어야 합니다.

문서의 모범 사례에서도 팀원들이 프로젝트 컨텍스트를 자동으로 로드하지만 "리드의 대화 기록은 상속받지 않으므로", "생성 프롬프트에 작업별 세부 정보를 포함해야 한다"고 설명합니다. 예시로 제공된 생성 프롬프트는 여러 문장으로 구성되어 있으며 모듈, 중점 분야, 토큰 저장 방식, 출력 형식을 지정하고 있습니다.

실제로 이 브리핑을 작성하는 주체가 누구인지 주목하십시오. 바로 사용자와의 대화를 압축해서 이해한 리드 에이전트입니다. 모든 팀원의 시작 지식은 사용자가 나눈 대화에 대해 다른 모델이 작성한 요약본이며, 리드가 관련이 있다고 판단한 내용으로 필터링된 결과물입니다.

팀원은 사용자의 컨텍스트가 아니라 프로젝트 컨텍스트를 받습니다

이 차이는 중요합니다. 팀원은 작업 디렉터리에서 CLAUDE.md를 읽고(문서에서도 "CLAUDE.md가 정상적으로 작동한다"고 확인해 줍니다), 프로젝트 및 사용자 설정에서 MCP 서버와 스킬을 가져옵니다.

따라서 커밋된 파일 형태의 지식은 전파됩니다. 하지만 그 외의 모든 것은 전파되지 않습니다. 채팅에서 언급한 제약 조건, 한 시간 전에 리드에게 준 피드백, 터미널을 열기 전 회의에서 내린 결정 등은 파일에 존재하지 않으므로 팀원에게 전달되지 않습니다.

서브에이전트 정의를 팀원 유형으로 사용할 때 주의해야 할 점도 있습니다. 문서에 따르면, 서브에이전트 정의의 skills 및 mcpServers 프런트매터 필드는 "해당 정의가 팀원으로 실행될 때는 적용되지 않습니다." 팀원은 일반 세션처럼 프로젝트 및 사용자 설정에서 스킬과 MCP 서버를 로드하기 때문입니다.

팀원이 학습한 내용은 팀과 함께 사라집니다

팀은 세션 범위(session-scoped)로 제한됩니다. 팀 이름은 세션 ID에서 파생되며(session- 뒤에 세션 ID의 처음 8글자 결합), "세션이 종료되면 팀 구성 디렉터리가 삭제됩니다." 작업 목록 디렉터리는 로컬에 유지되고 업로드되지 않으며, 보존 기간은 트랜스크립트에 사용하는 것과 동일한 cleanupPeriodDays에 의해 관리됩니다.

즉, 작업은 유지되지만 팀은 유지되지 않습니다. 아무것도 누적되지 않습니다. 오늘 아침에 에러 처리 규칙을 학습한 리뷰어 팀원은 오늘 오후가 되면 사라지고, 내일의 리뷰어는 동일한 생성 프롬프트에서 다시 시작해야 합니다. 또한 진행 중인 팀원에 대한 세션 재개 기능도 없습니다. /resume 및 /rewind 명령어로 팀원을 복구할 수 없으며, 리드가 "더 이상 존재하지 않는 팀원에게 메시지 전송을 시도할 수 있습니다."

메시지는 텍스트이며, 의도적으로 신뢰도가 낮게 설정되어 있습니다

사서함이 지식을 전달할 수 있다고 생각할 수도 있습니다. 사서함은 문장을 전달할 수 있지만, 시스템은 이 문장들을 의심하도록 설계되어 있습니다.

한 에이전트가 다른 에이전트에게 메시지를 보낼 때, "Claude Code는 수신 에이전트에게 해당 메시지가 사용자가 아닌 다른 Claude 세션에서 왔음을 알립니다." 팀원은 "사용자를 대신해 권한 프롬프트를 승인하거나 동의를 제공할 수 없으며", 작업을 거부당한 팀원이 "검사를 우회하기 위해 다른 팀원에게 작업을 전달할 수 없습니다." 자동 모드에서는 분류기(classifier)가 전달된 승인 요청을 신뢰할 수 없는 입력으로 취급하고 전송 전에 각 메시지를 검토하여 일부를 완전히 차단합니다.

이는 올바른 보안 설계이지만, 사서함이 지식 버스가 아니라 단순한 협업 채널임을 의미합니다. 또한 실무적인 형태도 알아둘 필요가 있습니다. 모든 팀원에게 메시지를 전달하려면 수신자당 하나의 메시지를 보내야 합니다.

그리고 이를 재구축하는 데는 실제 비용이 듭니다

문서에서는 에이전트 팀이 "단일 세션보다 훨씬 더 많은 토큰을 사용한다"고 명시하고 있으며, 활성 팀원 수에 비례하여 증가하므로 대부분의 워크플로우에서 3~5명을 권장합니다. 이 토큰 비용의 일부는 각 팀원이 동일한 이해를 재구축하기 위해 동일한 파일을 독립적으로 읽는 데 소비됩니다. 이는 공유 저장소가 한 번에 해결할 수 있는 문제를 가장 비용이 많이 드는 방식으로 해결하는 셈입니다.

거대한 생성 프롬프트 작성하기. 문서에 나와 있는 해결책이며 어느 정도 효과가 있습니다. 하지만 세션마다 팀원별로 브리핑을 직접 작성해야 하며, 이 브리핑은 대화를 압축한 것이기 때문에 팀원이 판단을 내려야 하는 중요한 순간에 제약 조건의 배경이 되는 이유가 누락되곤 합니다.

모든 내용을 `CLAUDE.md`에 넣기. 팀원들이 이 파일을 읽으므로 올바른 직관입니다. 한계는 크기입니다. 지침에 따르면 지시 파일은 짧게 유지해야 합니다. 파일이 길어지면 컨텍스트를 많이 소모하고 일관되게 준수되지 않기 때문입니다. 네 명의 팀원에게 필요한 모든 내용을 담은 CLAUDE.md는 결국 아무도 따르지 않는 파일이 됩니다.

리드가 발견한 내용을 전달하게 하기. 작동은 하지만, 리드가 병목이 되어 한 팀원이 배운 내용을 다른 팀원이 읽을 수 있도록 다시 작성하는 데 토큰을 낭비하게 됩니다. 또한 생성 프롬프트와 마찬가지로 정보 손실이 발생합니다.

각 팀원의 트랜스크립트를 직접 읽기. 가능합니다. 패널에서 팀원을 선택하고 Enter 키를 누르면 직접 확인하고 메시지를 보낼 수 있습니다. 방향을 잡아주는 데는 유용하지만, 시스템적인 메커니즘으로는 쓸모가 없습니다. 사용자가 직접 통합 레이어가 되어야 하기 때문입니다.

대신 서브에이전트 사용하기. 때로는 올바른 선택입니다. 서브에이전트는 비용이 적게 들고 결과를 보고하며, 문서에서는 작업자 간에 대화할 필요가 없을 때 서브에이전트를 권장합니다. 하지만 이 역시 지식 공유 문제를 해결하지는 못합니다. 서브에이전트도 동일하게 격리되어 있으며, 사서함조차 없습니다.

리포지토리에 임시 파일(scratch file) 유지하기. 가장 효과적인 임시 방편이며, 올바른 해결책을 수동으로 구현한 버전입니다. 개별 에이전트의 컨텍스트 외부에서 모든 에이전트가 읽고 쓸 수 있는 공간을 만드는 것입니다. 사람들이 결국 각자 이 방식으로 수렴하게 된다는 점은 주목할 만합니다.

격리 상태는 유지하십시오. 독립적인 컨텍스트 창 덕분에 5명의 에이전트로 구성된 팀이 서로의 출력에 묻히지 않고 병렬로 작업할 수 있으며, 신뢰도가 낮은 메시징 규칙이 사용자를 보호하고 있습니다.

해결해야 할 문제는 현재 "격리된 컨텍스트"가 "격리된 지식"을 의미한다는 점입니다. 이 둘은 분리할 수 있습니다. 모든 컨텍스트 창 외부에 팀을 위한 저장소를 제공하십시오. 리드가 제약 조건과 결정을 여기에 기록하고, 팀원들은 작업을 시작할 때 이를 읽고 발견한 내용을 다시 기록합니다. 그러면 다음 날의 다음 팀은 새로운 생성 프롬프트 대신 이전 팀이 배운 내용에서 시작할 수 있습니다.

MemoryLake는 이를 위한 메모리 레이어입니다. 결정 사항, 제약 조건, 원본 문서를 하나의 저장소에 보관하며, 모든 팀원, Codex, 그리고 API를 통해 ChatGPT에서 MCP를 통해 접근할 수 있습니다. 작업 목록은 협업을 조정하고, 저장소는 지식을 전달합니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 보낼 수 있습니다. 세션에 직접 붙여넣는 대신 환경 변수나 비밀 관리자(secret manager)에 보관하십시오.

2단계: 첫 번째 메모리 업로드하기

팀원들이 계속해서 다시 찾아내야 하는 문서, 이미지, 파일을 업로드하십시오. 배경 이유가 포함된 아키텍처 결정 사항, 장애 보고서, API 규약, 컨벤션, 이미 제외하기로 한 접근 방식 목록 등이 이에 해당합니다. 요약본 대신 원본 소스를 업로드하십시오. 생성 프롬프트는 이미 요약본이며, 요약 단계에서 배경 이유가 유실되기 쉽습니다.

3단계: AI 및 에이전트 연결하기

Claude, Codex, OpenClaw 및 기타 AI 에이전트가 MCP 또는 API를 통해 메모리에 접근할 수 있도록 하십시오. 팀원은 일반 세션과 마찬가지로 프로젝트 및 사용자 설정에서 MCP 서버를 로드하므로, 서버를 한 번만 구성하면 모든 팀원이 동일한 저장소를 공유하게 됩니다. 팀원별로 따로 설정할 필요가 없으며, 리드가 잊지 않고 전달해 주기를 바랄 필요도 없습니다.

첫 번째 차이점은 생성 프롬프트가 더 짧고 명확해진다는 것입니다. 전체 대화를 브리핑으로 압축하는 대신, 이 팀원이 담당할 작업이 무엇인지 명시하고 나머지는 저장소를 참조하도록 안내합니다. 정보 손실이 적고, 타이핑이 줄어들며, 모든 팀원에게 동일하게 적용할 수 있습니다.

두 번째는 발견한 내용이 팀보다 오래 살아남는다는 점입니다. 디버깅을 담당하는 팀원이 재시도 엔드포인트가 멱등성을 보장하지 않는다는 사실을 알게 되면, 이 내용이 저장소에 기록되어 내일의 팀으로 전달됩니다. 현재 방식에서는 이러한 발견이 세션과 함께 사라지는 컨텍스트 창에만 머무르게 됩니다.

세 번째는 병렬 작업 시 동일한 컨텍스트를 다섯 번씩 다시 추론할 필요가 없어진다는 점입니다. 각 팀원이 검색된 제약 조건을 읽는 것이, 각 팀원이 코드베이스를 읽고 이를 추론하는 것보다 훨씬 저렴합니다. 이는 팀이 훨씬 더 많은 토큰을 사용한다는 문서의 경고를 고려할 때 중요하며, 매 세션마다 코드베이스를 다시 읽는 에이전트의 문제를 해결하는 데도 중요합니다.

또한 이는 Claude Code가 이미 수행하는 작업들과 결합됩니다. CLAUDE.md는 상시 규칙을 계속 전달하고, 자동 메모리(auto memory)는 로컬 노트를 유지하며, 작업 목록은 협업을 계속 조정합니다. 이들 중 어느 것도 단일 진실 공급원(system of record)이 될 필요가 없습니다. 어차피 자동 메모리는 작성된 기기를 벗어나지 못하므로 그렇게 될 수도 없습니다.

팀원을 생성하기 전에 제약 조건을 기록해 두십시오

사용자와 리드가 결론에 도달하기 위해 40분을 보냈다면, 그 결론은 팀원이 읽을 수 있는 어딘가에 존재해야 합니다. 생성하기 전에 10분 동안 기록해 두면, 세 명의 팀원이 거부된 설계를 각자 독립적으로 다시 개발하는 일을 방지할 수 있습니다.

생성 프롬프트는 교육이 아니라 역할(ownership)에 집중하십시오

이 팀원이 무엇을 담당하는지, 완료 기준이 무엇인지, 컨텍스트를 어디서 찾아야 하는지 명시하십시오. 프롬프트에서 프로젝트 전체를 가르치려다 보면 브리핑이 600단어를 넘어가면서도 정작 중요한 내용을 놓치게 됩니다.

팀원에게 예측 가능한 이름을 부여하십시오

리드는 생성 시 각 팀원의 이름을 지정하며, 모든 팀원은 그 이름으로 다른 팀원에게 메시지를 보낼 수 있습니다. 나중에 참조할 수 있도록 생성 지침에서 리드에게 팀원들을 어떻게 부를지 알려주십시오. 그리고 모든 사람에게 메시지를 보내려면 수신자당 하나의 메시지를 보내야 한다는 점을 기억하십시오.

지식을 전달하기 위해 메시지에 의존하지 마십시오

사서함은 텍스트이며, 수신되는 메시지는 사용자가 아닌 다른 Claude 세션에서 온 것으로 취급되고 권한 요청은 명시적으로 신뢰되지 않습니다. 메시지는 "인증 모듈 작업을 완료했습니다"와 같은 협업 조정용으로 사용하고, 사실 정보는 저장소를 사용하십시오.

세션 재개 시 팀이 유지되지 않을 수 있음을 염두에 두십시오

/resume 및 /rewind는 진행 중인 팀원을 복구하지 않으며, 리드가 더 이상 존재하지 않는 팀원에게 메시지를 보내려고 시도할 수 있습니다. 이런 일이 발생하면 새 팀원을 생성하도록 지시하고, 새 팀원이 이전 팀원이 배운 내용을 읽을 수 있도록 하십시오.

3~5명의 팀원으로 시작하고 읽기 전용 작업부터 시작하십시오

문서에서 권장하는 사항이며 실패 사례와도 일치합니다. 협업 오버헤드와 토큰 비용은 팀 규모에 따라 증가하며, 병렬 구현은 파일 충돌을 유발하기 쉽습니다. 리뷰, 조사, 대립 가설 디버깅 등에서 팀 기능이 비용 대비 가치를 발휘합니다.

이 모든 것을 강제 적용(enforcement)과 혼동하지 마십시오

지시 파일과 메모리는 컨텍스트일 뿐 강제된 설정이 아닙니다. 포맷팅, 보호된 경로, main 브랜치로의 직접 푸시 금지 등 모든 팀원의 출력에서 반드시 지켜져야 하는 규칙이 있다면, 개별 팀원이 무엇을 읽었는지에 의존하지 않고 모두에게 적용되는 훅(hook)이나 CI에 설정하십시오.

Claude Code 에이전트 팀이 컨텍스트를 공유하지 않는 이유는 팀원이 설계상 독립적이기 때문입니다. 각 팀원은 고유한 컨텍스트 창을 가지며, 프로젝트 컨텍스트(CLAUDE.md, MCP 서버, 스킬)를 로드하고, "리드의 대화 기록은 전달되지 않습니다." 이들이 공유하는 것은 작업 목록과 사서함뿐이며, 사서함은 동의와 관련된 모든 사항에 대해 에이전트 간 메시지를 의도적으로 신뢰하지 않습니다. 팀 자체는 세션 범위로 제한됩니다. 세션이 끝나면 구성 디렉터리가 삭제되고, 진행 중인 팀원은 세션 재개 시 유지되지 않으며, 한 팀에서 다음 팀으로 누적되는 정보가 없습니다.

그러므로 격리 상태는 유지하되 공유 문제를 해결하십시오. 모든 팀원이 읽고 쓸 수 있는 저장소에 제약 조건과 결정을 기록하고, 생성 프롬프트는 교육이 아닌 역할에 집중하도록 하며, 작업 목록이 협업을 조정하도록 하십시오. 그러면 다섯 명의 에이전트가 사용자의 대화를 다섯 번 압축한 결과물이 아니라, 프로젝트에 대한 단 하나의 공통된 이해를 바탕으로 작업하게 됩니다.