Claude Code 하위 에이전트 및 에이전트 팀: 실용 가이드

"서브에이전트," "에이전트 팀," "오케스트레이션"이라는 단어를 보고 뭔가 놓치고 있는지 궁금할 수 있습니다. 짧은 대답: 대부분의 작업에서는 아닙니다. 하지만 큰 작업에서는 그렇고, 이해할 가치가 있습니다.

전문 용어 없이 이것을 풀어봅시다.

서브에이전트가 실제로 무엇인지

서브에이전트는 자체 컨텍스트, 자체 프롬프트, 자체 도구 권한을 가진 전문 보조자입니다.

메인 에이전트가 잘 정의된 하위 작업에 도달하면, 이를 서브에이전트에게 위임합니다. 그 서브에이전트는 자신의 컨텍스트 창에서 작업을 수행하고 결과만 반환합니다. 메인 에이전트는 전체 기록이 컨텍스트를 오염시키지 않고 결론만 받습니다.

핵심은 메인 에이전트의 컨텍스트를 깨끗하게 유지하는 것입니다. 50,000 토큰의 파일 검색에 빠진 하나의 에이전트 대신, 검색을 수행하고 유용한 세 줄을 보고하는 서브에이전트가 있는 것입니다.

프로젝트의 .claude/agents/ 폴더에서 서브에이전트를 선언합니다. 각각의 서브에이전트는 이름, 사용 시기를 설명하는 설명, 시스템 프롬프트를 가집니다.

---
name: test-writer
description: 테스트를 작성하거나 수정해야 할 때 사용
---
당신은 테스트를 작성합니다. 엣지 케이스 커버리지를 목표로 하며,
행복한 경로는 아닙니다. 절대 프로덕션 코드를 건드리지 않습니다.

에이전트 팀, 다음 단계

에이전트 팀은 Claude Code에 내장된 다중 에이전트 오케스트레이터입니다. 아직 실험적이며 기본적으로 비활성화되어 있지만, 견고한 시작점입니다.

아이디어는: 리드 에이전트가 큰 작업을 나누고, 각 부분을 전문 에이전트에게 위임합니다 (각각의 모델, 프롬프트, 도구를 가지고), 전문가들은 공유 파일 시스템에서 병렬로 작업하며 결과는 리드에게 돌아옵니다.

"전문가에게 위임"이라는 것이 서브에이전트처럼 들린다면, 그게 정상입니다. 에이전트 팀은 그 아이디어를 여러 에이전트를 진정한 병렬로 실행하는 것까지 밀어붙인 것입니다, 단순히 하나씩 순차적으로가 아니라.

내장된 것 외에도 Multiclaude와 Gas Town 같은 서드파티 오케스트레이터가 있습니다. 그들은 의견이 강하며, 시작할 때 좋은 출발점이 됩니다: 당신이 자신의 습관을 만들기 전까지 그들이 대신 결정해줍니다.

언제 필요하고 (언제 필요하지 않은지)

명확히 합시다: 다중 에이전트 오케스트레이션은 에이전트 지원 작업의 95%에 대해 무의미합니다. 대부분의 일상 작업에서는 단일 에이전트가 더 빠르고 간단합니다.

현재로서는, 다중 에이전트는 여전히 대형 프로젝트를 공격하는 비싼 실험적 방법입니다.

필요한 경우:

• 프로젝트가 서로 다른 파일을 건드리는 진정으로 독립적인 부분으로 나뉩니다.
• 단일 컨텍스트 창이 전체를 담을 수 없습니다.
• 광범위한 리팩터링이나 저장소 전체의 마이그레이션을 병렬화하고 싶습니다.

버그 수정, 집중된 기능, 또는 한 사람의 머리 안에 들어갈 수 있는 것에는 필요하지 않습니다.

함정은 하나의 에이전트가 5분 만에 할 일을 위해 열 개의 에이전트 "팀"을 구성하는 것입니다. 작업이 요구하지 않은 병렬성에 대해 토큰과 복잡성으로 대가를 치르게 됩니다.

진짜 문제: 가시성

충분히 이야기되지 않는 부분이 있습니다. 여러 서브에이전트나 에이전트 팀을 실행하는 순간, 흐름을 잃습니다.

리드가 다섯 명의 전문가에게 위임합니다. 누가 작업 중인가요? 누가 끝났나요? 누가 결정을 기다리고 있나요? 터미널에서는 스크롤되는 텍스트의 벽을 보고 누가 무엇을 하고 있는지 알 수 없습니다.

이때 시각적 대시보드가 모든 것을 바꿉니다. AgentsRoom은 각 에이전트와 각 서브에이전트를 자체 타일로 표시하며, 상태가 명확하게 표시됩니다. 위임이 어떻게 이루어지는지 보고, 누가 당신의 답변을 기다리고 있는지, 누가 충돌했는지 볼 수 있습니다. 텍스트의 벽이 읽을 수 있는 지도로 변합니다.

그 뷰가 없다면, 다중 에이전트 오케스트레이션은 일상적으로 관리할 수 없는 인상적인 데모로 남습니다. 그것이 있다면, 실제로 사용하는 도구가 됩니다.

어디서 시작할까

바로 여덟 개의 에이전트 팀으로 뛰어들지 마세요.

정확하고 반복적인 작업을 위한 하나 또는 두 개의 서브에이전트로 시작하세요: 테스트를 작성하는 것, 코드베이스를 검색하는 것. 메인 에이전트의 컨텍스트에서 빠르게 이점을 느낄 것입니다.

그 메커니즘이 자연스럽게 느껴지면, 작업이 명확하게 나뉘는 경우에 에이전트 팀을 켜세요. 누가 무엇을 하고 있는지 주시하고, 실행 전에 계획을 승인하고, 검토가 병목이 되는 순간 멈추세요.

다중 에이전트는 시작 전에 구조를 잡는 사람들에게 보상을 줍니다. 가장 많은 에이전트를 실행하는 사람들에게는 아닙니다.