Claude Code 서브에이전트와 Agent Teams, 세션 셋을 합칠 기준

기능별로 Claude Code 세션을 세 개 열면 속도는 빨라질 수 있다. 그런데 어느 순간 사용자는 개발자보다 작업 배차 담당자에 가까워진다. 서브에이전트와 Agent Teams는 이 부담을 줄일까, 아니면 더 복잡한 산출물을 만드는가?

세 개의 세션은 자동으로 한 팀이 되지 않는다

세션을 나누면 각 창은 자기 대화 이력과 판단만 가진다. 한 창에서 바뀐 설계가 다른 창에 자동 전달되지 않는다. 사용자가 계획, 변경 사항, 충돌을 직접 옮기면 병렬화의 이득이 관리비로 빠져나간다.

Claude Code의 선택지는 현재 네 갈래다. 단일 세션은 맥락이 계속 이어지는 순차 작업에 맞는다. 서브에이전트는 조사나 테스트처럼 독립적인 일을 맡고 요약만 메인 대화로 돌려준다. Agent Teams는 별도 컨텍스트를 가진 팀원들이 공유 작업 목록과 메시지로 조율한다.

파일 충돌은 별도 문제다. Anthropic은 Agent Teams가 팀원별 worktree를 자동 제공하지 않는다고 설명한다. 같은 파일을 건드릴 가능성이 있으면 `claude --worktree feature-auth`처럼 체크아웃을 분리해야 한다. 커스텀 서브에이전트에는 `isolation: worktree`를 지정할 수 있다.

서브에이전트와 Agent Teams의 경계는 대화 필요성이다

Anthropic은 Agent Teams를 2026년 2월 Claude Code 2.1.32에서 Research Preview로 공개했다. 현재도 기본 비활성화이며 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 설정이 필요하다. 최신 문서는 2.1.178부터 `TeamCreate`와 `TeamDelete`가 사라졌다고 안내한다. 예전 사용법을 그대로 따르면 동작을 오해하기 쉽다.

고르는 기준은 에이전트 수가 아니다. 결과만 받으면 되는 로그 분석, 문서 조사, 테스트 실행은 서브에이전트가 가볍다. 보안·성능·제품 요구를 서로 반박하거나 경쟁 가설을 시험해야 할 때 팀 메시지가 의미를 갖는다. 순서 의존성이 크거나 한 파일을 함께 고치는 작업에는 단일 세션이 낫다는 것이 공식 권고다.

써본 사람들 사이에서도 평가가 갈렸다. 독립 조사와 리뷰에서는 맥락 분리가 유용하다는 반응이 있었다. 반면 팀장이 기다리는 시간이 늘고, 설계 기준이 흐려지며, 조율 메시지가 사용량을 키운다는 불만도 반복됐다. 작은 프로젝트에는 직접 세션을 관리하는 편이 빠르다는 의견도 있었다.

통제는 지침, 능력, 강제 장치를 나눠야 한다

`CLAUDE.md`는 프로젝트 구조와 코딩 원칙을 모든 세션에 제공한다. 하지만 지침은 정책 엔진이 아니다. 설계 원칙을 적었다고 위반이 기술적으로 차단되지는 않는다. 서브에이전트의 작업 프롬프트에도 완료 조건과 수정 금지 범위를 다시 명시해야 한다.

반복 절차는 `.claude/skills/<name>/SKILL.md`로 옮긴다. 예를 들어 계획 검토, 구현, 테스트, 독립 리뷰 순서를 스킬에 적을 수 있다. 자동 발동이 위험하면 `disable-model-invocation: true`로 두고 사람이 직접 호출한다. 서브에이전트에 필요한 스킬은 정의 파일의 `skills` 항목으로 미리 넣는다.

실제 차단은 훅과 권한이 맡는다. `PreToolUse` 훅은 보호 파일 수정이나 특정 명령을 거부할 수 있다. `SubagentStop`과 `TaskCompleted` 훅은 테스트 결과나 체크리스트가 없을 때 종료를 막는 데 쓸 수 있다. 커스텀 에이전트의 `tools`, `disallowedTools`, `permissionMode`, `maxTurns`는 보이는 도구와 실행 범위를 좁힌다.

하네스는 역할보다 입출력을 먼저 적는다

작동하는 최소 구성은 거창한 페르소나 팀이 아니다. 먼저 `CLAUDE.md`에 아키텍처 불변 조건과 표준 검증 명령을 적는다. 다음으로 `.claude/agents/implementer.md`에는 소유 파일, 입력 명세, 금지 변경, 산출물을 둔다. `reviewer.md`에는 구현자와 다른 관점에서 요구사항과 diff를 대조하도록 적는다.

실행 순서도 짧게 고정한다. 메인 세션이 계획을 승인하고, 구현 에이전트가 격리된 worktree에서 변경한다. 리뷰 에이전트는 같은 요구사항과 diff만 받아 누락과 과잉 변경을 찾는다. 마지막 훅은 테스트 명령의 종료 코드와 필수 결과물이 있어야 작업 완료를 허용한다.

설계의 구멍을 의도로 착각하는 문제에는 중단 조건이 필요하다. 입력에 모순이 있거나 공개 API가 달라져야 하면 구현자가 추정하지 않고 질문을 반환하게 한다. 반대로 사소한 구현 선택까지 매번 묻지 않도록 수정 가능 범위도 함께 적는다. 네거티브 지시만 늘리는 방식보다 경계와 성공 조건을 짝지어 쓰는 편이 판단하기 쉽다.

관련 저장소인 sonmat은 이 문제를 검증 규율의 전파로 다룬다. README에 따르면 `/plugin marketplace add jun0-ds/sonmat`과 `/plugin install sonmat@sonmat`으로 설치한다. 세션 시작 훅이 `CLAUDE.md`에 참조를 심고, `discipline`, `skills`, `agents`를 함께 써서 작업자까지 검증 원칙을 전달한다. 해당 효과는 프로젝트의 설계 주장인 만큼 자체 작업에서도 확인이 필요하다.

에이전트를 늘리기 전에 실패 비용을 계산한다

병렬화는 무료가 아니다. Anthropic 비용 문서는 팀원이 계획 모드로 움직일 때 Agent Teams가 표준 세션보다 약 7배 많은 토큰을 쓸 수 있다고 밝힌다. 팀원마다 컨텍스트가 있고, 활동 중인 팀원은 종료 전까지 토큰을 소비한다. 개인 개발자와 소규모 팀에는 속도보다 재작업 비용이 더 큰 작업만 팀으로 넘길 이유가 생긴다.

복수 에이전트가 유리한 단위는 서로 독립적이며 결과를 합쳐 검증할 수 있어야 한다. 리뷰를 구현과 분리하고, 파일 소유권을 나누고, 실제 테스트를 종료 조건으로 묶으면 에이전트 수가 품질로 이어질 여지가 생긴다. 세션 세 개를 한 팀으로 바꾸는 핵심은 더 많은 대화가 아니라, 충돌하지 않는 책임과 실패를 멈추는 장치다.