8개 세션을 혼자서 마스터하기! Claude Code 오케스트레이션 완벽 가이드

"Claude Code를 사용하고 있는데, 규모가 커질수록 컨텍스트가 넘쳐나고 정확도가 떨어집니다."

"결국, AI에게 수정 지침을 내리는 제 손이 가장 큰 병목이 되었습니다."

많은 분들이 아마 이 지점에서 막혀 있을 겁니다. 저도 처음에는 코드, 테스트, 디자인 논의를 모두 하나의 세션에 넣어두고, 기록이 늘어남에 따라 Claude의 정확도가 떨어지는 것을 지켜보기만 했습니다.

최근에 깨달은 것은, Claude Code 자체가 공식적으로 여러 세션을 병렬로 실행할 수 있는 세 가지 메커니즘을 제공한다는 점입니다.

게다가 이 세 가지는 비슷하면서도 달라서 헷갈리면 사고로 이어질 수 있습니다. 반대로, 역할별로 구분하면 코드를 한 줄도 직접 작성하지 않고도 "지휘하는 입장"으로 전환할 수 있습니다.

오늘은 이 세 가지 메커니즘과 공식 문서의 1차 정보를 확인하면서 역할 경계를 올바르게 고정하는 방법을 정리하겠습니다.

구체적으로는 명령, 구현, 품질의 세 레이어에 8개의 세션을 배치하는 구성으로 설명합니다.

보너스로, "CLAUDE.md에 역할 ID를 작성해서 전환한다"거나 "SQLite로 메모리를 공유한다"는 흔한 설명이 공식 메커니즘과 왜 약간 다른지 1차 정보를 통해 설명하겠습니다.

저는 tatsuki(@nobel_824)입니다.

중소기업의 AI 활용을 지원하며, Claude / Codex의 업무 도입을 돕는 한편, 저 자신도 하루 종일 Claude Code를 돌리고 있습니다. 병렬 운영은 업무와 개인 프로젝트 모두에서 매일 접하는 분야입니다.

https://note.com/nobel/n/n8192ec07d689

1. "모든 것을 하나의 세션에 때려넣는 것"이 실패하는 이유

첫 번째 함정은 단일 세션에 너무 많은 정보를 과부하시키는 것입니다. 아무리 뛰어난 Claude 모델이라도 구조적인 한계에 부딪힙니다.

구체적으로는 다음 세 가지 문제가 발생합니다.

컨텍스트 오염: 구현 코드, 테스트, 디버그 기록, 설계 논의가 동일한 컨텍스트에 섞이면 추론의 기반이 흐려지고 정확도가 떨어집니다.
명령 충돌: "속도 우선으로 구현"과 "보안에 엄격해야 함"이 같은 공간에 존재하면 판단이 모호해집니다.
토큰 비대: 매번 방대한 기록을 불러오는 것은 시간과 비용 모두 낭비입니다.

해결책은 "단일 지휘관이 되어 전문화된 Claude들을 일렬로 세우는" 아이디어입니다. CTO가 Tech Lead와 Backend Lead를 두는 것과 비슷하지만, 중요한 것은 분위기가 아니라 공식 Claude Code 메커니즘을 올바르게 활용하는 것입니다.

오늘 바로 실행할 수 있는 한 가지: 현재 세션을 생각해보고 "구현", "연구", "리뷰"가 하나의 컨텍스트에 공존하고 있는지 확인하세요. 그렇다면, 그것이 분할을 시작하는 출발점입니다.

2. 공식적으로 제공되는 "세 가지 병렬 메커니즘" 바로잡기

이것이 이 글의 핵심입니다. Claude Code에는 병렬 처리를 위한 세 가지 메커니즘이 있으며, 각각 범위가 다릅니다.

첫 번째는 subagent(메인 대화와는 별도의 컨텍스트에서 실행되는 헬퍼 AI)입니다. 자체 컨텍스트 윈도우, 전용 시스템 프롬프트, 제한된 도구 권한을 사용하여 리서치나 리뷰 같은 사이드 태스크를 실행하고, 결과 요약만 메인 세션에 반환합니다. 핵심은 subagent가 동일한 세션 내에서 실행되며, 메인에게만 보고하고, subagent끼리는 서로 대화하지 않는다는 점입니다(공식 문서).

두 번째는 agent teams(여러 Claude Code 세션이 팀으로 협업하는 메커니즘)입니다. 하나의 세션이 팀 리드가 되어 동료를 생성하고, 공유 작업 목록과 사서함을 통해 협업합니다. subagent와 달리 팀원은 서로 직접 메시지를 보낼 수 있습니다. 이는 실험적 기능이며 기본적으로 비활성화되어 있습니다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정하고 Claude Code v2.1.32 이상을 사용해야 합니다(공식 문서).

세 번째는 git worktree(동일한 저장소에서 여러 작업 디렉토리를 허용하는 Git 기능)입니다. claude --worktree feature-auth로 시작하면 Claude가 다른 브랜치/디렉토리의 격리된 환경에서 실행됩니다. 다른 터미널에서 또 다른 인스턴스를 실행하면 서로의 파일을 침범하지 않고 병렬로 실행할 수 있습니다(공식 문서). 데스크탑 앱을 사용할 때는 새 세션마다 worktree가 자동으로 생성됩니다.

다음은 세 가지를 비교한 표입니다.

worktree는 파일 격리를, subagent와 agent teams는 작업 자체의 조정을 담당한다는 점을 기억하면 헷갈리지 않을 것입니다.

오늘 바로 실행할 수 있는 한 가지: 먼저 claude --worktree bugfix-test를 입력하여 격리된 세션 실행을 체험해보세요. 변경 후 종료하면 worktree를 유지할지 삭제할지 묻습니다.

3. 실전: 8개 세션을 "3-레이어 구조"로 배치하기

이 세 가지 메커니즘을 어떻게 8개 세션으로 구현할까요? 저는 명령, 실행, 품질 레이어로 구분된 구성을 사용합니다.

명령/설계 레이어 (2개 세션)

세션 1 PM (Project Manager): 전체 진행 관리, 작업 분할, 사람에게 보고.
세션 2 Architect: 기술적 일관성 및 디렉토리 구조 결정. 코드를 작성하지 않고 설계만 생성하려면 계획 승인이 필요합니다.

실행/구현 레이어 (4개 세션)

세션 3 Frontend: 컴포넌트 생성, UI 조정.
세션 4 Backend: 엔드포인트 구현, 쿼리 최적화.
세션 5 Infra/DevOps: Docker, CI/CD 유지보수.
세션 6 Security: 취약점 검사, 인증 강화.

품질/유지보수 레이어 (2개 세션)

세션 7 QA/Reviewer: PR 리뷰, 예외 상황 지적.
세션 8 Technical Writer: README, API 문서 유지보수.

이 구성에는 세 가지 팁이 있습니다. 구현 레이어의 4개 세션은 worktree로 격리하여 서로의 파일을 침범하지 않도록 합니다. 품질 레이어의 역할은 subagent 정의 또는 agent teams 팀원으로 고정합니다. 그리고 각 세션은 공유 Markdown 파일(설계 노트 또는 리뷰 결과)을 통해 정보를 중계합니다. Architect가 설계를 업데이트하면 구현 레이어가 이를 바탕으로 움직이고, Reviewer가 결과를 다시 기록합니다. 사람은 이러한 파일 업데이트를 트리거로 각 세션에 지시만 내리면 됩니다.

참고: 하나의 agent teams에 대한 공식 가이드라인은 3~5명이므로, 8명 모두를 한 팀에 한꺼번에 넣지 마세요(공식 문서). worktree로 격리된 세션과 3~5명의 agent teams, 그리고 필요에 따라 subagent를 조합하여 총 8명의 워커를 구성하는 것이 더 안전합니다.

오늘 바로 실행할 수 있는 한 가지: 위 8가지 역할 중 현재 프로젝트에서 분할하기 쉬워 보이는 두 가지를 선택하세요. 많은 경우 Architect와 Reviewer가 첫 번째 분할 지점입니다.

4. "CLAUDE.md"가 아닌 "Subagent 정의"로 역할 경계 고정하기

병렬 운영에 대한 한 가지 흔한 오해를 바로잡겠습니다. "CLAUDE.md에 역할(ID: arch, ID: dev-main...)을 작성하고 시작 시 페르소나를 전환한다"는 설명을 볼 수 있지만, 실제로 그러한 메커니즘은 존재하지 않습니다.

CLAUDE.md는 Claude Code가 시작 시 읽는 공유 명령 파일입니다. 그러나 공식 문서는 CLAUDE.md가 "컨텍스트이지 강제 설정이 아니다"라고 명확히 밝히고 있습니다. 시스템 프롬프트 이후에 사용자 메시지로 전달되므로 엄격한 준수가 보장되지 않습니다. 어떤 것을 절대적으로 막고 싶다면 hooks를 사용해야 합니다(공식 문서). 절대적인 "헌법"이 아닌 강력한 권장 사항으로 생각하세요.

그렇다면 역할은 어디서 고정해야 할까요? 정답은 subagent 정의입니다. .claude/agents/ 디렉토리 아래에 이름, 설명, 사용 가능한 도구, 모델을 frontmatter에 포함한 파일을 배치하면 재사용 가능한 전문가가 완성됩니다. 다음은 최소 예시입니다.

name: security-reviewer

description: 인증, 입력 검증, 세션 관리 측면에서 코드를 비판적으로 감사합니다.

tools: Read, Grep, Bash

model: sonnet

당신은 시니어 보안 리뷰어입니다. 토큰 처리,

세션 관리, 입력 검증에 집중하고, 심각도 수준과 함께 결과를 보고하세요.

또한, 이러한 정의는 agent teams에서 팀원으로 이름을 지정하여 호출할 수 있습니다. "security-reviewer 에이전트 유형으로 팀원을 설정하여 auth 모듈을 감사하게 해줘"라고 요청하면, 해당 정의의 도구와 모델을 상속받은 멤버가 됩니다(공식 문서). 역할을 한 번 subagent 정의로 작성하면 subagent와 팀 멤버 모두로 재사용할 수 있도록 설계되어 있습니다.

시도해볼 프롬프트 예시 (Claude에게 역할 정의를 생성하도록 하기):

.claude/agents/ 디렉토리에 배치할 subagent 정의를 생성하세요.

역할은 "구현 코드의 성능 문제와 N+1 쿼리를 지적하는 리뷰어"입니다.

frontmatter에 name / description / tools / model을 포함하고,

본문은 시니어 엔지니어의 페르소나로 작성하세요.

5. Agent Teams로 "Architect-Reviewer" 팀을 구축하여 정확도 향상

병렬 운영에서 매우 효과적인 구성은 "생성자"와 "의심자"를 별도로 설정하는 것입니다. 이는 단순한 이론이 아니라 공식 문서에서 실제 사례를 제공하고 있습니다.

공식 "병렬 코드 리뷰" 예시에서는 하나의 PR에 대해 보안, 성능, 테스트 커버리지라는 세 명의 팀원을 설정하고, 각각 다른 관점에서 검토하는 동안 리드가 결과를 통합합니다. 또한 "경쟁 가설" 예시에서는 버그에 대해 다섯 명의 팀원에게 서로 다른 가설을 할당하여 서로의 이론을 논박하고 반증하게 하여 살아남은 이론을 근본 원인으로 처리합니다(공식 문서). 단일 조사자는 첫 번째 이론에 끌리기 쉬우므로, 이 접근법은 의도적으로 갈등을 만들어 정확도를 향상시킵니다.

또한 공식 기능을 사용하여 Architect에게 "코드 작성 권한을 부여하지 않는" 운영도 구현할 수 있습니다. 팀원에게 계획 승인을 요구하면, 팀원은 읽기 전용 계획 모드에 머물러 리드가 승인할 때까지 설계만 생성합니다. 승인 기준은 리드의 프롬프트에 "테스트 커버리지를 포함한 계획만 승인"과 같이 작성할 수 있습니다.

시도해볼 프롬프트 예시 (한 번에 갈등 구조 설정하기):

PR #142를 리뷰할 agent teams를 생성하세요. 세 명의 팀원을 설정합니다:

한 명은 보안, 한 명은 성능, 한 명은 테스트 커버리지 담당입니다.

각자 독립적으로 리뷰하고 심각도와 함께 결과를 출력한 다음, 마지막에 통합하세요.

두 가지 디스플레이 모드가 있습니다: in-process(모든 팀원이 동일한 터미널에서 실행, Shift+Down으로 순환)와 split panes(각 팀원이 별도 창에서 실행, tmux 또는 iTerm2 필요). 추가 설정이 필요 없는 in-process로 시작하는 것이 더 쉽습니다.

6. "SQLite"가 아닌 공식 자동 메모리(Markdown)를 통해 메모리 공유

여러 세션을 실행할 때 다음 난관은 "세션 간 메모리 공유"입니다. "태그된 메모리를 SQLite에 저장하고 동적으로 주입하는" 고급 기술이 소개되기도 하지만, 이는 표준 Claude Code 기능이 아닙니다. MCP(Model Context Protocol)를 통해 DB를 구축하면 가능하지만, 공식적으로 제공되는 메모리 메커니즘과는 구분해야 합니다.

공식 자동 메모리(auto memory)는 markdown 파일로 작동합니다. ~/.claude/projects/<project>/memory/ 디렉토리 안에 MEMORY.md(인덱스) 및 debugging.md와 같은 주제별 파일이 위치하며, Claude가 작업하면서 이를 작성합니다. 로딩 규칙은 명확합니다. 모든 세션은 MEMORY.md의 처음 200줄 또는 25KB까지 읽고, Claude는 필요할 때만 주제별 파일을 읽습니다. 이는 Claude Code v2.1.59부터 사용 가능하며, 저장소별로 저장되고(따라서 worktree 간에 공유됨), 로컬에 저장됩니다(공식 문서).

이 설계의 장점은 "인덱스를 항상 로드하고 필요할 때만 세부 정보를 가져오는" 방식으로 컨텍스트 윈도우를 깔끔하게 유지할 수 있다는 점입니다. 수천 개의 소규모 규칙이 있더라도 인덱스가 비대해지지 않으면 매번 컨텍스트가 오염되지 않습니다.

순서상으로는, 커스텀 SQLite 솔루션을 구축하기 전에 먼저 공식 markdown 기반 자동 메모리를 최대한 활용하십시오.

오늘 바로 실행할 수 있는 한 가지: 세션 중 /memory를 입력하면 현재 로드된 CLAUDE.md 및 자동 메모리 파일 목록이 표시됩니다. 먼저 메모리가 어디에, 몇 개나 있는지 살펴보세요.

7. 병렬 운영의 세 가지 함정 (비용, DB, 권한)

이제 메커니즘을 이해했으니, 운영 시 주의할 세 가지 사항을 알려드리겠습니다.

첫째는 토큰 비용입니다. 공식 문서에 따르면 agent teams의 각 팀원은 독립적인 컨텍스트를 가지므로 토큰 사용량은 인원수에 비례하여 증가합니다. 일상적인 작업에 5명을 사용하면 비용 손실이 발생합니다. 그렇기 때문에 공식 권장 인원은 3~5명이며, "집중하는 3명이 산만한 5명보다 나은 경우가 많다"고 명시되어 있습니다(공식 문서).

둘째는 worktree의 격리 범위입니다. worktree는 단순히 파일 분리를 위한 Git 메커니즘일 뿐, 데이터베이스, 환경 변수, 실행 중인 서비스는 여전히 공유됩니다. 두 세션이 동일한 로컬 DB에서 마이그레이션을 실행하면 문제가 발생합니다. 공식 문서에서는 "각 worktree에서 개발 환경을 초기화(의존성 설치, 가상 환경 설정)하는 것을 잊지 말라"고 경고하며, 작업이 DB에 영향을 준다면 스키마, Docker 컨테이너 또는 .env 파일을 분리해야 한다고 설명합니다(공식 문서).

셋째는 권한입니다. 팀원은 생성될 때 리드의 권한 설정을 상속받습니다. --dangerously-skip-permissions으로 리드를 실행하면 모든 팀원도 동일한 미확인 상태가 됩니다. 사고의 영향이 병렬로 확산되므로, 리드 쪽에서 권한을 제한하는 것이 더 안전합니다.

8. 중급 사용자를 위한 FAQ: 인원, 확장, 품질 게이트

마지막으로, 일반적인 질문에 대한 몇 가지 보충 답변입니다.

Q. 몇 개의 세션이 현실적인가요?

앞서 언급한 3-레이어, 8-세션 구조가 좋은 기준입니다. 핵심은 8명을 하나의 agent teams에 때려넣는 것이 아니라, 3~5명 팀을 핵심으로 하고 worktree 세션이나 subagent를 추가하는 것입니다. 이는 공식 권장 사항(팀당 3~5명, 팀원당 5~6개 작업)과 일치합니다. 궁극적인 한계는 모니터링하고 조종할 수 있는 범위입니다. 명령할 수 있는 범위를 넘어 숫자를 늘리면 효율성이 감소합니다.

Q. subagent와 agent teams으로 충분하지 않으면 어떻게 하나요?

대량의 독립 세션을 한 곳에서 모니터링하고 싶다면, 공식 subagent 페이지에서 background agents라는 메커니즘을 언급하고 있습니다. 레이어별로 생각하면, 세션 내 도움을 위한 subagent, 대화형 병렬 팀을 위한 agent teams, 그리고 많은 독립 세션 관리를 위한 background agents가 있습니다.

Q. 품질을 어떻게 보장할 수 있나요?

CLAUDE.md의 권장 사항은 "따르기 쉬운 지침"일 뿐입니다. 반드시 실행해야 하는 검사는 hooks로 강제하세요. agent teams에는 TeammateIdle, TaskCreated, TaskCompleted와 같은 hooks가 있으며, 종료 코드 2를 반환하면 피드백을 보내고 작업을 계속하도록 강제합니다(공식 문서). 즉, "테스트가 통과할 때까지 완료하지 마라"와 같은 규칙을 프로그래밍 방식으로 적용할 수 있습니다.

요약: 모니터에서 설계자/위임자로

Claude Code의 가치는 단순히 코드를 더 빠르게 작성하는 것보다, 한 사람이 여러 전문화된 Claude를 제어할 수 있는 능력에 더 있습니다. 핵심 포인트는 다음과 같습니다.

세 가지 메커니즘을 혼동하지 마세요: subagent는 결과를 반환하고, agent teams는 대화형 팀이며, worktree는 파일을 격리합니다. 8개 세션을 명령, 구현, 품질 레이어로 나누고, 구현은 worktree로 격리하며, 품질 역할은 subagent 정의 또는 agent teams로 고정하세요. 역할 경계는 CLAUDE.md가 아닌 subagent 정의에서 고정하고, 절대적인 규칙은 hooks로 강제하세요. 커스텀 SQLite 솔루션을 구축하기 전에 공식 markdown 기반 자동 메모리를 먼저 정리하세요. 팀당 3~5명을 목표로 하고 레이어를 추가하여 총 8명의 워커를 구성하세요.

오늘부터 시작해볼 3단계:

[ ] claude --worktree test-1을 입력하여 격리된 세션 실행을 체험해보세요.
[ ] .claude/agents/ 디렉토리에 "리뷰어" 역할에 대한 subagent 정의를 하나 작성하고, 구현 코드를 리뷰하도록 해보세요.
[ ] CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 설정하고, 세 명의 팀원으로 PR 리뷰를 병렬로 실행해보세요.

단일 세션에서 수정 지침을 끊임없이 입력하던 시간은, 역할을 설계하고 위임하는 시간으로 바뀔 것입니다. 무엇을 놓아주고 무엇을 감독할지 결정하는 것이 병렬 운영에서 가장 인간다운 작업입니다.

참고 링크 (공식 1차 출처)