Claude Code 세션이 길어질수록 응답이 느려지고 비용이 올라가는 경험, 한 번쯤 해보셨을 겁니다. 파일을 읽고, 탐색하고, 수정하다 보면 컨텍스트 창에 모든 것이 쌓이고, 결국 주된 작업이 느려집니다.
Anthropic이 Claude Code의 서브에이전트(Subagents) 기능 활용 가이드를 공식 블로그에 공개했습니다. 서브에이전트는 독립된 컨텍스트를 가진 별도의 Claude 인스턴스로, 특정 작업을 위임받아 처리한 뒤 결과만 돌려주는 구조입니다. 어떤 상황에 써야 효과적이고, 어떤 상황에는 오히려 역효과인지를 구체적으로 설명합니다.
출처: How and when to use subagents in Claude Code – Anthropic
서브에이전트가 해결하는 문제
Claude Code 세션은 시간이 지날수록 무거워집니다. 읽은 파일, 탐색한 경로, 중간에 확인한 코드까지 모두 컨텍스트 창에 누적되기 때문입니다. 이 ‘컨텍스트 오염’은 응답 속도를 떨어뜨리고 토큰 비용을 높입니다.
서브에이전트는 이 문제를 구조적으로 우회합니다. 메인 세션과 독립된 컨텍스트 창을 가지며, 작업이 끝나면 결과만 반환합니다. Anthropic은 이를 “브라우저 탭”에 비유합니다. 탭을 열어 탐색하되, 메인 창의 흐름은 그대로 유지되는 것처럼요.
각 서브에이전트는 서로 다른 권한도 가질 수 있습니다. 코드베이스를 탐색하는 에이전트는 읽기 전용, 실제 변경을 수행하는 에이전트는 전체 편집 권한을 주는 식입니다.
언제 써야 하고, 언제 쓰지 말아야 하는가
Anthropic이 제시하는 서브에이전트 활용 신호는 명확합니다.
쓸 만한 상황:
- 수십 개의 파일을 탐색해야 할 때 — 결과만 요약해서 받을 수 있습니다
- 서로 독립적인 작업이 여러 개일 때 — 동시에 실행해 시간을 단축합니다
- 구현 후 편견 없는 검토가 필요할 때 — 대화 이력을 모르는 에이전트가 더 날카롭게 봅니다
- 설계→구현→테스트처럼 단계가 명확히 나뉠 때 — 각 단계가 다른 단계의 맥락에 오염되지 않습니다
쓰지 말아야 할 상황도 있습니다:
- 2단계가 1단계 결과 전체를 필요로 하는 순차 작업 — 메인 세션이 더 깔끔합니다
- 같은 파일을 두 에이전트가 동시에 수정하는 경우 — 충돌이 발생합니다
- 간단하고 빠른 작업 — 에이전트를 띄우는 오버헤드가 작업 자체보다 클 수 있습니다
- 서브에이전트끼리 소통이 필요한 경우 — 서브에이전트는 메인 세션에만 결과를 보고하고 서로 직접 대화하지 않습니다. 이런 경우엔 Agent Teams가 필요합니다
파일 10개 이상 탐색이 필요하거나, 독립적인 작업이 3개 이상이라면 서브에이전트 사용을 고려할 만하다고 Anthropic은 안내합니다.
어떻게 호출하는가
Anthropic은 가장 단순한 방법으로 시작해 점차 자동화하는 접근을 권장합니다.
가장 쉬운 방법은 대화에서 직접 요청하는 것입니다. “서브에이전트를 사용해서 인증 흐름을 탐색해줘”, “세 패키지를 동시에 수정해줘”처럼 자연어로 지시하면 됩니다. 터미널, VS Code, JetBrains, 웹, 데스크톱 앱 모두에서 작동합니다.
반복적으로 필요한 역할은 커스텀 서브에이전트로 정의할 수 있습니다. 보안 리뷰어, 테스트 작성자처럼 자주 등장하는 역할을 마크다운 파일로 한 번 설정해두면, 이후에는 관련 작업이 들어올 때 Claude가 자동으로 위임합니다. CLAUDE.md 파일에 정책을 적어두면 팀 전체가 동일한 방식으로 적용받고, Skills로 반복 워크플로우를 정의하거나 Hooks로 커밋 전 자동 검토를 구성하는 것도 가능합니다.
맥락을 나누는 설계
서브에이전트의 핵심은 ‘격리’입니다. 기능 하나를 추가할 때 코드베이스 전체를 한 세션에 쌓아두는 대신, 탐색·구현·검토를 분리된 인스턴스에 위임합니다. 각 에이전트는 자기 역할에 필요한 맥락만 가집니다.
이는 단순한 성능 최적화를 넘어 AI 코딩 워크플로우를 설계하는 방식의 변화이기도 합니다. 긴 단일 세션 대신 명확한 역할을 가진 에이전트들이 협력하는 구조로요. 커스텀 서브에이전트와 CLAUDE.md를 조합하면 개인 설정이 팀 워크플로우로 확장될 수 있다는 점도 주목할 부분입니다.
구체적인 호출 방법과 Hooks 설정 예시, Agent Teams와의 비교는 원문에서 확인할 수 있습니다.
답글 남기기